Skip to content
Branch: master
Find file History
Type Name Latest commit message Commit time
Failed to load latest commit information. Deprecate 'bases:' field. Jun 18, 2019
configMap.yaml demos --> examples May 25, 2018
deployment.yaml demos --> examples May 25, 2018
kustomization.yaml Revert "add apiVersion and kind to docs and examples" (#653) Dec 20, 2018
service.yaml demos --> examples May 25, 2018

Demo: hello world with variants


  1. Clone an existing configuration as a base.
  2. Customize it.
  3. Create two different overlays (staging and production) from the customized base.
  4. Run kustomize and kubectl to deploy staging and production.

First define a place to work:

DEMO_HOME=$(mktemp -d)

Alternatively, use


Establish the base

Let's run the hello service.

To use overlays to create variants, we must first establish a common base.

To keep this document shorter, the base resources are off in a supplemental data directory rather than declared here as HERE documents. Download them:

mkdir -p $BASE

curl -s -o "$BASE/#1.yaml" "\

Look at the directory:


Expect something like:

└── base
    ├── configMap.yaml
    ├── deployment.yaml
    ├── kustomization.yaml
    └── service.yaml

One could immediately apply these resources to a cluster:

kubectl apply -f $DEMO_HOME/base

to instantiate the hello service. kubectl would only recognize the resource files.

The Base Kustomization

The base directory has a kustomization file:

more $BASE/kustomization.yaml

Optionally, run kustomize on the base to emit customized resources to stdout:

kustomize build $BASE

Customize the base

A first customization step could be to change the app label applied to all resources:

sed -i.bak 's/app: hello/app: my-hello/' \

See the effect:

kustomize build $BASE | grep -C 3 app:

Create Overlays

Create a staging and production overlay:

  • Staging enables a risky feature not enabled in production.
  • Production has a higher replica count.
  • Web server greetings from these cluster variants will differ from each other.
mkdir -p $OVERLAYS/staging
mkdir -p $OVERLAYS/production

Staging Kustomization

In the staging directory, make a kustomization defining a new name prefix, and some different labels.

cat <<'EOF' >$OVERLAYS/staging/kustomization.yaml
namePrefix: staging-
  variant: staging
  org: acmeCorporation
  note: Hello, I am staging!
- ../../base
- map.yaml

Staging Patch

Add a configMap customization to change the server greeting from Good Morning! to Have a pineapple!

Also, enable the risky flag.

cat <<EOF >$OVERLAYS/staging/map.yaml
apiVersion: v1
kind: ConfigMap
  name: the-map
  altGreeting: "Have a pineapple!"
  enableRisky: "true"

Production Kustomization

In the production directory, make a kustomization with a different name prefix and labels.

cat <<EOF >$OVERLAYS/production/kustomization.yaml
namePrefix: production-
  variant: production
  org: acmeCorporation
  note: Hello, I am production!
- ../../base
- deployment.yaml

Production Patch

Make a production patch that increases the replica count (because production takes more traffic).

cat <<EOF >$OVERLAYS/production/deployment.yaml
apiVersion: apps/v1
kind: Deployment
  name: the-deployment
  replicas: 10

Compare overlays

DEMO_HOME now contains:

  • a base directory - a slightly customized clone of the original configuration, and

  • an overlays directory, containing the kustomizations and patches required to create distinct staging and production variants in a cluster.

Review the directory structure and differences:


Expecting something like:

├── base
│   ├── configMap.yaml
│   ├── deployment.yaml
│   ├── kustomization.yaml
│   └── service.yaml
└── overlays
    ├── production
    │   ├── deployment.yaml
    │   └── kustomization.yaml
    └── staging
        ├── kustomization.yaml
        └── map.yaml

Compare the output directly to see how staging and production differ:

diff \
  <(kustomize build $OVERLAYS/staging) \
  <(kustomize build $OVERLAYS/production) |\

The first part of the difference output should look something like

<   altGreeting: Have a pineapple!
<   enableRisky: "true"
>   altGreeting: Good Morning!
>   enableRisky: "false"
<     note: Hello, I am staging!
>     note: Hello, I am production!
<     variant: staging
>     variant: production


The individual resource sets are:

kustomize build $OVERLAYS/staging
kustomize build $OVERLAYS/production

To deploy, pipe the above commands to kubectl apply:

kustomize build $OVERLAYS/staging |\
    kubectl apply -f -
kustomize build $OVERLAYS/production |\
   kubectl apply -f -
You can’t perform that action at this time.