2.7. Configuration

In this lab, you keep configuration and passwords out of the container image and pass them to your Pods as environment variables and as files.

Step 1: Create a ConfigMap

Create a directory for the files of this lab and change into it:

mkdir -p ~/labs/2.7
cd ~/labs/2.7

Create the file app-config.yaml in ~/labs/2.7 with a ConfigMap that holds two settings:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  GREETING: Hello from the ConfigMap
  LOG_LEVEL: debug

Create the ConfigMap:

kubectl apply -f app-config.yaml
configmap/app-config created

List the ConfigMaps:

kubectl get configmaps
NAME               DATA   AGE
app-config         2      0s
kube-root-ca.crt   1      4h

Show its content:

kubectl describe configmap app-config
Name:         app-config
Namespace:    default
...
Data
====
GREETING:
----
Hello from the ConfigMap

LOG_LEVEL:
----
debug
...

Explanation

A ConfigMap stores configuration as key-value pairs under data. DATA 2 is the number of keys. Kubernetes creates the ConfigMap kube-root-ca.crt in every namespace by itself. It holds the certificate of the cluster.


Step 2: Create a Secret

Create the file app-secret.yaml with a Secret for a database password:

apiVersion: v1
kind: Secret
metadata:
  name: app-secret
stringData:
  DB_PASSWORD: s3cr3t

Create the Secret:

kubectl apply -f app-secret.yaml
secret/app-secret created

Show how Kubernetes stores it:

kubectl get secret app-secret -o yaml
apiVersion: v1
data:
  DB_PASSWORD: czNjcjN0
kind: Secret
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"v1","kind":"Secret","metadata":{"annotations":{},"name":"app-secret","namespace":"default"},"stringData":{"DB_PASSWORD":"s3cr3t"}}
  ...
  name: app-secret
  namespace: default
  ...
type: Opaque

Decode the stored value:

echo czNjcjN0 | base64 --decode
s3cr3t

Explanation

A Secret works like a ConfigMap, but is meant for sensitive values. Under stringData, you write the values in plain text. -o yaml prints the complete resource as Kubernetes stores it: the values are base64-encoded under data. type: Opaque is the default type for arbitrary values.

Base64 is an encoding, not an encryption: anyone who may read the Secret can decode its values. The annotation last-applied-configuration even contains the password in plain text: kubectl apply stores the whole manifest there. That’s why access to Secrets is usually restricted.


Step 3: Use Them as Environment Variables

Create the file env-demo.yaml with a Pod that prints three environment variables:

apiVersion: v1
kind: Pod
metadata:
  name: env-demo
spec:
  restartPolicy: Never
  containers:
    - name: app
      image: busybox:1.37
      command: ["sh", "-c", "echo Greeting: $GREETING; echo Log level: $LOG_LEVEL; echo Password: $DB_PASSWORD"]
      envFrom:
        - configMapRef:
            name: app-config
        - secretRef:
            name: app-secret

Create the Pod:

kubectl apply -f env-demo.yaml

Wait a few seconds and show its output:

kubectl logs env-demo
Greeting: Hello from the ConfigMap
Log level: debug
Password: s3cr3t

If kubectl logs reports that the container is waiting to start, wait a moment and repeat the command.

Explanation

envFrom turns every key of the ConfigMap and the Secret into an environment variable with the same name. Inside the container, the Secret value is plain text again.

Kubernetes sets the environment variables when the container starts. If you change the ConfigMap later, a running container keeps the old values until it’s started again.


Step 4: Mount Them as Files

Create the file files-demo.yaml with a Pod that mounts the ConfigMap and the Secret as directories:

apiVersion: v1
kind: Pod
metadata:
  name: files-demo
spec:
  restartPolicy: Never
  containers:
    - name: app
      image: busybox:1.37
      command: ["sh", "-c", "ls /config /secret; cat /config/GREETING; echo; cat /secret/DB_PASSWORD"]
      volumeMounts:
        - name: config
          mountPath: /config
        - name: secret
          mountPath: /secret
  volumes:
    - name: config
      configMap:
        name: app-config
    - name: secret
      secret:
        secretName: app-secret

Create the Pod:

kubectl apply -f files-demo.yaml

Wait a few seconds and show its output:

kubectl logs files-demo
/config:
GREETING
LOG_LEVEL

/secret:
DB_PASSWORD
Hello from the ConfigMap
s3cr3t

If kubectl logs reports that the container is waiting to start, wait a moment and repeat the command.

Explanation

Every key becomes a file with the key as its name and the value as its content. volumes makes the ConfigMap and the Secret available to the Pod, volumeMounts mounts them into directories of the container. Note the different field names: configMap takes name, secret takes secretName.

Files suit applications that read a configuration file, e.g. an application.properties or a certificate.

Secrets as files are the safer choice

Your Pod env-demo printed the password to its log. Applications do the same by accident, e.g. in error reports that include the environment. That’s why security guidelines like the CIS Kubernetes Benchmark recommend mounting Secrets as files. The application has to support reading its settings from files, though.


