Appearance

Kustomize and Helm

Render reusable configuration into reviewable Kubernetes objects before creating a release.

What you will understand

  • Choose overlays or chart values for a concrete configuration problem
  • Inspect rendered manifests before applying them
  • Explain Helm release history without treating templates as runtime controllers

Builds on: Metrics, logs, and traces

Mental model: Kubernetes reconciles rendered objects, not your packaging intent

Plain manifests become difficult to maintain when staging and production share most fields but differ in replicas, configuration and image versions. Kustomize composes resources and applies structured transformations without turning the whole manifest into a text template. A base contains reusable Kubernetes objects; overlays reference that base and declare deliberate differences. kubectl kustomize renders the result, and kubectl apply -k sends the rendered objects to the API.

Helm packages templates and defaults into a chart, combines them with supplied values, and manages a named release. Template logic can generate several related resources for a configurable application. A chart is useful for distributing an application with an explicit configuration interface, while an overlay can be simpler for modifying a known set of manifests. They can be combined deliberately, but layering tools without a clear owner for each field can make the final configuration harder to explain.

Neither Kustomize nor a rendered Helm template changes how the scheduler, Deployment controller or Service data plane works. The API receives ordinary resources. A syntactically valid rendering can still contain a broken selector, unsafe security settings or a Service targetPort that no process uses. Review the actual output rather than assuming a successful render proves application correctness.

Review the overlay output that the API will receive

Follow a reusable base through structured transformations, rendering and server validation.

Ownership viewStep 1 of 4
Start from a known baseThe base holds ordinary Kubernetes objects. Its selector and port relationships remain important after reuse.. Base resources, Deployment + Service, ready. Training overlay, Namespace, image and replica patch, active. Rendered manifests, Actual objects after transforms, idle. API dry-run, Schema + admission checks, idle. Cluster controllers, Reconcile admitted objects, idleBase resources: Deployment + Service
Base resourcesDeployment + ServiceReady
Training overlay: Namespace, image and replica patch
Training overlayNamespace, image and replica patchIn focus
Rendered manifests: Actual objects after transforms
Rendered manifestsActual objects after transformsContext
API dry-run: Schema + admission checks
API dry-runSchema + admission checksContext
Cluster controllers: Reconcile admitted objects
Cluster controllersReconcile admitted objectsContext
Base resourcesDeployment + ServiceReady
Training overlayNamespace, image and replica patchIn focus
Rendered manifestsActual objects after transformsContext
API dry-runSchema + admission checksContext
Cluster controllersReconcile admitted objectsContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Patch targets the wrong resource
Start from a known base

The base holds ordinary Kubernetes objects. Its selector and port relationships remain important after reuse.

Read the complete visual sequence
  1. Start from a known base

    The base holds ordinary Kubernetes objects. Its selector and port relationships remain important after reuse.

  2. Apply focused transformations

    The overlay changes only intended fields, producing a concrete rendered artifact that can be reviewed.

  3. Validate and diff the result

    Server dry-run tests API validation and admission without running the application; diff exposes live changes.

  4. Apply then verify behavior

    Controllers see the rendered resources. A rollout check and a real request test are still required after apply.

Patch targets the wrong resource

The intended replica change is absent or rendering fails.

  1. Target name differs

    The overlay expects api while the base uses another Deployment name.

  2. Rendering reveals the mismatch

    Depending on patch form and matching, the change can fail or not affect the intended object. Inspect the concrete output before applying.

  3. Correct the source target

    Repair the overlay target and re-render; do not manually edit the live Deployment as the only lasting fix.

About this model

The base already contains a Deployment with a replicas field and a matching Service.

Walkthrough: express a small environment change visibly

This kustomization.yaml assumes a base directory containing the module lab’s api Deployment and Service. The patch target identifies the intended Deployment, and the image transformation identifies the original image name.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
namespace: learning
images:
  - name: nginx
    newTag: 1.27-alpine       # Training tag; pin an approved digest for releases.
patches:
  - target:
      kind: Deployment
      name: api
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 3
kubectl kustomize overlays/training > rendered.yaml
kubectl apply --dry-run=server -f rendered.yaml
kubectl diff -k overlays/training
kubectl apply -k overlays/training
kubectl rollout status deployment/api -n learning --timeout=120s

kubectl diff normally exits with status 1 when it finds differences; that is a meaningful review result rather than automatically a command failure. Server dry-run exercises available validation and admission, but it does not schedule Pods or prove an external dependency will respond. Inspect selectors, image identifiers, resource settings and generated configuration references in the rendered file. Keep rendered artifacts free of real Secret values before saving them to an ordinary build log.

A chart produces resources and a named release history

Follow chart templates and values into release application, verification and later rollback limits.

