libimage

package
v0.61.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2024 License: Apache-2.0 Imports: 63 Imported by: 65

Documentation

Index

Constants

View Source
const (
	// Only debug log if an image does not match the expected platform.
	// Deprecated: new code should reference define.PlatformPolicyDefault directly.
	PlatformPolicyDefault = define.PlatformPolicyDefault
	// Warn if an image does not match the expected platform.
	// Deprecated: new code should reference define.PlatformPolicyWarn directly.
	PlatformPolicyWarn = define.PlatformPolicyWarn
)

Variables

View Source
var ErrNotAManifestList = errors.New("image is not a manifest list")

ErrNotAManifestList indicates that an image was found in the local containers storage but it is not a manifest list as requested.

Functions

func ErrorIsImageUnknown added in v0.54.0

func ErrorIsImageUnknown(err error) bool

ErrorIsImageUnknown returns true if the specified error indicates that an image is unknown or has been partially removed (e.g., a missing layer).

func NormalizeName

func NormalizeName(name string) (reference.Named, error)

NormalizeName normalizes the provided name according to the conventions by Podman and Buildah. If tag and digest are missing, the "latest" tag will be used. If it's a short name, it will be prefixed with "localhost/".

References to docker.io are normalized according to the Docker conventions. For instance, "docker.io/foo" turns into "docker.io/library/foo".

func NormalizePlatform added in v0.47.0

func NormalizePlatform(rawOS, rawArch, rawVariant string) (os, arch, variant string)

NormalizePlatform normalizes (according to the OCI spec) the specified os, arch and variant. If left empty, the individual item will be normalized. Deprecated: new code should call libimage/platform.Normalize() instead.

Types

type Copier added in v0.61.0

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

Copier is a helper to conveniently copy images.

func NewCopier added in v0.61.0

func NewCopier(options *CopyOptions, sc *types.SystemContext, reportResolvedReference *types.ImageReference) (*Copier, error)

NewCopier creates a Copier based on a provided system context. Note that fields in options *may* overwrite the counterparts of the specified system context. Please make sure to call `(*Copier).Close()`.

func (*Copier) Close added in v0.61.0

func (c *Copier) Close() error

Close open resources.

func (*Copier) Copy added in v0.61.0

func (c *Copier) Copy(ctx context.Context, source, destination types.ImageReference) ([]byte, error)

Copy the source to the destination. Returns the bytes of the copied manifest which may be used for digest computation.

type CopyOptions

