From 673d1d72120430c2b8b8c2032f075169d2bed67a Mon Sep 17 00:00:00 2001 From: Tom Kivlin Date: Tue, 19 Jul 2022 09:40:58 +0100 Subject: [PATCH 01/12] small edit and add back content from PR#2334 --- .../configure-pod-configmap.md | 98 +++++++++++++++---- 1 file changed, 78 insertions(+), 20 deletions(-) diff --git a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md index a4882ff882..c13fc2ce6a 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md +++ b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md @@ -10,7 +10,7 @@ card: Many applications rely on configuration which is used during either application initialization or runtime. Most of the times there is a requirement to adjust values assigned to configuration parameters. -ConfigMaps is the kubernetes way to inject application pods with configuration data. +ConfigMaps is the Kubernetes way to inject application pods with configuration data. ConfigMaps allow you to decouple configuration artifacts from image content to keep containerized applications portable. This page provides a series of usage examples demonstrating how to create ConfigMaps and configure Pods using data stored in ConfigMaps. @@ -623,24 +623,6 @@ Like before, all previous files in the `/etc/config/` directory will be deleted. You can project keys to specific paths and specific permissions on a per-file basis. The [Secrets](/docs/concepts/configuration/secret/#using-secrets-as-files-from-a-pod) user guide explains the syntax. -### Optional References - -A ConfigMap reference may be marked "optional". If the ConfigMap is non-existent, the mounted volume will be empty. If the ConfigMap exists, but the referenced -key is non-existent the path will be absent beneath the mount point. - -### Mounted ConfigMaps are updated automatically - -When a mounted ConfigMap is updated, the projected content is eventually updated too. This applies in the case where an optionally referenced ConfigMap comes into -existence after a pod has started. - -Kubelet checks whether the mounted ConfigMap is fresh on every periodic sync. However, it uses its local TTL-based cache for getting the current value of the -ConfigMap. As a result, the total delay from the moment when the ConfigMap is updated to the moment when new keys are projected to the pod can be as long as -kubelet sync period (1 minute by default) + TTL of ConfigMaps cache (1 minute by default) in kubelet. - -{{< note >}} -A container using a ConfigMap as a [subPath](/docs/concepts/storage/volumes/#using-subpath) volume will not receive ConfigMap updates. -{{< /note >}} - @@ -675,7 +657,7 @@ data: ### Restrictions -- You must create a ConfigMap before referencing it in a Pod specification (unless you mark the ConfigMap as "optional"). If you reference a ConfigMap that doesn't exist, the Pod won't start. Likewise, references to keys that don't exist in the ConfigMap will prevent the pod from starting. +- You must create a ConfigMap before referencing it in a Pod specification, or mark the ConfigMap as "optional" (see [Optional ConfigMaps](#optional-configmaps)). If you reference a ConfigMap that doesn't exist, or hasn't been marked as "optional" the Pod won't start. Likewise, references to keys that don't exist in the ConfigMap will prevent the pod from starting. - If you use `envFrom` to define environment variables from ConfigMaps, keys that are considered invalid will be skipped. The pod will be allowed to start, but the invalid names will be recorded in the event log (`InvalidVariableNames`). The log message lists each skipped key. For example: @@ -693,7 +675,83 @@ data: - You can't use ConfigMaps for {{< glossary_tooltip text="static pods" term_id="static-pod" >}}, because the Kubelet does not support this. +### Optional ConfigMaps +A ConfigMap reference may be marked "optional". +If the ConfigMap is non-existent, the mounted volume will be empty. +If the ConfigMap exists, but the referenced key is non-existent the path will be absent beneath the mount point. + +#### Optional ConfigMap in environment variables + +There might be situations where environment variables are not always required. +These environment variables can be marked as optional in a pod like so: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: dapi-test-pod +spec: + containers: + - name: test-container + image: gcr.io/google_containers/busybox + command: [ "/bin/sh", "-c", "env" ] + env: + - name: SPECIAL_LEVEL_KEY + valueFrom: + configMapKeyRef: + name: a-config + key: akey + optional: true + restartPolicy: Never +``` + +When this Pod is run, the output will be empty. + +#### Optional ConfigMap via volume plugin + +Volumes and files provided by a ConfigMap can be also be marked as optional. +The ConfigMap or the key specified does not have to exist. +The mount path for such items will always be created. + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: dapi-test-pod +spec: + containers: + - name: test-container + image: gcr.io/google_containers/busybox + command: [ "/bin/sh", "-c", "ls /etc/config" ] + volumeMounts: + - name: config-volume + mountPath: /etc/config + volumes: + - name: config-volume + configMap: + name: no-config + optional: true + restartPolicy: Never +``` + +When this pod is run, the output will be: + +```shell +``` + +### Mounted ConfigMaps are updated automatically + +When a mounted ConfigMap is updated, the projected content is eventually updated too. This applies in the case where an optionally referenced ConfigMap comes into +existence after a pod has started. + +Kubelet checks whether the mounted ConfigMap is fresh on every periodic sync. However, it uses its local TTL-based cache for getting the current value of the +ConfigMap. As a result, the total delay from the moment when the ConfigMap is updated to the moment when new keys are projected to the pod can be as long as +kubelet sync period (1 minute by default) + TTL of ConfigMaps cache (1 minute by default) in kubelet. + +{{< note >}} +A container using a ConfigMap as a [subPath](/docs/concepts/storage/volumes/#using-subpath) volume will not receive ConfigMap updates. +{{< /note >}} ## {{% heading "whatsnext" %}} From 00984b38b76a3e241f9a95f720b789e1ab9c618e Mon Sep 17 00:00:00 2001 From: Tom Kivlin <52716470+tomkivlin@users.noreply.github.com> Date: Thu, 21 Jul 2022 07:49:41 +0100 Subject: [PATCH 02/12] Update content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md Co-authored-by: Tim Bannister --- .../tasks/configure-pod-container/configure-pod-configmap.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md index c13fc2ce6a..668db33f09 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md +++ b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md @@ -684,7 +684,8 @@ If the ConfigMap exists, but the referenced key is non-existent the path will be #### Optional ConfigMap in environment variables There might be situations where environment variables are not always required. -These environment variables can be marked as optional in a pod like so: +You can mark an environment variables for a container as optional, +like this: ```yaml apiVersion: v1 From 9513b63d2e21816a9bc37cbc34fc7997223c99c0 Mon Sep 17 00:00:00 2001 From: Tom Kivlin <52716470+tomkivlin@users.noreply.github.com> Date: Thu, 21 Jul 2022 07:49:51 +0100 Subject: [PATCH 03/12] Update content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md Co-authored-by: Tim Bannister --- .../tasks/configure-pod-container/configure-pod-configmap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md index 668db33f09..f0055771b9 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md +++ b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md @@ -703,7 +703,7 @@ spec: configMapKeyRef: name: a-config key: akey - optional: true + optional: true # mark the variable as optional restartPolicy: Never ``` From 9289136116ae969e1e1657eb59274341aa63edc2 Mon Sep 17 00:00:00 2001 From: Tom Kivlin <52716470+tomkivlin@users.noreply.github.com> Date: Thu, 21 Jul 2022 07:49:59 +0100 Subject: [PATCH 04/12] Update content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md Co-authored-by: Tim Bannister --- .../tasks/configure-pod-container/configure-pod-configmap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md index f0055771b9..538fddeed6 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md +++ b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md @@ -732,7 +732,7 @@ spec: - name: config-volume configMap: name: no-config - optional: true + optional: true # mark the source ConfigMap as optional restartPolicy: Never ``` From 8066c73a871f247ec1f17156d54383de03f5e4c9 Mon Sep 17 00:00:00 2001 From: Tom Kivlin <52716470+tomkivlin@users.noreply.github.com> Date: Thu, 21 Jul 2022 07:50:09 +0100 Subject: [PATCH 05/12] Update content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md Co-authored-by: Tim Bannister --- .../tasks/configure-pod-container/configure-pod-configmap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md index 538fddeed6..2785177312 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md +++ b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md @@ -736,7 +736,7 @@ spec: restartPolicy: Never ``` -When this pod is run, the output will be: +If you run this pod, and there is no ConfigMap named `no-config`, the output is: ```shell ``` From a24f7c6febee21e979f8d2490d40fbc6ead73ddf Mon Sep 17 00:00:00 2001 From: Tom Kivlin <52716470+tomkivlin@users.noreply.github.com> Date: Thu, 21 Jul 2022 07:50:27 +0100 Subject: [PATCH 06/12] Update content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md Co-authored-by: Tim Bannister --- .../tasks/configure-pod-container/configure-pod-configmap.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md index 2785177312..b3cba70557 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md +++ b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md @@ -707,7 +707,10 @@ spec: restartPolicy: Never ``` -When this Pod is run, the output will be empty. +If you run this pod, and there is no ConfigMap named `a-config`, the output is empty. +If you run this pod, and there is a ConfigMap named `a-config` but that ConfigMap doesn't have +a key named `akey`, the output is also empty. If you do set a value for `akey` in the `a-config` +ConfigMap, this pod prints that value and then terminates. #### Optional ConfigMap via volume plugin From 461f5c72e73d4a6858b541953b4bd8ba32f06192 Mon Sep 17 00:00:00 2001 From: Tom Kivlin <52716470+tomkivlin@users.noreply.github.com> Date: Thu, 21 Jul 2022 07:50:36 +0100 Subject: [PATCH 07/12] Update content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md Co-authored-by: Tim Bannister --- .../tasks/configure-pod-container/configure-pod-configmap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md index b3cba70557..215eb7b65c 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md +++ b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md @@ -10,7 +10,7 @@ card: Many applications rely on configuration which is used during either application initialization or runtime. Most of the times there is a requirement to adjust values assigned to configuration parameters. -ConfigMaps is the Kubernetes way to inject application pods with configuration data. +ConfigMaps are the Kubernetes way to inject application pods with configuration data. ConfigMaps allow you to decouple configuration artifacts from image content to keep containerized applications portable. This page provides a series of usage examples demonstrating how to create ConfigMaps and configure Pods using data stored in ConfigMaps. From b0b5f5f2640446a8cd30a9d7e5b6eb6df731a11e Mon Sep 17 00:00:00 2001 From: Tom Kivlin <52716470+tomkivlin@users.noreply.github.com> Date: Thu, 21 Jul 2022 07:50:45 +0100 Subject: [PATCH 08/12] Update content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md Co-authored-by: Tim Bannister --- .../tasks/configure-pod-container/configure-pod-configmap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md index 215eb7b65c..11959ff8f2 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md +++ b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md @@ -677,7 +677,7 @@ data: ### Optional ConfigMaps -A ConfigMap reference may be marked "optional". +In a Pod, or pod template, you can mark a reference to a ConfigMap as _optional_. If the ConfigMap is non-existent, the mounted volume will be empty. If the ConfigMap exists, but the referenced key is non-existent the path will be absent beneath the mount point. From 7e16543b9dbe6771017730199b62e2b99c18803e Mon Sep 17 00:00:00 2001 From: Tom Kivlin <52716470+tomkivlin@users.noreply.github.com> Date: Thu, 21 Jul 2022 08:58:21 +0100 Subject: [PATCH 09/12] Update configure-pod-configmap.md --- .../configure-pod-container/configure-pod-configmap.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md index 11959ff8f2..b6679980ad 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md +++ b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md @@ -678,8 +678,8 @@ data: ### Optional ConfigMaps In a Pod, or pod template, you can mark a reference to a ConfigMap as _optional_. -If the ConfigMap is non-existent, the mounted volume will be empty. -If the ConfigMap exists, but the referenced key is non-existent the path will be absent beneath the mount point. +If the ConfigMap is non-existent, the configuration for which it provides data in the Pod (e.g. environment variable, mounted volume) will be empty. +If the ConfigMap exists, but the referenced key is non-existent the data is also empty. #### Optional ConfigMap in environment variables @@ -739,10 +739,7 @@ spec: restartPolicy: Never ``` -If you run this pod, and there is no ConfigMap named `no-config`, the output is: - -```shell -``` +If you run this pod, and there is no ConfigMap named `no-config`, the mounted volume will be empty. ### Mounted ConfigMaps are updated automatically From c3f86b7fc081ed84e972315c5352c421a60b0689 Mon Sep 17 00:00:00 2001 From: Tom Kivlin <52716470+tomkivlin@users.noreply.github.com> Date: Tue, 26 Jul 2022 09:19:15 +0100 Subject: [PATCH 10/12] Update content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md Co-authored-by: Shannon Kularathna --- .../tasks/configure-pod-container/configure-pod-configmap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md index b6679980ad..dd2f2b1c67 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md +++ b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md @@ -746,7 +746,7 @@ If you run this pod, and there is no ConfigMap named `no-config`, the mounted vo When a mounted ConfigMap is updated, the projected content is eventually updated too. This applies in the case where an optionally referenced ConfigMap comes into existence after a pod has started. -Kubelet checks whether the mounted ConfigMap is fresh on every periodic sync. However, it uses its local TTL-based cache for getting the current value of the +The kubelet checks whether the mounted ConfigMap is fresh on every periodic sync. However, it uses its local TTL-based cache for getting the current value of the ConfigMap. As a result, the total delay from the moment when the ConfigMap is updated to the moment when new keys are projected to the pod can be as long as kubelet sync period (1 minute by default) + TTL of ConfigMaps cache (1 minute by default) in kubelet. From 748d4a998d89bde6c78b3eb301f11deb7372be57 Mon Sep 17 00:00:00 2001 From: Tom Kivlin <52716470+tomkivlin@users.noreply.github.com> Date: Tue, 26 Jul 2022 09:20:11 +0100 Subject: [PATCH 11/12] Update content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md Co-authored-by: Shannon Kularathna --- .../configure-pod-container/configure-pod-configmap.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md index dd2f2b1c67..44b0dfcbd6 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md +++ b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md @@ -712,11 +712,8 @@ If you run this pod, and there is a ConfigMap named `a-config` but that ConfigMa a key named `akey`, the output is also empty. If you do set a value for `akey` in the `a-config` ConfigMap, this pod prints that value and then terminates. -#### Optional ConfigMap via volume plugin - -Volumes and files provided by a ConfigMap can be also be marked as optional. -The ConfigMap or the key specified does not have to exist. -The mount path for such items will always be created. +You can also mark the volumes and files provided by a ConfigMap as optional. Kubernetes always creates the mount paths for the volume, even if the referenced ConfigMap or key doesn't exist. For example, the following +Pod specification marks a volume that references a ConfigMap as optional: ```yaml apiVersion: v1 @@ -737,9 +734,6 @@ spec: name: no-config optional: true # mark the source ConfigMap as optional restartPolicy: Never -``` - -If you run this pod, and there is no ConfigMap named `no-config`, the mounted volume will be empty. ### Mounted ConfigMaps are updated automatically From ad33b0c10757978ffaddfa66a691dc9ea302bec1 Mon Sep 17 00:00:00 2001 From: Tom Kivlin Date: Tue, 26 Jul 2022 09:48:28 +0100 Subject: [PATCH 12/12] updates from Shannon feedback --- .../configure-pod-configmap.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md index 44b0dfcbd6..02329f931c 100644 --- a/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md +++ b/content/en/docs/tasks/configure-pod-container/configure-pod-configmap.md @@ -657,7 +657,7 @@ data: ### Restrictions -- You must create a ConfigMap before referencing it in a Pod specification, or mark the ConfigMap as "optional" (see [Optional ConfigMaps](#optional-configmaps)). If you reference a ConfigMap that doesn't exist, or hasn't been marked as "optional" the Pod won't start. Likewise, references to keys that don't exist in the ConfigMap will prevent the pod from starting. +- You must create the `ConfigMap` object before you reference it in a Pod specification. Alternatively, mark the ConfigMap reference as `optional` in the Pod spec (see [Optional ConfigMaps](#optional-configmaps)). If you reference a ConfigMap that doesn't exist and you don't mark the reference as `optional`, the Pod won't start. Similarly, references to keys that don't exist in the ConfigMap will also prevent the Pod from starting, unless you mark the key references as `optional`. - If you use `envFrom` to define environment variables from ConfigMaps, keys that are considered invalid will be skipped. The pod will be allowed to start, but the invalid names will be recorded in the event log (`InvalidVariableNames`). The log message lists each skipped key. For example: @@ -677,15 +677,11 @@ data: ### Optional ConfigMaps -In a Pod, or pod template, you can mark a reference to a ConfigMap as _optional_. -If the ConfigMap is non-existent, the configuration for which it provides data in the Pod (e.g. environment variable, mounted volume) will be empty. +You can mark a reference to a ConfigMap as _optional_ in a Pod specification. +If the ConfigMap doesn't exist, the configuration for which it provides data in the Pod (e.g. environment variable, mounted volume) will be empty. If the ConfigMap exists, but the referenced key is non-existent the data is also empty. -#### Optional ConfigMap in environment variables - -There might be situations where environment variables are not always required. -You can mark an environment variables for a container as optional, -like this: +For example, the following Pod specification marks an environment variable from a ConfigMap as optional: ```yaml apiVersion: v1 @@ -734,6 +730,7 @@ spec: name: no-config optional: true # mark the source ConfigMap as optional restartPolicy: Never +``` ### Mounted ConfigMaps are updated automatically