Kustomize vars: Legacy Variable Substitution
The vars field captures a field value from one resource and substitutes it into $(VAR) references elsewhere.
vars predates replacements and is now deprecated, but plenty of repos still use it. Knowing its objref/fieldref shape helps when you maintain or migrate those configs.
What it does
A var names a value pulled from a source resource (objref selects the resource, fieldref the path, defaulting to metadata.name). Kustomize then replaces $(VARNAME) tokens in the manifests with that value. It is limited and deprecated in favor of replacements.
Common usage
vars:
- name: SERVICE_NAME
objref:
kind: Service
name: backend
apiVersion: v1
fieldref:
fieldpath: metadata.name
# referenced elsewhere as $(SERVICE_NAME)Fields
| Field | What it does |
|---|---|
| name | Variable name used as $(name) |
| objref | Source resource (kind, name, apiVersion) |
| fieldref.fieldpath | Path to the value (default metadata.name) |
| (consumption) | $(name) tokens in manifests are substituted |
In CI
Migrate vars to replacements for new work; replacements are more capable and not deprecated. If you keep vars, every declared var must be referenced somewhere or the build errors. vars only substitutes in a fixed set of fields by default, which surprises people expecting arbitrary substitution.
Common errors in CI
"var 'X' cannot be unused" means a declared var has no $(X) reference; remove it or use it. "unable to find field ... for var" means the fieldref path does not exist on the source object. Substitution that does not happen often means the target field is not in the default substitution allowlist; replacements avoid this restriction.
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