type CopyOptions struct {
	// If set, will be used for copying the image.  Fields below may
	// override certain settings.
	SystemContext *types.SystemContext
	// Allows for customizing the source reference lookup.  This can be
	// used to use custom blob caches.
	SourceLookupReferenceFunc LookupReferenceFunc
	// Allows for customizing the destination reference lookup.  This can
	// be used to use custom blob caches.
	DestinationLookupReferenceFunc LookupReferenceFunc
	// CompressionFormat is the format to use for the compression of the blobs
	CompressionFormat *compression.Algorithm
	// CompressionLevel specifies what compression level is used
	CompressionLevel *int
	// ForceCompressionFormat ensures that the compression algorithm set in
	// CompressionFormat is used exclusively, and blobs of other compression
	// algorithms are not reused.
	ForceCompressionFormat bool

	// containers-auth.json(5) file to use when authenticating against
	// container registries.
	AuthFilePath string
	// Custom path to a blob-info cache.
	BlobInfoCacheDirPath string
	// Path to the certificates directory.
	CertDirPath string
	// Force layer compression when copying to a `dir` transport destination.
	DirForceCompress bool

	// ImageListSelection is one of CopySystemImage, CopyAllImages, or
	// CopySpecificImages, to control whether, when the source reference is a list,
	// copy.Image() copies only an image which matches the current runtime
	// environment, or all images which match the supplied reference, or only
	// specific images from the source reference.
	ImageListSelection copy.ImageListSelection
	// Allow contacting registries over HTTP, or HTTPS with failed TLS
	// verification. Note that this does not affect other TLS connections.
	InsecureSkipTLSVerify types.OptionalBool
	// Maximum number of retries with exponential backoff when facing
	// transient network errors.  A reasonable default is used if not set.
	// Default 3.
	MaxRetries *uint
	// RetryDelay used for the exponential back off of MaxRetries.
	// Default 1 time.Second.
	RetryDelay *time.Duration
	// ManifestMIMEType is the desired media type the image will be
	// converted to if needed.  Note that it must contain the exact MIME
	// types.  Short forms (e.g., oci, v2s2) used by some tools are not
	// supported.
	ManifestMIMEType string
	// Accept uncompressed layers when copying OCI images.
	OciAcceptUncompressedLayers bool
	// If OciEncryptConfig is non-nil, it indicates that an image should be
	// encrypted.  The encryption options is derived from the construction
	// of EncryptConfig object.  Note: During initial encryption process of
	// a layer, the resultant digest is not known during creation, so
	// newDigestingReader has to be set with validateDigest = false
	OciEncryptConfig *encconfig.EncryptConfig
	// OciEncryptLayers represents the list of layers to encrypt.  If nil,
	// don't encrypt any layers.  If non-nil and len==0, denotes encrypt
	// all layers.  integers in the slice represent 0-indexed layer
	// indices, with support for negative indexing. i.e. 0 is the first
	// layer, -1 is the last (top-most) layer.
	OciEncryptLayers *[]int
	// OciDecryptConfig contains the config that can be used to decrypt an
	// image if it is encrypted if non-nil. If nil, it does not attempt to
	// decrypt an image.
	OciDecryptConfig *encconfig.DecryptConfig
	// Reported to when ProgressInterval has arrived for a single
	// artifact+offset.
	Progress chan types.ProgressProperties
	// If set, allow using the storage transport even if it's disabled by
	// the specified SignaturePolicyPath.
	PolicyAllowStorage bool
	// SignaturePolicyPath to overwrite the default one.
	SignaturePolicyPath string
	// If non-empty, asks for signatures to be added during the copy
	// using the provided signers.
	Signers []*signer.Signer
	// If non-empty, asks for a signature to be added during the copy, and
	// specifies a key ID.
	SignBy string
	// If non-empty, passphrase to use when signing with the key ID from SignBy.
	SignPassphrase string
	// If non-empty, asks for a signature to be added during the copy, using
	// a sigstore private key file at the provided path.
	SignBySigstorePrivateKeyFile string
	// Passphrase to use when signing with SignBySigstorePrivateKeyFile.
	SignSigstorePrivateKeyPassphrase []byte
	// Remove any pre-existing signatures. SignBy will still add a new
	// signature.
	RemoveSignatures bool
	// Writer is used to display copy information including progress bars.
	Writer io.Writer

	// Architecture to use for choosing images.
	Architecture string
	// OS to use for choosing images.
	OS string
	// Variant to use when choosing images.
	Variant string

	// Username to use when authenticating at a container registry.
	Username string
	// Password to use when authenticating at a container registry.
	Password string
	// Credentials is an alternative way to specify credentials in format
	// "username[:password]".  Cannot be used in combination with
	// Username/Password.
	Credentials string
	// IdentityToken is used to authenticate the user and get
	// an access token for the registry.
	IdentityToken string `json:"identitytoken,omitempty"`
	// contains filtered or unexported fields
}

CopyOptions allow for customizing image-copy operations.

type DriverData added in v0.38.0

type DriverData struct {
	Name string            `json:"Name"`
	Data map[string]string `json:"Data"`
}

DriverData includes data on the storage driver of the image.

type Event

type Event struct {
	// ID of the object (e.g., image ID).
	ID string
	// Name of the object (e.g., image name "quay.io/containers/podman:latest")
	Name string
	// Time of the event.
	Time time.Time
	// Type of the event.
	Type EventType
	// Error in case of failure.
	Error error
}

Event represents an event such an image pull or image tag.

type EventType

type EventType int

EventType indicates the type of an event. Currently, there is only one supported type for container image but we may add more (e.g., for manifest lists) in the future.

const (
	// EventTypeUnknown is an uninitialized EventType.
	EventTypeUnknown EventType = iota
	// EventTypeImagePull represents an image pull.
	EventTypeImagePull
	// EventTypeImagePullError represents an image pull failed.
	EventTypeImagePullError
	// EventTypeImagePush represents an image push.
	EventTypeImagePush
	// EventTypeImageRemove represents an image removal.
	EventTypeImageRemove
	// EventTypeImageLoad represents an image being loaded.
	EventTypeImageLoad
	// EventTypeImageSave represents an image being saved.
	EventTypeImageSave
	// EventTypeImageTag represents an image being tagged.
	EventTypeImageTag
	// EventTypeImageUntag represents an image being untagged.
	EventTypeImageUntag
	// EventTypeImageMount represents an image being mounted.
	EventTypeImageMount
	// EventTypeImageUnmount represents an image being unmounted.
	EventTypeImageUnmount
)

type HasDifferentDigestOptions added in v0.42.3

type HasDifferentDigestOptions struct {
	// containers-auth.json(5) file to use when authenticating against
	// container registries.
	AuthFilePath string
	// Allow contacting registries over HTTP, or HTTPS with failed TLS
	// verification. Note that this does not affect other TLS connections.
	InsecureSkipTLSVerify types.OptionalBool
}

HasDifferentDigestOptions allows for customizing the check if another (remote) image has a different digest.

type Image

type Image struct {
	// ListData that is being set by (*Runtime).ListImages().  Note that
	// the data may be outdated.
	ListData struct {
		// Dangling indicates if the image is dangling.  Use
		// `IsDangling()` to compute the latest state.
		IsDangling *bool
		// Parent points to the parent image.  Use `Parent()` to
		// compute the latest state.
		Parent *Image
	}
	// contains filtered or unexported fields
}

