libimage

package
v0.59.2 Latest Latest
Warning

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

 Go to latest Published: Jun 28, 2024 License: Apache-2.0 Imports: 60 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 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
	// 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) 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 no 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.
	Annotations map[string]string
	// Add the specified architecture to the added image.
	Architecture string
	// Add the specified features to the added image.
	Features []string
	// Add the specified OS to the added image.
	OS string
	// Add the specified OS features to the added image.
	OSFeatures []string
	// Add the specified OS version to the added image.
	OSVersion string
	// Add the specified variant to the added image.
	Variant string
	// Add the specified annotations to the index itself.
	IndexAnnotations map[string]string
	// Set the subject to which the index refers.
	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, names []string, options *ListImagesOptions) ([]*Image, error)

ListImages lists images in the local container storage. If names are specified, only images with the specified names are looked up and filtered.

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.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.