Documentation
¶
Overview ¶
Package images implements the operations on the images of a project: listing the images its containers run, working out the identity of a local image, and removing the images `down` and `watch` leave behind.
Index ¶
- func ImageBelongsToKnownService(project *types.Project, removeOrphans bool, img image.Summary) bool
- func LocalContentDigest(inspect client.ImageInspectResult, platform string) (string, bool, error)
- func Summarize(repoTag string, inspect client.ImageInspectResult) api.ImageSummary
- type Backend
- type PruneOptions
- type Pruner
- type Service
- func (s *Service) CanonicalBuiltDigest(ctx context.Context, imageRef, platform, builderDigest string) string
- func (s *Service) EligibleDanglingImages(ctx context.Context, projectName string, keep func(image.Summary) bool) ([]image.Summary, error)
- func (s *Service) ImageInspectOptions(ctx context.Context) ([]client.ImageInspectOption, error)
- func (s *Service) Images(ctx context.Context, projectName string, options api.ImagesOptions) (map[string]api.ImageSummary, error)
- func (s *Service) InspectLocalContent(ctx context.Context, ref string, platform string) (string, bool, error)
- func (s *Service) InspectLocalImages(ctx context.Context, repoTags []string) (map[string]client.ImageInspectResult, error)
- func (s *Service) RemoveDanglingImages(ctx context.Context, projectName string, keep func(image.Summary) bool) ([]string, error)
- func (s *Service) RemoveImages(ctx context.Context, images []image.Summary, limiter *semaphore.Weighted) (removed, stillInUse []string, err error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ImageBelongsToKnownService ¶
ImageBelongsToKnownService reports whether img should be pruned: it belongs to a service of project, or to an orphan when removeOrphans is set. A declared but disabled service is not an orphan. project must already be narrowed to the services being torn down. Shared by tagged and dangling image pruning.
func LocalContentDigest ¶
LocalContentDigest returns the digest identifying an inspected image's runnable content (config + layers) for the requested platform (empty means the host default), plus whether the local image satisfies that platform. Note the satisfied bool is only meaningful for an explicitly requested platform: with platform empty, the manifests path reports host-default satisfaction while the manifest-less path always reports true.
With BuildKit provenance attestations enabled (the default since recent Buildx/BuildKit), the image is stored as an index whose top-level digest (inspect.ID) also covers the attestation manifest, so it changes on every build even when the runnable image is unchanged — making compose recreate containers needlessly (see https://github.com/docker/compose/issues/13636). The digest of the "image" kind manifest reflects only the image content, which is what compose needs to detect staleness. Images inspected without manifest data (engines that can't report them) keep the plain image ID — already the config digest — with platform satisfaction from the inspect's flat platform fields, the pre-manifest behavior. Every image identity compose records for staleness comparison must be computed through here, whatever the image's provenance (pulled, built, already local), so any two runs produce comparable values.
The converse also holds: this platform-specific digest is ONLY an identity for staleness comparison. Pinning image references in a reproducible compose model (publish / config --resolve-image-digests) must keep using the registry descriptor digest — the multi-platform index — through ImageDigestResolver, or the published file would be bound to the platform of whoever resolved it.
func Summarize ¶
func Summarize(repoTag string, inspect client.ImageInspectResult) api.ImageSummary
Summarize builds the summary of an image from the tag it was found under and its inspection.
Types ¶
type Backend ¶
type Backend interface {
// APIClient talks to the Docker daemon.
APIClient() client.APIClient
// MaxConcurrency bounds the daemon calls made in parallel, 0 meaning no bound.
MaxConcurrency() int
// RuntimeAPIVersion is the API version negotiated with the daemon.
RuntimeAPIVersion(ctx context.Context) (string, error)
// ClassifyRemovalError reports whether the error of a resource removal is a
// benign "still in use" or "already gone", shared with the removal of the
// other resources of a project so the two agree on what is tolerable.
ClassifyRemovalError(err error) (stillInUse, alreadyGone bool)
}
Backend is what the operations need from the engine they act on. It is narrow on purpose: it redeclares APIClient and MaxConcurrency of engine.Backend rather than embedding it, which would force every implementation (the fake of the tests included) to provide Containers and SpecifiedContainer, that these operations never call.
type PruneOptions ¶
type PruneOptions struct {
Mode api.ImagePruneMode
// RemoveOrphans also removes project images that belong to no declared
// service. Images for declared services disabled by a profile or left out
// of the teardown selection are kept.
RemoveOrphans bool
}
PruneOptions controls the behavior of image pruning.
type Pruner ¶
type Pruner struct {
// contains filtered or unexported fields
}
Pruner handles image removal during Compose `down` operations.
func NewPruner ¶
func NewPruner(imageClient client.ImageAPIClient, project *types.Project, limiter *semaphore.Weighted) *Pruner
NewPruner creates a Pruner object for a project. limiter may be nil, meaning unbounded.
func (*Pruner) ImagesToPrune ¶
ImagesToPrune returns the set of images that should be removed.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service runs the image operations on a Backend.
func (*Service) CanonicalBuiltDigest ¶
func (s *Service) CanonicalBuiltDigest(ctx context.Context, imageRef, platform, builderDigest string) string
CanonicalBuiltDigest resolves the canonical content digest of a just-built image so the recorded identity matches what later runs compute for the same local image. Registry-only builds (push-only, multi-platform without load) are not locally inspectable and keep the builder-reported digest: a volatile but honest value — an actual rebuild is still detected — preferred over a stable marker that would hide real image changes. Best effort: never fails an already-successful build.
func (*Service) EligibleDanglingImages ¶
func (s *Service) EligibleDanglingImages(ctx context.Context, projectName string, keep func(image.Summary) bool) ([]image.Summary, error)
EligibleDanglingImages lists a project's dangling images and filters out those spared by keep. Shared by down --rmi (which also needs the list itself, to decide whether there's anything to report) and watch --prune, so the two don't drift apart.
func (*Service) ImageInspectOptions ¶
ImageInspectOptions requests per-manifest data when the engine supports it (see manifestsSupported).
func (*Service) Images ¶
func (s *Service) Images(ctx context.Context, projectName string, options api.ImagesOptions) (map[string]api.ImageSummary, error)
Images lists the images the containers of a project run.
func (*Service) InspectLocalContent ¶
func (s *Service) InspectLocalContent(ctx context.Context, ref string, platform string) (string, bool, error)
InspectLocalContent inspects ref and returns its canonical content digest for the requested platform (empty means the host default), plus whether the local image satisfies that platform — see LocalContentDigest.
func (*Service) InspectLocalImages ¶
func (s *Service) InspectLocalImages(ctx context.Context, repoTags []string) (map[string]client.ImageInspectResult, error)
InspectLocalImages inspects the given references in parallel, requesting per-manifest data on engines that support it. References not found locally are simply absent from the result.
func (*Service) RemoveDanglingImages ¶
func (s *Service) RemoveDanglingImages(ctx context.Context, projectName string, keep func(image.Summary) bool) ([]string, error)
RemoveDanglingImages lists a project's dangling images and removes those not spared by keep. Shared by down --rmi and watch --prune, which differ only in what keep spares.
func (*Service) RemoveImages ¶
func (s *Service) RemoveImages(ctx context.Context, images []image.Summary, limiter *semaphore.Weighted) (removed, stillInUse []string, err error)
RemoveImages removes the given images in parallel, tolerating individual failures so one bad image doesn't abort the rest. An image already gone (a benign race with something else removing it concurrently) or still in use is never joined into err — same tolerance down already gives a tagged image in either situation (its own distinct, correctly worded event, not an error). "Still in use" is returned in its own bucket, not folded into removed, since a caller aggregating several images (down's removal of dangling images) needs that distinction to report the batch honestly; an already-gone image reached the goal the same as an actual removal, so it's simply not counted against either bucket. Any other removal error is joined into err so callers reporting failures to the user keep the actual daemon error instead of just an image ID.
Source Files