Documentation
¶
Index ¶
- Variables
- func NormalizeName(name string) (reference.Named, error)
- func NormalizePlatform(rawOS, rawArch, rawVariant string) (os, arch, variant string)
- 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) 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(ctx 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) AnnotateInstance(d digest.Digest, options *ManifestListAnnotateOptions) error
- func (m *ManifestList) ID() string
- func (m *ManifestList) Inspect() (*manifest.Schema2List, 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 ManifestListAddOptions
- type ManifestListAnnotateOptions
- type ManifestListPushOptions
- type NameTagPair
- 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, 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, names []string, options *ListImagesOptions) ([]*Image, error)
- func (r *Runtime) Load(ctx context.Context, path string, 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, 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 SearchFilter
- type SearchOptions
- type SearchResult
Constants ¶
This section is empty.
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 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 not be normalized.
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 // 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.Scond. 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 a signature to be added during the copy, and // specifies a key ID. SignBy string // 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 }
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 // 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 }
HasDifferentDigestOptions allows for customizing the check if another (remote) image has a different digest.
type Image ¶
type Image struct {
// 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) 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 ¶
func (i *Image) Mount(ctx 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
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 no 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 }
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 // 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 func(ref types.ImageReference) (types.ImageReference, error)
LookupReferenceFunc return an image reference based on the specified one. This can be used to pass custom blob caches to the copy operation.
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) 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() (*manifest.Schema2List, 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 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 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 }
Options for annotationg 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 }
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 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 custommizing image pulls.
type PushOptions ¶
type PushOptions struct {
CopyOptions
}
PushOptions allows for custommizing 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 // 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 }
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, 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
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 specicifed 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 ¶
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 ¶
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) 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, 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 SearchFilter ¶
type SearchFilter struct { // Stars describes the minimal amount of starts of an image. Stars int // IsAutomated decides if only images from automated builds are displayed. IsAutomated types.OptionalBool // IsOfficial decides if only official images are displayed. IsOfficial types.OptionalBool }
SearchFilter allows filtering images while searching.
func ParseSearchFilter ¶ added in v0.38.0
func ParseSearchFilter(filter []string) (*SearchFilter, error)
ParseSearchFilter turns the filter into a SearchFilter that can be used for searching images.
type SearchOptions ¶
type SearchOptions struct { // Filter allows to filter the results. 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 // 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.