Kubernetes Configmap: Our Complete Guide

Mastering ConfigMaps in Kubernetes is crucial for anyone looking to streamline their container orchestration processes. This guide dives into the pivotal role of ConfigMaps in Kubernetes, detailing their function in managing non-confidential data as key-value pairs. We will explore their crucial role in decoupling configuration from container images and enhancing adaptability across various environments like development and production. Additionally, the guide contrasts ConfigMaps with Kubernetes Secrets to illuminate their distinct roles in data management. Through a series of practical steps and best practices, you will gain insights into creating, implementing, and managing ConfigMaps effectively, ensuring streamlined deployment and management within your Kubernetes cluster.

Morgan Perry

Morgan Perry

November 23, 2023 · 8 min read
Kubernetes Configmap: Our Complete Guide - Qovery

Let’s start with their importance in the Kubernetes ecosystem.

#The value of Kubernetes Configmap 

#Definition and Role in Kubernetes

Kubernetes ConfigMap emerged as a fundamental tool. Essentially, a ConfigMap is a Kubernetes object used to store non-confidential data in key-value pairs. This data can be consumed by pods or other Kubernetes objects in your cluster. The primary role of ConfigMap is to separate configuration details from the container image, thus enhancing flexibility and reusability. For instance, you can have different ConfigMaps for distinct environments like development, testing, and production, each holding appropriate settings for that environment.

ConfigMap simplifies application configuration and management. Instead of hardcoding configuration data within your application or Docker container, you can externalize it using a ConfigMap. This approach not only makes updating configuration easier but also allows your applications to be environment-agnostic, enhancing their portability across different Kubernetes setups.

  How does Configmap work. Source: https://www.weave.works/blog/kubernetes-configmap
  How does Configmap work. Source: https://www.weave.works/blog/kubernetes-configmap

#Creating and implementing Configmaps

#A. Steps to create a Configmap using kubectl

ConfigMaps in Kubernetes serves as a method to inject configuration data into containers. To create a ConfigMap using kubectl, follow these steps:

  1. Define Your ConfigMap: Start by defining the ConfigMap in a YAML file. This involves specifying the apiVersion, kind, and metadata. Within the data section, add your configuration as key-value pairs. Each key under data represents a different configuration item.
apiVersion: v1
kind: ConfigMap
  name: example-configmap
  config.json: |
      "key": "value",
      "service": "example"
  1. Create ConfigMap in Cluster: Use the kubectl create command to add your ConfigMap to the Kubernetes cluster. For example: kubectl create -f yourconfigmap.yaml. This command reads your YAML file and creates a ConfigMap in your specified environment.
  2. Verify Creation: Ensure your ConfigMap is correctly created with kubectl get configmaps, which lists all ConfigMaps in your current namespace.

#B. Using Configmap in pods

To deploy configurations using ConfigMaps in pods:

  1. Reference ConfigMap in Pod Specification: In your pod's YAML file, under spec, use env to define environment variables. Reference the ConfigMap with 'valueFrom' and 'configMapKeyRef' to assign values from your ConfigMap to the container's environment variables.
apiVersion: v1
kind: Pod
  name: example-pod
    - name: example-container
      image: example-image
        - name: SPECIAL_CONFIG
              name: example-configmap
              key: config.json
Mounting a ConfigMap as a volume in Kubernetes Pod. Source: https://reachmnadeem.wordpress.com/2019/07/31/kubernetes-configmap-file-volume-mount/ 
Mounting a ConfigMap as a volume in Kubernetes Pod. Source: https://reachmnadeem.wordpress.com/2019/07/31/kubernetes-configmap-file-volume-mount/ 
  1. Mount ConfigMap as Volume: For more complex configurations, you can mount the entire ConfigMap as a volume. Under volumes, reference your ConfigMap, and use 'volumeMounts' in the container spec to specify the 'mountPath'.
- name: config-volume
  mountPath: /etc/config
- name: config-volume
    name: example-configmap

