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

kustomization.yaml

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.