Image represents an image in the containers storage and allows for further operations and data manipulation.

func (*Image) Children

func (i *Image) Children(ctx context.Context) ([]*Image, error)

Children returns the image's children.

func (*Image) Containers

func (i *Image) Containers() ([]string, error)

Containers returns a list of containers using the image.

func (*Image) ConvertToManifestList added in v0.61.0

func (i *Image) ConvertToManifestList(ctx context.Context) (*ManifestList, error)

ConvertToManifestList converts the image into a manifest list if it is not already also a list. An error is returned if the conversion fails.

func (*Image) Created

func (i *Image) Created() time.Time

Created returns the time the image was created.

func (*Image) Digest

func (i *Image) Digest() digest.Digest

Digest is a digest value that we can use to locate the image, if one was specified at creation-time. Typically it is the digest of one among possibly many digests that we have stored for the image, so many applications are better off using the entire list returned by Digests().

func (*Image) Digests

func (i *Image) Digests() []digest.Digest

Digests is a list of digest values of the image's manifests, and possibly a manually-specified value, that we can use to locate the image. If Digest is set, its value is also in this list.

func (*Image) HasChildren

func (i *Image) HasChildren(ctx context.Context) (bool, error)

HasChildren returns indicates if the image has children.

func (*Image) HasDifferentDigest

func (i *Image) HasDifferentDigest(ctx context.Context, remoteRef types.ImageReference, options *HasDifferentDigestOptions) (bool, error)

HasDifferentDigest returns true if the image specified by `remoteRef` has a different digest than the local one. This check can be useful to check for updates on remote registries.

func (*Image) History

func (i *Image) History(ctx context.Context) ([]ImageHistory, error)

History computes the image history of the image including all of its parents.

func (*Image) ID

func (i *Image) ID() string

ID returns the ID of the image.

func (*Image) Inspect

func (i *Image) Inspect(ctx context.Context, options *InspectOptions) (*ImageData, error)

Inspect inspects the image.

func (*Image) IsDangling

func (i *Image) IsDangling(ctx context.Context) (bool, error)

IsDangling returns true if the image is dangling, that is an untagged image without children.

func (*Image) IsIntermediate

func (i *Image) IsIntermediate(ctx context.Context) (bool, error)

IsIntermediate returns true if the image is an intermediate image, that is an untagged image with children.

func (*Image) IsManifestList added in v0.38.0

func (i *Image) IsManifestList(ctx context.Context) (bool, error)

IsManifestList returns true if the image is a manifest list (Docker) or an image index (OCI). This information may be critical to make certain execution paths more robust (e.g., suppress certain errors).

func (*Image) IsReadOnly

func (i *Image) IsReadOnly() bool

IsReadOnly returns whether the image is set read only.

func (*Image) Labels

func (i *Image) Labels(ctx context.Context) (map[string]string, error)

Labels returns the label of the image.

func (*Image) Manifest added in v0.38.0

func (i *Image) Manifest(ctx context.Context) (rawManifest []byte, mimeType string, err error)

Manifest returns the raw data and the MIME type of the image's manifest.

func (*Image) Mount

func (i *Image) Mount(_ context.Context, mountOptions []string, mountLabel string) (string, error)

Mount the image with the specified mount options and label, both of which are directly passed down to the containers storage. Returns the fully evaluated path to the mount point.

func (*Image) Mountpoint added in v0.38.0

func (i *Image) Mountpoint() (string, error)

Mountpoint returns the path to image's mount point. The path is empty if the image is not mounted.

func (*Image) NamedRepoTags added in v0.38.0

func (i *Image) NamedRepoTags() ([]reference.Named, error)

NamedRepoTags returns the repotags associated with the image as a slice of reference.Named.

func (*Image) NamedTaggedRepoTags

func (i *Image) NamedTaggedRepoTags() ([]reference.NamedTagged, error)

NamedTaggedRepoTags returns the repotags associated with the image as a slice of reference.NamedTagged.

func (*Image) Names

func (i *Image) Names() []string

Names returns associated names with the image which may be a mix of tags and digests.

func (*Image) NamesHistory

func (i *Image) NamesHistory() []string

NamesHistory returns a string array of names previously associated with the image, which may be a mixture of tags and digests.

func (*Image) NamesReferences added in v0.47.0

func (i *Image) NamesReferences() ([]reference.Reference, error)

NamesReferences returns Names() as references.

func (*Image) Parent

func (i *Image) Parent(ctx context.Context) (*Image, error)

Parent returns the parent image or nil if there is none

func (*Image) RepoDigests

func (i *Image) RepoDigests() ([]string, error)

RepoDigests returns a string array of repodigests associated with the image.

func (*Image) RepoTags

func (i *Image) RepoTags() ([]string, error)