#C. Example code snippets and best practices

  • Keep Configmaps and code separate: Avoid hardcoding configuration data in your code or image. Instead, use ConfigMaps to keep your application code and configuration separate.

Example code snippet:

 # pod.yaml
apiVersion: v1
kind: Pod
  name: my-pod
  - name: my-container
image: my-image
- configMapRef:
     name: my-configmap

This snippet shows how to use envFrom to inject all key-value pairs from my-configmap into the pod's environment variables, keeping the configuration separate from the code.

  • Use multiple configmaps: For complex applications, consider using multiple ConfigMaps. This approach allows you to organize configuration data logically and maintain cleaner code.

Example code snippet:

# multiple-configmaps.yaml
apiVersion: v1
kind: Pod
  name: complex-pod
  - name: complex-container
image: complex-image
- configMapRef:
     name: database-config
- configMapRef:
     name: feature-toggle-config

This example demonstrates referencing multiple ConfigMaps (database-config and feature-toggle-config) in a single Sod, showcasing how to manage different aspects of configuration separately.

  • Managing changes: When updating ConfigMaps, remember that changes don’t automatically propagate to pods. You may need to restart the affected services for the updated configurations to take effect.

Example Code Snippet:

# Update ConfigMap
kubectl create configmap my-configmap --from-file=my-config.properties --dry-run=client -o yaml | kubectl apply -f -
# Restart pods to pick up the new config
kubectl rollout restart deployment my-deployment

This script first updates the my-configmap ConfigMap with new configurations and then triggers a rollout restart of the my-deployment to ensure that the pods pick up the new configuration.

#Managing Configmaps 

#A. Storage and lifecycle management

In a Kubernetes cluster, ConfigMaps are fundamental for storing non-sensitive data in key-value pairs. They are crucial in decoupling configuration artifacts from container images, leading to more streamlined container updates. Stored within the Kubernetes API, these ConfigMaps can be referenced by pods and provide a mechanism to inject configuration data into containers. Managing their lifecycle involves defining them as configmap objects within your Kubernetes manifests. Utilizing kubectl, you can create, update, and manage these configmaps, ensuring that the right configuration is applied to the right service at the right time. This approach allows for dynamic updating of environment variables and configuration data, minimizing the need for container rebuilds.

#B. Handling changes and updates in configmaps 

When changes occur in the ConfigMaps, it's crucial to propagate these changes effectively across the cluster. Update your ConfigMaps through the kubectl command, and Kubernetes ensures that the updated values are mounted into the containers via volumes or environment variables. However, note that updating a ConfigMap doesn't automatically update the configuration of existing pods. To apply the changes, you might need to restart the associated pods. This process highlights the importance of understanding the connection between ConfigMaps, pods, and how Kubernetes handles updates to maintain service stability and functionality. ConfigMaps, thus, serve as a versatile tool, managing and applying changes across multiple environments in your Kubernetes cluster, enhancing the efficiency of deploying and managing applications.

#Advanced Configmap Techniques 

#A. Integrating configmaps with kubernetes api and services

ConfigMaps can be dynamically linked with Kubernetes API, enabling containers to adapt to configuration changes without redeployment. This integration is achieved through the kubectl command, which facilitates the creation and management of ConfigMaps. By utilizing the API, applications can reference ConfigMaps, allowing for a seamless update of configuration data. This is particularly useful in scenarios where service configurations require frequent updates.

The use of volume mounts ('volumeMounts') and spec references in Kubernetes service manifests allows containers to access ConfigMap data as files or environment variables. For instance, by defining a 'mountPath' in the container spec, the contents of a ConfigMap can be mounted into a container, making the configuration data available as files within the filesystem. This method provides a flexible approach to managing configurations for services running in a Kubernetes cluster.

#B. Complex scenarios

Structuring configmaps for different environments

In a large-scale application, it's crucial to segregate configuration data into multiple ConfigMaps, each tailored to specific components or environments like development, staging, and production. This segregation aids in:

  • Minimizing configuration conflicts: Separate ConfigMaps for different environments prevent accidental application of incorrect settings.
  • Streamlined updates: Specific ConfigMaps for distinct services or modules simplify the update process, as changes are isolated to relevant areas.

