Kubernetes ConfigMaps provide a flexible way to decouple configuration data from container images, allowing you to manage app settings without rebuilding or redeploying workloads. They store non-confidential data as key-value pairs and make it accessible to Pods through environment variables or mounted files.

In real-world deployments, ConfigMaps are essential for maintaining clean, portable, and environment-agnostic applications — especially when managing multiple environments like dev, staging, and production. This guide walks through every practical way to create, manage, and mount ConfigMaps in Kubernetes — from simple literals and YAML files to more advanced techniques involving external sources, namespaces, and volume mounts.

Whether you’re deploying microservices or configuring stateful workloads, mastering ConfigMaps ensures you can handle dynamic application configuration with precision, security, and scalability.

Note: A Kubernetes ConfigMap has a size limit of 1 MiB and is not meant for storing large data. For bigger configurations, use a volume, database, or external file service instead.

K8s configmap Example:

kubectl create configmap app-config --from-literal=APP_MODE=production

This command creates a ConfigMap named app-config with two key-value pairs for your Kubernetes application.

Different Ways to Create ConfigMap in Kubernetes

Kubernetes offers multiple ways to create a ConfigMap depending on your configuration source — such as literal values, files, directories, environment variables, or even external sources like JSON, databases, or URLs.
Below is a quick list of common methods, each linked to its detailed explanation section for easy navigation.

• From Literal Values
• From a YAML File
• From a JSON File
• From a File or Directory
• From an Environment File
• From Another Namespace
• From a Secret
• From a Volume
• From a Database or URL
• From Multiple Files or Templates

ConfigMap from Literal Values

You can create a ConfigMap directly using inline key-value pairs with the --from-literal flag. This is useful for adding small configuration values without creating files.

kubectl create configmap app-settings --from-literal=ENV=dev --from-literal=DEBUG=true

ConfigMap from a YAML File

A YAML file defines your ConfigMap declaratively, allowing version control and easy updates. This approach is ideal for production setups where you want consistency across environments.

kubectl apply -f configmap.yaml

ConfigMap from a JSON File

If your application already uses JSON for configuration, you can create a ConfigMap directly from it. Kubernetes treats JSON files just like any other text-based input.

kubectl create configmap json-config --from-file=config.json

ConfigMap from a File or Directory

You can create a ConfigMap from one file or from all files in a directory. Each file name becomes a key, and its content becomes the value—perfect for organizing multiple config files.

kubectl create configmap file-config --from-file=app.properties
# or
kubectl create configmap dir-config --from-file=./config-dir

ConfigMap from an Environment File

Use a .env file containing key-value pairs to populate a ConfigMap. This approach simplifies environment variable management across pods.

kubectl create configmap env-config --from-env-file=.env

ConfigMap from Another Namespace

You can duplicate an existing ConfigMap from one namespace to another. This is handy when the same configuration is required across multiple environments.

kubectl get configmap app-config -n dev -o yaml | kubectl apply -n prod -f -

ConfigMap from a Secret

Although not a common use case, you can convert a Kubernetes Secret into a ConfigMap for non-sensitive configuration. This is generally discouraged for actual secrets but useful for public data.

kubectl get secret app-secret -o jsonpath='{.data}' | kubectl create configmap from-secret --from-literal=data="$(base64 --decode)"

ConfigMap from a Volume

Mount a ConfigMap into a Pod as a volume to make configuration files directly accessible to your application. This is often used to inject config files dynamically at runtime.

volumes:
  - name: config-volume
    configMap:
      name: app-config

ConfigMap from a Database or URL

You can fetch remote configuration data from an API, database, or external URL and use it to create a ConfigMap dynamically. This helps when config data is generated outside Kubernetes.

curl -s https://example.com/config.json | kubectl create configmap remote-config --from-file=/dev/stdin

ConfigMap from Multiple Files or Templates

When you have multiple related configuration files, combine them into a single ConfigMap. Kubernetes will map each filename as a key in the ConfigMap.

kubectl create configmap multi-config \
  --from-file=db.conf \
  --from-file=app.conf \
  --from-file=cache.conf

Mounting ConfigMaps in Kubernetes