RepoTags returns a string slice of repotags associated with the image.

func (*Image) Size

func (i *Image) Size() (int64, error)

Size computes the size of the image layers and associated data.

func (*Image) StorageImage

func (i *Image) StorageImage() *storage.Image

StorageImage returns the underlying storage.Image.

func (*Image) StorageReference

func (i *Image) StorageReference() (types.ImageReference, error)

StorageReference returns the image's reference to the containers storage using the image ID.

func (*Image) Tag

func (i *Image) Tag(name string) error

Tag the image with the specified name and store it in the local containers storage. The name is normalized according to the rules of NormalizeName.

func (*Image) ToManifestList added in v0.38.0

func (i *Image) ToManifestList() (*ManifestList, error)

ToManifestList converts the image into a manifest list. An error is thrown if the image is not a manifest list.

func (*Image) TopLayer

func (i *Image) TopLayer() string

TopLayer returns the top layer id as a string

func (*Image) Tree

func (i *Image) Tree(traverseChildren bool) (string, error)

Tree generates a tree for the specified image and its layers. Use `traverseChildren` to traverse the layers of all children. By default, only layers of the image are printed.

func (*Image) Unmount

func (i *Image) Unmount(force bool) error

Unmount the image. Use force to ignore the reference counter and forcefully unmount.

func (*Image) Untag

func (i *Image) Untag(name string) error

Untag the image with the specified name and make the change persistent in the local containers storage. The name is normalized according to the rules of NormalizeName.

type ImageConfig

type ImageConfig struct {
	ociv1.ImageConfig
	OnBuild []string
}

ImageConfig is a wrapper around the OCIv1 Image Configuration struct exported by containers/image, but containing additional fields that are not supported by OCIv1 (but are by Docker v2) - notably OnBuild.

func ImageConfigFromChanges

func ImageConfigFromChanges(changes []string) (*ImageConfig, error)

ImageConfigFromChanges produces a v1.ImageConfig from the --change flag that is accepted by several Podman commands. It accepts a (limited subset) of Dockerfile instructions. Valid changes are: * USER * EXPOSE * ENV * ENTRYPOINT * CMD * VOLUME * WORKDIR * LABEL * STOPSIGNAL * ONBUILD

type ImageData added in v0.38.0

type ImageData struct {
	ID           string                        `json:"Id"`
	Digest       digest.Digest                 `json:"Digest"`
	RepoTags     []string                      `json:"RepoTags"`
	RepoDigests  []string                      `json:"RepoDigests"`
	Parent       string                        `json:"Parent"`
	Comment      string                        `json:"Comment"`
	Created      *time.Time                    `json:"Created"`
	Config       *ociv1.ImageConfig            `json:"Config"`
	Version      string                        `json:"Version"`
	Author       string                        `json:"Author"`
	Architecture string                        `json:"Architecture"`
	Os           string                        `json:"Os"`
	Size         int64                         `json:"Size"`
	VirtualSize  int64                         `json:"VirtualSize"`
	GraphDriver  *DriverData                   `json:"GraphDriver"`
	RootFS       *RootFS                       `json:"RootFS"`
	Labels       map[string]string             `json:"Labels"`
	Annotations  map[string]string             `json:"Annotations"`
	ManifestType string                        `json:"ManifestType"`
	User         string                        `json:"User"`
	History      []ociv1.History               `json:"History"`
	NamesHistory []string                      `json:"NamesHistory"`
	HealthCheck  *manifest.Schema2HealthConfig `json:"Healthcheck,omitempty"`
}

ImageData contains the inspected data of an image.

type ImageDiskUsage added in v0.38.0

type ImageDiskUsage struct {
	// Number of containers using the image.
	Containers int
	// ID of the image.
	ID string
	// Repository of the image.
	Repository string
	// Tag of the image.
	Tag string
	// Created time stamp.
	Created time.Time
	// The amount of space that an image shares with another one (i.e. their common data).
	SharedSize int64
	// The the amount of space that is only used by a given image.
	UniqueSize int64
	// Sum of shared an unique size.
	Size int64
}

ImageDiskUsage reports the total size of an image. That is the size

type ImageHistory added in v0.38.0

type ImageHistory struct {
	ID        string     `json:"id"`
	Created   *time.Time `json:"created"`
	CreatedBy string     `json:"createdBy"`
	Size      int64      `json:"size"`
	Comment   string     `json:"comment"`
	Tags      []string   `json:"tags"`
}

ImageHistory contains the history information of an image.

type ImportOptions

type ImportOptions struct {
	CopyOptions

	// Apply the specified changes to the created image. Please refer to
	// `ImageConfigFromChanges` for supported change instructions.
	Changes []string
	// Set the commit message as a comment to created image's history.
	CommitMessage string
	// Tag the imported image with this value.
	Tag string
	// Overwrite OS of imported image.
	OS string
	// Overwrite Arch of imported image.
	Arch string
}