Labeling and grouping configurations

Effective management of numerous ConfigMaps involves:

  • Systematic Labeling: Assign labels to ConfigMaps to denote their purpose, environment, or association with specific services.
  • Logical Grouping: Group related configurations together, such as all database-related settings in one ConfigMap, which enhances clarity and accessibility.

Dynamic configmap updates

For applications requiring real-time configuration updates, Kubernetes' dynamic update capabilities are vital:

  • Linking with Kubernetes API: Utilize Kubernetes' API to enable automatic updates in container environments when a ConfigMap is modified.
  • Real-time Adaptation: Ensure applications can adapt to these updates without needing redeployment, enhancing efficiency and reducing downtime.

#Common challenges and solutions 

#A. Addressing typical issues and troubleshooting tips

  1. Variable Misconfiguration: One frequent challenge in Kubernetes is misconfiguring environment variables in ConfigMaps. To ensure accuracy, double-check key-value pairs and use 'kubectl' commands for verification. This reduces the risk of errors in your container's environment.
  2. Volume Mount Issues: When using ConfigMaps to mount data into a container, issues often arise with 'volumeMounts' specifications. It's crucial to verify the mountPath and ensure it aligns with your container's directory structure. This precision prevents clashes and ensures the correct mounting of configuration data.
  3. API Version Mismatch: Ensure compatibility between your ConfigMap API version and the Kubernetes cluster version. Mismatches can lead to service disruptions or failure to deploy containers.
  4. Handling Multiple Environments: Managing different sets of variables for multiple environments can be challenging. Utilize separate ConfigMaps for each environment, and reference them accordingly in your pod's spec. This keeps your configuration organized and environment-specific.
  5. ConfigMap Size Limitations: Kubernetes ConfigMaps have a size limit. Exceeding this with extensive configuration data can cause deployment failures. Consider splitting large configurations into multiple ConfigMaps or using alternative methods like volumes for larger data sets.

#B. FAQs: Answering related questions

  1. How do I create a pod using a ConfigMap?
    Use the kubectl command to create a pod and reference the ConfigMap in the pod's spec for environment variables or volume configuration.
  2. Can I store file paths in a ConfigMap?
    Yes, you can store file paths as values in key-value pairs within a ConfigMap.
  3. How do I update a ConfigMap?
    Modify the ConfigMap contents using kubectl and redeploy the service for changes to take effect.
  4. Is it possible to use a ConfigMap for multiple containers?
    Absolutely, a single ConfigMap can be shared across multiple containers within a pod.
  5. What happens if a ConfigMap is deleted while in use?
    The existing pods will retain the old ConfigMap data, but new pods will fail to start until the ConfigMap is restored or updated in the configuration.


Kubernetes ConfigMaps stands as a crucial tool in modern container orchestration, providing an efficient and dynamic means to manage non-sensitive configuration data across multiple environments. Their ability to separate key-value pairs from container images enhances the flexibility and adaptability of services within a Kubernetes cluster. By effectively using ConfigMaps, developers can streamline application deployment and ensure a seamless service experience. It is essential to remember the practices highlighted in this guide: leveraging Kubectl for precise configuration management, understanding the distinct roles of ConfigMaps and Secrets, and employing volume mounts and environment variables for optimal integration. Adopting these techniques will simplify configuration challenges and empower your Kubernetes infrastructure to be more resilient and responsive to changes.

Your Favorite Internal Developer Platform

Qovery is an Internal Developer Platform Helping 50.000+ Developers and Platform Engineers To Ship Faster.

Try it out now!
Your Favorite Internal Developer Platform
Qovery white logo

Your Favorite Internal Developer Platform

Qovery is an Internal Developer Platform Helping 50.000+ Developers and Platform Engineers To Ship Faster.

Try it out now!
KubernetesDevOpsPlatform Engineering