From 7abcc6c8540a7b0a4f6712e77e0f5cb134271bed Mon Sep 17 00:00:00 2001 From: Michael Fraenkel Date: Tue, 24 Jan 2017 06:31:10 -0700 Subject: [PATCH] Document new optional support for ConfigMap and Secret Corresponds to proposal https://github.com/kubernetes/community/pull/175 --- docs/user-guide/configmap/index.md | 70 ++++++++++++++++++++++++++-- docs/user-guide/secrets/index.md | 74 +++++++++++++++++++++++++++--- 2 files changed, 134 insertions(+), 10 deletions(-) diff --git a/docs/user-guide/configmap/index.md b/docs/user-guide/configmap/index.md index d630ed2aa8..2e80ec8d9b 100644 --- a/docs/user-guide/configmap/index.md +++ b/docs/user-guide/configmap/index.md @@ -291,6 +291,37 @@ SPECIAL_LEVEL_KEY=very SPECIAL_TYPE_KEY=charm ``` +#### 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, its output will include the lines: + +```shell +``` + ### Use-Case: Set command-line arguments with ConfigMap ConfigMaps can also be used to set the value of the command or arguments in a container. This is @@ -422,6 +453,38 @@ very You can project keys to specific paths and specific permissions on a per-file basis. The [Secrets](/docs/user-guide/secrets/) user guide explains the syntax. +#### 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 +``` + ## Real World Example: Configuring Redis Let's take a look at a real-world example: configuring redis using ConfigMap. Say we want to inject @@ -517,9 +580,10 @@ $ kubectl exec -it redis redis-cli ## Restrictions -ConfigMaps must be created before they are consumed in pods. Controllers may be written to tolerate -missing configuration data; consult individual components configured via ConfigMap on a case-by-case -basis. +ConfigMaps must be created before they are consumed in pods unless they are +marked as optional. Controllers may be written to tolerate missing +configuration data; consult individual components configured via ConfigMap on +a case-by-case basis. ConfigMaps reside in a namespace. They can only be referenced by pods in the same namespace. diff --git a/docs/user-guide/secrets/index.md b/docs/user-guide/secrets/index.md index 6942b52ff3..7da0f446fd 100644 --- a/docs/user-guide/secrets/index.md +++ b/docs/user-guide/secrets/index.md @@ -372,6 +372,41 @@ files. When a secret being already consumed in a volume is updated, projected keys are eventually updated as well. The update time depends on the kubelet syncing period. +#### Optional Secrets as Files from a Pod + +Volumes and files provided by a Secret can be also be marked as optional. +The Secret or the key within a Secret does not have to exist. The mount path for +such items will always be created. + +```json +{ + "apiVersion": "v1", + "kind": "Pod", + "metadata": { + "name": "mypod", + "namespace": "myns" + }, + "spec": { + "containers": [{ + "name": "mypod", + "image": "redis", + "volumeMounts": [{ + "name": "foo", + "mountPath": "/etc/foo" + }] + }], + "volumes": [{ + "name": "foo", + "secret": { + "secretName": "mysecret", + "defaultMode": 256, + "optional": true + } + }] + } +} +``` + #### Using Secrets as Environment Variables To use a secret in an environment variable in a pod: @@ -418,6 +453,30 @@ $ echo $SECRET_PASSWORD 1f2d1e2e67df ``` +#### Optional Secrets from Environment Variables + +You may not want to require all your secrets to exist. They can be marked as +optional as shown in the pod: + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: optional-secret-env-pod +spec: + containers: + - name: mycontainer + image: redis + env: + - name: OPTIONAL_SECRET + valueFrom: + secretKeyRef: + name: mysecret + key: username + optional: true + restartPolicy: Never +``` + #### Using imagePullSecrets An imagePullSecret is a way to pass a secret that contains a Docker (or other) image registry @@ -449,7 +508,8 @@ can be automatically attached to pods based on their service account. Secret volume sources are validated to ensure that the specified object reference actually points to an object of type `Secret`. Therefore, a secret -needs to be created before any pods that depend on it. +needs to be created before any pods that depend on it, unless it is marked as +optional. Secret API objects reside in a namespace. They can only be referenced by pods in that same namespace. @@ -469,12 +529,12 @@ not common ways to create pods.) When a pod is created via the API, there is no check whether a referenced secret exists. Once a pod is scheduled, the kubelet will try to fetch the -secret value. If the secret cannot be fetched because it does not exist or -because of a temporary lack of connection to the API server, kubelet will -periodically retry. It will report an event about the pod explaining the -reason it is not started yet. Once the secret is fetched, the kubelet will -create and mount a volume containing it. None of the pod's containers will -start until all the pod's volumes are mounted. +secret value. If a required secret cannot be fetched because it does not +exist or because of a temporary lack of connection to the API server, the +kubelet will periodically retry. It will report an event about the pod +explaining the reason it is not started yet. Once the secret is fetched, the +kubelet will create and mount a volume containing it. None of the pod's +containers will start until all the pod's volumes are mounted. ## Use cases