Merge pull request #20023 from erictune/secrets-doc

Auto commit by PR queue bot

docs/user-guide/images.md

@@ -51,6 +51,9 @@ The `image` property of a container supports the same syntax as the `docker` com
     - [Configuring Nodes to Authenticate to a Private Repository](#configuring-nodes-to-authenticate-to-a-private-repository)
     - [Pre-pulling Images](#pre-pulling-images)
     - [Specifying ImagePullSecrets on a Pod](#specifying-imagepullsecrets-on-a-pod)
+      - [Creating a Secret with a Docker Config](#creating-a-secret-with-a-docker-config)
+        - [Bypassing kubectl create secrets](#bypassing-kubectl-create-secrets)
+      - [Referring to an imagePullSecrets on a Pod](#referring-to-an-imagepullsecrets-on-a-pod)
     - [Use Cases](#use-cases)
 
 <!-- END MUNGE: GENERATED_TOC -->
@@ -207,42 +210,40 @@ where node creation is automated.
 
 Kubernetes supports specifying registry keys on a pod.
 
-First, create a `.docker/config.json`, such as by running `docker login <registry.domain>`.
+#### Creating a Secret with a Docker Config
-Then put the resulting `.docker/config.json` file into a [secret resource](secrets.md).  For example:
+
+Run the following command, substituting the appropriate uppercase values:
 
 ```console
-$ docker login
+$ kubectl create secret docker-registry my-registry-secret --docker-server=DOCKER_REGISTRY_SERVER --docker-username=DOCKER_USER --docker-password=DOCKER_PASSWORD --docker-email=DOCKER_EMAIL
-Username: janedoe
+secret "my-registry-secret" created.
-Password: ●●●●●●●●●●●
-Email: jdoe@example.com
-WARNING: login credentials saved in /Users/jdoe/.docker/config.json.
-Login Succeeded
-
-$ echo $(cat ~/.docker/config.json)
-{ "https://index.docker.io/v1/": { "auth": "ZmFrZXBhc3N3b3JkMTIK", "email": "jdoe@example.com" } }
-
-$ cat ~/.docker/config.json | base64
-eyAiaHR0cHM6Ly9pbmRleC5kb2NrZXIuaW8vdjEvIjogeyAiYXV0aCI6ICJabUZyWlhCaGMzTjNiM0prTVRJSyIsICJlbWFpbCI6ICJqZG9lQGV4YW1wbGUuY29tIiB9IH0K
-
-$ cat > /tmp/image-pull-secret.yaml <<EOF
-apiVersion: v1
-kind: Secret
-metadata:
-  name: myregistrykey
-data:
-  .dockerconfigjson: eyAiaHR0cHM6Ly9pbmRleC5kb2NrZXIuaW8vdjEvIjogeyAiYXV0aCI6ICJabUZyWlhCaGMzTjNiM0prTVRJSyIsICJlbWFpbCI6ICJqZG9lQGV4YW1wbGUuY29tIiB9IH0K
-type: kubernetes.io/dockerconfigjson
-EOF
-
-$ kubectl create -f /tmp/image-pull-secret.yaml
-secrets/myregistrykey
 ```
 
+If you need access to multiple registries, you can create one secret for each registry.
+Kubelet will merge any `imagePullSecrets` into a single virtual `.docker/config.json`
+when pulling images for your Pods.
+
+Pods can only reference image pull secrets in their own namespace,
+so this process needs to be done one time per namespace.
+
+##### Bypassing kubectl create secrets
+
+If for some reason you need multiple items in a single `.docker/config.json` or need
+control not given by the above command, then you can [create a secret using
+json or yaml](secrets.md#creating-a-secret-manually).
+
+Be sure to:
+
+- set the name of the data item to `.dockerconfigjson`
+- base64 encode the docker file and paste that string, unbroken
+  as the value for field `data[".dockerconfigjson"]`
+- set `type` to `kubernetes.io/dockerconfigjson`
+
 If you get the error message `error: no objects passed to create`, it may mean the base64 encoded string is invalid.
 If you get an error message like `Secret "myregistrykey" is invalid: data[.dockerconfigjson]: invalid value ...` it means
 the data was successfully un-base64 encoded, but could not be parsed as a `.docker/config.json` file.
 
-This process needs to be done one time per namespace, or to any non-default service accounts you create.
+#### Referring to an imagePullSecrets on a Pod
 
 Now, you can create pods which reference that secret by adding an `imagePullSecrets`
 section to a pod definition.
@@ -261,6 +262,7 @@ spec:
 ```
 
 This needs to be done for each pod that is using a private registry.
+
 However, setting of this field can be automated by setting the imagePullSecrets
 in a [serviceAccount](service-accounts.md) resource.
 

docs/user-guide/secrets.md

@@ -44,12 +44,19 @@ 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 Attach Secrets with API Credentials](#service-accounts-automatically-create-and-attach-secrets-with-api-credentials)
+    - [Built-in Secrets](#built-in-secrets)
-    - [Creating a Secret Manually](#creating-a-secret-manually)
+      - [Service Accounts Automatically Create and Attach Secrets with API Credentials](#service-accounts-automatically-create-and-attach-secrets-with-api-credentials)
+    - [Creating your own Secrets](#creating-your-own-secrets)
+      - [Creating a Secret Using kubectl secret](#creating-a-secret-using-kubectl-secret)
+      - [Creating a Secret Manually](#creating-a-secret-manually)
+      - [Decoding a Secret](#decoding-a-secret)
     - [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)
+    - [Using Secrets](#using-secrets)
-    - [Arranging for imagePullSecrets to be Automatically Attached](#arranging-for-imagepullsecrets-to-be-automatically-attached)
+      - [Using imagePullSecrets](#using-imagepullsecrets)
-    - [Automatic Mounting of Manually Created Secrets](#automatic-mounting-of-manually-created-secrets)
+        - [Manually specifying an imagePullSecret](#manually-specifying-an-imagepullsecret)
+        - [Arranging for imagePullSecrets to be Automatically Attached](#arranging-for-imagepullsecrets-to-be-automatically-attached)
+      - [Using Secrets as Files from a Pod](#using-secrets-as-files-from-a-pod)
+      - [Automatic Mounting of Manually Created Secrets](#automatic-mounting-of-manually-created-secrets)
   - [Details](#details)
     - [Restrictions](#restrictions)
     - [Consuming Secret Values](#consuming-secret-values)
@@ -78,7 +85,9 @@ To use a secret, a pod needs to reference the secret.
 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
 its containers, or used by kubelet when pulling images for the pod.
 
-### Service Accounts Automatically Create and Attach Secrets with API Credentials
+### Built-in Secrets
+
+#### 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
@@ -91,9 +100,70 @@ this is the recommended workflow.
 See the [Service Account](service-accounts.md) documentation for more
 information on how Service Accounts work.
 
-### Creating a Secret Manually
+### Creating your own Secrets
 
-This is an example of a simple secret, in yaml format:
+#### Creating a Secret Using kubectl secret
+
+Say that some pods need to access a database.  The
+username and password that the pods should use is in the files
+`./username.txt` and `./password.txt` on your local machine.
+
+```console
+# Create files needed for rest of example.
+$ echo "admin" > ./username.txt
+$ echo "1f2d1e2e67df" > ./password.txt
+```
+
+The `kubectl create secret` command
+packages these files into a Secret and creates
+the object on the Apiserver.
+
+```console
+$ kubectl create secret generic db-user-pass --from-file=./username.txt --from-file=./password.txt
+secret "db-user-pass" created
+```
+
+You can check that the secret was created like this:
+
+```console
+$ kubectl get secrets
+NAME                  TYPE                                  DATA      AGE
+db-user-pass          Opaque                                2         51s
+$ kubectl describe secrets/db-user-pass
+Name:		db-user-pass
+Namespace:	default
+Labels:		<none>
+Annotations:	<none>
+
+Type:	Opaque
+
+Data
+====
+password.txt:	13 bytes
+username.txt:	6 bytes
+```
+
+Note that neither `get` nor `describe` shows the contents of the file by default.
+This is to protect the secret from being exposed accidentally to someone looking
+or from being stored in a terminal log.
+
+See [decoding a secret](#decoding-a-secret) for how to see the contents.
+
+#### Creating a Secret Manually
+
+You can also create a secret object in a file first,
+in json or yaml format, and then create that object.
+
+Each item must be base64 encoded:
+
+```console
+$ echo "admin" | base64
+YWRtaW4K
+$ echo "1f2d1e2e67df" | base64
+MWYyZDFlMmU2N2RmCg==
+```
+
+Now write a secret object that looks like this:
 
 ```yaml
 apiVersion: v1
@@ -102,23 +172,57 @@ metadata:
   name: mysecret
 type: Opaque
 data:
-  password: dmFsdWUtMg0K
+  password: MWYyZDFlMmU2N2RmCg==
-  username: dmFsdWUtMQ0K
+  username: YWRtaW4K
 ```
 
 The data field is a map.  Its keys must match
 [`DNS_SUBDOMAIN`](../design/identifiers.md), except that leading dots are also
-allowed.  The values are arbitrary data, encoded using base64. The values of
+allowed.  The values are arbitrary data, encoded using base64.
-username and password in the example above, before base64 encoding,
-are `value-1` and `value-2`, respectively, with carriage return and newline characters at the end.
 
-Create the secret using [`kubectl create`](kubectl/kubectl_create.md).
+Create the secret using [`kubectl create`](kubectl/kubectl_create.md):
 
-Once the secret is created, you can need to modify your pod to specify
+```console
-that it should use the secret.
+$ kubectl create -f ./secret.yaml
+secret "mysecret" created
+```
+
+**Encoding Note:** The serialized JSON and YAML values of secret data are encoded as
+base64 strings.  Newlines are not valid within these strings and must be
+omitted (i.e. do not use `-b` option of `base64` which breaks long lines.)
+
+#### Decoding a Secret
+
+Get back the secret created in the previous section:
+
+```console
+$ kubectl get secret mysecret -o yaml
+apiVersion: v1
+data:
+  password: MWYyZDFlMmU2N2RmCg==
+  username: YWRtaW4K
+kind: Secret
+metadata:
+  creationTimestamp: 2016-01-22T18:41:56Z
+  name: mysecret
+  namespace: default
+  resourceVersion: "164619"
+  selfLink: /api/v1/namespaces/default/secrets/mysecret
+  uid: cfee02d6-c137-11e5-8d73-42010af00002
+type: Opaque
+```
+
+Decode the password field:
+
+```console
+$ echo "MWYyZDFlMmU2N2RmCg==" | base64 -D
+1f2d1e2e67df
+```
 
 ### Manually specifying a Secret to be Mounted on a Pod
 
+Once the secret is created, you can create a pod that consumes that secret.
+
 This is an example of a pod that mounts a secret in a volume:
 
 ```json
@@ -159,11 +263,23 @@ whichever is convenient.
 
 See another example of creating a secret and a pod that consumes that secret in a volume [here](secrets/).
 
-### Manually specifying an imagePullSecret
+### Using Secrets
+
+Secrets can be mounted as data volumes to be used by a container in a pod.
+They can also be used by other parts of the system, without being directly
+exposed to the pod.  For example, they can hold credentials that other
+parts of the system should use to interact with external systems on your behalf.
+
+#### Using imagePullSecrets
+
+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
 
 Use of imagePullSecrets is described in the [images documentation](images.md#specifying-imagepullsecrets-on-a-pod)
 
-### Arranging for imagePullSecrets to be Automatically Attached
+##### Arranging for imagePullSecrets to be Automatically Attached
 
 You can manually create an imagePullSecret, and reference it from
 a serviceAccount.  Any pods created with that serviceAccount
@@ -172,8 +288,18 @@ 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.
 
+#### Using Secrets as Files from a Pod
 
-### Automatic Mounting of Manually Created Secrets
+To use a secret from a Pod:
+
+1. Create a secret or use an existing one.  Multiple pods can reference the same secret.
+1. Modify your Pod definition to add a volume under `spec.volumes[]`.  Name the volume anything, and have a `spec.volumes[].secret.secretName` field equal to the name of the secret object.
+1. Add a `spec.containers[].volumeMounts[]` to each container that needs the secret.  Specify `spec.containers[].volumeMounts[].readOnly = true` and `spec.containers[].volumeMounts[].mountPath` to an unused directory name where you would like the secrets to appear.
+1. Modify your image and/or command line so that the the program looks for files in that directory.  Each key in the secret `data` map becomes the filename under `mountPath`.
+
+See the [Use Cases](#use-cases) section for detailed examples.
+
+#### 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)
@@ -259,25 +385,14 @@ update the data of existing secrets, but to create new ones with distinct names.
 
 ### Use-Case: Pod with ssh keys
 
-To create a pod that uses an ssh key stored as a secret, we first need to create a secret:
+Create a secret containing some ssh keys:
 
-```json
+```console
-{
+$ kubectl create secret generic my-secret --from-file=ssh-privatekey=/path/to/.ssh/id_rsa --from-file=ssh-publickey=/path/to/.ssh/id_rsa.pub
-  "kind": "Secret",
-  "apiVersion": "v1",
-  "metadata": {
-    "name": "ssh-key-secret"
-  },
-  "data": {
-    "id-rsa": "dmFsdWUtMg0KDQo=",
-    "id-rsa.pub": "dmFsdWUtMQ0K"
-  }
-}
 ```
 
-**Note:** The serialized JSON and YAML values of secret data are encoded as
+**Security Note:** think carefully before sending your own ssh keys: other users of the cluster may have access to the secret.  Use a service account which you want to have accessible to all the users with whom you share the kubernetes cluster, and can revoke if they are compromised.
-base64 strings.  Newlines are not valid within these strings and must be
+
-omitted.
 
 Now we can create a pod which references the secret with the ssh key and
 consumes it in a volume:
@@ -331,39 +446,16 @@ This example illustrates a pod which consumes a secret containing prod
 credentials and another pod which consumes a secret with test environment
 credentials.
 
-The secrets:
+Make the secrets:
 
-```json
+```console
-{
+$ kubectl create secret generic prod-db-password --from-literal=user=produser --from-literal=password=Y4nys7f11
-  "apiVersion": "v1",
+secret "prod-db-password" created
-  "kind": "List",
+$ kubectl create secret generic test-db-password --from-literal=user=testuser --from-literal=password=iluvtests
-  "items":
+secret "test-db-password" created
-  [{
-    "kind": "Secret",
-    "apiVersion": "v1",
-    "metadata": {
-      "name": "prod-db-secret"
-    },
-    "data": {
-      "password": "dmFsdWUtMg0KDQo=",
-      "username": "dmFsdWUtMQ0K"
-    }
-  },
-  {
-    "kind": "Secret",
-    "apiVersion": "v1",
-    "metadata": {
-      "name": "test-db-secret"
-    },
-    "data": {
-      "password": "dmFsdWUtMg0KDQo=",
-      "username": "dmFsdWUtMQ0K"
-    }
-  }]
-}
 ```
 
-The pods:
+Now make the pods:
 
 ```json
 {