|
| 1 | +--- |
| 2 | +title: ConfigMaps |
| 3 | +content_template: templates/concept |
| 4 | +weight: 20 |
| 5 | +--- |
| 6 | + |
| 7 | +{{% capture overview %}} |
| 8 | + |
| 9 | +{{< glossary_definition term_id="configmap" prepend="A ConfigMap is" length="all" >}} |
| 10 | + |
| 11 | +{{< caution >}} |
| 12 | +ConfigMap does not provide secrecy or encryption. |
| 13 | +If the data you want to store are confidential, use a |
| 14 | +{{< glossary_tooltip text="Secret" term_id="secret" >}} rather than a ConfigMap, |
| 15 | +or use additional (third party) tools to keep your data private. |
| 16 | +{{< /caution >}} |
| 17 | + |
| 18 | +{{% /capture %}} |
| 19 | + |
| 20 | +{{% capture body %}} |
| 21 | +## Motivation |
| 22 | + |
| 23 | +Use a ConfigMap for setting configuration data separately from application code. |
| 24 | + |
| 25 | +For example, imagine that you are developing an application that you can run on your |
| 26 | +own computer (for development) and in the cloud (to handle real traffic). |
| 27 | +You write the code to |
| 28 | +look in an environment variable named `DATABASE_HOST`. Locally, you set that variable |
| 29 | +to `localhost`. In the cloud, you set it to refer to a Kubernetes |
| 30 | +{{< glossary_tooltip text="Service" term_id="service" >}} that exposes the database |
| 31 | +component to your cluster. |
| 32 | + |
| 33 | +This lets you fetch a container image running in the cloud and |
| 34 | +debug the exact same code locally if needed. |
| 35 | + |
| 36 | +## ConfigMap object |
| 37 | + |
| 38 | +A ConfigMap is an API [object](/docs/concepts/overview/working-with-objects/kubernetes-objects/) |
| 39 | +that lets you store configuration for other objects to use. Unlike most |
| 40 | +Kubernetes objects that have a `spec`, a ConfigMap has a `data` section to |
| 41 | +store items (keys) and their values. |
| 42 | + |
| 43 | +The name of a ConfigMap must be a valid |
| 44 | +[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names). |
| 45 | + |
| 46 | +## ConfigMaps and Pods |
| 47 | + |
| 48 | +You can write a Pod `spec` that refers to a ConfigMap and configures the container(s) |
| 49 | +in that Pod based on the data in the ConfigMap. The Pod and the ConfigMap must be in |
| 50 | +the same {{< glossary_tooltip text="namespace" term_id="namespace" >}}. |
| 51 | + |
| 52 | +Here's an example ConfigMap that has some keys with single values, |
| 53 | +and other keys where the value looks like a fragment of a configuration |
| 54 | +format. |
| 55 | + |
| 56 | +```yaml |
| 57 | +apiVersion: v1 |
| 58 | +kind: ConfigMap |
| 59 | +metadata: |
| 60 | + Name: game-demo |
| 61 | +data: |
| 62 | + # property-like keys; each key maps to a simple value |
| 63 | + player_initial_lives: 3 |
| 64 | + ui_properties_file_name: "user-interface.properties" |
| 65 | + # |
| 66 | + # file-like keys |
| 67 | + game.properties: | |
| 68 | + enemy.types=aliens,monsters |
| 69 | + player.maximum-lives=5 |
| 70 | + user-interface.properties: | |
| 71 | + color.good=purple |
| 72 | + color.bad=yellow |
| 73 | + allow.textmode=true |
| 74 | +``` |
| 75 | +
|
| 76 | +There are four different ways that you can use a ConfigMap to configure |
| 77 | +a container inside a Pod: |
| 78 | +
|
| 79 | +1. Command line arguments to the entrypoint of a container |
| 80 | +1. Environment variables for a container |
| 81 | +1. Add a file in read-only volume, for the application to read |
| 82 | +1. Write code to run inside the Pod that uses the Kubernetes API to read a ConfigMap |
| 83 | +
|
| 84 | +These different methods lend themselves to different ways of modeling |
| 85 | +the data being consumed. |
| 86 | +For the first three methods, the |
| 87 | +{{< glossary_tooltip text="kubelet" term_id="kubelet" >}} uses the data from |
| 88 | +the Secret when it launches container(s) for a Pod. |
| 89 | +
|
| 90 | +The fourth method means you have to write code to read the Secret and its data. |
| 91 | +However, because you're using the Kubernetes API directly, your application can |
| 92 | +subscribe to get updates whenever the ConfigMap changes, and react |
| 93 | +when that happens. By accessing the Kubernetes API directly, this |
| 94 | +technique also lets you access a ConfigMap in a different namespace. |
| 95 | +
|
| 96 | +Here's an example Pod that uses values from `game-demo` to configure a Pod: |
| 97 | +```yaml |
| 98 | +apiVersion: v1 |
| 99 | +kind: Pod |
| 100 | +metadata: |
| 101 | + name: configmap-demo-pod |
| 102 | +spec: |
| 103 | + containers: |
| 104 | + - name: demo |
| 105 | + image: game.example/demo-game |
| 106 | + env: |
| 107 | + # Define the environment variable |
| 108 | + - name: PLAYER_INITIAL_LIVES # Notice that the case is different here |
| 109 | + # from the key name in the ConfigMap. |
| 110 | + valueFrom: |
| 111 | + configMapKeyRef: |
| 112 | + name: game-demo # The ConfigMap this value comes from. |
| 113 | + key: player_initial_lives # The key to fetch. |
| 114 | + - name: UI_PROPERTIES_FILE_NAME |
| 115 | + valueFrom: |
| 116 | + configMapKeyRef: |
| 117 | + name: game-demo |
| 118 | + key: ui_properties_file_name |
| 119 | + volumeMounts: |
| 120 | + - name: config |
| 121 | + mountPath: "/config" |
| 122 | + readOnly: true |
| 123 | + volumes: |
| 124 | + # You set volumes at the Pod level, then mount them into containers inside that Pod |
| 125 | + - name: config |
| 126 | + configMap: |
| 127 | + # Provide the name of the ConfigMap you want to mount. |
| 128 | + name: game-demo |
| 129 | +``` |
| 130 | + |
| 131 | + |
| 132 | +A ConfigMap doesn't differentiate between single line property values and |
| 133 | +multi-line file-like values. |
| 134 | +What matters how Pods and other objects consume those values. |
| 135 | +For this example, defining a volume and mounting it inside the `demo` |
| 136 | +container as `/config` creates four files: |
| 137 | + |
| 138 | +- `/config/player_initial_lives` |
| 139 | +- `/config/ui_properties_file_name` |
| 140 | +- `/config/game.properties` |
| 141 | +- `/config/user-interface.properties` |
| 142 | + |
| 143 | +If you want to make sure that `/config` only contains files with a |
| 144 | +`.properties` extension, use two different ConfigMaps, and refer to both |
| 145 | +ConfigMaps in the `spec` for a Pod. The first ConfigMap defines |
| 146 | +`player_initial_lives` and `ui_properties_file_name`. The second |
| 147 | +ConfigMap defines the files that the kubelet places into `/config`. |
| 148 | + |
| 149 | +{{< note >}} |
| 150 | +The most common way to use ConfigMaps is to configure settings for |
| 151 | +containers running in a Pod in the same namespace. You can also use a |
| 152 | +ConfigMap separately. |
| 153 | + |
| 154 | +For example, you |
| 155 | +might encounter {{< glossary_tooltip text="addons" term_id="addons" >}} |
| 156 | +or {{< glossary_tooltip text="operators" term_id="operator-pattern" >}} that |
| 157 | +adjust their behavior based on a ConfigMap. |
| 158 | +{{< /note >}} |
| 159 | + |
| 160 | + |
| 161 | +{{% /capture %}} |
| 162 | +{{% capture whatsnext %}} |
| 163 | + |
| 164 | +* Read about [Secrets](/docs/concepts/configuration/secret/). |
| 165 | +* Read [Configure a Pod to Use a ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap/). |
| 166 | +* Read [The Twelve-Factor App](https://12factor.net/) to understand the motivation for |
| 167 | + separating code from configuration. |
| 168 | + |
| 169 | +{{% /capture %}} |
0 commit comments