remote

README

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.

Documentation

Overview

Package remote provides facilities for reading/writing v1.Images from/to a remote image registry.

Index

• func Catalog(ctx context.Context, target name.Registry, options ...Option) ([]string, error)
• func CatalogPage(target name.Registry, last string, n int, options ...Option) ([]string, error)
• func CheckPushPermission(ref name.Reference, kc authn.Keychain, t http.RoundTripper) error
• func Delete(ref name.Reference, options ...Option) error
• func Head(ref name.Reference, options ...Option) (*v1.Descriptor, error)
• func Image(ref name.Reference, options ...Option) (v1.Image, error)
• func Index(ref name.Reference, options ...Option) (v1.ImageIndex, error)
• func Layer(ref name.Digest, options ...Option) (v1.Layer, error)
• func List(repo name.Repository, options ...Option) ([]string, error)
• func ListWithContext(ctx context.Context, repo name.Repository, options ...Option) ([]string, error)
• func Tag(tag name.Tag, t Taggable, options ...Option) error
• func Write(ref name.Reference, img v1.Image, options ...Option) error
• func WriteIndex(ref name.Reference, ii v1.ImageIndex, options ...Option) error
• func WriteLayer(repo name.Repository, layer v1.Layer, options ...Option) error
• type Descriptor
  • func Get(ref name.Reference, options ...Option) (*Descriptor, error)
  • func (d *Descriptor) Image() (v1.Image, error)
  • func (d *Descriptor) ImageIndex() (v1.ImageIndex, error)
  • func (d *Descriptor) RawManifest() ([]byte, error)
• type ErrSchema1
  • func (e *ErrSchema1) Error() string
• type MountableLayer
  • func (ml *MountableLayer) Descriptor() (*v1.Descriptor, error)
• type Option
  • func WithAuth(auth authn.Authenticator) Option
  • func WithAuthFromKeychain(keys authn.Keychain) Option
  • func WithContext(ctx context.Context) Option
  • func WithPlatform(p v1.Platform) Option
  • func WithTransport(t http.RoundTripper) Option
• type Taggable

Functions

func Catalog

func Catalog(ctx context.Context, target name.Registry, options ...Option) ([]string, error)

Catalog calls /_catalog, returning the list of repositories on the registry.

func CatalogPage

func CatalogPage(target name.Registry, last string, n int, options ...Option) ([]string, error)

CatalogPage calls /_catalog, returning the list of repositories on the registry.

func CheckPushPermission

func CheckPushPermission(ref name.Reference, kc authn.Keychain, t http.RoundTripper) error

CheckPushPermission returns an error if the given keychain cannot authorize a push operation to the given ref.

This can be useful to check whether the caller has permission to push an image before doing work to construct the image.

