manifests

Documentation

Index

• Variables
• func LockerForImage(store storage.Store, image string) (lockfile.Locker, error)
• type AddArtifactOptions
• type List
  • func Create() List
  • func LoadFromImage(store storage.Store, image string) (string, List, error)
• type LookupReferenceFunc
• type PushOptions

Variables

var ErrListImageUnknown = errors.New("unable to determine which image holds the manifest list")

ErrListImageUnknown is returned when we attempt to create an image reference for a List that has not yet been saved to an image.

Functions

func LockerForImage

func LockerForImage(store storage.Store, image string) (lockfile.Locker, error)

LockerForImage returns a Locker for a given image record. It's recommended that processes which use LoadFromImage() to load a list from an image and then use that list's SaveToImage() method to save a modified version of the list to that image record use this lock to avoid accidentally wiping out changes that another process is also attempting to make.

Types

type AddArtifactOptions

type AddArtifactOptions struct {
	ManifestArtifactType *string              // overall type of the artifact manifest. default: "application/vnd.unknown.artifact.v1"
	Platform             v1.Platform          // default: add to the index without platform information
	ConfigDescriptor     *v1.Descriptor       // default: a descriptor for an explicitly empty config blob
	ConfigFile           string               // path to config contents, recorded if ConfigDescriptor.Size != 0 and ConfigDescriptor.Data is not set
	LayerMediaType       *string              // default: mime.TypeByExtension() if basename contains ".", else http.DetectContentType()
	Annotations          map[string]string    // optional, default is none
	SubjectReference     types.ImageReference // optional
	ExcludeTitles        bool                 // don't add "org.opencontainers.image.title" annotations set to file base names
}

This should provide for all of the ways to construct a manifest outlined in https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidelines-for-artifact-usage

• no blobs ￫ set ManifestArtifactType
• blobs, no configuration ￫ set ManifestArtifactType and possibly LayerMediaType, and provide file names
• blobs and configuration ￫ set ManifestArtifactType, possibly LayerMediaType, and ConfigDescriptor, and provide file names

The older style of describing artifacts:

• leave ManifestArtifactType blank
• specify a zero-length application/vnd.oci.image.config.v1+json config blob
• set LayerMediaType to a custom type

When reading data produced elsewhere, note that newer tooling will produce manifests with ArtifactType set. If the manifest's ArtifactType is not set, consumers should consult the config descriptor's MediaType.

type List

type List interface {
	manifests.List
	SaveToImage(store storage.Store, imageID string, names []string, mimeType string) (string, error)
	Reference(store storage.Store, multiple cp.ImageListSelection, instances []digest.Digest) (types.ImageReference, error)
	Push(ctx context.Context, dest types.ImageReference, options PushOptions) (reference.Canonical, digest.Digest, error)
	Add(ctx context.Context, sys *types.SystemContext, ref types.ImageReference, all bool) (digest.Digest, error)
	AddArtifact(ctx context.Context, sys *types.SystemContext, options AddArtifactOptions, files ...string) (digest.Digest, error)
	InstanceByFile(file string) (digest.Digest, error)
	Files(instanceDigest digest.Digest) ([]string, error)
}

List is a manifest list or image index, either created using Create(), or loaded from local storage using LoadFromImage().

func Create

func Create() List

Create creates a new list containing information about the specified image, computing its manifest's digest, and retrieving OS and architecture information from its configuration blob. Returns the new list, and the instanceDigest for the initial image.

func LoadFromImage

func LoadFromImage(store storage.Store, image string) (string, List, error)

LoadFromImage reads the manifest list or image index, and additional information about where the various instances that it contains live, from an image record with the specified ID in local storage.

type LookupReferenceFunc

type LookupReferenceFunc func(ref types.ImageReference) (types.ImageReference, error)

LookupReferenceFunc return an image reference based on the specified one. The returned reference can return custom ImageSource or ImageDestination objects which intercept or filter blobs, manifests, and signatures as they are read and written.

type PushOptions

type PushOptions struct {
	Store                            storage.Store
	SystemContext                    *types.SystemContext  // github.com/containers/image/types.SystemContext
	ImageListSelection               cp.ImageListSelection // set to either CopySystemImage, CopyAllImages, or CopySpecificImages
	Instances                        []digest.Digest       // instances to copy if ImageListSelection == CopySpecificImages
	ReportWriter                     io.Writer             // will be used to log the writing of the list and any blobs
	Signers                          []*signer.Signer      // if non-empty, asks for signatures to be added during the copy using the provided signers.
	SignBy                           string                // fingerprint of GPG key to use to sign images
	SignPassphrase                   string                // passphrase to use when signing with the key ID from SignBy.
	SignBySigstorePrivateKeyFile     string                // if non-empty, asks for a signature to be added during the copy, using a sigstore private key file at the provided path.
	SignSigstorePrivateKeyPassphrase []byte                // passphrase to use when signing with SignBySigstorePrivateKeyFile.
	RemoveSignatures                 bool                  // true to discard signatures in images
	ManifestType                     string                // the format to use when saving the list - possible options are oci, v2s1, and v2s2
	SourceFilter                     LookupReferenceFunc   // filter the list source
	AddCompression                   []string              // add existing instances with requested compression algorithms to manifest list
	ForceCompressionFormat           bool                  // force push with requested compression ignoring the blobs which can be reused.
	// Maximum number of retries with exponential backoff when facing
	// transient network errors. Default 3.
	MaxRetries *uint
	// RetryDelay used for the exponential back off of MaxRetries.
	RetryDelay *time.Duration
}

PushOptions includes various settings which are needed for pushing the manifest list and its instances.