ImportOptions allow for customizing image imports.

type InspectOptions added in v0.47.0

type InspectOptions struct {
	// Compute the size of the image (expensive).
	WithSize bool
	// Compute the parent of the image (expensive).
	WithParent bool
}

InspectOptions allow for customizing inspecting images.

type IsExternalContainerFunc added in v0.47.0

type IsExternalContainerFunc func(containerID string) (bool, error)

IsExternalContainerFunc allows for checking whether the specified container is an external one. The definition of an external container can be set by callers.

type ListImagesOptions

type ListImagesOptions struct {
	// Filters to filter the listed images.  Supported filters are
	// * after,before,since=image
	// * containers=true,false,external
	// * dangling=true,false
	// * intermediate=true,false (useful for pruning images)
	// * id=id
	// * label=key[=value]
	// * readonly=true,false
	// * reference=name[:tag] (wildcards allowed)
	Filters []string
	// IsExternalContainerFunc allows for checking whether the specified
	// container is an external one (when containers=external filter is
	// used).  The definition of an external container can be set by
	// callers.
	IsExternalContainerFunc IsExternalContainerFunc
	// SetListData will populate the Image.ListData fields of returned images.
	SetListData bool
}

ListImagesOptions allow for customizing listing images.

type LoadOptions

type LoadOptions struct {
	CopyOptions
}

type LookupImageOptions

type LookupImageOptions struct {
	// Lookup an image matching the specified architecture.
	Architecture string
	// Lookup an image matching the specified OS.
	OS string
	// Lookup an image matching the specified variant.
	Variant string

	// Controls the behavior when checking the platform of an image.
	PlatformPolicy define.PlatformPolicy

	// If matching images resolves to a manifest list, return manifest list
	// instead of resolving to image instance, if manifest list is not found
	// try resolving image.
	ManifestList bool
	// contains filtered or unexported fields
}

LookupImageOptions allow for customizing local image lookups.

type LookupReferenceFunc

type LookupReferenceFunc = manifests.LookupReferenceFunc

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 ManifestList added in v0.38.0

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

ManifestList represents a manifest list (Docker) or an image index (OCI) in the local containers storage.

func (*ManifestList) Add added in v0.38.0

func (m *ManifestList) Add(ctx context.Context, name string, options *ManifestListAddOptions) (digest.Digest, error)

Add adds one or more manifests to the manifest list and returns the digest of the added instance.

func (*ManifestList) AddArtifact added in v0.58.0

func (m *ManifestList) AddArtifact(ctx context.Context, options *ManifestListAddArtifactOptions, files ...string) (digest.Digest, error)

Add adds one or more manifests to the manifest list and returns the digest of the added instance.

func (*ManifestList) AnnotateInstance added in v0.38.0

func (m *ManifestList) AnnotateInstance(d digest.Digest, options *ManifestListAnnotateOptions) error

Annotate an image instance specified by `d` in the manifest list.

func (*ManifestList) ID added in v0.38.0

func (m *ManifestList) ID() string

ID returns the ID of the manifest list.

func (*ManifestList) Inspect added in v0.38.0

func (m *ManifestList) Inspect() (*define.ManifestListData, error)

Inspect returns a dockerized version of the manifest list.

func (*ManifestList) LookupInstance added in v0.38.0

func (m *ManifestList) LookupInstance(ctx context.Context, architecture, os, variant string) (*Image, error)

LookupInstance looks up an instance of the manifest list matching the specified platform. The local machine's platform is used if left empty.

func (*ManifestList) Push added in v0.38.0

func (m *ManifestList) Push(ctx context.Context, destination string, options *ManifestListPushOptions) (digest.Digest, error)

Push pushes a manifest to the specified destination.

func (*ManifestList) RemoveInstance added in v0.38.0

func (m *ManifestList) RemoveInstance(d digest.Digest) error

RemoveInstance removes the instance specified by `d` from the manifest list. Returns the new ID of the image.

type ManifestListAddArtifactOptions added in v0.58.0

type ManifestListAddArtifactOptions struct {
	// The artifactType to set in the artifact manifest.
	Type *string `json:"artifact_type"`
	// The mediaType to set in the config.MediaType field in the artifact manifest.
	ConfigType string `json:"artifact_config_type"`
	// Content to point to from the config field in the artifact manifest.
	Config string `json:"artifact_config"`
	// The mediaType to set in the layer descriptors in the artifact manifest.
	LayerType string `json:"artifact_layer_type"`
	// Whether or not to suppress the org.opencontainers.image.title annotation in layer descriptors.
	ExcludeTitles bool `json:"exclude_layer_titles"`
	// Annotations to set in the artifact manifest.
	Annotations map[string]string `json:"annotations"`
	// Subject to set in the artifact manifest.
	Subject string `json:"subject"`
}

Options for creating an artifact manifest for one or more files and adding the artifact manifest to a manifest list.