Ownership viewStep 1 of 4
Combine templates and valuesThe chart defines the configuration interface; final values select the manifest details. Package version and application image version are different identifiers.. Chart, Templates + package version, idle. Values, Defaults plus explicit overrides, idle. Rendered resources, Concrete Kubernetes objects, active. Helm release api, Revision history in namespace, idle. Cluster workload, Readiness and customer behavior, idle. External database, Migration side effects, idleChart: Templates + package version
ChartTemplates + package versionContext
Values: Defaults plus explicit overrides
ValuesDefaults plus explicit overridesContext
Rendered resources: Concrete Kubernetes objects
Rendered resourcesConcrete Kubernetes objectsIn focus
Helm release api: Revision history in namespace
Helm release apiRevision history in namespaceContext
Cluster workload: Readiness and customer behavior
Cluster workloadReadiness and customer behaviorContext
External database: Migration side effects
External databaseMigration side effectsContext
ChartTemplates + package versionContext
ValuesDefaults plus explicit overridesContext
Rendered resourcesConcrete Kubernetes objectsIn focus
Helm release apiRevision history in namespaceContext
Cluster workloadReadiness and customer behaviorContext
External databaseMigration side effectsContext
Animation controls
Speed
0.5×
1×
2×
Explore a scenario
Normal behavior
Resource readiness hides a semantic defect
Combine templates and values

The chart defines the configuration interface; final values select the manifest details. Package version and application image version are different identifiers.

Read the complete visual sequence
  1. Combine templates and values

    The chart defines the configuration interface; final values select the manifest details. Package version and application image version are different identifiers.

  2. Inspect before install

    Lint and template make output reviewable, including selectors, privileges and configuration references.

  3. Apply a release revision

    Helm tracks a named release while Kubernetes reconciles its objects. Wait settings do not prove every business request works.

  4. Separate resource rollback from data

    A historical manifest revision can be reapplied, but external migrations or messages may be irreversible or incompatible with old code.

Resource readiness hides a semantic defect

All Pods are ready but the configured external backend is wrong.

  1. Release checks pass

    The configured readiness checks complete and the release command can report success.

  2. Customer path fails

    The application targets an incorrect external database or endpoint that the readiness check did not exercise.

  3. Use flow-specific verification

    Run a safe customer-path smoke test, compare effective values and choose a compatible correction or rollback.

About this model

Local chart and values are already reviewed; external business state is outside Helm resource rollback.

Practice: make a chart’s configuration contract explicit

A Helm chart typically includes Chart.yaml, default values.yaml, templates and optional dependencies. The chart version and application version describe different things: the package can change without changing the application binary. Values are inputs to templates, and supplied files or command-line settings can override defaults. Read the final values and rendered manifests for a release rather than assuming a committed default file is the effective configuration.

# Optional extension: supply a local chart and values file first.
# They are not included in the downloadable Kustomize baseline.
helm lint ./chart
helm template api ./chart -n learning -f values-training.yaml > helm-rendered.yaml
helm upgrade --install api ./chart -n learning \
  -f values-training.yaml --wait --timeout 5m
helm history api -n learning
helm get values api -n learning --all
helm get manifest api -n learning

helm get values --all includes computed defaults as well as supplied overrides; without --all, the command normally shows supplied values. Review this output securely because values can contain credentials. Helm’s wait behavior checks configured resource readiness according to the installed Helm version and options; waiting for ordinary Job completion also requires --wait-for-jobs. It is not a substitute for a user-facing smoke test. A release revision records deployment history, but a Helm rollback cannot reverse external side effects or make an incompatible database migration safe. Hooks and CRDs have additional lifecycle behavior, so inspect charts before installing them with broad permissions. Dependencies should be pinned and reviewed, including lock information where applicable.

Pitfalls: multiple writers make reproducibility fragile

A live manual edit can drift from the source overlay or chart values. Reapplying the source can overwrite that edit, while another controller such as an HPA can legitimately own replica count. Avoid forcing a fixed replicas value on every delivery when an autoscaler should manage it. Record one configuration source and field-ownership policy, then inspect diffs before reconciliation. A secret passed through --set can appear in command history and release metadata; use the approved credential workflow instead.

Check your understanding

Helm rendered successfully and the release command returned success. Has the API’s real customer flow been verified?

No. Rendering proves template evaluation, and release status covers particular resource checks. A wrong backend URL, missing permission or semantically broken application can still pass those boundaries. Run a targeted end-to-end smoke test and inspect the relevant telemetry before promoting the release.

Use the delivery lab to compare an overlay’s rendered diff with the live resources. Next, scale replica count and node supply without introducing conflicting configuration writers.

Primary documentation

Go to the source

Reviewed 2026-10-27 · Kubernetes 1.37 · Related local exercise

Search the book

Search loads when you open it.