Kustomize images: Override Image Names and Tags
The images field rewrites the image name, tag, or digest of every matching container in the rendered output.
This is the field CI pipelines touch most: set the freshly built tag once and Kustomize updates every Deployment, StatefulSet, and CronJob that uses the image.
What it does
The images list matches containers by their current image name and rewrites them. newName changes the repository, newTag changes the tag, and digest pins an immutable @sha256 digest (digest and newTag are mutually exclusive for one entry).
Common usage
images:
- name: myapp
newName: registry.example.com/team/myapp
newTag: 1.4.2
- name: nginx
digest: sha256:abc123...Fields
| Field | What it does |
|---|---|
| name | Existing image name to match (required) |
| newName | Replacement repository/image name |
| newTag | Replacement tag |
| digest | Pin to an immutable @sha256 digest (excludes newTag) |
| tagSuffix | Append a suffix to the existing tag |
In CI
Pin the tag from the pipeline with kustomize edit set image myapp=:$GIT_SHA, or better, pin a digest so deploys are reproducible. The name field must match the image string in the manifest exactly, including any registry prefix already present.
Common errors in CI
If the tag is not applied, the name almost never matches the manifest exactly (a registry prefix in the manifest but not in name, or vice versa). Setting both newTag and digest on one entry is rejected. A digest without the sha256: prefix is invalid. The images transformer silently no-ops on a non-matching name rather than erroring, so verify with kustomize build | grep image.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes