Kustomize bases and initial overlays

Give environment differences a home

A base contains the common Kubernetes objects. An overlay selects that base and applies intentional differences. Start with base/ and overlays/local/; add QA, preproduction, and production overlays when you have defined their configuration and deployment targets.

Keep image identity, resource sizing, and environment labels reviewable. Keep credentials outside Git. A kustomization.yaml is input to Kustomize; Kubernetes receives its rendered objects. It is different from an application's ConfigMap.

Make a tiny overlay without a cluster

Rendering means turning configuration inputs into the Kubernetes objects that would be sent to the API. It is useful before Argo CD exists. In a new .local/kustomize-practice/ directory, create base/ and overlays/local/. Save this as base/page.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: reading-room
data:
  colour: blue

Save base/kustomization.yaml with these contents:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - page.yaml

Save overlays/local/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: classroom
resources:
  - ../../base
patches:
  - target:
      kind: ConfigMap
      name: reading-room
    patch: |-
      - op: replace
        path: /data/colour
        value: green

Run kubectl kustomize .local/kustomize-practice/base, then kubectl kustomize .local/kustomize-practice/overlays/local from the checkout root. Neither command applies anything. Expect the base to contain colour: blue; the overlay result should contain colour: green and namespace: classroom. The base file should still be blue. The patch selected one object by kind/name and replaced one value; it did not rewrite the source file.

Change the patch to a misspelled field path and render again. A replace operation needs the target path to exist, so an error is useful feedback. Restore the correct path. This gives you a small way to understand a failed render before the input grows to several services.

Render before applying

After the Kubernetes lab, the GitOps lab puts its generated apps.json in a base and adds a local overlay. The initial overlay adds an annotation:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: microbank
resources:
  - ../../base
commonAnnotations:
  learning.learnwithsk.dev/environment: local

kubectl kustomize infra/study/gitops/overlays/local > evidence/local-rendered.yaml

Inspect the complete result: namespace, selectors, images, replicas, and Secret references. Kustomize transforms can affect fields beyond the one you first notice. Review a rendered diff as well as the short overlay diff. Configuration generation is not secret encryption.

MicroBank boundary

The first GitOps application owns Accounts and Ledger workload declarations and Services. The prerequisite lab owns local databases, emulator resources, and the private runtime Secret. Separate ownership avoids Argo CD trying to create topics or regenerate credentials implicitly. Later platform work can formalize these boundaries into separate applications.

Checkpoint: explain which file you would change for a new Accounts image and which rendered field proves the change. An image tag containing a commit is useful, but a registry digest is the stronger artifact identity when moving beyond local loaded images.

Checkpoint answer: change the intended image reference in the base or the overlay's image transformation, then inspect the rendered Deployment's container image. A changed filename or Git commit alone does not prove that field changed. Save your successful render and move to Argo CD applications and sync, which introduces a controller that reads these inputs from Git.

Sources

Kustomize task guide↗, Kustomize reference↗.