Ultimate Guide to ConfigMaps in Kubernetes

How do you manage your application's configuration? For a Python or Node.js application, where do you store configuration? How do you set connection strings, analytics keys, and service URLs?

If you're using Kubernetes, the answer is ConfigMaps.

With this guide, tutorial, and examples, you’ll learn how to use ConfigMaps in Kubernetes. We’ll teach you how to create ConfigMaps. Then, you'll learn how to mount them in volumes and use them as environment variables.

What is a ConfigMap in Kubernetes?

A ConfigMap is a dictionary of configuration settings. This dictionary consists of key-value pairs of strings. Kubernetes provides these values to your containers. Like with other dictionaries (maps, hashes, ...) the key lets you get and set the configuration value.

Why would you use a ConfigMap in Kubernetes?

Use a ConfigMap to keep your application code separate from your configuration.

It is an important part of creating a Twelve-Factor Application.

This lets you change easily configuration depending on the environment (development, production, testing) and to dynamically change configuration at runtime.

What is a ConfigMap used for?

A ConfigMap stores configuration settings for your code. Store connection strings, public credentials, hostnames, and URLs in your ConfigMap.

How does a ConfigMap work?

Here's a quick animation I made showing how a ConfigMap works in Kubernetes.

First, you have multiple ConfigMaps, one for each environment.

Second, a ConfigMap is created and added to the Kubernetes cluster.

Third, containers in the Pod reference the ConfigMap and use its values.

How to create a ConfigMap in YAML? How to mount a ConfigMap as a Volume?

Defining the ConfigMap in YAML and mounting it as a Volume is the easiest way to use ConfigMaps.

The official documentation waaay overcomplicates this.

Here's the method I use. It's simpler and easier for when you're starting to learn about ConfigMaps.

My favourite way is to define the ConfigMap dictionary in a YAML file.

This lets you create that ConfigMap like any other Kubernetes resources using `kubectl apply -f $file.yaml`. After that, you mount the ConfigMap as a Volume in your Pod's YAML specification.

1. Define the ConfigMap in a YAML file.

Create a YAML file setting the key-value pairs for your ConfigMap.

2. Create the ConfigMap in your Kubernetes cluster

Create the ConfigMap using the command kubectl apply -f config-map.yaml

3. Mount the ConfigMap through a Volume

Each property name in this ConfigMap becomes a new file in the mounted directory (`/etc/config`) after you mount it.

Attach to the created Pod using `kubectl exec -it pod-using-configmap sh`. Then run `ls /etc/config` and you can see each key from the ConfigMap added as a file in the directory. Use `cat` to look at the contents of each file and you’ll see the values from the ConfigMap.

You can then read the configuration settings using Python/Node.js/PHP from this file.

How to use a ConfigMap with Environment Variables and `envFrom`?

You can consume a ConfigMap via environment variables in a running container using the `envFrom` property.

1. Create the ConfigMap

Create the ConfigMap using the example from the previous section.

2. Add the `envFrom` property to your Pod's YAML

Set the `envFrom` key in each container to an object containing the list of ConfigMaps you want to include.

Attach to the created Pod using `kubectl exec -it pod-env-var sh`. Then run `env` and see that each key from the ConfigMap is now available as an environment variable.

What are the other ways to create and use ConfigMaps?

There are three other ways to create ConfigMaps using the `kubectl create configmap` command. I prefer the methods used above, but here are your options.

1. Use the contents of an entire directory with kubectl create configmap my-config --from-file=./my/dir/path/
2. Use the contents of a file or specific set of files with kubectl create configmap my-config --from-file=./my/file.txt
3. Use literal key-value pairs defined on the command line with kubectl create configmap my-config --from-literal=key1=value1 --from-literal=key2=value2

You can get more information about this command using kubectl create configmap --help.

In the guide above, we covered both of the main ways to consume and use ConfigMaps – by mounting them into a file or injecting them as environment variables.

What questions do you have?

Send me any questions you have via Twitter on @_matthewpalmer or through email at [email protected] and I'll give you answers.