Kubernetes Kustomize Image Management

Kubernetes Kustomize Image Management is the practice of using Kustomize's dedicated images transformer to override container image names, tags, and digests per environment without patching a Deployment's container spec directly, keeping image version control centralized, greppable, and decoupled from the rest of a resource's structural definition.

The images Transformer

Overriding Tag by Name Match

images:
  - name: myapp
    newTag: "1.4.0"

# base deployment.yaml
containers:
  - name: web
    image: myapp:latest

kustomize build overlays/production
# containers:
#   - name: web
#     image: myapp:1.4.0

The images field matches container image references by their repository name (myapp) across every resource in scope and substitutes a new tag, entirely independent of which Deployment, StatefulSet, or Job actually references that image, meaning a single entry updates every occurrence consistently.

Overriding Repository and Registry

images:
  - name: myapp
    newName: registry.internal.example.com/myapp
    newTag: "1.4.0"

Combining newName with newTag redirects an image reference to an entirely different registry, useful when a base is authored against a public or generic image reference and an overlay needs to point at an organization's private mirror or internal registry without touching the base's container definitions at all.

Digest Pinning for Immutability

Pinning by Digest Instead of Tag

images:
  - name: myapp
    newTag: "1.4.0"
    digest: sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b85

Specifying a digest alongside or instead of a tag produces an image reference pinned to an exact, immutable content hash, closing the gap where a mutable tag (even a specific version tag, if it was overwritten in the registry) could resolve to different actual image content over time; production overlays commonly pin by digest specifically for this reproducibility guarantee.

kustomize build overlays/production | grep image:
# image: registry.internal.example.com/myapp@sha256:e3b0c44...

Per-Environment Image Overrides

Different Images per Overlay

# overlays/staging/kustomization.yaml
images:
  - name: myapp
    newTag: "1.5.0-rc1"

# overlays/production/kustomization.yaml
images:
  - name: myapp
    newTag: "1.4.0"

Each overlay declares its own images entries independently, letting staging run a release candidate while production continues running the last validated stable tag, both built from the identical base Deployment definition with no divergence in structure, only in which image version is substituted at render time.

Automating Image Tag Updates

CI-Driven Tag Bumps

kustomize edit set image myapp=registry.internal.example.com/myapp:1.4.1

The kustomize edit set image command modifies an overlay's kustomization.yaml programmatically, which is the mechanism CI pipelines commonly use to automate "bump the deployed image tag to the one just built and pushed," committing the resulting change to Git as an explicit, reviewable commit rather than requiring a human to hand-edit YAML for every release.

Interaction with GitOps Image Automation Tools

Marker-Based Automated Updates

containers:
  - name: web
    image: registry.internal.example.com/myapp:1.4.0 # {"$imagepolicy": "flux-system:myapp"}

GitOps image automation controllers, such as Flux's image update automation, can be configured to detect new image tags matching a policy and rewrite the images entry in an overlay's kustomization.yaml automatically, committing the change back to Git, closing the loop between a new image being published and a corresponding overlay update without manual intervention, while still preserving Git as the auditable record of every version actually deployed.

Relationship to the Kustomize Package Model and Patch Management

Image management via the dedicated images transformer is a purpose-built alternative to expressing the same change through a general-purpose patch, and it exists specifically because image tag changes are common enough, and structurally simple enough, to warrant a first-class Kustomize feature rather than requiring every overlay to author its own strategic merge or JSON6902 patch against a container's image field; it complements the broader Kustomize package model and patch management practices by handling one of the single most frequent customization needs, environment-specific image version, cleanly and centrally.