Improve ConfigMap concept
This PR adds some missing information to the ConfigMap concept page.pull/23807/head
Qiming Teng
parent
0b9a6fd844
commit
b1490ef95f
|
|
@ -16,7 +16,6 @@ or use additional (third party) tools to keep your data private.
|
|||
{{< /caution >}}
|
||||
|
||||
|
||||
|
||||
<!-- body -->
|
||||
## 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
|
||||
own computer (for development) and in the cloud (to handle real traffic).
|
||||
You write the code to
|
||||
look in an environment variable named `DATABASE_HOST`. Locally, you set that variable
|
||||
to `localhost`. In the cloud, you set it to refer to a Kubernetes
|
||||
{{< glossary_tooltip text="Service" term_id="service" >}} that exposes the database
|
||||
component to your cluster.
|
||||
|
||||
You write the code to look in an environment variable named `DATABASE_HOST`.
|
||||
Locally, you set that variable to `localhost`. In the cloud, you set it to
|
||||
refer to a Kubernetes {{< glossary_tooltip text="Service" term_id="service" >}}
|
||||
that exposes the database component to your cluster.
|
||||
This lets you fetch a container image running in the cloud and
|
||||
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
|
||||
|
||||
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
|
||||
Kubernetes objects that have a `spec`, a ConfigMap has a `data` section to
|
||||
store items (keys) and their values.
|
||||
Kubernetes objects that have a `spec`, a ConfigMap has `data` and `binaryData`
|
||||
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
|
||||
[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
|
||||
|
||||
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
|
||||
player_initial_lives: "3"
|
||||
ui_properties_file_name: "user-interface.properties"
|
||||
#
|
||||
|
||||
# file-like keys
|
||||
game.properties: |
|
||||
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.
|
||||
|
||||
Here's an example Pod that uses values from `game-demo` to configure a Pod:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
|
|
@ -134,7 +147,6 @@ spec:
|
|||
path: "user-interface.properties"
|
||||
```
|
||||
|
||||
|
||||
A ConfigMap doesn't differentiate between single line property values and
|
||||
multi-line file-like 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,
|
||||
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
|
||||
containers running in a Pod in the same namespace. You can also use a
|
||||
ConfigMap separately.
|
||||
|
|
@ -162,16 +173,23 @@ For example, you
|
|||
might encounter {{< glossary_tooltip text="addons" term_id="addons" >}}
|
||||
or {{< glossary_tooltip text="operators" term_id="operator-pattern" >}} that
|
||||
adjust their behavior based on a ConfigMap.
|
||||
{{< /note >}}
|
||||
|
||||
### Using ConfigMaps as files from 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. 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.
|
||||
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 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`.
|
||||
1. Create a ConfigMap or use an existing one. Multiple Pods can reference the
|
||||
same ConfigMap.
|
||||
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.
|
||||
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:
|
||||
|
||||
|
|
@ -201,8 +219,8 @@ own `volumeMounts` block, but only one `.spec.volumes` is needed per ConfigMap.
|
|||
|
||||
#### Mounted ConfigMaps are updated automatically
|
||||
|
||||
When a config map 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.
|
||||
When a ConfigMap currently consumed in a volume is updated, projected keys are eventually updated as well.
|
||||
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.
|
||||
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).
|
||||
|
|
@ -224,12 +242,13 @@ data has the following advantages:
|
|||
|
||||
- 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
|
||||
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
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
|
|
@ -240,17 +259,13 @@ data:
|
|||
immutable: true
|
||||
```
|
||||
|
||||
{{< note >}}
|
||||
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` field. You can only delete and recreate the ConfigMap.
|
||||
Existing Pods maintain a mount point to the deleted ConfigMap - it is recommended to recreate
|
||||
these pods.
|
||||
{{< /note >}}
|
||||
|
||||
Once a ConfigMap 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
|
||||
only delete and recreate the ConfigMap. Because existing Pods maintain a mount point
|
||||
to the deleted ConfigMap, it is recommended to recreate these pods.
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
|
||||
* Read about [Secrets](/docs/concepts/configuration/secret/).
|
||||
* 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue