Documentation

Index

Constants

View Source
const (
	MediaTypeDockerSchema2Layer            = "application/vnd.docker.image.rootfs.diff.tar"
	MediaTypeDockerSchema2LayerForeign     = "application/vnd.docker.image.rootfs.foreign.diff.tar"
	MediaTypeDockerSchema2LayerGzip        = "application/vnd.docker.image.rootfs.diff.tar.gzip"
	MediaTypeDockerSchema2LayerForeignGzip = "application/vnd.docker.image.rootfs.foreign.diff.tar.gzip"
	MediaTypeDockerSchema2Config           = "application/vnd.docker.container.image.v1+json"
	MediaTypeDockerSchema2Manifest         = "application/vnd.docker.distribution.manifest.v2+json"
	MediaTypeDockerSchema2ManifestList     = "application/vnd.docker.distribution.manifest.list.v2+json"
	// Checkpoint/Restore Media Types
	MediaTypeContainerd1Checkpoint               = "application/vnd.containerd.container.criu.checkpoint.criu.tar"
	MediaTypeContainerd1CheckpointPreDump        = "application/vnd.containerd.container.criu.checkpoint.predump.tar"
	MediaTypeContainerd1Resource                 = "application/vnd.containerd.container.resource.tar"
	MediaTypeContainerd1RW                       = "application/vnd.containerd.container.rw.tar"
	MediaTypeContainerd1CheckpointConfig         = "application/vnd.containerd.container.checkpoint.config.v1+proto"
	MediaTypeContainerd1CheckpointOptions        = "application/vnd.containerd.container.checkpoint.options.v1+proto"
	MediaTypeContainerd1CheckpointRuntimeName    = "application/vnd.containerd.container.checkpoint.runtime.name"
	MediaTypeContainerd1CheckpointRuntimeOptions = "application/vnd.containerd.container.checkpoint.runtime.options+proto"
	// Legacy Docker schema1 manifest
	MediaTypeDockerSchema1Manifest = "application/vnd.docker.distribution.manifest.v1+prettyjws"
)

    mediatype definitions for image components handled in containerd.

    oci components are generally referenced directly, although we may centralize here for clarity.

    View Source
    const (
    	// AnnotationImageName is an annotation on a Descriptor in an index.json
    	// containing the `Name` value as used by an `Image` struct
    	AnnotationImageName = "io.containerd.image.name"
    )

    Variables

    View Source
    var (
    	// ErrSkipDesc is used to skip processing of a descriptor and
    	// its descendants.
    	ErrSkipDesc = fmt.Errorf("skip descriptor")
    
    	// ErrStopHandler is used to signify that the descriptor
    	// has been handled and should not be handled further.
    	// This applies only to a single descriptor in a handler
    	// chain and does not apply to descendant descriptors.
    	ErrStopHandler = fmt.Errorf("stop handler")
    )

    Functions

    func Check

    func Check(ctx context.Context, provider content.Provider, image ocispec.Descriptor, platform platforms.MatchComparer) (available bool, required, present, missing []ocispec.Descriptor, err error)

      Check returns nil if the all components of an image are available in the provider for the specified platform.

      If available is true, the caller can assume that required represents the complete set of content required for the image.

      missing will have the components that are part of required but not available in the provider.

      If there is a problem resolving content, an error will be returned.

      func ChildGCLabels

      func ChildGCLabels(desc ocispec.Descriptor) []string

        ChildGCLabels returns the label for a given descriptor to reference it

        func ChildGCLabelsFilterLayers

        func ChildGCLabelsFilterLayers(desc ocispec.Descriptor) []string

          ChildGCLabelsFilterLayers returns the labels for a given descriptor to reference it, skipping layer media types

          func Children

          func Children(ctx context.Context, provider content.Provider, desc ocispec.Descriptor) ([]ocispec.Descriptor, error)

            Children returns the immediate children of content described by the descriptor.

            func Config

              Config resolves the image configuration descriptor using a content provided to resolve child resources on the image.

              The caller can then use the descriptor to resolve and process the configuration of the image.

              func DiffCompression

              func DiffCompression(ctx context.Context, mediaType string) (string, error)

                DiffCompression returns the compression as defined by the layer diff media type. For Docker media types without compression, "unknown" is returned to indicate that the media type may be compressed. If the media type is not recognized as a layer diff, then it returns errdefs.ErrNotImplemented

                func Dispatch

                func Dispatch(ctx context.Context, handler Handler, limiter *semaphore.Weighted, descs ...ocispec.Descriptor) error

                  Dispatch runs the provided handler for content specified by the descriptors. If the handler decode subresources, they will be visited, as well.

                  Handlers for siblings are run in parallel on the provided descriptors. A handler may return `ErrSkipDesc` to signal to the dispatcher to not traverse any children.

                  A concurrency limiter can be passed in to limit the number of concurrent handlers running. When limiter is nil, there is no limit.

                  Typically, this function will be used with `FetchHandler`, often composed with other handlers.

                  If any handler returns an error, the dispatch session will be canceled.

                  func GetDiffID

                  func GetDiffID(ctx context.Context, cs content.Store, desc ocispec.Descriptor) (digest.Digest, error)

                    GetDiffID gets the diff ID of the layer blob descriptor.

                    func IsConfigType

                    func IsConfigType(mt string) bool

                      IsConfigType returns true if the media type is an OCI-compatible image config. No support for containerd checkpoint configs.

                      func IsDockerType

                      func IsDockerType(mt string) bool

                        IsDockerType returns true if the media type has "application/vnd.docker." prefix

                        func IsIndexType

                        func IsIndexType(mt string) bool

                          IsIndexType returns true if the media type is an OCI-compatible index.

                          func IsKnownConfig

                          func IsKnownConfig(mt string) bool

                            IsKnownConfig returns true if the media type is a known config type, including containerd checkpoint configs

                            func IsLayerType

                            func IsLayerType(mt string) bool

                              IsLayerType returns true if the media type is a layer

                              func IsManifestType

                              func IsManifestType(mt string) bool

                                IsManifestType returns true if the media type is an OCI-compatible manifest. No support for schema1 manifest.

                                func IsNonDistributable

                                func IsNonDistributable(mt string) bool

                                  IsNonDistributable returns true if the media type is non-distributable.

                                  func Manifest

                                  func Manifest(ctx context.Context, provider content.Provider, image ocispec.Descriptor, platform platforms.MatchComparer) (ocispec.Manifest, error)

                                    Manifest resolves a manifest from the image for the given platform.

                                    When a manifest descriptor inside of a manifest index does not have a platform defined, the platform from the image config is considered.

                                    If the descriptor points to a non-index manifest, then the manifest is unmarshalled and returned without considering the platform inside of the config.

                                    TODO(stevvooe): This violates the current platform agnostic approach to this package by returning a specific manifest type. We'll need to refactor this to return a manifest descriptor or decide that we want to bring the API in this direction because this abstraction is not needed.`

                                    func Platforms

                                    func Platforms(ctx context.Context, provider content.Provider, image ocispec.Descriptor) ([]ocispec.Platform, error)

                                      Platforms returns one or more platforms supported by the image.

                                      func RootFS

                                      func RootFS(ctx context.Context, provider content.Provider, configDesc ocispec.Descriptor) ([]digest.Digest, error)

                                        RootFS returns the unpacked diffids that make up and images rootfs.

                                        These are used to verify that a set of layers unpacked to the expected values.

                                        func Walk

                                        func Walk(ctx context.Context, handler Handler, descs ...ocispec.Descriptor) error

                                          Walk the resources of an image and call the handler for each. If the handler decodes the sub-resources for each image,

                                          This differs from dispatch in that each sibling resource is considered synchronously.

                                          Types

                                          type DeleteOpt

                                          type DeleteOpt func(context.Context, *DeleteOptions) error

                                            DeleteOpt allows configuring a delete operation

                                            func SynchronousDelete

                                            func SynchronousDelete() DeleteOpt

                                              SynchronousDelete is used to indicate that an image deletion and removal of the image resources should occur synchronously before returning a result.

                                              type DeleteOptions

                                              type DeleteOptions struct {
                                              	Synchronous bool
                                              }

                                                DeleteOptions provide options on image delete

                                                type Exporter

                                                type Exporter interface {
                                                	// Export exports an image to a tar stream.
                                                	Export(ctx context.Context, store content.Provider, desc ocispec.Descriptor, writer io.Writer) error
                                                }

                                                  Exporter is the interface for image exporter.

                                                  type Handler

                                                  type Handler interface {
                                                  	Handle(ctx context.Context, desc ocispec.Descriptor) (subdescs []ocispec.Descriptor, err error)
                                                  }

                                                    Handler handles image manifests

                                                    type HandlerFunc

                                                    type HandlerFunc func(ctx context.Context, desc ocispec.Descriptor) (subdescs []ocispec.Descriptor, err error)

                                                      HandlerFunc function implementing the Handler interface

                                                      func ChildrenHandler

                                                      func ChildrenHandler(provider content.Provider) HandlerFunc

                                                        ChildrenHandler decodes well-known manifest types and returns their children.

                                                        This is useful for supporting recursive fetch and other use cases where you want to do a full walk of resources.

                                                        One can also replace this with another implementation to allow descending of arbitrary types.

                                                        func FilterPlatforms

                                                        func FilterPlatforms(f HandlerFunc, m platforms.Matcher) HandlerFunc

                                                          FilterPlatforms is a handler wrapper which limits the descriptors returned based on matching the specified platform matcher.

                                                          func Handlers

                                                          func Handlers(handlers ...Handler) HandlerFunc

                                                            Handlers returns a handler that will run the handlers in sequence.

                                                            A handler may return `ErrStopHandler` to stop calling additional handlers

                                                            func LimitManifests

                                                            func LimitManifests(f HandlerFunc, m platforms.MatchComparer, n int) HandlerFunc

                                                              LimitManifests is a handler wrapper which filters the manifest descriptors returned using the provided platform. The results will be ordered according to the comparison operator and use the ordering in the manifests for equal matches. A limit of 0 or less is considered no limit. A not found error is returned if no manifest is matched.

                                                              func SetChildrenLabels

                                                              func SetChildrenLabels(manager content.Manager, f HandlerFunc) HandlerFunc

                                                                SetChildrenLabels is a handler wrapper which sets labels for the content on the children returned by the handler and passes through the children. Must follow a handler that returns the children to be labeled.

                                                                func SetChildrenMappedLabels

                                                                func SetChildrenMappedLabels(manager content.Manager, f HandlerFunc, labelMap func(ocispec.Descriptor) []string) HandlerFunc

                                                                  SetChildrenMappedLabels is a handler wrapper which sets labels for the content on the children returned by the handler and passes through the children. Must follow a handler that returns the children to be labeled. The label map allows the caller to control the labels per child descriptor. For returned labels, the index of the child will be appended to the end except for the first index when the returned label does not end with '.'.

                                                                  func (HandlerFunc) Handle

                                                                  func (fn HandlerFunc) Handle(ctx context.Context, desc ocispec.Descriptor) (subdescs []ocispec.Descriptor, err error)

                                                                    Handle image manifests

                                                                    type Image

                                                                    type Image struct {
                                                                    	// Name of the image.
                                                                    	//
                                                                    	// To be pulled, it must be a reference compatible with resolvers.
                                                                    	//
                                                                    	// This field is required.
                                                                    	Name string
                                                                    
                                                                    	// Labels provide runtime decoration for the image record.
                                                                    	//
                                                                    	// There is no default behavior for how these labels are propagated. They
                                                                    	// only decorate the static metadata object.
                                                                    	//
                                                                    	// This field is optional.
                                                                    	Labels map[string]string
                                                                    
                                                                    	// Target describes the root content for this image. Typically, this is
                                                                    	// a manifest, index or manifest list.
                                                                    	Target ocispec.Descriptor
                                                                    
                                                                    	CreatedAt, UpdatedAt time.Time
                                                                    }

                                                                      Image provides the model for how containerd views container images.

                                                                      func (*Image) Config

                                                                      func (image *Image) Config(ctx context.Context, provider content.Provider, platform platforms.MatchComparer) (ocispec.Descriptor, error)

                                                                        Config resolves the image configuration descriptor.

                                                                        The caller can then use the descriptor to resolve and process the configuration of the image.

                                                                        func (*Image) RootFS

                                                                        func (image *Image) RootFS(ctx context.Context, provider content.Provider, platform platforms.MatchComparer) ([]digest.Digest, error)

                                                                          RootFS returns the unpacked diffids that make up and images rootfs.

                                                                          These are used to verify that a set of layers unpacked to the expected values.

                                                                          func (*Image) Size

                                                                          func (image *Image) Size(ctx context.Context, provider content.Provider, platform platforms.MatchComparer) (int64, error)

                                                                            Size returns the total size of an image's packed resources.

                                                                            type Importer

                                                                            type Importer interface {
                                                                            	// Import imports an image from a tar stream.
                                                                            	Import(ctx context.Context, store content.Store, reader io.Reader) (ocispec.Descriptor, error)
                                                                            }

                                                                              Importer is the interface for image importer.

                                                                              type Store

                                                                              type Store interface {
                                                                              	Get(ctx context.Context, name string) (Image, error)
                                                                              	List(ctx context.Context, filters ...string) ([]Image, error)
                                                                              	Create(ctx context.Context, image Image) (Image, error)
                                                                              
                                                                              	// Update will replace the data in the store with the provided image. If
                                                                              	// one or more fieldpaths are provided, only those fields will be updated.
                                                                              	Update(ctx context.Context, image Image, fieldpaths ...string) (Image, error)
                                                                              
                                                                              	Delete(ctx context.Context, name string, opts ...DeleteOpt) error
                                                                              }

                                                                                Store and interact with images

                                                                                Directories

                                                                                Path Synopsis
                                                                                Package archive provides a Docker and OCI compatible importer
                                                                                Package archive provides a Docker and OCI compatible importer
                                                                                Package converter provides image converter
                                                                                Package converter provides image converter