kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Improve ConfigMap concept 

This PR adds some missing information to the ConfigMap concept page.
pull/23807/head
Qiming Teng 2020-09-11 14:22:21 +08:00
parent 0b9a6fd844
commit b1490ef95f
1 changed files with 47 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
content/en/docs/concepts/configuration/configmap.md
View File

@ -16,7 +16,6 @@ or use additional (third party) tools to keep your data private.
{{< /caution >}} {{< /caution >}}
<!-- body --> <!-- body -->
## Motivation ## Motivation
@ -24,25 +23,38 @@ Use a ConfigMap for setting configuration data separately from application code.
For example, imagine that you are developing an application that you can run on your For example, imagine that you are developing an application that you can run on your
own computer (for development) and in the cloud (to handle real traffic). own computer (for development) and in the cloud (to handle real traffic).
You write the code to You write the code to look in an environment variable named `DATABASE_HOST`.
look in an environment variable named `DATABASE_HOST`. Locally, you set that variable Locally, you set that variable to `localhost`. In the cloud, you set it to
to `localhost`. In the cloud, you set it to refer to a Kubernetes refer to a Kubernetes {{< glossary_tooltip text="Service" term_id="service" >}}
{{< glossary_tooltip text="Service" term_id="service" >}} that exposes the database that exposes the database component to your cluster.
component to your cluster.
This lets you fetch a container image running in the cloud and This lets you fetch a container image running in the cloud and
debug the exact same code locally if needed. debug the exact same code locally if needed.
A ConfigMap is not designed to hold large chunks of data. The data stored in a
ConfigMap cannot exeed 1 MiB. If you need to store settings that are
larger than this limit, you may want to consider mounting a volume or use a
separate database or file service.
## ConfigMap object ## ConfigMap object
A ConfigMap is an API [object](/docs/concepts/overview/working-with-objects/kubernetes-objects/) A ConfigMap is an API [object](/docs/concepts/overview/working-with-objects/kubernetes-objects/)
that lets you store configuration for other objects to use. Unlike most that lets you store configuration for other objects to use. Unlike most
Kubernetes objects that have a `spec`, a ConfigMap has a `data` section to Kubernetes objects that have a `spec`, a ConfigMap has `data` and `binaryData`
store items (keys) and their values. fields. These fields accepts key-value pairs as their values. Both the `data`
field and the `binaryData` are optional. The `data` field is designed to
contain UTF-8 byte sequences while the `binaryData` field is designed to
contain binary data.
The name of a ConfigMap must be a valid The name of a ConfigMap must be a valid
[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names). [DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
Each key under the `data` or the `binaryData` field must consist of
alphanumeric characters, `-`, `_` or `.`. The keys stored in `data` must not
overlap with the keys in the `binaryData` field.
Starting from v1.19, you can add an `immutable` field to a ConfigMap
definition to create an [immutable ConfigMap](#configmap-immutable).
## ConfigMaps and Pods ## ConfigMaps and Pods
You can write a Pod `spec` that refers to a ConfigMap and configures the container(s) You can write a Pod `spec` that refers to a ConfigMap and configures the container(s)
@ -62,7 +74,7 @@ data:
# property-like keys; each key maps to a simple value # property-like keys; each key maps to a simple value
player_initial_lives: "3" player_initial_lives: "3"
ui_properties_file_name: "user-interface.properties" ui_properties_file_name: "user-interface.properties"
#
# file-like keys # file-like keys
game.properties: | game.properties: |
enemy.types=aliens,monsters enemy.types=aliens,monsters
@ -94,6 +106,7 @@ when that happens. By accessing the Kubernetes API directly, this
technique also lets you access a ConfigMap in a different namespace. technique also lets you access a ConfigMap in a different namespace.
Here's an example Pod that uses values from `game-demo` to configure a Pod: Here's an example Pod that uses values from `game-demo` to configure a Pod:
```yaml ```yaml
apiVersion: v1 apiVersion: v1
kind: Pod kind: Pod
@ -134,7 +147,6 @@ spec:
path: "user-interface.properties" path: "user-interface.properties"
``` ```
A ConfigMap doesn't differentiate between single line property values and A ConfigMap doesn't differentiate between single line property values and
multi-line file-like values. multi-line file-like values.
What matters is how Pods and other objects consume those values. What matters is how Pods and other objects consume those values.
@ -153,7 +165,6 @@ ConfigMaps can be mounted as data volumes. ConfigMaps can also be used by other
parts of the system, without being directly exposed to the Pod. For example, parts of the system, without being directly exposed to the Pod. For example,
ConfigMaps can hold data that other parts of the system should use for configuration. ConfigMaps can hold data that other parts of the system should use for configuration.
{{< note >}}
The most common way to use ConfigMaps is to configure settings for The most common way to use ConfigMaps is to configure settings for
containers running in a Pod in the same namespace. You can also use a containers running in a Pod in the same namespace. You can also use a
ConfigMap separately. ConfigMap separately.
@ -162,16 +173,23 @@ For example, you
might encounter {{< glossary_tooltip text="addons" term_id="addons" >}} might encounter {{< glossary_tooltip text="addons" term_id="addons" >}}
or {{< glossary_tooltip text="operators" term_id="operator-pattern" >}} that or {{< glossary_tooltip text="operators" term_id="operator-pattern" >}} that
adjust their behavior based on a ConfigMap. adjust their behavior based on a ConfigMap.
{{< /note >}}
### Using ConfigMaps as files from a Pod ### Using ConfigMaps as files from a Pod
To consume a ConfigMap in a volume in a Pod: To consume a ConfigMap in a volume in a Pod:
1. Create a config map or use an existing one. Multiple Pods can reference the same config map. 1. Create a ConfigMap or use an existing one. Multiple Pods can reference the
1. Modify your Pod definition to add a volume under `.spec.volumes[]`. Name the volume anything, and have a `.spec.volumes[].configMap.name` field set to reference your ConfigMap object. same ConfigMap.
1. Add a `.spec.containers[].volumeMounts[]` to each container that needs the config map. Specify `.spec.containers[].volumeMounts[].readOnly = true` and `.spec.containers[].volumeMounts[].mountPath` to an unused directory name where you would like the config map to appear. 1. Modify your Pod definition to add a volume under `.spec.volumes[]`. Name
1. Modify your image or command line so that the program looks for files in that directory. Each key in the config map `data` map becomes the filename under `mountPath`. the volume anything, and have a `.spec.volumes[].configMap.name` field set
to reference your ConfigMap object.
1. Add a `.spec.containers[].volumeMounts[]` to each container that needs the
ConfigMap. Specify `.spec.containers[].volumeMounts[].readOnly = true` and
`.spec.containers[].volumeMounts[].mountPath` to an unused directory name
where you would like the ConfigMap to appear.
1. Modify your image or command line so that the program looks for files in
that directory. Each key in the ConfigMap `data` map becomes the filename
under `mountPath`.
This is an example of a Pod that mounts a ConfigMap in a volume: This is an example of a Pod that mounts a ConfigMap in a volume:
@ -201,8 +219,8 @@ own `volumeMounts` block, but only one `.spec.volumes` is needed per ConfigMap.
#### Mounted ConfigMaps are updated automatically #### Mounted ConfigMaps are updated automatically
When a config map currently consumed in a volume is updated, projected keys are eventually updated as well. When a ConfigMap currently consumed in a volume is updated, projected keys are eventually updated as well.
The kubelet checks whether the mounted config map is fresh on every periodic sync. The kubelet checks whether the mounted ConfigMap is fresh on every periodic sync.
However, the kubelet uses its local cache for getting the current value of the ConfigMap. However, the kubelet uses its local cache for getting the current value of the ConfigMap.
The type of the cache is configurable using the `ConfigMapAndSecretChangeDetectionStrategy` field in The type of the cache is configurable using the `ConfigMapAndSecretChangeDetectionStrategy` field in
the [KubeletConfiguration struct](https://github.com/kubernetes/kubernetes/blob/{{< param "docsbranch" >}}/staging/src/k8s.io/kubelet/config/v1beta1/types.go). the [KubeletConfiguration struct](https://github.com/kubernetes/kubernetes/blob/{{< param "docsbranch" >}}/staging/src/k8s.io/kubelet/config/v1beta1/types.go).
@ -224,12 +242,13 @@ data has the following advantages:
- protects you from accidental (or unwanted) updates that could cause applications outages - protects you from accidental (or unwanted) updates that could cause applications outages
- improves performance of your cluster by significantly reducing load on kube-apiserver, by - improves performance of your cluster by significantly reducing load on kube-apiserver, by
closing watches for config maps marked as immutable. closing watches for ConfigMaps marked as immutable.
This feature is controlled by the `ImmutableEphemeralVolumes`
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/).
You can create an immutable ConfigMap by setting the `immutable` field to `true`.
For example:
This feature is controlled by the `ImmutableEphemeralVolumes` [feature
gate](/docs/reference/command-line-tools-reference/feature-gates/),
which is enabled by default since v1.19. You can create an immutable
ConfigMap by setting the `immutable` field to `true`. For example,
```yaml ```yaml
apiVersion: v1 apiVersion: v1
kind: ConfigMap kind: ConfigMap
@ -240,17 +259,13 @@ data:
immutable: true immutable: true
``` ```
{{< note >}} Once a ConfigMap is marked as immutable, it is _not_ possible to revert this change
Once a ConfigMap or Secret is marked as immutable, it is _not_ possible to revert this change nor to mutate the contents of the `data` or the `binaryData` field. You can
nor to mutate the contents of the `data` field. You can only delete and recreate the ConfigMap. only delete and recreate the ConfigMap. Because existing Pods maintain a mount point
Existing Pods maintain a mount point to the deleted ConfigMap - it is recommended to recreate to the deleted ConfigMap, it is recommended to recreate these pods.
these pods.
{{< /note >}}
## {{% heading "whatsnext" %}} ## {{% heading "whatsnext" %}}
* Read about [Secrets](/docs/concepts/configuration/secret/). * Read about [Secrets](/docs/concepts/configuration/secret/).
* Read [Configure a Pod to Use a ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap/). * Read [Configure a Pod to Use a ConfigMap](/docs/tasks/configure-pod-container/configure-pod-configmap/).
* Read [The Twelve-Factor App](https://12factor.net/) to understand the motivation for * Read [The Twelve-Factor App](https://12factor.net/) to understand the motivation for