# kustomization.yaml: The Kustomize Config File

> kustomization.yaml is the file Kustomize reads to render manifests. Reference for apiVersion, kind, resources, and the field-name errors that fail CI builds.

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

kustomization.yaml declares the resources, transformers, and generators that kustomize build assembles into final manifests.

Every Kustomize directory is anchored by a kustomization.yaml. Knowing its top-level fields and exact spelling avoids most build failures.

## What it does

kustomization.yaml is a YAML document with apiVersion kustomize.config.k8s.io/v1beta1 and kind Kustomization. It lists inputs (resources, components) and the transformers and generators applied to them. kustomize build reads it and emits combined manifests on stdout.

## Common usage

```kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: web
namePrefix: prod-

resources:
  - deployment.yaml
  - service.yaml

images:
  - name: myapp
    newTag: 1.4.2
```

## Top-level fields

| Field | What it does |
| --- | --- |
| apiVersion / kind | kustomize.config.k8s.io/v1beta1 and Kustomization |
| resources | Files or directories to include |
| components | Reusable Kustomization Components to apply |
| namespace / namePrefix / nameSuffix | Namespace and name transformers |
| images | Override image names and tags |
| patches | Strategic-merge or JSON 6902 patches |
| configMapGenerator / secretGenerator | Generate ConfigMaps and Secrets |

## In CI

Always set apiVersion and kind explicitly so newer kustomize versions do not warn or default unexpectedly. Render with kustomize build into an artifact and apply that, so the same bytes that passed review reach the cluster.

## Common errors in CI

A newer kustomize rejecting an old key with "json: unknown field \"patchesStrategicMerge\"" means the field was deprecated in favor of patches. "kind: should be Kustomization but got <X>" means a typo. "accumulating resources: missing metadata.name" means a listed resource is not valid YAML.

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

### kustomization.yaml: The Kustomize Config File?

Every Kustomize directory is anchored by a kustomization.yaml. Knowing its top-level fields and exact spelling avoids most build failures.

### What it does?

kustomization.yaml is a YAML document with apiVersion kustomize.config.k8s.io/v1beta1 and kind Kustomization. It lists inputs (resources, components) and the transformers and generators applied to them. kustomize build reads it and emits combined manifests on stdout.

### In CI?

Always set apiVersion and kind explicitly so newer kustomize versions do not warn or default unexpectedly. Render with kustomize build into an artifact and apply that, so the same bytes that passed review reach the cluster.

### Common errors in CI?

A newer kustomize rejecting an old key with "json: unknown field \"patchesStrategicMerge\"" means the field was deprecated in favor of patches. "kind: should be Kustomization but got <X>" means a typo. "accumulating resources: missing metadata.name" means a listed resource is not valid YAML.

---

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