Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 37 ยท Helm, Kustomize and Config Management

Kustomize in Argo CD

Use Kustomize with Argo CD: bases and overlays, in-Application overrides for images, prefixes and replicas, components, build options and common pitfalls.

Kustomize builds Kubernetes manifests by layering changes on top of plain YAML, with no templating language. Argo CD detects a kustomization.yaml in the source path and runs kustomize build for you, so a typical GitOps repository can hold a shared base and one overlay per environment.

Base and overlays

A common layout:

TEXT
apps/shop/
  base/
    deployment.yaml
    service.yaml
    kustomization.yaml
  overlays/
    staging/
      kustomization.yaml
    prod/
      kustomization.yaml
      replicas-patch.yaml

base/kustomization.yaml lists the resources. An overlay references the base and changes it:

YAML
# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
namespace: shop-prod
namePrefix: prod-
images:
  - name: shop/web
    newTag: 2.8.1
patches:
  - path: replicas-patch.yaml

Point one Application at each overlay:

YAML
spec:
  source:
    repoURL: https://git.example.com/platform/shop.git
    targetRevision: main
    path: apps/shop/overlays/prod
  destination:
    name: in-cluster
    namespace: shop-prod

Argo CD sees kustomization.yaml in path and builds it. No extra field is needed.

Overrides inside the Application

Sometimes you want a small change without editing the overlay, for example when a pipeline bumps an image tag. The kustomize block accepts the same kinds of settings as kustomization.yaml:

YAML
source:
  path: apps/shop/overlays/prod
  kustomize:
    namePrefix: prod-
    nameSuffix: -v2
    images:
      - shop/web=registry.example.com/shop/web:2.8.2
    commonLabels:
      team: shop
    commonAnnotations:
      owner: platform
    replicas:
      - name: web
        count: 5

Use these sparingly. Two sources of truth (the overlay and the Application) are harder to review than one. A good rule: structure in the overlay, release data (image tag) in the Application or in the overlay's images: list, never both.

Field Effect
namePrefix, nameSuffix Added to every resource name (references are updated)
namespace Sets the namespace on namespaced resources
images Replaces image names or tags (name=newname:tag)
replicas Overrides replica counts by resource name
commonLabels, commonAnnotations Added to every resource; forceCommonLabels allows overwriting
components Reusable feature bundles
patches Inline strategic-merge or JSON 6902 patches
version Pick a specific Kustomize binary configured by the admin

commonLabels also rewrites selectors. Changing it on a live Deployment is a change to an immutable field and the sync fails. Prefer labels added through labels with includeSelectors: false in the kustomization.

Patches

Strategic-merge patches look like partial manifests:

YAML
# overlays/prod/replicas-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 5

JSON 6902 patches name a target and list operations:

YAML
patches:
  - target:
      kind: Deployment
      name: web
    patch: |-
      - op: replace
        path: /spec/template/spec/containers/0/resources/limits/memory
        value: 1Gi

Components

A component is a reusable fragment that overlays can opt into, for example "add monitoring sidecar":

YAML
resources:
  - ../../base
components:
  - ../../components/monitoring

Helm inside Kustomize

Kustomize can inflate a chart with helmCharts:. For safety Argo CD does not allow this by default. An administrator must add kustomize.buildOptions: --enable-helm to argocd-cm. Many teams skip it and use Argo CD's own Helm source or multiple sources instead.

Stand-in: a tiny overlay engine

Real Kustomize is a Go program. This stand-in shows the idea of layering with a handful of operations.

Python Stand-in: base plus overlay

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The base is never edited; each overlay produces its own result. That is why overlays make environment differences easy to review.

Troubleshooting tips

  • Run kustomize build apps/shop/overlays/prod locally; if it fails there, it fails in Argo CD.
  • Paths in resources are relative to the kustomization file. Referencing files outside the repository root is blocked by default.
  • A remote base such as github.com/org/repo//path?ref=v1.2.0 works but pin the ref, or the app can change without a commit of yours.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does Argo CD know to run Kustomize for an Application?

    Tool detection looks for Chart.yaml, then kustomization.yaml; otherwise the folder is treated as plain manifests.
  2. 2. Which Application field changes an image tag without editing the overlay?

    The kustomize block accepts images entries like newName:tag.
  3. 3. Why is commonLabels risky on an existing Deployment?

    commonLabels also changes selectors, which Kubernetes does not allow you to modify on a Deployment.
  4. 4. What must an admin enable before Kustomize helmCharts work in Argo CD?

    Helm inflation is disabled by default; the build option is set in argocd-cm.

Summary

  • Argo CD builds a path that contains kustomization.yaml with kustomize build.
  • Use one base and an overlay per environment; point one Application at each overlay.
  • The Application's kustomize block can override names, images, replicas, labels and patches; use it sparingly.
  • Watch commonLabels, unpinned remote bases and disabled Helm inflation.

Next: Directory, Jsonnet and Plugins