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.
|ConfigMap Data Source||Example kubectl command|
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:
- Use an existing ConfigMap or create a new one. The same ConfigMap can be referenced by multiple pods.
- Modify the definition of your pod, adding a volume under
.spec.volumes.Name the volume and set a
.spec.volumes.configMap.namefield to reference the ConfigMap object.
- Add a
.spec.containers.volumeMountsto every container using the ConfigMap. Specify
.spec.containers.volumeMounts.readOnly = trueand set
.spec.containers.volumeMounts.mountPathto a path where the ConfigMap should be mounted.
- 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 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.
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
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.
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.
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.