ConfigMaps

    You are viewing documentation for a release that is no longer supported. The latest supported version of version 3 is [3.11]. For the most recent version 4, see

    Many applications require configuration using some combination of configuration files, command line arguments, and environment variables. These configuration artifacts should be decoupled from image content in order to keep containerized applications portable.

    The object provides mechanisms to inject containers with configuration data while keeping containers agnostic of OKD. A **ConfigMap** can be used to store fine-grained information like individual properties or coarse-grained information like entire configuration files or JSON blobs.

    The **ConfigMap** API object holds key-value pairs of configuration data that can be consumed in pods or used to store configuration data for system components such as controllers. **ConfigMap** is similar to secrets, but designed to more conveniently support working with strings that do not contain sensitive information.

    For example:

    ConfigMap Object Definition

    You can use the binaryData field when you .

    Configuration data can be consumed in pods in a variety of ways. A **ConfigMap** can be used to:

    1. Populate the value of environment variables.

    2. Set command-line arguments in a container.

    3. Populate configuration files in a volume.

    Both users and system components may store configuration data in a **ConfigMap**.

    You can use the following command to create a **ConfigMap** easily from directories, specific files, or literal values:

    1. $ oc create configmap <configmap_name> [options]

    The following sections cover the different ways you can create a **ConfigMap**.

    Consider a directory with some files that already contain the data with which you want to populate a **ConfigMap**:

    1. $ ls example-files
    2. game.properties
    3. ui.properties
    5. $ cat example-files/game.properties
    6. enemies=aliens
    7. lives=3
    8. enemies.cheat=true
    9. enemies.cheat.level=noGoodRotten
    10. secret.code.passphrase=UUDDLRLRBABAS
    11. secret.code.allowed=true
    12. secret.code.lives=30
    14. $ cat example-files/ui.properties
    15. color.good=purple
    16. color.bad=yellow
    17. allow.textmode=true
    18. how.nice.to.look=fairlyNice

    You can use the following command to create a **ConfigMap** holding the content of each file in this directory:

    1. $ oc create configmap game-config \
    2.     --from-file=example-files/

    When the --from-file option points to a directory, each file directly in that directory is used to populate a key in the **ConfigMap**, where the name of the key is the file name, and the value of the key is the content of the file.

    For example, the above command creates the following **ConfigMap**:

    1. $ oc describe configmaps game-config
    2. Name:           game-config
    3. Namespace:      default
    4. Labels:         <none>
    5. Annotations:    <none>
    7. Data
    9. game.properties:        121 bytes
    10. ui.properties:          83 bytes

    If you want to see the values of the keys, you can oc get the object with the -o option:

    1. $ oc get configmaps game-config -o yaml
    3. apiVersion: v1
    4. data:
    5.   game.properties: |-
    6.     enemies=aliens
    7.     lives=3
    8.     enemies.cheat=true
    9.     enemies.cheat.level=noGoodRotten
    10.     secret.code.passphrase=UUDDLRLRBABAS
    11.     secret.code.allowed=true
    12.     secret.code.lives=30
    13.   ui.properties: |
    14.     color.good=purple
    15.     color.bad=yellow
    16.     allow.textmode=true
    17.     how.nice.to.look=fairlyNice
    18. kind: ConfigMap
    19. metadata:
    20.   creationTimestamp: 2016-02-18T18:34:05Z
    21.   name: game-config
    22.   namespace: default
    23.   resourceVersion: "407"-
    24.   selflink: /api/v1/namespaces/default/configmaps/game-config
    25.   uid: 30944725-d66e-11e5-8cd0-68f728db1985

    Creating from Files

    You can also pass the --from-file option with a specific file, and pass it multiple times to the CLI. The following yields equivalent results to the example:

    1. Create the **ConfigMap** specifying a specific file:

      1. $ oc create configmap game-config-2 \
      2.     --from-file=example-files/game.properties \
      3.     --from-file=example-files/ui.properties

    2. Verify the results:

      1. $ oc get configmaps game-config-2 -o yaml
      3. apiVersion: v1
      4. data:
      5.   game.properties: |-
      6.     enemies=aliens
      7.     lives=3
      8.     enemies.cheat=true
      9.     enemies.cheat.level=noGoodRotten
      10.     secret.code.passphrase=UUDDLRLRBABAS
      11.     secret.code.allowed=true
      12.     secret.code.lives=30
      13.   ui.properties: |
      14.     color.good=purple
      15.     color.bad=yellow
      16.     allow.textmode=true
      17.     how.nice.to.look=fairlyNice
      18. kind: ConfigMap
      19. metadata:
      20.   creationTimestamp: 2016-02-18T18:52:05Z
      21.   name: game-config-2
      22.   namespace: default
      23.   resourceVersion: "516"
      24.   selflink: /api/v1/namespaces/default/configmaps/game-config-2
      25.   uid: b4952dc3-d670-11e5-8cd0-68f728db1985

    You can also set the key to use for an individual file with the --from-file option by passing an expression of key=value. For example:

    1. Verify the results:

      1. $ oc get configmaps game-config-3 -o yaml
      3. apiVersion: v1
      4. data:
      6.     enemies=aliens
      7.     lives=3
      8.     enemies.cheat=true
      9.     enemies.cheat.level=noGoodRotten
      10.     secret.code.passphrase=UUDDLRLRBABAS
      11.     secret.code.allowed=true
      12.     secret.code.lives=30
      13. kind: ConfigMap
      14. metadata:
      15.   creationTimestamp: 2016-02-18T18:54:22Z
      16.   name: game-config-3
      17.   namespace: default
      18.   resourceVersion: "530"
      19.   selflink: /api/v1/namespaces/default/configmaps/game-config-3
      20.   uid: 05f8da22-d671-11e5-8cd0-68f728db1985

    You can also supply literal values for a **ConfigMap**. The --from-literal option takes a key=value syntax that allows literal values to be supplied directly on the command line:

    1. Create the **ConfigMap** specifying a literal value:

    2. Verify the results:

      1. $ oc get configmaps special-config -o yaml
      3. apiVersion: v1
      4. data:
      5.   special.how: very
      6.   special.type: charm
      7. kind: ConfigMap
      8. metadata:
      9.   creationTimestamp: 2016-02-18T19:14:38Z
      10.   name: special-config
      11.   namespace: default
      12.   resourceVersion: "651"
      13.   selflink: /api/v1/namespaces/default/configmaps/special-config
      14.   uid: dadce046-d673-11e5-8cd0-68f728db1985

    The following sections describe some uses cases when consuming **ConfigMap** objects in pods.

    Consuming in Environment Variables

    **ConfigMaps** can be used to populate individual environment variables or can populate environment variables from all keys that form valid environment variable names. As an example, consider the following **ConfigMaps**:

    ConfigMap with two environment variables

    1. apiVersion: v1
    2. kind: ConfigMap
    3. metadata:
    4.   name: special-config (1)
    5.   namespace: default
    6. data:
    7.   special.how: very (2)
    8.   special.type: charm (2)
    1Name of the ConfigMap.
    2Environment variables to inject.

    ConfigMap with one environment variable

    1. apiVersion: v1
    2. kind: ConfigMap
    3. metadata:
    4.   name: env-config (1)
    5.   namespace: default
    6. data:
    7.   log_level: INFO (2)

    You can consume the keys of this **ConfigMap** in a pod using **configMapKeyRef** sections:

    Sample pod specification configured to inject specific environment variables

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: dapi-test-pod
    5. spec:
    6.   containers:
    7.     - name: test-container
    8.       image: gcr.io/google_containers/busybox
    9.       command: [ "/bin/sh", "-c", "env" ]
    10.       env: (1)
    11.         - name: SPECIAL_LEVEL_KEY
    12.           valueFrom:
    13.             configMapKeyRef:
    14.               name: special-config (2)
    15.               key: special.how (3)
    16.         - name: SPECIAL_TYPE_KEY
    17.           valueFrom:
    18.             configMapKeyRef:
    19.               name: special-config (2)
    20.               key: special.type (3)
    21.               optional: true (4)
    22.       envFrom: (5)
    23.         - configMapRef:
    24.             name: env-config (6)
    25.   restartPolicy: Never
    1Stanza to pull the specified environment variables from a ConfigMap.
    2Name of the ConfigMap to pull specific environment variables from.
    3Environment variable to pull from the ConfigMap.
    4Makes the environment variable optional. As optional, the pod will be started even if the specified ConfigMap and keys do not exist.
    5Stanza to pull all environment variables from a ConfigMap.
    6Name of the ConfigMap to pull all environment variables.

    When this pod is run, its output will include the following lines:

    1. SPECIAL_LEVEL_KEY=very
    2. log_level=INFO
    1. apiVersion: v1
    2. kind: ConfigMap
    3. metadata:
    4.   name: special-config
    5.   namespace: default
    6. data:
    7.   special.how: very
    8.   special.type: charm

    To inject values into the command line, you must consume the keys you want to use as environment variables, as in the use case. Then you can refer to them in a container’s command using the $(VAR_NAME) syntax.

    Sample pod specification configured to inject specific environment variables

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: dapi-test-pod
    5. spec:
    6.   containers:
    7.     - name: test-container
    8.       image: gcr.io/google_containers/busybox
    9.       command: [ "/bin/sh", "-c", "echo $(SPECIAL_LEVEL_KEY) $(SPECIAL_TYPE_KEY)" ]
    10.       env:
    11.         - name: SPECIAL_LEVEL_KEY
    12.             configMapKeyRef:
    14.               key: special.how
    15.         - name: SPECIAL_TYPE_KEY
    16.           valueFrom:
    17.             configMapKeyRef:
    18.               name: special-config
    19.               key: special.type
    20.   restartPolicy: Never

    When this pod is run, the output from the test-container container will be:

    1. very charm

    Consuming in Volumes

    A **ConfigMap** can also be consumed in volumes. Returning again to the following example **ConfigMap**:

    1. apiVersion: v1
    2. kind: ConfigMap
    3. metadata:
    4.   name: special-config
    5.   namespace: default
    6. data:
    7.   special.how: very
    8.   special.type: charm

    You have a couple different options for consuming this **ConfigMap** in a volume. The most basic way is to populate the volume with files where the key is the file name and the content of the file is the value of the key:

    When this pod is run, the output will be:

    1. very

    You can also control the paths within the volume where **ConfigMap** keys are projected:

    1. apiVersion: v1
    2. kind: Pod
    3. metadata:
    4.   name: dapi-test-pod
    5. spec:
    6.   containers:
    7.     - name: test-container
    8.       image: gcr.io/google_containers/busybox
    9.       command: [ "/bin/sh", "cat", "/etc/config/path/to/special-key" ]
    10.       volumeMounts:
    11.       - name: config-volume
    12.         mountPath: /etc/config
    13.   volumes:
    14.     - name: config-volume
    15.       configMap:
    16.         name: special-config
    17.         items:
    18.         - key: special.how
    19.           path: path/to/special-key
    20.   restartPolicy: Never

    When this pod is run, the output will be:

    1. very

    For a real-world example, you can configure Redis using a **ConfigMap**. To inject Redis with the recommended configuration for using Redis as a cache, the Redis configuration file should contain the following:

    1. maxmemory 2mb
    2. maxmemory-policy allkeys-lru

    If your configuration file is located at example-files/redis/redis-config, create a **ConfigMap** with it:

    1. Create the **ConfigMap** specifying the configuration file:

      1. $ oc create configmap example-redis-config \
      2.     --from-file=example-files/redis/redis-config

    2. Verify the results:

      1. $ oc get configmap example-redis-config -o yaml
      3. apiVersion: v1
      4. data:
      5.   redis-config: |
      6.     maxmemory 2mb
      7.     maxmemory-policy allkeys-lru
      8. kind: ConfigMap
      9. metadata:
      10.   creationTimestamp: 2016-04-06T05:53:07Z
      11.   name: example-redis-config
      12.   namespace: default
      13.   resourceVersion: "2985"
      14.   selflink: /api/v1/namespaces/default/configmaps/example-redis-config
      15.   uid: d65739c1-fbbb-11e5-8a72-68f728db1985

    Now, create a pod that uses this **ConfigMap**:

    1. Create a pod definition like the following and save it to a file, for example redis-pod.yaml:

      1. apiVersion: v1
      2. kind: Pod
      3. metadata:
      4.   name: redis
      5. spec:
      6.   containers:
      7.   - name: redis
      8.     image: kubernetes/redis:v1
      9.     env:
      10.     - name: MASTER
      11.       value: "true"
      12.     ports:
      13.     - containerPort: 6379
      14.     resources:
      15.       limits:
      16.         cpu: "0.1"
      17.     volumeMounts:
      18.     - mountPath: /redis-master-data
      19.       name: data
      20.     - mountPath: /redis-master
      21.       name: config
      22.   volumes:
      23.     - name: data
      24.       emptyDir: {}
      25.     - name: config
      26.       configMap:
      27.         name: example-redis-config
      28.         items:
      29.         - key: redis-config
      30.           path: redis.conf

    2. Create the pod:

      1. $ oc create -f redis-pod.yaml

    The newly-created pod has a **ConfigMap** volume that places the redis-config key of the example-redis-config **ConfigMap** into a file called redis.conf. This volume is mounted into the /redis-master directory in the Redis container, placing our configuration file at /redis-master/redis.conf, which is where the image looks for the Redis configuration file for the master.

    If you oc exec into this pod and run the redis-cli tool, you can check that the configuration was applied correctly:

    1. $ oc exec -it redis redis-cli
    2. 127.0.0.1:6379> CONFIG GET maxmemory
    3. 1) "maxmemory"
    4. 2) "2097152"
    5. 127.0.0.1:6379> CONFIG GET maxmemory-policy
    6. 1) "maxmemory-policy"

    A **ConfigMap** must be created before they are consumed in pods. Controllers can be written to tolerate missing configuration data; consult individual components configured via **ConfigMap** on a case-by-case basis.

    The Kubelet only supports use of a **ConfigMap** for pods it gets from the API server. This includes any pods created using the CLI, or indirectly from a replication controller. It does not include pods created using the OKD node’s flag, its --config flag, or its REST API (these are not common ways to create pods).