From d98f7ab88435f219d0e21390d0ee98c1e892057c Mon Sep 17 00:00:00 2001 From: Eric Tune Date: Thu, 13 Aug 2015 18:25:46 -0700 Subject: [PATCH] Improve secrets docs. Explain that imagePullSecrets added to a service account are added automatically to pods using that service account. Reword text to not imply that ordinary secrets added to a service account are not automatically added as volumes to a pod. --- docs/user-guide/secrets.md | 48 ++++++++++++++----------- docs/user-guide/service-accounts.md | 56 +++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+), 21 deletions(-) diff --git a/docs/user-guide/secrets.md b/docs/user-guide/secrets.md index 0eca9b16aba..90e4a7b9512 100644 --- a/docs/user-guide/secrets.md +++ b/docs/user-guide/secrets.md @@ -43,11 +43,12 @@ a docker image. See [Secrets design document](../design/secrets.md) for more inf - [Secrets](#secrets) - [Overview of Secrets](#overview-of-secrets) - - [Service Accounts Automatically Create and Use Secrets with API Credentials](#service-accounts-automatically-create-and-use-secrets-with-api-credentials) + - [Service Accounts Automatically Create and Attach Secrets with API Credentials](#service-accounts-automatically-create-and-attach-secrets-with-api-credentials) - [Creating a Secret Manually](#creating-a-secret-manually) - [Manually specifying a Secret to be Mounted on a Pod](#manually-specifying-a-secret-to-be-mounted-on-a-pod) - [Manually specifying an imagePullSecret](#manually-specifying-an-imagepullsecret) - - [Automatic use of Manually Created Secrets](#automatic-use-of-manually-created-secrets) + - [Arranging for imagePullSecrets to be Automatically Attached](#arranging-for-imagepullsecrets-to-be-automatically-attached) + - [Automatic Mounting of Manually Created Secrets](#automatic-mounting-of-manually-created-secrets) - [Details](#details) - [Restrictions](#restrictions) - [Consuming Secret Values](#consuming-secret-values) @@ -64,19 +65,18 @@ a docker image. See [Secrets design document](../design/secrets.md) for more inf ## Overview of Secrets +A Secret is an object that contains a small amount of sensitive data such as +a password, a token, or a key. Such information might otherwise be put in a +Pod specification or in an image; putting it in a Secret object allows for +more control over how it is used, and reduces the risk of accidental exposure. -Creation of secrets can be manual (done by the user) or automatic (done by -automation built into the cluster). +Users can create secrets, and the system also creates some secrets. -A secret can be used with a pod in two ways: either as files in a [volume](volumes.md) mounted on one or more of +To use a secret, a pod needs to reference the secret. +A secret can be used with a pod in two ways: eithe as files in a [volume](volumes.md) mounted on one or more of its containers, or used by kubelet when pulling images for the pod. -To use a secret, a pod needs to reference the secret. This reference -can likewise be added manually or automatically. - -A single Pod may use various combination of the above options. - -### Service Accounts Automatically Create and Use Secrets with API Credentials +### Service Accounts Automatically Create and Attach Secrets with API Credentials Kubernetes automatically creates secrets which contain credentials for accessing the API and it automatically modifies your pods to use this type of @@ -112,9 +112,8 @@ are `value-1` and `value-2`, respectively, with carriage return and newline char Create the secret using [`kubectl create`](kubectl/kubectl_create.md). -Once the secret is created, you can: - - create pods that automatically use it via a [Service Account](service-accounts.md). - - modify your pod specification to use the secret +Once the secret is created, you can need to modify your pod to specify +that it should use the secret. ### Manually specifying a Secret to be Mounted on a Pod @@ -162,15 +161,22 @@ See another example of creating a secret and a pod that consumes that secret in Use of imagePullSecrets is described in the [images documentation](images.md#specifying-imagepullsecrets-on-a-pod) -### Automatic use of Manually Created Secrets +### Arranging for imagePullSecrets to be Automatically Attached -*This feature is planned but not implemented. See [issue -9902](http://issue.k8s.io/9902).* +You can manually create an imagePullSecret, and reference it from +a serviceAccount. Any pods created with that serviceAccount +or that default to use that serviceAccount, will get have the imagePullSecret of the +field set to that of the service account. +See [here](service-accounts.md#adding-imagepullsecrets-to-a-service-account) + for a detailed explanation of that process. -You can reference manually created secrets from a [Service Account](service-accounts.md). -Then, pods which use that Service Account will have -`volumeMounts` and/or `imagePullSecrets` added to them. -The secrets will be mounted at **TBD**. + +### Automatic Mounting of Manually Created Secrets + +We plan to extend the service account behavior so that manually created +secrets (e.g. one containing a token for accessing a github account) +can be automatically attached to pods based on their service account. +*This is not implemented yet. See [issue 9902](http://issue.k8s.io/9902).* ## Details diff --git a/docs/user-guide/service-accounts.md b/docs/user-guide/service-accounts.md index 3ddb821e44d..dbd99a44bc3 100644 --- a/docs/user-guide/service-accounts.md +++ b/docs/user-guide/service-accounts.md @@ -160,6 +160,62 @@ token: > Note that the content of `token` is elided here. +## Adding ImagePullSecrets to a service account + +First, create an imagePullSecret, as described [here](images.md#specifying-imagepullsecrets-on-a-pod) +Next, verify it has been created. For example: + +```console +$ kubectl get secrets myregistrykey +NAME TYPE DATA +myregistrykey kubernetes.io/dockercfg 1 +``` + +Next, read/modify/write the service account for the namespace to use this secret as an imagePullSecret + +```console +$ kubectl get serviceaccounts default -o yaml > ./sa.yaml +$ cat sa.yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + creationTimestamp: 2015-08-07T22:02:39Z + name: default + namespace: default + resourceVersion: "243024" + selfLink: /api/v1/namespaces/default/serviceaccounts/default + uid: 052fb0f4-3d50-11e5-b066-42010af0d7b6 +secrets: +- name: default-token-uudge +$ vi sa.yaml +[editor session not shown] +[delete line with key "resourceVersion"] +[add lines with "imagePullSecret:"] +$ cat sa.yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + creationTimestamp: 2015-08-07T22:02:39Z + name: default + namespace: default + selfLink: /api/v1/namespaces/default/serviceaccounts/default + uid: 052fb0f4-3d50-11e5-b066-42010af0d7b6 +secrets: +- name: default-token-uudge +imagePullSecrets: +- name: myregistrykey +$ kubectl replace serviceaccount default -f ./sa.yaml +serviceaccounts/default +``` + +Now, any new pods created in the current namespace will have this added to their spec: + +```yaml +spec: + imagePullSecrets: + - name: myregistrykey +``` + ## Adding Secrets to a service account. TODO: Test and explain how to use additional non-K8s secrets with an existing service account.