Container images are release artifacts, not disposable build outputs. This guide provides a reusable lifecycle checklist for naming images, choosing tags or digests, building multi-architecture manifests, scanning and signing releases, promoting them between environments, deploying safely, and cleaning a registry without deleting images that active workloads still need.
Overview
A reliable image lifecycle separates four concerns: identifying an artifact, proving what it contains, moving it between environments, and deciding when it can be retired. Tags make images convenient to reference, while digests provide content-addressable identity. A practical workflow uses both: human-readable immutable release tags for operations and digests for deployment-level precision.
For example, a release might be published as registry.example.com/payments/api:2026.11.0 and resolve to a digest such as sha256:.... The tag helps engineers recognize the release. The digest ensures that a later tag movement cannot silently change the image pulled by a workload.
Tag versus digest
| Reference | Best used for | Strength | Risk or limitation |
|---|---|---|---|
Mutable tag, such as latest or main | Local development or explicitly continuous environments | Simple and familiar | The referenced content can change without a manifest change |
Immutable release tag, such as 2026.11.0 | Release communication, promotion records, and rollback labels | Readable and stable when tag mutation is prevented | It still depends on registry controls and team discipline |
Digest, such as image@sha256:... | Production deployment, audit records, and reproducibility | Identifies exact content | Less readable and must be updated deliberately |
Do not treat a version-looking tag as immutable by assumption. Configure registry permissions or admission controls so release tags cannot be overwritten, and record the resolved digest in the deployment system. Kubernetes manifests can use a digest directly:
image: registry.example.com/payments/api@sha256:REPLACE_WITH_RESOLVED_DIGESTWhen a platform or deployment controller supports both a tag and digest, keep the tag in release metadata for humans and use the digest as the effective runtime reference. Validate the exact syntax supported by your tooling before standardizing it.
Use a predictable naming policy
A name should identify the registry, ownership boundary, application, and optionally the build stream. For example:
registry.example.com/team-or-product/serviceKeep environment names out of the artifact identity when the same immutable image is promoted from development to production. Environment-specific configuration belongs in deployment configuration, secrets, or values managed by the platform. This prevents separate rebuilds from introducing unreviewed differences between environments.
A practical policy template is:
- Repository:
<registry>/<team-or-product>/<service>. - Release tag: a reviewed version or release identifier that cannot be overwritten.
- Build metadata: a separate traceable label containing the source revision, build identifier, and build time where useful.
- Deployment reference: the immutable digest recorded by the release system.
- Retention: keep active production references, rollback candidates, recent verified releases, and images required by an agreed audit or recovery window.
- Deletion authority: automated cleanup may remove only images that pass dependency and retention checks.
Checklist by scenario
1. Building a standard release image
- Build from a reviewed source revision and a controlled build definition.
- Use a minimal, appropriate base image and document its update process.
- Generate a unique candidate tag for the build. Do not use
latestas the release identity. - Attach useful OCI labels, such as source revision, version, and build reference, without placing secrets in labels or layers.
- Run unit, integration, policy, and image-level checks before publishing a release candidate.
- Scan the image and record findings with the artifact. Define how the team handles fixable, accepted, and blocking findings.
- Publish the image to a staging or candidate repository, then resolve and record its digest.
2. Tagging and promoting an approved release
- Confirm that the candidate digest passed required tests and review.
- Apply one immutable release tag to the approved content, or promote the existing digest according to the registry's supported workflow.
- Sign the image or related artifact using the signing process approved by your organization. Keep signing keys outside the image build context and protect them with the team's secrets controls.
- Store provenance, scan results, approval information, and the final digest with the release record.
- Promote the same digest to the next environment. Avoid rebuilding the source between environments.
- Update deployment configuration through the normal review path. A GitOps workflow can make this change visible and reversible; see the GitOps repository structure guide.
3. Building for multiple architectures
A multi-architecture image is typically represented by an OCI index or Docker manifest list that points to architecture-specific image manifests. The command below is a common Buildx pattern, but flags and authentication behavior should be checked against the versions used by your build environment:
docker buildx build \
--platform linux/amd64,linux/arm64 \
--tag registry.example.com/team/service:2026.11.0 \
--push .After publishing, verify that the index contains the intended operating-system and architecture entries. Test at least one representative runtime for each supported architecture, especially when native dependencies, compiled extensions, or CPU-specific assumptions are present. Sign and promote the resulting index according to your policy, and retain the child manifests as dependencies of the published index.
4. Deploying to Kubernetes
- Resolve the intended tag to a digest before production deployment.
- Confirm that every node architecture is supported by the image index or constrain scheduling with appropriate node selectors or affinity.
- Check that image pull credentials are available in the target namespace and are not embedded in manifests or image layers.
- Deploy through the approved controller and verify the resulting pod image ID, not only the requested tag.
- Observe startup, readiness, error rate, resource use, and rollback signals.
- Retain the previous known-good digest until the rollback window and operational review are complete.
For related operational planning, pair image changes with the Kubernetes cluster upgrade checklist when a release also changes cluster versions or add-ons.
5. Cleaning obsolete images
- Export a current list of repository tags, digests, creation times, and manifest relationships.
- Identify live references from deployments, jobs, scheduled jobs, stateful workloads, admission policies, rollback records, and other environments.
- Protect production, disaster-recovery, and explicitly retained rollback digests.
- Apply the retention policy to unreferenced images only.
- Run cleanup in report or dry-run mode where supported.
- Review the deletion set with an owner before the first automated execution.
- Delete by digest or registry-supported artifact identity, then verify that active deployments still resolve and pull successfully.
- Record what was deleted, when, by which automation, and under which policy version.
What to double-check
- Digest scope: distinguish a platform index digest from a platform-specific child manifest digest. A Kubernetes node may pull a child manifest while the release record references the index.
- Registry behavior: confirm whether deleting a tag also deletes a manifest, whether garbage collection is separate, and how retention rules treat shared layers.
- Signature verification: verify the exact artifact being deployed, including how your signing tool handles indexes and attached attestations.
- Pull policy: understand the runtime's image pull behavior. A digest is precise, but credentials, network access, cache state, and registry availability still affect deployment.
- Architecture coverage: check the image index, base image support, native libraries, and test matrix rather than assuming a successful build supports every target.
- Rollback availability: a rollback reference is useful only if the digest, image layers, registry access, and compatible configuration remain available.
- Metadata privacy: inspect labels, build arguments, logs, and layers for credentials, tokens, internal URLs, or other sensitive values.
Common mistakes
- Deploying
latestin production: this obscures which content is running and makes rollback analysis harder. - Rebuilding during promotion: rebuilding can produce a different digest from the tested artifact. Promote the verified digest instead.
- Overwriting release tags: mutable release tags break audit trails and can make an old deployment unreproducible.
- Deleting by age alone: an old image may still be the active production version, a rollback target, or a child manifest referenced by a multi-architecture index.
- Scanning only at build time: image contents and vulnerability data change over time. Define a process for rescanning retained images and deciding when redeployment is required.
- Ignoring registry dependencies: deleting a tag, signature, attestation, or child manifest without understanding relationships can break verification or deployment workflows.
- Mixing environment configuration into images: this encourages rebuilds for every environment and can expose secrets through layers.
When to revisit
Review this lifecycle whenever the build system, registry, signing tool, deployment controller, or OCI-related behavior changes. Also revisit it before seasonal planning cycles, architecture migrations, major base-image updates, vulnerability remediation campaigns, and registry cost or capacity reviews.
At least monthly, review the naming policy, immutable-tag enforcement, retention exceptions, cleanup reports, active digest references, and multi-architecture test coverage. A useful review produces four outputs: a list of protected images, a list of safely removable images, unresolved policy exceptions, and actions with owners and dates.
Before changing cleanup automation, run a report-only job against a representative repository set. Compare its proposed deletions with live deployment inventories and rollback records. After approval, delete a small scope first, monitor image pulls and deployment reconciliations, and then expand gradually. Finally, update the policy documentation and release checklist so the next build, promotion, or registry audit uses the same decisions.