Optional Tasks

Finished early? Try these tasks. The following labs don’t depend on them. Each task lists the commands you need. Open the solution if you get stuck.

Task 1: Live Update

Serve a web page from a ConfigMap with nginx, then change the page in the ConfigMap. Does nginx need a restart? Mount the ConfigMap at /usr/share/nginx/html, the directory from which nginx serves the file index.html.

You know all the commands you need: kubectl port-forward works with a Pod as well, e.g. pod/web.

Solution

Create the file web-content.yaml in ~/labs/2.7 with the page:

apiVersion: v1
kind: ConfigMap
metadata:
  name: web-content
data:
  index.html: |
    <h1>Version 1</h1>

Create the file web.yaml in ~/labs/2.7 with the Pod:

apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  containers:
    - name: nginx
      image: nginx:1.29
      volumeMounts:
        - name: content
          mountPath: /usr/share/nginx/html
  volumes:
    - name: content
      configMap:
        name: web-content

| starts a multi-line value: the content of the file index.html. Create the ConfigMap:

kubectl apply -f ~/labs/2.7/web-content.yaml
configmap/web-content created

Create the Pod:

kubectl apply -f ~/labs/2.7/web.yaml
pod/web created

Check the Pod:

kubectl get pod web
NAME   READY   STATUS    RESTARTS   AGE
web    1/1     Running   0          5s

If the Pod isn’t Running yet, wait a moment and repeat the command. Forward a port to the Pod. The command keeps running:

kubectl port-forward pod/web 8080:80
Forwarding from 127.0.0.1:8080 -> 80
Forwarding from [::1]:8080 -> 80

In a second terminal, call the page:

curl http://localhost:8080
<h1>Version 1</h1>

Change Version 1 to Version 2 in web-content.yaml and apply it:

kubectl apply -f ~/labs/2.7/web-content.yaml

It takes about a minute until nginx serves the new page. Call it every few seconds until it does:

curl http://localhost:8080
<h1>Version 2</h1>

nginx serves the new page without a restart: Kubernetes updates mounted ConfigMaps in running Pods. Environment variables don’t change that way.

In the first terminal, stop the port forwarding with Ctrl+C.

Task 2: Set in Stone

Mark the ConfigMap app-config as unchangeable with the top-level field immutable: true. Then try to change LOG_LEVEL to info.

You know all the commands you need.

Solution

Add the field to app-config.yaml, at the same level as data:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  GREETING: Hello from the ConfigMap
  LOG_LEVEL: debug
immutable: true

Apply it:

kubectl apply -f ~/labs/2.7/app-config.yaml
configmap/app-config configured

Change LOG_LEVEL to info and apply it again:

kubectl apply -f ~/labs/2.7/app-config.yaml
The ConfigMap "app-config" is invalid: data: Forbidden: field is immutable when `immutable` is set

Kubernetes rejects every change. To change an immutable ConfigMap, you delete it and create it again. Immutable ConfigMaps protect against accidental changes and spare the cluster from watching them for updates.

Task 3: Missing Piece

Create a Pod that loads its environment variables from a ConfigMap feature-flags, before the ConfigMap exists. What does Kubernetes report, and what happens once you create the ConfigMap?

You know all the commands you need.

Solution

Create the file missing.yaml in ~/labs/2.7:

apiVersion: v1
kind: Pod
metadata:
  name: missing
spec:
  restartPolicy: Never
  containers:
    - name: app
      image: busybox:1.37
      command: ["sh", "-c", "echo Feature: $FEATURE"]
      envFrom:
        - configMapRef:
            name: feature-flags

Create the Pod:

kubectl apply -f ~/labs/2.7/missing.yaml
pod/missing created

Check its status:

kubectl get pod missing
NAME      READY   STATUS                       RESTARTS   AGE
missing   0/1     CreateContainerConfigError   0          8s

If the status is still ContainerCreating, wait a moment and repeat the command.

kubectl describe pod missing shows the cause in its events: Error: configmap "feature-flags" not found. Create the file feature-flags.yaml in ~/labs/2.7:

apiVersion: v1
kind: ConfigMap
metadata:
  name: feature-flags
data:
  FEATURE: dark-mode

Create the ConfigMap:

kubectl apply -f ~/labs/2.7/feature-flags.yaml

Wait about ten seconds and show the output of the Pod:

kubectl logs missing
Feature: dark-mode

Kubernetes keeps retrying to start the container and succeeds as soon as the ConfigMap exists.


Clean Up

Delete all resources of this lab, since the following labs don’t need them:

kubectl delete -f ~/labs/2.7/
configmap "app-config" deleted from default namespace
secret "app-secret" deleted from default namespace
pod "env-demo" deleted from default namespace
pod "files-demo" deleted from default namespace

If you did the optional tasks, their ConfigMaps and Pods are deleted as well.