kustomize

What this skill does

# Kustomize

Customize Kubernetes resources declaratively without templating.

## When to Use This Skill

Use this skill when:
- Managing Kubernetes configs across environments
- Patching existing manifests without modification
- Creating configuration variants from bases
- Customizing third-party manifests
- Preferring declarative over templating approach

## Prerequisites

- kubectl 1.14+ (includes kustomize)
- Or standalone kustomize CLI
- Basic Kubernetes manifest knowledge

## Directory Structure

```
myapp/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── configmap.yaml
└── overlays/
    ├── development/
    │   ├── kustomization.yaml
    │   └── replica-patch.yaml
    ├── staging/
    │   ├── kustomization.yaml
    │   └── namespace.yaml
    └── production/
        ├── kustomization.yaml
        ├── replica-patch.yaml
        └── resource-patch.yaml
```

## Base Configuration

### kustomization.yaml

```yaml
# base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml

commonLabels:
  app: myapp
  
commonAnnotations:
  managed-by: kustomize
```

### Base Resources

```yaml
# base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: myapp:latest
        ports:
        - containerPort: 8080
        resources:
          requests:
            memory: "64Mi"
            cpu: "100m"
          limits:
            memory: "128Mi"
            cpu: "200m"
```

## Overlays

### Development Overlay

```yaml
# overlays/development/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

namespace: myapp-dev

namePrefix: dev-

commonLabels:
  environment: development

images:
  - name: myapp
    newTag: dev-latest
```

### Production Overlay

```yaml
# overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

namespace: myapp-prod

namePrefix: prod-

commonLabels:
  environment: production

replicas:
  - name: myapp
    count: 5

images:
  - name: myapp
    newName: registry.example.com/myapp
    newTag: v2.0.0

patches:
  - path: resource-patch.yaml
```

## Patching

### Strategic Merge Patch

```yaml
# overlays/production/resource-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: myapp
        resources:
          requests:
            memory: "256Mi"
            cpu: "500m"
          limits:
            memory: "512Mi"
            cpu: "1000m"
```

### JSON Patch

```yaml
# kustomization.yaml
patches:
  - target:
      kind: Deployment
      name: myapp
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5
      - op: add
        path: /spec/template/spec/containers/0/env
        value:
          - name: LOG_LEVEL
            value: info
```

### Inline Patches

```yaml
# kustomization.yaml
patches:
  - patch: |-
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: myapp
      spec:
        replicas: 3
    target:
      kind: Deployment
      name: myapp
```

## Configuration Generation

### ConfigMap Generator

```yaml
# kustomization.yaml
configMapGenerator:
  - name: myapp-config
    literals:
      - APP_ENV=production
      - LOG_LEVEL=info
    files:
      - config.yaml
    envs:
      - config.env
    options:
      disableNameSuffixHash: false
```

### Secret Generator

```yaml
# kustomization.yaml
secretGenerator:
  - name: myapp-secrets
    literals:
      - api-key=secret123
    files:
      - tls.crt
      - tls.key
    type: kubernetes.io/tls
```

## Image Transformations

```yaml
# kustomization.yaml
images:
  # Change tag
  - name: myapp
    newTag: v2.0.0
  
  # Change registry
  - name: myapp
    newName: registry.example.com/myapp
    newTag: v2.0.0
  
  # Use digest
  - name: myapp
    digest: sha256:abc123...
```

## Resource Transformations

### Name Prefix/Suffix

```yaml
# kustomization.yaml
namePrefix: prod-
nameSuffix: -v2
```

### Namespace

```yaml
# kustomization.yaml
namespace: production
```

### Labels and Annotations

```yaml
# kustomization.yaml
commonLabels:
  app.kubernetes.io/name: myapp
  app.kubernetes.io/environment: production

commonAnnotations:
  example.com/owner: team-a
```

### Replicas

```yaml
# kustomization.yaml
replicas:
  - name: myapp
    count: 5
  - name: worker
    count: 3
```

## Components

```yaml
# components/monitoring/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component

resources:
  - servicemonitor.yaml

patches:
  - patch: |-
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: myapp
      spec:
        template:
          metadata:
            annotations:
              prometheus.io/scrape: "true"
              prometheus.io/port: "8080"
```

```yaml
# overlays/production/kustomization.yaml
components:
  - ../../components/monitoring
```

## Remote Resources

```yaml
# kustomization.yaml
resources:
  # Remote Git repository
  - https://github.com/org/manifests//base?ref=v1.0.0
  
  # Remote URL
  - https://raw.githubusercontent.com/org/repo/main/deployment.yaml
```

## Commands

```bash
# Build and view output
kubectl kustomize overlays/production

# Apply to cluster
kubectl apply -k overlays/production

# Delete resources
kubectl delete -k overlays/production

# View diff
kubectl diff -k overlays/production

# Build with standalone kustomize
kustomize build overlays/production

# Build and apply
kustomize build overlays/production | kubectl apply -f -
```

## Helm Chart Integration

```yaml
# kustomization.yaml
helmCharts:
  - name: prometheus
    repo: https://prometheus-community.github.io/helm-charts
    version: 25.0.0
    releaseName: prometheus
    namespace: monitoring
    valuesFile: values.yaml
    includeCRDs: true
```

## Variable Substitution

```yaml
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml

replacements:
  - source:
      kind: ConfigMap
      name: myapp-config
      fieldPath: data.APP_VERSION
    targets:
      - select:
          kind: Deployment
          name: myapp
        fieldPaths:
          - spec.template.spec.containers.[name=myapp].image
        options:
          delimiter: ':'
          index: 1
```

## Common Issues

### Issue: Name Hash Conflicts
**Problem**: Resources not updating when ConfigMap changes
**Solution**: Enable name suffix hash (default) or use replacement

### Issue: Patch Not Applying
**Problem**: Strategic merge patch doesn't work
**Solution**: Verify resource names match, use JSON patch for complex changes

### Issue: Remote Resource Fails
**Problem**: Cannot fetch remote resources
**Solution**: Check URL, verify ref/tag exists, ensure network access

### Issue: Label Selector Mismatch
**Problem**: commonLabels breaks selectors
**Solution**: Use includeSelectors: false or exclude specific resources

```yaml
commonLabels:
  app: myapp
configurations:
  - labelExclusions.yaml
```

## Best Practices

- Keep base manifests environment-agnostic
- Use overlays for environment-specific config
- Prefer strategic merge patches for simple changes
- Use components for optional features
- Pin remote resource versions
- Enable ConfigMap/Secret hash suffixes
- Document overlay structure in README
- Test builds before applying

## Related Skills

- [kubernetes-ops](../kubernetes-ops/) - K8s fundamentals
- [helm-charts](../helm-charts/) - Helm alternative
- [argocd-gitops](../argocd-gitops/) - GitOps deployment