TODO(#412): Remove the need for this method.

func Delete

func Delete(ref name.Reference, options ...Option) error

Delete removes the specified image reference from the remote registry.

func Head

func Head(ref name.Reference, options ...Option) (*v1.Descriptor, error)

Head returns a v1.Descriptor for the given reference by issuing a HEAD request.

func Image

func Image(ref name.Reference, options ...Option) (v1.Image, error)

Image provides access to a remote image reference.

func Index

func Index(ref name.Reference, options ...Option) (v1.ImageIndex, error)

Index provides access to a remote index reference.

func Layer

func Layer(ref name.Digest, options ...Option) (v1.Layer, error)

Layer reads the given blob reference from a registry as a Layer. A blob reference here is just a punned name.Digest where the digest portion is the digest of the blob to be read and the repository portion is the repo where that blob lives.

func List

func List(repo name.Repository, options ...Option) ([]string, error)

List wraps ListWithContext using the background context.

func ListWithContext

func ListWithContext(ctx context.Context, repo name.Repository, options ...Option) ([]string, error)

ListWithContext calls /tags/list for the given repository, returning the list of tags in the "tags" property.

func Tag

func Tag(tag name.Tag, t Taggable, options ...Option) error

Tag adds a tag to the given Taggable.

func Write

func Write(ref name.Reference, img v1.Image, options ...Option) error

Write pushes the provided img to the specified image reference.

func WriteIndex

func WriteIndex(ref name.Reference, ii v1.ImageIndex, options ...Option) error

WriteIndex pushes the provided ImageIndex to the specified image reference. WriteIndex will attempt to push all of the referenced manifests before attempting to push the ImageIndex, to retain referential integrity.

func WriteLayer

func WriteLayer(repo name.Repository, layer v1.Layer, options ...Option) error

WriteLayer uploads the provided Layer to the specified repo.

Types

type Descriptor

type Descriptor struct {
	v1.Descriptor
	Manifest []byte
	// contains filtered or unexported fields
}

Descriptor provides access to metadata about remote artifact and accessors for efficiently converting it into a v1.Image or v1.ImageIndex.

func Get

func Get(ref name.Reference, options ...Option) (*Descriptor, error)

Get returns a remote.Descriptor for the given reference. The response from the registry is left un-interpreted, for the most part. This is useful for querying what kind of artifact a reference represents.

See Head if you don't need the response body.

func (*Descriptor) Image

func (d *Descriptor) Image() (v1.Image, error)

Image converts the Descriptor into a v1.Image.

If the fetched artifact is already an image, it will just return it.

If the fetched artifact is an index, it will attempt to resolve the index to a child image with the appropriate platform.

See WithPlatform to set the desired platform.

func (*Descriptor) ImageIndex

func (d *Descriptor) ImageIndex() (v1.ImageIndex, error)

ImageIndex converts the Descriptor into a v1.ImageIndex.

func (*Descriptor) RawManifest

func (d *Descriptor) RawManifest() ([]byte, error)

RawManifest exists to satisfy the Taggable interface.

type ErrSchema1

type ErrSchema1 struct {
	// contains filtered or unexported fields
}

ErrSchema1 indicates that we received a schema1 manifest from the registry. This library doesn't have plans to support this legacy image format: https://github.com/google/go-containerregistry/issues/377

func (*ErrSchema1) Error

func (e *ErrSchema1) Error() string

Error implements error.

type MountableLayer

type MountableLayer struct {
	v1.Layer

	Reference name.Reference
}

MountableLayer wraps a v1.Layer in a shim that enables the layer to be "mounted" when published to another registry.

func (*MountableLayer) Descriptor

func (ml *MountableLayer) Descriptor() (*v1.Descriptor, error)

Descriptor retains the original descriptor from an image manifest. See partial.Descriptor.

type Option

type Option func(*options) error

Option is a functional option for remote operations.

func WithAuth

func WithAuth(auth authn.Authenticator) Option

WithAuth is a functional option for overriding the default authenticator for remote operations.

The default authenticator is authn.Anonymous.

func WithAuthFromKeychain

func WithAuthFromKeychain(keys authn.Keychain) Option

WithAuthFromKeychain is a functional option for overriding the default authenticator for remote operations, using an authn.Keychain to find credentials.

The default authenticator is authn.Anonymous.

func WithContext

func WithContext(ctx context.Context) Option

WithContext is a functional option for setting the context in http requests performed by a given function. Note that this context is used for _all_ http requests, not just the initial volley. E.g., for remote.Image, the context will be set on http requests generated by subsequent calls to RawConfigFile() and even methods on layers returned by Layers().

The default context is context.Background().

func WithPlatform

func WithPlatform(p v1.Platform) Option

WithPlatform is a functional option for overriding the default platform that Image and Descriptor.Image use for resolving an index to an image.

The default platform is amd64/linux.

func WithTransport

func WithTransport(t http.RoundTripper) Option

WithTransport is a functional option for overriding the default transport for remote operations.

The default transport its http.DefaultTransport.

type Taggable

type Taggable interface {
	RawManifest() ([]byte, error)
}

Taggable is an interface that enables a manifest PUT (e.g. for tagging).