README.md

remote

The remote package implements a client for accessing a registry, per the OCI distribution spec.

It leans heavily on the lower level transport package, which handles the authentication handshake and structured errors.

Usage

package main

import (
	"github.com/google/go-containerregistry/pkg/authn"
	"github.com/google/go-containerregistry/pkg/name"
	"github.com/google/go-containerregistry/pkg/v1/remote"
)

func main() {
	ref, err := name.ParseReference("gcr.io/google-containers/pause")
	if err != nil {
		panic(err)
	}

	img, err := remote.Image(ref, remote.WithAuthFromKeychain(authn.DefaultKeychain))
	if err != nil {
		panic(err)
	}

	// do stuff with img
}

Structure

Background

There are a lot of confusingly similar terms that come up when talking about images in registries.

Anatomy of an image

In general...

• A tag refers to an image manifest.
• An image manifest references a config file and an orderered list of compressed layers by sha256 digest.
• A config file references an ordered list of uncompressed layers by sha256 digest and contains runtime configuration.
• The sha256 digest of the config file is the image id for the image.

For example, an image with two layers would look something like this:

Anatomy of an index

In the normal case, an index is used to represent a multi-platform image. This was the original use case for a manifest list.

It is possible for an index to reference another index, per the OCI image-spec. In theory, both an image and image index can reference arbitrary things via descriptors, e.g. see the image layout example, which references an application/xml file from an image index.

That could look something like this:

Using a recursive index like this might not be possible with all registries, but this flexibility allows for some interesting applications, e.g. the OCI Artifacts effort.

Anatomy of an image upload

The structure of an image requires a delicate ordering when uploading an image to a registry. Below is a (slightly simplified) figure that describes how an image is prepared for upload to a registry and how the data flows between various artifacts:

Note that:

• A config file references the uncompressed layer contents by sha256.
• A manifest references the compressed layer contents by sha256 and the size of the layer.
• A manifest references the config file contents by sha256 and the size of the file.

It follows that during an upload, we need to upload layers before the config file, and we need to upload the config file before the manifest.

Sometimes, we know all of this information ahead of time, (e.g. when copying from remote.Image), so the ordering is less important.

In other cases, e.g. when using a stream.Layer, we can't compute anything until we have already uploaded the layer, so we need to be careful about ordering.

Caveats

schema 1

This package does not support schema 1 images, see #377, however, it's possible to do something useful with them via remote.Get, which doesn't try to interpret what is returned by the registry.

crane.Copy takes advantage of this to implement support for copying schema 1 images, see here.