Documentation ¶
Index ¶
- Constants
- Variables
- func ErrorIsImageUnknown(err error) bool
- func NormalizeName(name string) (reference.Named, error)
- func NormalizePlatform(rawOS, rawArch, rawVariant string) (os, arch, variant string)
- type Copier
- type CopyOptions
- type DriverData
- type Event
- type EventType
- type HasDifferentDigestOptions
- type Image
- func (i *Image) Children(ctx context.Context) ([]*Image, error)
- func (i *Image) Containers() ([]string, error)
- func (i *Image) ConvertToManifestList(ctx context.Context) (*ManifestList, error)
- func (i *Image) Created() time.Time
- func (i *Image) Digest() digest.Digest
- func (i *Image) Digests() []digest.Digest
- func (i *Image) HasChildren(ctx context.Context) (bool, error)
- func (i *Image) HasDifferentDigest(ctx context.Context, remoteRef types.ImageReference, ...) (bool, error)
- func (i *Image) History(ctx context.Context) ([]ImageHistory, error)
- func (i *Image) ID() string
- func (i *Image) Inspect(ctx context.Context, options *InspectOptions) (*ImageData, error)
- func (i *Image) IsDangling(ctx context.Context) (bool, error)
- func (i *Image) IsIntermediate(ctx context.Context) (bool, error)
- func (i *Image) IsManifestList(ctx context.Context) (bool, error)
- func (i *Image) IsReadOnly() bool
- func (i *Image) Labels(ctx context.Context) (map[string]string, error)
- func (i *Image) Manifest(ctx context.Context) (rawManifest []byte, mimeType string, err error)
- func (i *Image) Mount(_ context.Context, mountOptions []string, mountLabel string) (string, error)
- func (i *Image) Mountpoint() (string, error)
- func (i *Image) NamedRepoTags() ([]reference.Named, error)
- func (i *Image) NamedTaggedRepoTags() ([]reference.NamedTagged, error)
- func (i *Image) Names() []string
- func (i *Image) NamesHistory() []string
- func (i *Image) NamesReferences() ([]reference.Reference, error)
- func (i *Image) Parent(ctx context.Context) (*Image, error)
- func (i *Image) RepoDigests() ([]string, error)
- func (i *Image) RepoTags() ([]string, error)
- func (i *Image) Size() (int64, error)
- func (i *Image) StorageImage() *storage.Image
- func (i *Image) StorageReference() (types.ImageReference, error)
- func (i *Image) Tag(name string) error
- func (i *Image) ToManifestList() (*ManifestList, error)
- func (i *Image) TopLayer() string
- func (i *Image) Tree(traverseChildren bool) (string, error)
- func (i *Image) Unmount(force bool) error
- func (i *Image) Untag(name string) error
- type ImageConfig
- type ImageData
- type ImageDiskUsage
- type ImageHistory
- type ImportOptions
- type InspectOptions
- type IsExternalContainerFunc
- type ListImagesOptions
- type LoadOptions
- type LookupImageOptions
- type LookupReferenceFunc
- type ManifestList
- func (m *ManifestList) Add(ctx context.Context, name string, options *ManifestListAddOptions) (digest.Digest, error)
- func (m *ManifestList) AddArtifact(ctx context.Context, options *ManifestListAddArtifactOptions, files ...string) (digest.Digest, error)
- func (m *ManifestList) AnnotateInstance(d digest.Digest, options *ManifestListAnnotateOptions) error
- func (m *ManifestList) ID() string
- func (m *ManifestList) Inspect() (*define.ManifestListData, error)
- func (m *ManifestList) LookupInstance(ctx context.Context, architecture, os, variant string) (*Image, error)
- func (m *ManifestList) Push(ctx context.Context, destination string, options *ManifestListPushOptions) (digest.Digest, error)
- func (m *ManifestList) RemoveInstance(d digest.Digest) error
- type ManifestListAddArtifactOptions
- type ManifestListAddOptions
- type ManifestListAnnotateOptions
- type ManifestListPushOptions
- type NameTagPair
- type PlatformPolicy
- type PullOptions
- type PushOptions
- type RemoveContainerFunc
- type RemoveImageReport
- type RemoveImagesOptions
- type RootFS
- type Runtime
- func (r *Runtime) CreateManifestList(name string) (*ManifestList, error)
- func (r *Runtime) DiskUsage(ctx context.Context) ([]ImageDiskUsage, int64, error)
- func (r *Runtime) EventChannel() chan *Event
- func (r *Runtime) Exists(name string) (bool, error)
- func (r *Runtime) Import(ctx context.Context, path string, options *ImportOptions) (string, error)
- func (r *Runtime) ListImages(ctx context.Context, options *ListImagesOptions) ([]*Image, error)
- func (r *Runtime) ListImagesByNames(names []string) ([]*Image, error)
- func (r *Runtime) Load(ctx context.Context, path string, options *LoadOptions) ([]string, error)
- func (r *Runtime) LoadReference(ctx context.Context, ref types.ImageReference, options *LoadOptions) ([]string, error)
- func (r *Runtime) LookupImage(name string, options *LookupImageOptions) (*Image, string, error)
- func (r *Runtime) LookupManifestList(name string) (*ManifestList, error)
- func (r *Runtime) Pull(ctx context.Context, name string, pullPolicy config.PullPolicy, ...) (_ []*Image, pullError error)
- func (r *Runtime) Push(ctx context.Context, source, destination string, options *PushOptions) ([]byte, error)
- func (r *Runtime) RemoveImages(ctx context.Context, names []string, options *RemoveImagesOptions) (reports []*RemoveImageReport, rmErrors []error)
- func (r *Runtime) ResolveName(name string) (string, error)
- func (r *Runtime) Save(ctx context.Context, names []string, format, path string, options *SaveOptions) error
- func (r *Runtime) Search(ctx context.Context, term string, options *SearchOptions) ([]SearchResult, error)
- func (r *Runtime) Shutdown(force bool) error
- func (r *Runtime) SystemContext() *types.SystemContext
- type RuntimeOptions
- type SaveOptions
- type SearchOptions
- type SearchResult
Constants ¶
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 ¶
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
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 ¶
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
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()`.
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
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) Containers ¶
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) 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 ¶
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) IsDangling ¶
IsDangling returns true if the image is dangling, that is an untagged image without children.
func (*Image) IsIntermediate ¶
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
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 ¶
IsReadOnly returns whether the image is set read only.
func (*Image) Manifest ¶ added in v0.38.0
Manifest returns the raw data and the MIME type of the image's manifest.
func (*Image) Mount ¶
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
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
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 ¶
Names returns associated names with the image which may be a mix of tags and digests.
func (*Image) NamesHistory ¶
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
NamesReferences returns Names() as references.
func (*Image) RepoDigests ¶
RepoDigests returns a string array of repodigests associated with the image.
func (*Image) StorageImage ¶
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 ¶
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) Tree ¶
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.
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 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
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 ¶
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
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
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 ¶
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 ¶
Import imports a custom tarball at the specified path. Returns the name of the imported image.
func (*Runtime) ListImages ¶
ListImages lists the images in the local container storage and filter the images by ListImagesOptions
func (*Runtime) ListImagesByNames ¶ added in v0.61.0
ListImagesByNames lists the images in the local container storage by specified names The name lookups use the LookupImage semantics.
func (*Runtime) Load ¶
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 ¶
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
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 ¶
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.