Overlays

Now that we've explored kustomization.yaml files and their various functionalities, let's see how Kustomize can be used to tailor a base Kubernetes configuration for different environments such as development, staging, and production. In this guide, we'll walk through the primary use case of Kustomize and illustrate how to implement environment-specific customizations using overlays.

A typical Kustomize project is organized into two main sections:

1. Base Configuration – Contains all shared configurations applicable across environments.
2. Overlays – Contains environment-specific customizations that are applied as patches or additional resources.

Consider the following directory structure:

k8s/
├── base/
│   ├── kustomization.yaml
│   ├── nginx-depl.yaml
│   ├── service.yaml
│   └── redis-depl.yaml
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml
    │   └── config-map.yaml
    ├── stg/
    │   ├── kustomization.yaml
    │   └── config-map.yaml
    └── prod/
        ├── kustomization.yaml
        └── config-map.yaml

In this example, the base folder holds all the default Kubernetes configurations, while each overlay folder (dev, stg, prod) includes custom configurations specific to their respective environments.

How Overlays Work

To customize your base configuration for a specific environment, you define patches within the overlay. For instance, suppose you have a base deployment file for nginx (nginx-depl.yaml) that specifies a replica count of 1. To adjust the replica count for the development environment, you can define a kustomization.yaml file in the dev overlay folder as follows:

bases:
  - ../../base
patch: |-
  - op: replace
    path: /spec/replicas
    value: 2

The corresponding base deployment configuration remains:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 1

Here, the bases property points to the relative path of the base configurations. The provided patch updates the replicas value to 2 for the development environment. The notation ../../base indicates that from the dev folder, you move up two levels (from dev to overlays, and from overlays to k8s), then enter the base directory.

For the production environment, you might require a higher replica count. The kustomization.yaml in the production overlay could look like this:

bases:
  - ../../base
patch: |-
  - op: replace
    path: /spec/replicas
    value: 3

Adding Unique Resources

Overlays are not limited to patching the base configuration. In your overlay folders, you can also introduce additional resources that do not exist in the base. For example, if the production environment requires a Grafana deployment, you can add it using the following kustomization.yaml:

bases:
  - ../../base
resources:
  - grafana-depl.yaml
patch: |-
  - op: replace
    path: /spec/replicas
    value: 2

In this configuration, not only is the replica count updated for an existing deployment, but an additional resource (grafana-depl.yaml) is also imported specifically for the production environment.

Flexible Directory Structure

Kustomize offers significant flexibility in organizing your Kubernetes configurations. You are not limited to a fixed directory layout; you can structure your base and overlay directories into subfolders by features or any other scheme that suits your project. The key is ensuring that the resources are correctly referenced in the kustomization.yaml files.

This structure demonstrates that with Kustomize, you can tailor your directory layout to best meet your operational needs, while still benefiting from a clear separation between common configurations and environment-specific customizations.

By following these practices, you can efficiently manage your Kubernetes configurations and ensure that your environments are both consistent and tailored to their specific requirements.