Skip to main content
Base overlays provide the foundation configurations for all components in the cluster. They define default settings that can be customized by environment-specific overlays.

​
Directory Structure

The base overlays are located in overlays/base/ and organized by component: 
overlays/base/
├── bind9/                    # DNS server
├── cert-manager/             # TLS certificate management
├── grafana/                  # Observability stack
│   ├── grafana-alloy/       # Telemetry collection
│   ├── grafana-loki/        # Log aggregation
│   └── grafana-operator/    # Grafana instance management
├── kgateway/                 # Kubernetes Gateway API
├── knowledge-hub/            # Knowledge base application
├── metallb/                  # Load balancer
├── metrics-server/           # Resource metrics
├── n8n/                      # Workflow automation
├── prometheus/               # Monitoring stack
├── sealed-secrets/           # Secret encryption
├── tailscale/                # VPN operator
├── tools/                    # Utility applications
│   ├── http-echo/
│   ├── mysql/
│   └── no/
├── version-management/       # Version tracking application
└── yopass/                   # Secret sharing

​
Base Overlay Anatomy

Each base overlay typically contains:
  1. kustomization.yaml - Defines resources to include
  2. namespace.yaml - Namespace definition (if needed)
  3. helm-repository.yaml - Helm chart repository (for Helm-based apps)
  4. helm-release.yaml or helmrelease.yaml - HelmRelease definition
  5. deployment.yaml - Deployment manifest (for non-Helm apps)
  6. service.yaml - Service definition (for non-Helm apps)

​
Example: cert-manager Base

overlays/base/cert-manager/kustomization.yaml
resources:
  - namespace.yaml
  - helm-repository.yaml
  - helm-release.yaml

​
Infrastructure Components

​
Helm-Based Components

These components use Helm charts and include HelmRepository + HelmRelease:

cert-manager

TLS certificate management with Let’s Encrypt integration

grafana-operator

Manages Grafana instances using Kubernetes operators

grafana-loki

Log aggregation and storage system

grafana-alloy

Collects and forwards telemetry data

metallb

Provides LoadBalancer services for bare-metal clusters

kgateway

Kubernetes Gateway API implementation

metrics-server

Provides resource metrics API for HPA and kubectl top

prometheus

Complete monitoring stack with Alertmanager

sealed-secrets

Encrypts secrets for safe storage in Git

tailscale

VPN operator for secure networking

n8n

Workflow automation and integration platform

​
Kubernetes Manifest Components

These components use plain Kubernetes manifests:

bind9

DNS server deployment with ConfigMap-based configuration

knowledge-hub

Knowledge base application with Deployment + Service

version-management

Application version tracking system

yopass

Secure secret sharing with time-limited access

​
Kustomization.yaml Structure

Base kustomization files define which resources to include:

​
Simple Example

resources:
  - namespace.yaml
  - helm-repository.yaml
  - helm-release.yaml

​
With Multiple Components

overlays/kimawesome/infrastructure/observability/kustomization.yaml
namespace: observability
resources:
  - namespace.yaml
  - grafana-alloy
  - prometheus
  - ../../../base/grafana/helm-repository.yaml
  - grafana-operator
  - monitors-infrastructure/kustomization.flux.yaml
  - grafana-loki

​
With Namespace Transformation

namespace: my-namespace
resources:
  - ../../../base/cert-manager
All resources from the base will be created in my-namespace unless they explicitly specify a namespace.

​
Using Base Overlays

Environment overlays reference base overlays in their kustomization: 
# overlays/kimawesome/infrastructure/cert-manager/kustomization.yaml
namespace: cert-manager
resources:
  - ../../../base/cert-manager

​
Customization Patterns

​
Shared Helm Repository

Multiple components can share a HelmRepository: 
# overlays/base/grafana/helm-repository.yaml
apiVersion: source.toolkit.fluxcd.io/v1
kind: HelmRepository
metadata:
  name: grafana
  namespace: flux-system
spec:
  interval: 24h
  url: https://grafana.github.io/helm-charts
Referenced by multiple HelmReleases:
  • grafana-operator
  • grafana-loki
  • grafana-alloy

​
Minimal Configuration

Base overlays provide minimal, production-ready defaults. Environment overlays add specific configuration: Base (minimal): 
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: metallb
spec:
  chart:
    spec:
      chart: metallb
      version: "=0.15.3"
  interval: 24h
Environment (adds IPPool): 
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: default-pool
  namespace: metallb-system
spec:
  addresses:
    - 192.168.1.100-192.168.1.110

​
Benefits of Base Overlays

Define each component once, reuse across all environments. Changes to base configurations automatically propagate.
All environments start with the same base configuration, ensuring consistency across dev, staging, and production.
Base overlays contain application definitions. Environment overlays contain environment-specific configuration.
Update chart versions or configurations in one place. All environments benefit from the update.
Base configurations can be tested independently before applying to production environments.

​
Best Practices

  1. Keep bases minimal - Only include essential configuration
  2. Use semantic versioning - Pin exact chart versions in bases
  3. Document dependencies - Use comments to explain why specific settings exist
  4. Avoid environment-specific values - Move those to environment overlays
  5. Group related components - Use subdirectories for component families (e.g., grafana/)
  6. Include all required resources - Namespace, HelmRepository, and HelmRelease

​
Viewing Base Configurations

To see what a base overlay will deploy: 
kubectl kustomize overlays/base/cert-manager/
kubectl kustomize overlays/base/prometheus/
To see how an environment uses a base: 
kubectl kustomize overlays/kimawesome/infrastructure/cert-manager/

Build docs developers (and LLMs) love

Get started for freeTalk to us