type ManifestListAddOptions added in v0.38.0

type ManifestListAddOptions struct {
	// Add all images to the list if the to-be-added image itself is a
	// manifest list.
	All bool `json:"all"`
	// containers-auth.json(5) file to use when authenticating against
	// container registries.
	AuthFilePath string
	// Path to the certificates directory.
	CertDirPath string
	// Allow contacting registries over HTTP, or HTTPS with failed TLS
	// verification. Note that this does not affect other TLS connections.
	InsecureSkipTLSVerify types.OptionalBool
	// Username to use when authenticating at a container registry.
	Username string
	// Password to use when authenticating at a container registry.
	Password string
}

Options for adding an image or artifact to a manifest list.

type ManifestListAnnotateOptions added in v0.38.0

type ManifestListAnnotateOptions struct {
	// Add the specified annotations to the added image.  Empty values are ignored.
	Annotations map[string]string
	// Add the specified architecture to the added image.  Empty values are ignored.
	Architecture string
	// Add the specified features to the added image.  Empty values are ignored.
	Features []string
	// Add the specified OS to the added image.  Empty values are ignored.
	OS string
	// Add the specified OS features to the added image.  Empty values are ignored.
	OSFeatures []string
	// Add the specified OS version to the added image.  Empty values are ignored.
	OSVersion string
	// Add the specified variant to the added image.  Empty values are ignored unless Architecture is set to a non-empty value.
	Variant string
	// Add the specified annotations to the index itself.  Empty values are ignored.
	IndexAnnotations map[string]string
	// Set the subject to which the index refers.  Empty values are ignored.
	Subject string
}

Options for annotating a manifest list.

type ManifestListPushOptions added in v0.38.0

type ManifestListPushOptions struct {
	CopyOptions

	// For tweaking the list selection.
	ImageListSelection imageCopy.ImageListSelection
	// Use when selecting only specific imags.
	Instances []digest.Digest
	// Add existing instances with requested compression algorithms to manifest list
	AddCompression []string
}

ManifestListPushOptions allow for customizing pushing a manifest list.

type NameTagPair

type NameTagPair struct {
	// Name of the RepoTag. Maybe "<none>".
	Name string
	// Tag of the RepoTag. Maybe "<none>".
	Tag string
	// contains filtered or unexported fields
}

NameTagPair represents a RepoTag of an image.

func ToNameTagPairs

func ToNameTagPairs(repoTags []reference.Named) ([]NameTagPair, error)

ToNameTagsPairs splits repoTags into name&tag pairs. Guaranteed to return at least one pair.

type PlatformPolicy added in v0.49.0

type PlatformPolicy = define.PlatformPolicy

PlatformPolicy controls the behavior of image-platform matching. Deprecated: new code should use define.PlatformPolicy directly.

type PullOptions

type PullOptions struct {
	CopyOptions

	// If true, all tags of the image will be pulled from the container
	// registry.  Only supported for the docker transport.
	AllTags bool
}

PullOptions allows for customizing image pulls.

type PushOptions

type PushOptions struct {
	CopyOptions
}

PushOptions allows for customizing image pushes.

type RemoveContainerFunc

type RemoveContainerFunc func(imageID string) error

RemoveContainerFunc allows for customizing the removal of containers using an image specified by imageID.

type RemoveImageReport added in v0.38.0

type RemoveImageReport struct {
	// ID of the image.
	ID string
	// Image was removed.
	Removed bool
	// Size of the removed image.  Only set when explicitly requested in
	// RemoveImagesOptions.
	Size int64
	// The untagged tags.
	Untagged []string
}

RemoveImagesReport is the assembled data from removing *one* image.

type RemoveImagesOptions

type RemoveImagesOptions struct {
	// Force will remove all containers from the local storage that are
	// using a removed image.  Use RemoveContainerFunc for a custom logic.
	// If set, all child images will be removed as well.
	Force bool
	// LookupManifest will expect all specified names to be manifest lists (no instance look up).
	// This allows for removing manifest lists.
	// By default, RemoveImages will attempt to resolve to a manifest instance matching
	// the local platform (i.e., os, architecture, variant).
	LookupManifest bool
	// RemoveContainerFunc allows for a custom logic for removing
	// containers using a specific image.  By default, all containers in
	// the local containers storage will be removed (if Force is set).
	RemoveContainerFunc RemoveContainerFunc
	// Ignore if a specified image does not exist and do not throw an error.
	Ignore bool
	// IsExternalContainerFunc allows for checking whether the specified
	// container is an external one (when containers=external filter is
	// used).  The definition of an external container can be set by
	// callers.
	IsExternalContainerFunc IsExternalContainerFunc
	// Remove external containers even when Force is false.  Requires
	// IsExternalContainerFunc to be specified.
	ExternalContainers bool
	// Filters to filter the removed images.  Supported filters are
	// * after,before,since=image
	// * containers=true,false,external
	// * dangling=true,false
	// * intermediate=true,false (useful for pruning images)
	// * id=id
	// * label=key[=value]
	// * readonly=true,false
	// * reference=name[:tag] (wildcards allowed)
	Filters []string
	// The RemoveImagesReport will include the size of the removed image.
	// This information may be useful when pruning images to figure out how
	// much space was freed. However, computing the size of an image is
	// comparatively expensive, so it is made optional.
	WithSize bool
	// NoPrune will not remove dangling images
	NoPrune bool
}

