Kustomize Deployment & Usage Guide

1. Prerequisites

• Go 1.21+ (required only for building from source)
• Git (for cloning the repository)
• Kubernetes cluster (optional, for applying generated manifests)
• kubectl v1.14+ (optional, for kubectl-integrated usage)
• Make (optional, for using Makefile targets)

2. Installation

Option A: Standalone Binary (Recommended)

Install the latest release using Go:

go install sigs.k8s.io/kustomize/kustomize/v5@latest

Or download pre-built binaries from the releases page:

# Linux/macOS example (adjust version and arch as needed)
curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
sudo mv kustomize /usr/local/bin/

Option B: kubectl Integration

Kustomize is embedded in kubectl v1.14+. Check your version:

kubectl version --client

Version Compatibility Matrix:

Note: Standalone kustomize typically receives updates faster than kubectl-embedded versions.

Option C: Build from Source

git clone https://github.com/kubernetes-sigs/kustomize.git
cd kustomize/kustomize
make build
# Binary will be at ./bin/kustomize

3. Configuration

Directory Structure

Create a workspace with the following structure:

base/
├── kustomization.yaml
├── deployment.yaml
└── service.yaml
overlays/
├── production/
│   ├── kustomization.yaml
│   └── patch-replicas.yaml
└── staging/
    ├── kustomization.yaml
    └── patch-env.yaml

kustomization.yaml Reference

Base configuration (base/kustomization.yaml):

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml

labels:
  - includeSelectors: true
    pairs:
      app: myapp

configMapGenerator:
  - name: myapp-config
    literals:
      - KEY=value
      - LOG_LEVEL=info

Overlay configuration (overlays/production/kustomization.yaml):

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

patches:
  - path: patch-replicas.yaml

namePrefix: prod-
namespace: production

Environment Variables

• KUSTOMIZE_PLUGIN_HOME: Directory for custom plugins (default: $HOME/.config/kustomize/plugin)
• KUSTOMIZE_ENABLE_ALPHA_COMMANDS: Set to true to enable alpha features

4. Build & Run

Local Development Build

cd kustomize/kustomize

# Build binary
make build

# Run tests
make test

# Install to $GOPATH/bin
make install

Generate Manifests

Build base resources:

kustomize build base/

Build specific overlay:

kustomize build overlays/production/

Apply directly to cluster:

kustomize build overlays/production/ | kubectl apply -f -

Using with kubectl

# Equivalent to kustomize build + kubectl apply
kubectl apply -k overlays/production/

# View generated manifests
kubectl kustomize overlays/production/

5. Deployment

CI/CD Pipeline Integration

Add to GitHub Actions:

- name: Set up Kustomize
  run: |
    curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
    sudo mv kustomize /usr/local/bin/

- name: Build and Deploy
  run: |
    kustomize build overlays/production/ | kubectl apply -f -

GitOps (ArgoCD/Flux)

Kustomize is natively supported by GitOps tools. Ensure your repository contains a kustomization.yaml at the target path.

For ArgoCD, specify the path in the Application manifest:

spec:
  source:
    repoURL: https://github.com/org/repo
    targetRevision: HEAD
    path: overlays/production

Team Distribution

Pin versions in your team documentation:

# Pin to specific version for reproducibility
go install sigs.k8s.io/kustomize/kustomize/v5@v5.4.2

6. Troubleshooting

Version Mismatch Errors

Issue: Error: unable to find ... field in specified path

Solution: Ensure kustomization.yaml apiVersion matches your kustomize version. Update standalone binary or use kubectl matching your cluster version.

YAML Parsing Failures

Issue: yaml: line X: did not find expected key

Solution:

• Validate YAML indentation (2 spaces standard)
• Check for tabs vs spaces
• Use yamllint for validation:

  yamllint kustomization.yaml
  

OpenAPI Schema Errors

Issue: SchemaError or validation failures on CRDs

Solution:

• Update OpenAPI schema:

  kustomize build --enable-helm --load-restrictor LoadRestrictionsNone .
  

• For custom resources, ensure CRD schemas are available in the cluster

Plugin Loading Issues

Issue: plugin ... not found

Solution:

• Verify KUSTOMIZE_PLUGIN_HOME is set correctly
• Ensure plugin executables have correct permissions (chmod +x)
• Check plugin is compiled for your architecture

Concurrent Access Panics

Issue: Intermittent panics during parallel builds (related to schema parsing race conditions)

Solution:

• Serialize kustomize builds in CI pipelines
• Use --load-restrictor LoadRestrictionsNone with caution in concurrent environments
• Update to latest version (v5.0.0+) which includes schema locking fixes

Resource Not Found

Issue: no matches for kind ... in version ...

Solution:

• Verify Kubernetes cluster version supports the API version
• Check resources: section in kustomization.yaml includes all dependent manifests
• Ensure namespace is correctly specified if resource is namespaced