Skip to content
Branch: master
Find file Copy path
Find file Copy path
7 contributors

Users who have contributed to this file

@Liujingfang1 @monopole @zoncoen @knqyf263 @schweikert @seriousben @ahmetb
215 lines (169 sloc) 5.8 KB

ConfigMap generation and rolling updates

Kustomize provides two ways of adding ConfigMap in one kustomization, either by declaring ConfigMap as a resource or declaring ConfigMap from a ConfigMapGenerator. The formats inside kustomization.yaml are

# declare ConfigMap as a resource
- configmap.yaml

# declare ConfigMap from a ConfigMapGenerator
- name: a-configmap
    # configfile is used as key
    - configs/configfile
    # configkey is used as key
    - configkey=configs/another_configfile

The ConfigMaps declared as resource are treated the same way as other resources. Kustomize doesn't append any hash to the ConfigMap name. The ConfigMap declared from a ConfigMapGenerator is treated differently. A hash is appended to the name and any change in the ConfigMap will trigger a rolling update.

In this demo, the same hello_world is used while the ConfigMap declared as [resources] is replaced by a ConfigMap declared from a ConfigmapGenerator. The change in this ConfigMap will result in a hash change and a rolling update.

Establish base and staging

Establish the base with a configMapGenerator

DEMO_HOME=$(mktemp -d)

mkdir -p $BASE

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

cat <<'EOF' >$BASE/kustomization.yaml
  app: hello
- deployment.yaml
- service.yaml
- name: the-map	
    - altGreeting=Good Morning!	
    - enableRisky="false"

Establish the staging with a patch applied to the ConfigMap

mkdir -p $OVERLAYS/staging

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

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


The hello-world deployment running in this cluster is configured with data from a configMap.

The deployment refers to this map by name:

grep -C 2 configMapKeyRef $BASE/deployment.yaml

Changing the data held by a live configMap in a cluster is considered bad practice. Deployments have no means to know that the configMaps they refer to have changed, so such updates have no effect.

The recommended way to change a deployment's configuration is to

  1. create a new configMap with a new name,
  2. patch the deployment, modifying the name value of the appropriate configMapKeyRef field.

This latter change initiates rolling update to the pods in the deployment. The older configMap, when no longer referenced by any other resource, is eventually garbage collected.

How this works with kustomize

The staging variant here has a configMap patch:

cat $OVERLAYS/staging/map.yaml

This patch is by definition a named but not necessarily complete resource spec intended to modify a complete resource spec.

The ConfigMap it modifies is declared from a configMapGenerator.

grep -C 4 configMapGenerator $BASE/kustomization.yaml

For a patch to work, the names in the metadata/name fields must match.

However, the name values specified in the file are not what gets used in the cluster. By design, kustomize modifies names of ConfigMaps declared from ConfigMapGenerator. To see the names ultimately used in the cluster, just run kustomize:

kustomize build $OVERLAYS/staging |\
    grep -B 8 -A 1 staging-the-map

The configMap name is prefixed by staging-, per the namePrefix field in $OVERLAYS/staging/kustomization.yaml.

The configMap name is suffixed by -v1, per the nameSuffix field in $OVERLAYS/staging/kustomization.yaml.

The suffix to the configMap name is generated from a hash of the maps content - in this case the name suffix is k25m8k5k5m:

kustomize build $OVERLAYS/staging | grep k25m8k5k5m

Now modify the map patch, to change the greeting the server will use:

sed -i.bak 's/pineapple/kiwi/' $OVERLAYS/staging/map.yaml

See the new greeting:

kustomize build $OVERLAYS/staging |\
  grep -B 2 -A 3 kiwi

Run kustomize again to see the new configMap names:

kustomize build $OVERLAYS/staging |\
    grep -B 8 -A 1 staging-the-map

Confirm that the change in configMap content resulted in three new names ending in cd7kdh48fd - one in the configMap name itself, and two in the deployment that uses the map:

test 3 == \
  $(kustomize build $OVERLAYS/staging | grep cd7kdh48fd | wc -l); \
  echo $?

Applying these resources to the cluster will result in a rolling update of the deployments pods, retargetting them from the k25m8k5k5m maps to the cd7kdh48fd maps. The system will later garbage collect the unused maps.


To rollback, one would undo whatever edits were made to the configuation in source control, then rerun kustomize on the reverted configuration and apply it to the cluster.

You can’t perform that action at this time.