Kustomize Components

Kustomize components guide

As of v3.7.0 Kustomize supports a special type of kustomization that allows one to define reusable pieces of configuration logic that can be included from multiple overlays.

Components come in handy when dealing with applications that support multiple optional features and you wish to enable only a subset of them in different overlays, i.e., different features for different environments or audiences.

For more details regarding this feature you can read the Kustomize Components KEP.

Use case

Suppose you’ve written a very simple Web application:

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4.   name: example
  5. spec:
  6.   template:
  7.     spec:
  8.       containers:
  9.       - name: example
  10.         image: example:1.0

You want to deploy a community edition of this application as SaaS, so you add support for persistence (e.g. an external database), and bot detection (e.g. Google reCAPTCHA).

You’ve now attracted enterprise customers who want to deploy it on-premises, so you add LDAP support, and disable Google reCAPTCHA. At the same time, the devs need to be able to test parts of the application, so they want to deploy it with some features enabled and others not.

Here’s a matrix with the deployments of this application and the features enabled for each one:

External DBLDAPreCAPTCHA
Community✔️✔️
Enterprise✔️✔️
Dev✅✅✅

(✔️ enabled, ✅: optional)

So, you want to make it easy to deploy your application in any of the above three environments. Here’s how you can do this with Kustomize components: each opt-in feature gets packaged as a component, so that it can be referred to from multiple higher-level overlays.

First, define a place to work:

  1. DEMO_HOME=$(mktemp -d)

Define a common base that has a Deployment and a simple ConfigMap, that is mounted on the application’s container.

  1. BASE=$DEMO_HOME/base
  2. mkdir $BASE
  1. # $BASE/kustomization.yaml
  2. resources:
  3. - deployment.yaml
  5. configMapGenerator:
  6. - name: conf
  7.   literals:
  8.     - main.conf=|
  9.         color=cornflower_blue
  10.         log_level=info
  1. # $BASE/deployment.yaml
  2. apiVersion: apps/v1
  3. kind: Deployment
  4. metadata:
  5.   name: example
  6. spec:
  7.   template:
  8.     spec:
  9.       containers:
  10.       - name: example
  11.         image: example:1.0
  12.         volumeMounts:
  13.         - name: conf
  14.           mountPath: /etc/config
  15.       volumes:
  16.         - name: conf
  17.           configMap:
  18.             name: conf

Define an external_db component, using kind: Component, that creates a Secret for the DB password and a new entry in the ConfigMap:

  1. EXT_DB=$DEMO_HOME/components/external_db
  2. mkdir -p $EXT_DB
  1. # $EXT_DB/kustomization.yaml
  2. apiVersion: kustomize.config.k8s.io/v1alpha1  # <-- Component notation
  3. kind: Component
  5. secretGenerator:
  6. - name: dbpass
  7.   files:
  8.     - dbpass.txt
  10. patchesStrategicMerge:
  11.   - configmap.yaml
  13. patchesJson6902:
  14. - target:
  15.     group: apps
  16.     version: v1
  17.     kind: Deployment
  18.     name: example
  19.   path: deployment.yaml
  1. # $EXT_DB/deployment.yaml
  2. - op: add
  3.   path: /spec/template/spec/volumes/0
  4.   value:
  5.     name: dbpass
  6.     secret:
  7.       secretName: dbpass
  8. - op: add
  9.   path: /spec/template/spec/containers/0/volumeMounts/0
  10.   value:
  11.     mountPath: /var/run/secrets/db/
  12.     name: dbpass
  1. # $EXT_DB/configmap.yaml
  2. apiVersion: v1
  3. kind: ConfigMap
  4. metadata:
  5.   name: conf
  6. data:
  7.   db.conf: |
  8.     endpoint=127.0.0.1:1234
  9.     name=app
  10.     user=admin
  11.     pass=/var/run/secrets/db/dbpass.txt
  12. EOF

Define an ldap component, that creates a Secret for the LDAP password and a new entry in the ConfigMap:

  1. LDAP=$DEMO_HOME/components/ldap
  2. mkdir -p $LDAP
  1. # $LDAP/kustomization.yaml
  2. apiVersion: kustomize.config.k8s.io/v1alpha1
  3. kind: Component
  5. secretGenerator:
  6. - name: ldappass
  7.   files:
  8.     - ldappass.txt
  10. patchesStrategicMerge:
  11.   - configmap.yaml
  13. patchesJson6902:
  14. - target:
  15.     group: apps
  16.     version: v1
  17.     kind: Deployment
  18.     name: example
  19.   path: deployment.yaml
  1. # $LDAP/deployment.yaml
  2. - op: add
  3.   path: /spec/template/spec/volumes/0
  4.   value:
  5.     name: ldappass
  6.     secret:
  7.       secretName: ldappass
  8. - op: add
  9.   path: /spec/template/spec/containers/0/volumeMounts/0
  10.   value:
  11.     mountPath: /var/run/secrets/ldap/
  12.     name: ldappass
  1. # $LDAP/configmap.yaml
  2. apiVersion: v1
  3. kind: ConfigMap
  4. metadata:
  5.   name: conf
  6. data:
  7.   ldap.conf: |
  8.     endpoint=ldap://ldap.example.com
  9.     bindDN=cn=admin,dc=example,dc=com
  10.     pass=/var/run/secrets/ldap/ldappass.txt
  11. EOF

