All Products
Search

This Product

    Container Service for Kubernetes:Use a ConfigMap

    Document Center

    Container Service for Kubernetes:Use a ConfigMap

    Last Updated:May 06, 2026

    Running the same container image across development, staging, and production environments often requires different configuration values. A ConfigMap lets you store those values separately from the image, so you can change configuration without rebuilding or redeploying the image. The following sections cover three injection methods: environment variables, command-line arguments, and volume-mounted files.

    Prerequisites

    Before you begin, ensure that you have:

    • An ACK cluster with at least one node

    • kubectl configured to connect to your cluster

    You can also apply these YAML manifests through the ACK console at https://cs.console.alibabacloud.com by navigating to your cluster → Workloads > Deployments → Create from YAML.

    Create a ConfigMap

    All examples below reference a ConfigMap named special-config with two key-value pairs.

    Apply the following manifest to create it:

    apiVersion: v1
kind: ConfigMap
metadata:
  name: special-config
  namespace: default
data:
  SPECIAL_LEVEL: very
  SPECIAL_TYPE: charm
    The pod and the ConfigMap must be in the same cluster and namespace.

    Inject ConfigMap data as environment variables

    Inject a single key

    Use valueFrom with configMapKeyRef to map a specific ConfigMap key to an environment variable.

    apiVersion: v1
kind: Pod
metadata:
  name: config-pod-1
spec:
  containers:
    - name: test-container
      image: busybox
      command: ["/bin/sh", "-c", "env"]
      env:
        - name: SPECIAL_LEVEL_KEY
          valueFrom:
            configMapKeyRef:
              name: special-config   # ConfigMap to reference
              key: SPECIAL_LEVEL     # Key within the ConfigMap
  restartPolicy: Never

    After the pod completes, verify the injected variable:

    kubectl logs config-pod-1

    The output includes:

    SPECIAL_LEVEL_KEY=very

    Inject all keys

    Use envFrom with configMapRef to load every key in a ConfigMap as a separate environment variable. Each ConfigMap key becomes an environment variable name.

    apiVersion: v1
kind: Pod
metadata:
  name: config-pod-2
spec:
  containers:
    - name: test-container
      image: busybox
      command: ["/bin/sh", "-c", "env"]
      envFrom:
        - configMapRef:
            name: special-config
  restartPolicy: Never

    Verify:

    kubectl logs config-pod-2

    Expected output includes:

    SPECIAL_LEVEL=very
SPECIAL_TYPE=charm

    Use ConfigMap values as command-line arguments

    Reference environment variables in a container's command field using the $(VAR_NAME) syntax. First inject the ConfigMap keys as environment variables, then reference them in the command.

    apiVersion: v1
kind: Pod
metadata:
  name: config-pod-3
spec:
  containers:
    - name: test-container
      image: busybox
      command: ["/bin/sh", "-c", "echo $(SPECIAL_LEVEL_KEY) $(SPECIAL_TYPE_KEY)"]
      env:
        - name: SPECIAL_LEVEL_KEY
          valueFrom:
            configMapKeyRef:
              name: special-config
              key: SPECIAL_LEVEL
        - name: SPECIAL_TYPE_KEY
          valueFrom:
            configMapKeyRef:
              name: special-config
              key: SPECIAL_TYPE
  restartPolicy: Never

    Verify:

    kubectl logs config-pod-3

    Expected output:

    very charm

    Mount a ConfigMap as a volume

    Mounting a ConfigMap as a volume exposes each key as a file. The key name becomes the filename and the key value becomes the file content. Files appear in the directory specified by mountPath.

    apiVersion: v1
kind: Pod
metadata:
  name: config-pod-4
spec:
  containers:
    - name: test-container
      image: busybox
      command: ["/bin/sh", "-c", "ls /etc/config/"]
      volumeMounts:
        - name: config-volume
          mountPath: /etc/config
  volumes:
    - name: config-volume
      configMap:
        name: special-config
  restartPolicy: Never

    Verify:

    kubectl logs config-pod-4

    Expected output lists one filename per ConfigMap key:

    SPECIAL_TYPE
SPECIAL_LEVEL

    Limitations

    Same cluster and namespace required

    A pod can only reference a ConfigMap in the same cluster and namespace.

    Invalid key names with envFrom

    Keys that are not valid environment variable names are silently skipped. The pod still starts, but skipped keys are recorded as InvalidEnvironmentVariableNames events. Run kubectl get events to inspect them.

    ConfigMap must exist before the pod

    If a pod references a ConfigMap that does not exist, the pod fails to start. To allow a pod to start when the referenced ConfigMap is absent, set optional: true on the reference:

    env:
  - name: SPECIAL_LEVEL_KEY
    valueFrom:
      configMapKeyRef:
        name: special-config
        key: SPECIAL_LEVEL
        optional: true   # Pod starts even if special-config does not exist

    What's next

    • Configure a Pod to Use a ConfigMap — Kubernetes upstream reference with additional advanced patterns, including mounting specific keys to custom paths and automatic updates when a ConfigMap changes

    References