RemoveImagesOptions allow for customizing image removal.

type RootFS added in v0.38.0

type RootFS struct {
	Type   string          `json:"Type"`
	Layers []digest.Digest `json:"Layers"`
}

RootFS includes data on the root filesystem of the image.

type Runtime

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

Runtime is responsible for image management and storing them in a containers storage.

func RuntimeFromStore

func RuntimeFromStore(store storage.Store, options *RuntimeOptions) (*Runtime, error)

RuntimeFromStore returns a Runtime for the specified store.

func RuntimeFromStoreOptions

func RuntimeFromStoreOptions(runtimeOptions *RuntimeOptions, storeOptions *storage.StoreOptions) (*Runtime, error)

RuntimeFromStoreOptions returns a return for the specified store options.

func (*Runtime) CreateManifestList added in v0.38.0

func (r *Runtime) CreateManifestList(name string) (*ManifestList, error)

CreateManifestList creates a new empty manifest list with the specified name.

func (*Runtime) DiskUsage added in v0.38.0

func (r *Runtime) DiskUsage(ctx context.Context) ([]ImageDiskUsage, int64, error)

DiskUsage calculates the disk usage for each image in the local containers storage. Note that a single image may yield multiple usage reports, one for each repository tag.

func (*Runtime) EventChannel added in v0.38.0

func (r *Runtime) EventChannel() chan *Event

EventChannel creates a buffered channel for events that the Runtime will use to write events to. Callers are expected to read from the channel in a timely manner. Can be called once for a given Runtime.

func (*Runtime) Exists

func (r *Runtime) Exists(name string) (bool, error)

Exists returns true if the specified image exists in the local containers storage. Note that it may return false if an image corrupted.

func (*Runtime) Import

func (r *Runtime) Import(ctx context.Context, path string, options *ImportOptions) (string, error)

Import imports a custom tarball at the specified path. Returns the name of the imported image.

func (*Runtime) ListImages

func (r *Runtime) ListImages(ctx context.Context, options *ListImagesOptions) ([]*Image, error)

ListImages lists the images in the local container storage and filter the images by ListImagesOptions

func (*Runtime) ListImagesByNames added in v0.61.0

func (r *Runtime) ListImagesByNames(names []string) ([]*Image, error)

ListImagesByNames lists the images in the local container storage by specified names The name lookups use the LookupImage semantics.

func (*Runtime) Load

func (r *Runtime) Load(ctx context.Context, path string, options *LoadOptions) ([]string, error)

Load loads one or more images (depending on the transport) from the specified path. The path may point to an image the following transports: oci, oci-archive, dir, docker-archive.

func (*Runtime) LoadReference added in v0.59.0

func (r *Runtime) LoadReference(ctx context.Context, ref types.ImageReference, options *LoadOptions) ([]string, error)

LoadReference loads one or more images from the specified location.

func (*Runtime) LookupImage

func (r *Runtime) LookupImage(name string, options *LookupImageOptions) (*Image, string, error)

Lookup Image looks up `name` in the local container storage. Returns the image and the name it has been found with. Note that name may also use the `containers-storage:` prefix used to refer to the containers-storage transport. Returns storage.ErrImageUnknown if the image could not be found.

Unless specified via the options, the image will be looked up by name only without matching the architecture, os or variant. An exception is if the image resolves to a manifest list, where an instance of the manifest list matching the local or specified platform (via options.{Architecture,OS,Variant}) is returned.

If the specified name uses the `containers-storage` transport, the resolved name is empty.

func (*Runtime) LookupManifestList added in v0.38.0

func (r *Runtime) LookupManifestList(name string) (*ManifestList, error)

LookupManifestList looks up a manifest list with the specified name in the containers storage.

func (*Runtime) Pull

func (r *Runtime) Pull(ctx context.Context, name string, pullPolicy config.PullPolicy, options *PullOptions) (_ []*Image, pullError error)

Pull pulls the specified name. Name may refer to any of the supported transports from github.com/containers/image. If no transport is encoded, name will be treated as a reference to a registry (i.e., docker transport).

Note that pullPolicy is only used when pulling from a container registry but it *must* be different than the default value `config.PullPolicyUnsupported`. This way, callers are forced to decide on the pull behaviour. The reasoning behind is that some (commands of some) tools have different default pull policies (e.g., buildah-bud versus podman-build). Making the pull-policy choice explicit is an attempt to prevent silent regressions.