Define a recaptcha component, that creates a Secret for the reCAPTCHA site/secret keys and a new entry in the ConfigMap:

  1. RECAPTCHA=$DEMO_HOME/components/recaptcha
  2. mkdir -p $RECAPTCHA
  1. # $RECAPTCHA/kustomization.yaml
  2. apiVersion: kustomize.config.k8s.io/v1alpha1
  3. kind: Component
  5. secretGenerator:
  6. - name: recaptcha
  7.   files:
  8.     - site_key.txt
  9.     - secret_key.txt
  11. # Updating the ConfigMap works with generators as well.
  12. configMapGenerator:
  13. - name: conf
  14.   behavior: merge
  15.   literals:
  16.     - recaptcha.conf=|
  17.         enabled=true
  18.         site_key=/var/run/secrets/recaptcha/site_key.txt
  19.         secret_key=/var/run/secrets/recaptcha/secret_key.txt
  21. patchesJson6902:
  22. - target:
  23.     group: apps
  24.     version: v1
  25.     kind: Deployment
  26.     name: example
  27.   path: deployment.yaml
  1. # $RECAPTCHA/deployment.yaml
  2. - op: add
  3.   path: /spec/template/spec/volumes/0
  4.   value:
  5.     name: recaptcha
  6.     secret:
  7.       secretName: recaptcha
  8. - op: add
  9.   path: /spec/template/spec/containers/0/volumeMounts/0
  10.   value:
  11.     mountPath: /var/run/secrets/recaptcha/
  12.     name: recaptcha
  13. EOF

Define a community variant, that bundles the external DB and reCAPTCHA components:

  1. COMMUNITY=$DEMO_HOME/overlays/community
  2. mkdir -p $COMMUNITY
  2. # $COMMUNITY/kustomization.yaml
  3. apiVersion: kustomize.config.k8s.io/v1beta1
  4. kind: Kustomization
  6. resources:
  7.   - ../../base
  9. components:
  10.   - ../../components/external_db
  11.   - ../../components/recaptcha
  12. EOF

Define an enterprise overlay, that bundles the external DB and LDAP components:

  1. ENTERPRISE=$DEMO_HOME/overlays/enterprise
  2. mkdir -p $ENTERPRISE
  1. # $ENTERPRISE/kustomization.yaml
  2. apiVersion: kustomize.config.k8s.io/v1beta1
  3. kind: Kustomization
  5. resources:
  6.   - ../../base
  8. components:
  9.   - ../../components/external_db
  10.   - ../../components/ldap
  11. EOF

Define a dev overlay, that points to all the components and has LDAP disabled:

  1. DEV=$DEMO_HOME/overlays/dev
  2. mkdir -p $DEV
  1. # $DEV/kustomization.yaml
  2. apiVersion: kustomize.config.k8s.io/v1beta1
  3. kind: Kustomization
  5. resources:
  6.   - ../../base
  8. components:
  9.   - ../../components/external_db
  10.   #- ../../components/ldap
  11.   - ../../components/recaptcha
  12. EOF

Now, the workspace has the following directories:

  1. ├── base
  2. │   ├── deployment.yaml
  3. │   └── kustomization.yaml
  4. ├── components
  5. │   ├── external_db
  6. │   │   ├── configmap.yaml
  7. │   │   ├── dbpass.txt
  8. │   │   ├── deployment.yaml
  9. │   │   └── kustomization.yaml
  10. │   ├── ldap
  11. │   │   ├── configmap.yaml
  12. │   │   ├── deployment.yaml
  13. │   │   ├── kustomization.yaml
  14. │   │   └── ldappass.txt
  15. │   └── recaptcha
  16. │       ├── deployment.yaml
  17. │       ├── kustomization.yaml
  18. │       ├── secret_key.txt
  19. │       └── site_key.txt
  20. └── overlays
  21.     ├── community
  22.     │   └── kustomization.yaml
  23.     ├── dev
  24.     │   └── kustomization.yaml
  25.     └── enterprise
  26.         └── kustomization.yaml

With this structure, you can generate the YAML manifests for each deployment using kustomize build:

  1. kustomize build overlays/community
  2. kustomize build overlays/enterprise
  3. kustomize build overlays/dev