Mounting ConfigMaps in Kubernetes allows you to inject configuration data directly into Pods as files or directories.
This makes it easier to manage app settings, environment variables, or scripts without rebuilding images.
Depending on your use case, you can mount ConfigMaps as single files, directories, or subPaths, customize permissions, and even control ownership or read/write behavior.

Below is a structured list of every major mounting variation and technique — each linked to its in-depth explanation for smoother navigation.

• Mount ConfigMap as File or Directory
• Mount ConfigMap with SubPath and Permissions
• Mount ConfigMap in Pods, Deployments, or Jobs
• Mount ConfigMap from Another Namespace
• Mount ConfigMap as Executable or with Custom Ownership

Mount ConfigMap as File or Directory

When you mount a ConfigMap, each key becomes a file.
You can either mount all keys as separate files in a directory, or a specific key as a single file using items.

Example – Mounting one file:

volumes:
  - name: config-volume
    configMap:
      name: app-config
      items:
        - key: "settings.json"
          path: "settings.json"

This mounts only the settings.json key instead of all keys.

Mount ConfigMap with SubPath and Permissions

By default, Nginx includes a built-in configuration file at /etc/nginx/nginx.conf that controls how the server runs. In production, DevOps teams often provide a custom nginx.conf to override default settings like ports, caching, or routing.

Instead of rebuilding the image, Kubernetes lets you mount this custom file from a ConfigMap using subPath, replacing the default config at runtime seamlessly.

Use subPath to mount a ConfigMap file into a specific path inside a container rather than an entire directory.
You can also control file access modes with defaultMode.

Example – SubPath with permissions:

volumes:
  - name: config-volume
    configMap:
      name: app-config
      defaultMode: 0644
containers:
  - name: web
    image: nginx
    volumeMounts:
      - name: config-volume
        mountPath: /etc/nginx/nginx.conf
        subPath: nginx.conf

Mount ConfigMap in Pods, Deployments, or Jobs

In a real-world setup, web applications often run across multiple replicas for load balancing and high availability. Each replica needs the same configuration files—like a shared index.html, environment settings, or app config—to behave consistently. Instead of manually copying these files into every container image, Kubernetes lets you mount a single ConfigMap into all pods within a Deployment or Job.

This ensures every instance runs with identical configuration while allowing DevOps teams to update settings centrally without rebuilding or redeploying images.

ConfigMaps can be attached to any workload type (Pod, Deployment, Job).
They all use the same underlying mechanism — define a volume and attach it via volumeMounts.

Example – Deployment using ConfigMap:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-deployment
spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: web
          image: nginx
          volumeMounts:
            - name: config
              mountPath: /app/config
      volumes:
        - name: config
          configMap:
            name: app-config

Mount ConfigMap from Another Namespace

Kubernetes doesn’t allow cross-namespace mounting directly.
Instead, export and re-create the ConfigMap in the target namespace.

Mount ConfigMap as Executable or with Custom Ownership

In real deployments, you might use this setup when a container needs to execute startup scripts, database migration scripts, or setup routines before the main application runs.

For example, a DevOps team can package a start.sh or init.sh script inside a ConfigMap and mount it with executable permissions. By setting custom ownership (runAsUser, fsGroup), you ensure the container follows security best practices — running as a non-root user while still having permission to execute the script safely.

By default, ConfigMap files are read-only and root-owned.
To make them executable or owned by a specific user, configure security settings in your Pod spec.

Example – Changing ownership and permission:

securityContext:
  runAsUser: 1000
  fsGroup: 2000
volumes:
  - name: script-config
    configMap:
      name: startup-script
      defaultMode: 0755

This makes the mounted file executable by the container’s user.

Summary

A ConfigMap in a Kubernetes orchestration platform simplify application configuration by externalizing non-sensitive settings from container images. They can be created from literals, files, directories, or even external data sources, and mounted into Pods in multiple ways — as files, directories, or subPaths with customized permissions and ownership.

While ConfigMaps are powerful, they come with a 1 MiB size limit and are not intended for storing large data. For bigger or dynamic configurations, it’s better to use persistent volumes, databases, or external configuration services.

By combining declarative YAML definitions with flexible mounting options, ConfigMaps give you full control over runtime configurations — helping you maintain consistency, reduce image rebuilds, and streamline multi-environment deployments in Kubernetes.