Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update secrets docs. #20023

Merged
merged 1 commit into from
Feb 4, 2016
Merged

Update secrets docs. #20023

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
52 changes: 27 additions & 25 deletions docs/user-guide/images.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->
Expand Down Expand Up @@ -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>`.
Then put the resulting `.docker/config.json` file into a [secret resource](secrets.md). For example:
#### Creating a Secret with a Docker Config

Run the following command, substituting the appropriate uppercase values:

```console
$ docker login
Username: janedoe
Password: ●●●●●●●●●●●
Email: jdoe@example.com
WARNING: login credentials saved in /Users/jdoe/.docker/config.json.
Login Succeeded
$ 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
secret "my-registry-secret" created.
```

$ echo $(cat ~/.docker/config.json)
{ "https://index.docker.io/v1/": { "auth": "ZmFrZXBhc3N3b3JkMTIK", "email": "jdoe@example.com" } }
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.

$ cat ~/.docker/config.json | base64
eyAiaHR0cHM6Ly9pbmRleC5kb2NrZXIuaW8vdjEvIjogeyAiYXV0aCI6ICJabUZyWlhCaGMzTjNiM0prTVRJSyIsICJlbWFpbCI6ICJqZG9lQGV4YW1wbGUuY29tIiB9IH0K
Pods can only reference image pull secrets in their own namespace,
so this process needs to be done one time per namespace.

$ cat > /tmp/image-pull-secret.yaml <<EOF
apiVersion: v1
kind: Secret
metadata:
name: myregistrykey
data:
.dockerconfigjson: eyAiaHR0cHM6Ly9pbmRleC5kb2NrZXIuaW8vdjEvIjogeyAiYXV0aCI6ICJabUZyWlhCaGMzTjNiM0prTVRJSyIsICJlbWFpbCI6ICJqZG9lQGV4YW1wbGUuY29tIiB9IH0K
type: kubernetes.io/dockerconfigjson
EOF
##### Bypassing kubectl create secrets

$ kubectl create -f /tmp/image-pull-secret.yaml
secrets/myregistrykey
```
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.
Expand All @@ -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.

Expand Down
222 changes: 157 additions & 65 deletions docs/user-guide/secrets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
- [Creating a Secret Manually](#creating-a-secret-manually)
- [Built-in Secrets](#built-in-secrets)
- [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)
- [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)
- [Using Secrets](#using-secrets)
- [Using imagePullSecrets](#using-imagepullsecrets)
- [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)
Expand Down Expand Up @@ -77,7 +84,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
Expand All @@ -90,9 +99,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

#### 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.

This is an example of a simple secret, in yaml format:
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
Expand All @@ -101,23 +171,57 @@ metadata:
name: mysecret
type: Opaque
data:
password: dmFsdWUtMg0K
username: dmFsdWUtMQ0K
password: MWYyZDFlMmU2N2RmCg==
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
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.
allowed. The values are arbitrary data, encoded using base64.

Create the secret using [`kubectl create`](kubectl/kubectl_create.md):

```console
$ 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
```

Create the secret using [`kubectl create`](kubectl/kubectl_create.md).
Decode the password field:

Once the secret is created, you can need to modify your pod to specify
that it should use the secret.
```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
Expand Down Expand Up @@ -158,11 +262,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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll add doc on secret in envs as a follow-up to this :)

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
Expand All @@ -171,8 +287,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

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
#### 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)
Expand Down Expand Up @@ -258,25 +384,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
{
"kind": "Secret",
"apiVersion": "v1",
"metadata": {
"name": "ssh-key-secret"
},
"data": {
"id-rsa": "dmFsdWUtMg0KDQo=",
"id-rsa.pub": "dmFsdWUtMQ0K"
}
}
```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
```

**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.
**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.


Now we can create a pod which references the secret with the ssh key and
consumes it in a volume:
Expand Down Expand Up @@ -330,39 +445,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
{
"apiVersion": "v1",
"kind": "List",
"items":
[{
"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"
}
}]
}
```console
$ kubectl create secret generic prod-db-password --from-literal=user=produser --from-literal=password=Y4nys7f11
secret "prod-db-password" created
$ kubectl create secret generic test-db-password --from-literal=user=testuser --from-literal=password=iluvtests
secret "test-db-password" created
```

The pods:
Now make the pods:

```json
{
Expand Down