Kustomize Common Anno — Quick Fix Guide

In this tutorial, you'll learn about Kustomize Common Anno. We cover key concepts, practical examples, and best practices.

The Hook

Kustomize Common Anno is a frequent source of Kustomize build failures. When patches don't match targets or generators produce unstable names, the deployment pipeline stalls. Kustomize's declarative overlay model demands precision in every configuration block — but the error messages are often silent, making debugging frustrating for developers.

Wrong

A common mistake is omitting target selectors for patches and forgetting to stabilize generated names:

# kustomization.yaml — wrong approach
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
patches:
  - path: fix.yaml
configMapGenerator:
  - name: app-config
    literals:
      - KEY=VALUE

kustomize build . 2>&1
# No output — patch silently skipped!
kustomize build . | grep app-config
# app-config-962d8f7t2m  (hash changes every build)

The patch is ignored without a matching target, and the ConfigMap name changes with every build because the hash suffix is enabled by default.

Right

Always specify targets and generator options:

# kustomization.yaml — with targets and stable names
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
patches:
  - path: fix.yaml
    target:
      kind: Deployment
      name: web-server
configMapGenerator:
  - name: app-config
    literals:
      - KEY=VALUE
    options:
      disableNameSuffixHash: true
      labels:
        app.kubernetes.io/managed-by: kustomize

kustomize build . | grep replicas
# replicas: 5  (patch applied)
kustomize build . | grep app-config
# name: app-config  (stable name)

DodaTech runs kustomize build in CI pipelines and diffs the output against expected manifests to catch overlay issues before deployment.

Prevention

• Always specify target kind and name in every patch selector block
• Use disableNameSuffixHash for ConfigMaps and Secrets referenced by name in deployments
• Run kustomize build in CI and pipe through diff tools to detect unexpected changes
• Test overlays in isolation with kustomize build --load-restrictor LoadRestrictionsNone
• Store kustomization.yaml files in version control with mandatory code review
• Use patchesStrategicMerge for whole-resource overrides and patchesJson6902 for precise JSON path operations
• Validate final YAML with kubectl apply --dry-run=client -f - in staging environments
• Document patch target conventions in your team's Kustomize style guide

Common Mistakes with common anno

1. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
2. Using return to exit a function early instead of wrapping a pure value in the monad
3. Mixing let bindings with <- bindings in do notation, producing type errors

These mistakes appear frequently in real-world KUSTOMIZE code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

Q: Why does Kustomize silently ignore my patch?
A: The target selector doesn't match any base resource. Verify that the kind, name, and optional apiVersion in the target block exactly match the resource metadata in your base.

Q: What is the difference between patchesStrategicMerge and patchesJson6902?
A: Strategic merge patches merge whole resource objects by kind and name, supporting list merging. JSON 6902 patches perform precise RFC 6902 operations (add, replace, remove) on specific JSON paths. Use strategic merge for common overrides and JSON patch for surgical field edits.

Q: How does DodaTech validate Kustomize overlays in CI?
A: We run kustomize build for every overlay and diff against a golden reference. The pipeline fails if unexpected changes appear. DodaZIP's configuration auditing tool validates naming conventions across all kustomization.yaml files.