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 reader, 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 reader, 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.

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 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.

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"
	"io/ioutil"
	"os"

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

func main() {
	/* calculations for this test:
	The image we are using is docker.io/library/alpine:3.10
	its size on disk is 2800640
	The filesizes inside are:
	-rw-r--r--  0 0      0        1509 Jan  1  1970 sha256:be4e4bea2c2e15b403bb321562e78ea84b501fb41497472e91ecb41504e8a27c
	-rw-r--r--  0 0      0     2795580 Jan  1  1970 21c83c5242199776c232920ddb58cfa2a46b17e42ed831ca9001c8dbc532d22d.tar.gz
	-rw-r--r--  0 0      0         216 Jan  1  1970 manifest.json
	when rounding each to a 512-byte block, plus the header, we get:
	1509    ->    1536 + 512 = 2048
	2795580 -> 2796032 + 512 = 2796544
	216     ->     512 + 512 = 1024
	add in 2 blocks of all 0x00 to indicate end of archive
	                         = 1024
	                        -------
	Total:                  2800640
	*/
	// buffered channel to make the example test easier
	c := make(chan v1.Update, 200)
	// Make a tempfile for tarball writes.
	fp, err := ioutil.TempFile("", "")
	if err != nil {
		fmt.Printf("error creating temp file: %v\n", err)
		return
	}
	defer fp.Close()
	defer os.Remove(fp.Name())

	tag, err := name.NewDigest("docker.io/library/alpine@sha256:f0e9534a598e501320957059cb2a23774b4d4072e37c7b2cf7e95b241f019e35", name.StrictValidation)
	if err != nil {
		fmt.Printf("error creating test tag: %v\n", err)
		return
	}
	desc, err := remote.Get(tag)
	if err != nil {
		fmt.Printf("error getting manifest: %v", err)
		return
	}
	img, err := desc.Image()
	if err != nil {
		fmt.Printf("error image: %v", err)
		return
	}
	go func() {
		_ = tarball.WriteToFile(fp.Name(), tag, 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:

2800640/2800640

Source Files

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

Version
v0.9.0
Published
May 17, 2022
Platform
js/wasm
Imports
22 packages
Last checked
2 minutes ago –

Tools for package owners.