Managing Kubernetes Resource Manifests with Kustomize: Aggregation, Overlays, and Components

Kubernetes has become the de‑facto platform for modern applications, but as adoption grows the number and complexity of Resource Manifests increase, making it hard for engineers to keep manifests consistent and avoid copy‑paste errors.

To address this, Tubi adopted a small, focused toolset and chose Kustomize as its primary manifest processor. Kustomize works directly on native Kubernetes YAML without templates, allowing developers to stay in familiar territory while providing powerful aggregation and patching capabilities.

Why Use Kustomize?

Eliminates duplicated fields such as namespaces, annotations, and labels across many manifests.

Provides a client‑side binary that can be integrated with CI/CD tools like kubectl and ArgoCD.

Avoids the long‑term maintenance burden of template‑based solutions.

Core Features

Kustomize offers two core functions: aggregating resources and patching fields. The article demonstrates both with concrete examples.

Aggregating Resources with Kustomizations

A simple kustomization.yaml can list multiple resource files and produce a single combined manifest.

# folder structure
frontend/
  kustomization.yaml
  resources/
    service.yaml
    deployment.yaml

# contents of frontend/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- resources/service.yaml
- resources/deployment.yaml

Running kustomize build frontend outputs a combined Service and Deployment ready for kubectl apply or kubectl diff .

Patching Resource Fields

Kustomize can modify any field using JSON Patch syntax. Example patches a Deployment’s replica count to 15:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: frontend
commonLabels:
  app: frontend
resources:
- resources/service.yaml
- resources/deployment.yaml
patches:
- target:
    kind: Deployment
    name: frontend
  patch: |-
    - op: replace
      path: /spec/replicas
      value: 15

The patch is applied to all matching resources, demonstrating how to enforce consistent configuration.

Organizing with Bases and Overlays

Complex deployments are structured using Bases (self‑contained sets of resources) and Overlays (higher‑level Kustomizations that reference Bases). This hierarchy mirrors the logical separation of apps, namespaces, and clusters.

# folder structure
apps/
  frontend/
    kustomization.yaml
  api/
    kustomization.yaml
namespaces/
  web/kustomization.yaml
  internal-site/kustomization.yaml
clusters/
  staging/kustomization.yaml
  production/kustomization.yaml

Namespace overlays include multiple app bases, while cluster overlays aggregate several namespace overlays, enabling a tree‑like organization of resources.

Reusable Patches with Components

Newer Kustomize versions support kind: Component , which packages reusable patches or resources that can be included in multiple overlays without duplicating code.

# clusters/staging/components/environment-annotation/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component
commonAnnotations:
  provider: kustomize

Components can be referenced from any overlay, and their patches are applied to the parent overlay’s resources, not just the component’s own resources.

Security Restrictions

Kustomize enforces a security rule that a Base may only reference files within its own directory. Attempting to reference a patch outside the Base results in errors such as:

Error: trouble configuring builtin PatchStrategicMergeTransformer with config:
  paths:
  - ../../common-patches/environment-annotation-patch.yaml
: security; file 'clusters/staging/common-patches/environment-annotation-patch.yaml' is not in or below 'clusters/staging/namespaces/web/kustomization.yaml'

The article explains how to work around this limitation using the --enable-alpha-plugins flag or, preferably, by structuring patches as Components.

Best Practices and Recommendations

Use resources: for native Kubernetes objects and bases: for other Kustomizations.

Prefer commonLabels and commonAnnotations to avoid repetitive field definitions.

Leverage Components for cross‑overlay patches and shared resources.

Follow the security model to keep each Base self‑contained, preventing accidental cross‑namespace modifications.

By adopting these patterns, teams can manage large numbers of manifests with minimal duplication, clear hierarchy, and safe, repeatable patches.

Conclusion

Kustomize provides a scalable way to manage Kubernetes Resource Manifests through aggregation, overlays, and reusable components, making it especially suitable for engineering teams that run workloads in a single‑cluster environment.