The error is storage.ErrImageUnknown iff the pull policy is set to "never" and no local image has been found. This allows for an easier integration into some users of this package (e.g., Buildah).

func (*Runtime) Push

func (r *Runtime) Push(ctx context.Context, source, destination string, options *PushOptions) ([]byte, error)

Push pushes the specified source which must refer to an image in the local containers storage. It may or may not have the `containers-storage:` prefix. Use destination to push to a custom destination. The destination can refer to any supported transport. If not transport is specified, the docker transport (i.e., a registry) is implied. If destination is left empty, the docker destination will be extrapolated from the source.

Return storage.ErrImageUnknown if source could not be found in the local containers storage.

func (*Runtime) RemoveImages

func (r *Runtime) RemoveImages(ctx context.Context, names []string, options *RemoveImagesOptions) (reports []*RemoveImageReport, rmErrors []error)

RemoveImages removes images specified by names. If no names are specified, remove images as specified via the options' filters. All images are expected to exist in the local containers storage.

If an image has more names than one name, the image will be untagged with the specified name. RemoveImages returns a slice of untagged and removed images.

Note that most errors are non-fatal and collected into `rmErrors` return value.

func (*Runtime) ResolveName added in v0.38.0

func (r *Runtime) ResolveName(name string) (string, error)

ResolveName resolves the specified name. If the name resolves to a local image, the fully resolved name will be returned. Otherwise, the name will be properly normalized.

Note that an empty string is returned as is.

func (*Runtime) Save

func (r *Runtime) Save(ctx context.Context, names []string, format, path string, options *SaveOptions) error

Save saves one or more images indicated by `names` in the specified `format` to `path`. Supported formats are oci-archive, docker-archive, oci-dir and docker-dir. The latter two adhere to the dir transport in the corresponding oci or docker v2s2 format. Please note that only docker-archive supports saving more than one images. Other formats will yield an error attempting to save more than one.

func (*Runtime) Search

func (r *Runtime) Search(ctx context.Context, term string, options *SearchOptions) ([]SearchResult, error)

Search searches term. If term includes a registry, only this registry will be used for searching. Otherwise, the unqualified-search registries in containers-registries.conf(5) or the ones specified in the options will be used.

func (*Runtime) Shutdown

func (r *Runtime) Shutdown(force bool) error

Shutdown attempts to free any kernel resources which are being used by the underlying driver. If "force" is true, any mounted (i.e., in use) layers are unmounted beforehand. If "force" is not true, then layers being in use is considered to be an error condition.

func (*Runtime) SystemContext added in v0.41.0

func (r *Runtime) SystemContext() *types.SystemContext

Returns a copy of the runtime's system context.

type RuntimeOptions

type RuntimeOptions struct {
	// The base system context of the runtime which will be used throughout
	// the entire lifespan of the Runtime.  Certain options in some
	// functions may override specific fields.
	SystemContext *types.SystemContext
}

RuntimeOptions allow for creating a customized Runtime.

type SaveOptions

type SaveOptions struct {
	CopyOptions

	// AdditionalTags for the saved image.  Incompatible when saving
	// multiple images.
	AdditionalTags []string
}

SaveOptions allow for customizing saving images.

type SearchOptions

type SearchOptions struct {
	// Filter allows to filter the results.
	Filter filter.SearchFilter
	// Limit limits the number of queries per index (default: 25). Must be
	// greater than 0 to overwrite the default value.
	Limit int
	// NoTrunc avoids the output to be truncated.
	NoTrunc bool
	// Authfile is the path to the authentication file.
	Authfile string
	// Path to the certificates directory.
	CertDirPath string
	// Username to use when authenticating at a container registry.
	Username string
	// Password to use when authenticating at a container registry.
	Password string
	// Credentials is an alternative way to specify credentials in format
	// "username[:password]".  Cannot be used in combination with
	// Username/Password.
	Credentials string
	// IdentityToken is used to authenticate the user and get
	// an access token for the registry.
	IdentityToken string `json:"identitytoken,omitempty"`
	// InsecureSkipTLSVerify allows to skip TLS verification.
	InsecureSkipTLSVerify types.OptionalBool
	// ListTags returns the search result with available tags
	ListTags bool
	// Registries to search if the specified term does not include a
	// registry.  If set, the unqualified-search registries in
	// containers-registries.conf(5) are ignored.
	Registries []string
}

SearchOptions customize searching images.

type SearchResult

type SearchResult struct {
	// Index is the image index (e.g., "docker.io" or "quay.io")
	Index string
	// Name is the canonical name of the image (e.g., "docker.io/library/alpine").
	Name string
	// Description of the image.
	Description string
	// Stars is the number of stars of the image.
	Stars int
	// Official indicates if it's an official image.
	Official string
	// Automated indicates if the image was created by an automated build.
	Automated string
	// Tag is the image tag
	Tag string
}

SearchResult is holding image-search related data.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL