Managing Immutable Artifacts in Container Registries

Establish a versioning strategy for container images to ensure that the exact same binary moves through testing, staging, and production environments.

In this lesson, you will learn how to implement an immutable image strategy to guarantee that the identical binary you validated in staging is what ultimately executes in production.

The Problem with Mutable Tags

In many pipelines, developers use "floating" tags like :latest or :dev. This is a dangerous practice for CI/CD because if you deploy my-app:latest to staging and test it, that tag could be overwritten by a new build five minutes later. By the time you promote that same "version" to production, you might be deploying different code entirely. This breaks the fundamental rule of CI/CD: build once, deploy many.

Enforcing Immutability via Digest and Versioning

To achieve true immutability, you must treat your container images as "read-only" artifacts. Once an image is pushed to the registry, it should never be modified or replaced. Instead of relying on mutable tags, your pipeline should utilize two strategies:

Unique Semantic Versioning: Append a unique identifier to every build (e.g., v1.2.0-sha.a1b2c3d).
Content-Addressable Digests: Every image has a unique SHA-256 hash provided by the registry. While a tag like :v1.2.0 can theoretically be re-pointed to a different image, the digest is cryptographically tied to the exact binary content.

Example Pipeline Strategy

When your CI pipeline builds an image, have it output the exact digest to your deployment manifest:

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: my-app
        # Referencing the image by its unique digest ensures
        # the binary never changes, regardless of tag movement.
        image: my-registry.com/app@sha256:7f90...d2e1

By using the digest or a strictly unique version tag, you eliminate "environment drift." If your observability tools (like Jaeger or Prometheus) report an issue in production, you can be 100% certain that the binary running there is the exact same byte-for-byte image that passed your integration tests in the lower environments. Treat your images as immutable objects; if you need to fix a bug, build a new image with a new version tag rather than overwriting an old one.

Key Takeaway: Never overwrite existing image tags; instead, use unique semantic versions or immutable content-addressable digests to ensure the exact same binary is promoted through every pipeline stage.