# Kustomize images: Override Image Names and Tags

> The images field rewrites container image names, tags, and digests across manifests. Reference for newName, newTag, digest, and the pinning errors in CI.

Source: https://latchkey.dev/learn/command-reference/kustomize-images-transformer  
Updated: 2026-06-30

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

```kustomization.yaml
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.

```Terminal
# 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
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### Kustomize images: Override Image Names and Tags?

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).

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt