What Is a Kubernetes ConfigMap?

A Kubernetes ConfigMap is an API object that allows you to store data as key-value pairs. Kubernetes pods can use ConfigMaps as configuration files, environment variables or command-line arguments.

ConfigMaps allow you to decouple environment-specific configurations from containers to make applications portable. However, they are not suitable for confidential data storage. ConfigMaps are not encrypted in any way, and all data they contain is visible to anyone who can access the file. You can use Kubernetes secrets to store sensitive information.

Another potential drawback of ConfigMaps is that files must be limited to 1MB. Larger datasets may require different storage methods, such as separate file mounts, file services or databases.

Related content: read our guide to Kubernetes architecture ›

In this article, you will learn:

• Creating and Viewing ConfigMaps
• Creating a ConfigMap
• Viewing a ConfigMap
• How to Consume Kubernetes ConfigMaps
• Using ConfigMaps as Files from a Pod
• Immutable ConfigMaps
• Managing ConfigMaps
• Defining ConfigMaps as Optional
• Injecting ConfigMaps into Environment Variables
• Updating ConfigMaps

Creating and Viewing ConfigMaps

The code examples in this section were shared in the Kubernetes documentation.

Creating a ConfigMap

To create a new ConfigMap, use this kubectl command:

kubectl create configmap <name> <data-source>

The <name> is the name of the ConfigMap, which should be valid for use as a DNS subdomain. The <data-source> indicates the files or values from which ConfigMap data should be obtained.

You can create ConfigMaps based on one file, several files, directories, or env-files (lists of environment variables). The basename of each file is used as the key, and the contents of the file becomes the value.

Viewing a ConfigMap

To view the data in a ConfigMap via console output, use the command:

kubectl describe configmaps <name>

The output looks like this. Each key, which was created based on a filename, is followed by the separator “—-”. In this example the ConfigMap was created from two files, game.properties and ui.properties.

To view the ConfigMap in YAML format, use this command:

kubectl get configmaps <name> -o yaml

The output looks like this:

How to Consume Kubernetes ConfigMaps

There are three main ways to ConfigMaps can be accessed:

• Mounting a ConfigMap as a data volume
• Accessing the ConfigMap remotely by pods in the same namespace
• Defining a ConfigMap separately from pods and using them for other components of the Kubernetes cluster

Using ConfigMaps as Files from a Pod 

To ingest a ConfigMap in a volume within a pod:

1. Use an existing ConfigMap or create a new one. The same ConfigMap can be referenced by multiple pods.
2. Modify the definition of your pod, adding a volume under .spec.volumes[]. Name the volume and set a .spec.volumes[].configMap.name field to reference the ConfigMap object.
3. Add a .spec.containers[].volumeMounts[] to every container using the ConfigMap. Specify .spec.containers[].volumeMounts[].readOnly = true and set .spec.containers[].volumeMounts[].mountPath to a path where the ConfigMap should be mounted.
4. Each key in the ConfigMap will now become a file in the mounted directory. To access the data, change your command line instructions to look for files in the directory matching the keys in the ConfigMap.

See the example below.

Related content: read our guide to Kubernetes pods ›

Immutable ConfigMaps 

Immutable Secrets and ConfigMaps allow you to prevent changes to data for clusters that use ConfigMaps extensively (tens of thousands of unique mounts or more). This can protect against unintended updates that may cause an application outage, and also improve cluster performance, due to a reduced load on kube-apiserver.

The ImmutableEphemeralVolumes feature gate controls this feature – to make a ConfigMap immutable, set immutable to true, as follows:

If a ConfigMap is set as immutable, you cannot change this setting or modify the data and binaryData fields. You have to delete the ConfigMap and recreate it. Existing pods maintain mount points to deleted ConfigMaps, so it is advisable to recreate these pods.

Managing ConfigMaps

Here are a few important configuration for day-to-day management of ConfigMaps.

Defining ConfigMaps as Optional

Before a pod is deployed, the namespace must contain the ConfigMap. You can set the optional flag, to prevent pods failing to start in the absence of the ConfigMap. An admission controller prevents deployments that lack specific configuration values.

If you are using Helm, you need to ensure the ConfigMap template exists before the Deployment starts running. A lifecycle hook is usually the best way to achieve this.

Injecting ConfigMaps into Environment Variables

If your application uses system environment variables, you can create environment variables in a pod using ConfigMap data. When ConfigMap data is consumed as environment variables, the pod is not updated if the ConfigMap data is updated. You will need to restart the pod, either by deleting and creating a new pod or initiating a Deployment update.

Updating ConfigMaps

Any change to a ConfigMap requires updating the entire Deployment to ensure that the new configuration data will reach the pods.  You can use a CI/CD pipeline to update the name property of ConfigMaps, and then change the reference in the Deployment. This will trigger a normal Kubernetes update, which will refresh ConfigMaps in the deployment.