From 407a05b6d2e8abd2a68f76bf95c905df926e0b68 Mon Sep 17 00:00:00 2001 From: Jan Chaloupka Date: Sat, 7 May 2016 09:49:00 +0200 Subject: [PATCH 1/2] Extend secrets docs with key to path mapping and automatic updates of mounted secrets. Secret volume plugin has been refactored. Currently, AtomicWritter is used to project all keys. Allowing to automatically refresh projected secrets. --- docs/user-guide/secrets/index.md | 70 ++++++++++++++++++++++++-------- 1 file changed, 52 insertions(+), 18 deletions(-) diff --git a/docs/user-guide/secrets/index.md b/docs/user-guide/secrets/index.md index 25eb5cfbee..7e23b14bd5 100644 --- a/docs/user-guide/secrets/index.md +++ b/docs/user-guide/secrets/index.md @@ -214,6 +214,52 @@ You can package many files into one secret, or use many secrets, whichever is co See another example of creating a secret and a pod that consumes that secret in a volume [here](/docs/user-guide/secrets/). +##### Projection of secret keys to specific paths + +We can also control the paths within the volume where Secret keys are projected. +You can use `spec.volumes[].secret.items` field to change target path of each key: + +```json +{ + "apiVersion": "v1", + "kind": "Pod", + "metadata": { + "name": "mypod", + "namespace": "myns" + }, + "spec": { + "containers": [{ + "name": "mypod", + "image": "redis", + "volumeMounts": [{ + "name": "foo", + "mountPath": "/etc/foo", + "readOnly": true + }] + }], + "volumes": [{ + "name": "foo", + "secret": { + "secretName": "mysecret", + "items": [{ + "key": "username", + "path": "my-group/my-username" + }] + } + }] + } +} +``` + +What will happen: + +* `username` secret is stored under `/etc/foo/my-group/my-username` file instead of `/etc/foo/username`. +* `password` secret is not projected + +If `spec.volumes[].secret.items` is used, only keys specified in `items` are projected. +To consume all keys from the secret, all of them must be listed in the `items` field. +All listed keys must exist in the corresponding secret. Otherwise, the volume is not created. + ##### Consuming Secret Values from Volumes Inside the container that mounts a secret volume, the secret keys appear as @@ -234,6 +280,11 @@ $ cat /etc/foo/password The program in a container is responsible for reading the secret(s) from the files. +##### Mounted Secrets are updated automatically + +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. + #### Using Secrets as Environment Variables To use a secret in an environment variable in a pod: @@ -334,27 +385,10 @@ 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 a secret is fetched, the kubelet will +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. -Once the kubelet has started a pod's containers, its secret volumes will not -change, even if the secret resource is modified. To change the secret used, -the original pod must be deleted, and a new pod (perhaps with an identical -`PodSpec`) must be created. Therefore, updating a secret follows the same -workflow as deploying a new container image. The `kubectl rolling-update` -command can be used ([man page](/docs/user-guide/kubectl/kubectl_rolling-update)). - -The [`resourceVersion`](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/api-conventions.md#concurrency-control-and-consistency) -of the secret is not specified when it is referenced. -Therefore, if a secret is updated at about the same time as pods are starting, -then it is not defined which version of the secret will be used for the pod. It -is not possible currently to check what resource version of a secret object was -used when a pod was created. It is planned that pods will report this -information, so that a replication controller restarts ones using an old -`resourceVersion`. In the interim, if this is a concern, it is recommended to not -update the data of existing secrets, but to create new ones with distinct names. - ## Use cases ### Use-Case: Pod with ssh keys From 3589ddbde77fa19442c44b2b55f994a7e62bd865 Mon Sep 17 00:00:00 2001 From: Jan Chaloupka Date: Wed, 1 Jun 2016 09:34:00 +0200 Subject: [PATCH 2/2] Convert level-5 heading into bold heading --- docs/user-guide/secrets/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/user-guide/secrets/index.md b/docs/user-guide/secrets/index.md index 7e23b14bd5..4fcea9e303 100644 --- a/docs/user-guide/secrets/index.md +++ b/docs/user-guide/secrets/index.md @@ -214,7 +214,7 @@ You can package many files into one secret, or use many secrets, whichever is co See another example of creating a secret and a pod that consumes that secret in a volume [here](/docs/user-guide/secrets/). -##### Projection of secret keys to specific paths +**Projection of secret keys to specific paths** We can also control the paths within the volume where Secret keys are projected. You can use `spec.volumes[].secret.items` field to change target path of each key: @@ -260,7 +260,7 @@ If `spec.volumes[].secret.items` is used, only keys specified in `items` are pro To consume all keys from the secret, all of them must be listed in the `items` field. All listed keys must exist in the corresponding secret. Otherwise, the volume is not created. -##### Consuming Secret Values from Volumes +**Consuming Secret Values from Volumes** Inside the container that mounts a secret volume, the secret keys appear as files and the secret values are base-64 decoded and stored inside these files. @@ -280,7 +280,7 @@ $ cat /etc/foo/password The program in a container is responsible for reading the secret(s) from the files. -##### Mounted Secrets are updated automatically +**Mounted Secrets are updated automatically** 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. @@ -318,7 +318,7 @@ spec: restartPolicy: Never ``` -##### Consuming Secret Values from Environment Variables +**Consuming Secret Values from Environment Variables** Inside a container that consumes a secret in an environment variables, the secret keys appear as normal environment variables containing the base-64 decoded values of the secret data. @@ -336,7 +336,7 @@ $ echo $SECRET_PASSWORD An imagePullSecret is a way to pass a secret that contains a Docker (or other) image registry password to the Kubelet so it can pull a private image on behalf of your Pod. -##### Manually specifying an imagePullSecret +**Manually specifying an imagePullSecret** Use of imagePullSecrets is described in the [images documentation](/docs/user-guide/images/#specifying-imagepullsecrets-on-a-pod)