package tarball

import "github.com/google/go-containerregistry/pkg/v1/tarball"

Package tarball provides facilities for reading/writing v1.Images from/to a tarball on-disk.

Index

Examples

Functions

func CalculateSize 

func CalculateSize(refToImage map[name.Reference]v1.Image) (size int64, err error)

CalculateSize calculates the expected complete size of the output tar file

func Image 

func Image(opener Opener, tag *name.Tag) (v1.Image, error)

Image exposes an image from the tarball at the provided path.

func ImageFromPath 

func ImageFromPath(path string, tag *name.Tag) (v1.Image, error)

ImageFromPath returns a v1.Image from a tarball located on path.

func LayerFromFile 

func LayerFromFile(path string, opts ...LayerOption) (v1.Layer, error)

LayerFromFile returns a v1.Layer given a tarball

func LayerFromOpener 

func LayerFromOpener(opener Opener, opts ...LayerOption) (v1.Layer, error)

LayerFromOpener returns a v1.Layer given an Opener function. The Opener may return either an uncompressed tarball (common), or a compressed tarball (uncommon).

When using this in conjunction with something like remote.Write the uncompressed path may end up gzipping things multiple times:

  1. Compute the layer SHA256
  2. Upload the compressed layer.

Since gzip can be expensive, we support an option to memoize the compression that can be passed here: tarball.WithCompressedCaching

func LayerFromReader 

func LayerFromReader(reader io.Reader, opts ...LayerOption) (v1.Layer, error)

LayerFromReader returns a v1.Layer given a io.Reader.

The reader's contents are read and buffered to a temp file in the process.

Deprecated: Use LayerFromOpener or stream.NewLayer instead, if possible.

func MultiRefWrite 

func MultiRefWrite(refToImage map[name.Reference]v1.Image, w io.Writer, opts ...WriteOption) error

MultiRefWrite writes the contents of each image to the provided writer, in the compressed format. The contents are written in the following format: One manifest.json file at the top level containing information about several images. One file for each layer, named after the layer's SHA. One file for the config blob, named after its SHA.

func MultiRefWriteToFile 

func MultiRefWriteToFile(p string, refToImage map[name.Reference]v1.Image, opts ...WriteOption) error

MultiRefWriteToFile writes in the compressed format to a tarball, on disk. This is just syntactic sugar wrapping tarball.MultiRefWrite with a new file.

func MultiWrite 

func MultiWrite(tagToImage map[name.Tag]v1.Image, w io.Writer, opts ...WriteOption) error

MultiWrite writes the contents of each image to the provided writer, in the compressed format. The contents are written in the following format: One manifest.json file at the top level containing information about several images. One file for each layer, named after the layer's SHA. One file for the config blob, named after its SHA.

func MultiWriteToFile 

func MultiWriteToFile(p string, tagToImage map[name.Tag]v1.Image, opts ...WriteOption) error

MultiWriteToFile writes in the compressed format to a tarball, on disk. This is just syntactic sugar wrapping tarball.MultiWrite with a new file.

func WithCompressedCaching 

func WithCompressedCaching(l *layer)

WithCompressedCaching is a functional option that overrides the logic for accessing the compressed bytes to memoize the result and avoid expensive repeated gzips.

func WithEstargz 

func WithEstargz(l *layer)

WithEstargz is a functional option that explicitly enables estargz support.

Deprecated: WithEstargz is deprecated, and will be removed in a future release.

func Write 

func Write(ref name.Reference, img v1.Image, w io.Writer, opts ...WriteOption) error

Write is a wrapper to write a single image and tag to a tarball.

func WriteToFile 

func WriteToFile(p string, ref name.Reference, img v1.Image, opts ...WriteOption) error

WriteToFile writes in the compressed format to a tarball, on disk. This is just syntactic sugar wrapping tarball.Write with a new file.

Types

type Descriptor 

type Descriptor struct {
	Config   string
	RepoTags []string
	Layers   []string

	// Tracks foreign layer info. Key is DiffID.
	LayerSources map[v1.Hash]v1.Descriptor `json:",omitempty"`
}

Descriptor stores the manifest data for a single image inside a `docker save` tarball.

type LayerOption 

type LayerOption func(*layer)

LayerOption applies options to layer

func WithCompression 

func WithCompression(comp compression.Compression) LayerOption

WithCompression is a functional option for overriding the default compression algorithm used for compressing uncompressed tarballs. Please note that WithCompression(compression.ZStd) should be used in conjunction with WithMediaType(types.OCILayerZStd)

func WithCompressionLevel 

func WithCompressionLevel(level int) LayerOption

WithCompressionLevel is a functional option for overriding the default compression level used for compressing uncompressed tarballs.

func WithEstargzOptions 

func WithEstargzOptions(opts ...estargz.Option) LayerOption

WithEstargzOptions is a functional option that allow the caller to pass through estargz.Options to the underlying compression layer. This is only meaningful when estargz is enabled.

Deprecated: WithEstargz is deprecated, and will be removed in a future release.

func WithMediaType 

func WithMediaType(mt types.MediaType) LayerOption

WithMediaType is a functional option for overriding the layer's media type.

type Manifest 

type Manifest []Descriptor

Manifest represents the manifests of all images as the `manifest.json` file in a `docker save` tarball.

func ComputeManifest 

func ComputeManifest(refToImage map[name.Reference]v1.Image) (Manifest, error)

ComputeManifest get the manifest.json that will be written to the tarball for multiple references

func LoadManifest 

func LoadManifest(opener Opener) (Manifest, error)

LoadManifest load manifest

type Opener 

type Opener func() (io.ReadCloser, error)

Opener is a thunk for opening a tar file.

type WriteOption 

type WriteOption func(*writeOptions) error

WriteOption a function option to pass to Write()

func WithProgress 

func WithProgress(updates chan<- v1.Update) WriteOption

WithProgress create a WriteOption for passing to Write() that enables a channel to receive updates as they are downloaded and written to disk.

Example

Code:play  

package main

import (
	"errors"
	"fmt"
	"io"
	"os"

	v1 "github.com/google/go-containerregistry/pkg/v1"
	"github.com/google/go-containerregistry/pkg/v1/tarball"
)

func main() {
	// buffered channel to make the example test easier
	c := make(chan v1.Update, 200)
	// Make a tempfile for tarball writes.
	fp, err := os.CreateTemp("", "")
	if err != nil {
		fmt.Printf("error creating temp file: %v\n", err)
		return
	}
	defer fp.Close()
	defer os.Remove(fp.Name())

	img, err := tarball.ImageFromPath("testdata/test_image_1.tar", nil)
	go func() {
		_ = tarball.WriteToFile(fp.Name(), nil, img, tarball.WithProgress(c))
	}()
	for update := range c {
		switch {
		case update.Error != nil && errors.Is(update.Error, io.EOF):
			fmt.Fprintf(os.Stderr, "receive error message: %v\n", err)
			fmt.Printf("%d/%d", update.Complete, update.Total)

			return
		case update.Error != nil:
			fmt.Printf("error writing tarball: %v\n", update.Error)
			return
		default:
			fmt.Fprintf(os.Stderr, "receive update: %#v\n", update)
		}
	}
}

Output:

4096/4096

Source Files

doc.go image.go layer.go write.go

Version
v0.20.3 (latest)
Published
Jan 15, 2025
Platform
linux/amd64
Imports
25 packages
Last checked
17 hours ago –

Tools for package owners.