Cheatsheet - Kustomize

Kustomize is an open-source tool for customizing Kubernetes configurations without templates. It allows you to define a base configuration and then apply overlays to create environment-specific variations, promoting a "Don't Repeat Yourself" (DRY) principle. Kustomize is integrated directly into kubectl (since version 1.14), but can also be used as a standalone binary.

Core Concepts

• kustomization.yaml: This is the main configuration file in a Kustomize directory. It declares the base resources, patches, and other customizations to be applied.
• Base: A directory containing a kustomization.yaml file and the common Kubernetes resource definitions (e.g., Deployments, Services) that will be used across multiple environments.
• Overlay: A directory with its own kustomization.yaml that refers to a base (or other kustomizations) and applies environment-specific customizations (patches) on top of it.
• Patches: YAML files that define modifications to be applied to resources in the base. Kustomize supports strategic merge patches and JSON patches.
• Generators: Functions that create new resources, such as ConfigMap or Secret from files, literals, or environment variables.
• Transformers: Functions that modify existing resources, like adding common labels, annotations, or name prefixes.

1. Building Configurations (kustomize build)

This is the most fundamental Kustomize command, used to render the final Kubernetes manifests after applying all customizations.

• kustomize build <PATH>
  • Builds and prints the customized Kubernetes manifests to standard output (stdout).
  • <PATH> can be a local directory containing a kustomization.yaml or a Git repository URL.
  • Example: kustomize build . (Builds the kustomization.yaml in the current directory).
  • Example: kustomize build overlays/production (Builds the production overlay).
  • Example: kustomize build https://github.com/kubernetes-sigs/kustomize.git/examples/helloWorld?ref=v1.0.6 (Builds from a remote Git repository).

2. Managing kustomization.yaml (kustomize edit)

Commands to declaratively modify the kustomization.yaml file.

• kustomize create --autodetect
  • Generates a kustomization.yaml file in the current directory by automatically detecting Kubernetes resource files.
• kustomize edit add resource <FILE_PATH>
  • Adds a resource (YAML file) to the resources list in kustomization.yaml.
  • Example: kustomize edit add resource deployment.yaml
• kustomize edit add patch <FILE_PATH>
  • Adds a patch file to the patches or patchesStrategicMerge section.
  • Example: kustomize edit add patch my-deployment-patch.yaml
• kustomize edit set image <OLD_IMAGE>=<NEW_IMAGE>:<NEW_TAG>
  • Updates the image in the images section of kustomization.yaml.
  • Example: kustomize edit set image nginx=myregistry/nginx:v2
  • Example: kustomize edit set image monopole/hello:1=monopole/hello:latest
• kustomize edit add configmap <NAME> --from-literal=<KEY>=<VALUE>
  • Generates a ConfigMap entry in kustomization.yaml from literals.
  • Example: kustomize edit add configmap my-config --from-literal=key1=value1
• kustomize edit add secret <NAME> --from-file=<FILE_PATH>
  • Generates a Secret entry in kustomization.yaml from a file.
  • Example: kustomize edit add secret my-secret --from-file=./secrets/db-password
• kustomize edit set namespace <NAMESPACE_NAME>
  • Sets a common namespace for all resources in the kustomization.
  • Example: kustomize edit set namespace dev-ns
• kustomize edit set nameprefix <PREFIX>
  • Adds a prefix to the names of all resources.
  • Example: kustomize edit set nameprefix dev-
• kustomize edit add label <KEY>:<VALUE>
  • Adds common labels to all resources.
  • Example: kustomize edit add label app:my-app
• kustomize edit add annotation <KEY>:<VALUE>
  • Adds common annotations to all resources.
  • Example: kustomize edit add annotation oncallPager:800-555-1212

3. Integration with kubectl

Kustomize functionality is deeply integrated into kubectl.

• kubectl apply -k <DIR>
  • Applies the Kustomize-built configuration from the specified directory directly to the Kubernetes cluster. This is equivalent to kustomize build <DIR> | kubectl apply -f -.
  • Example: kubectl apply -k overlays/production
• kubectl kustomize <DIR>
  • This kubectl command is an alias for kustomize build <DIR>. It outputs the rendered YAML.
  • Example: kubectl kustomize .
• kubectl diff -k <DIR>
  • Compares the Kustomize-built configuration with the live state on the cluster.
  • Example: kubectl diff -k overlays/staging
• kubectl apply -k <DIR> --dry-run=client -o yaml
  • Shows what would be applied to the cluster without actually making changes, useful for testing patches and transformations.

4. Other Useful Commands

• kustomize version
  • Displays the Kustomize CLI version.
• kustomize help [COMMAND]
  • Provides help for a specific Kustomize command or group.