mirror of
https://github.com/k3s-io/kubernetes.git
synced 2025-07-25 04:33:26 +00:00
Merge pull request #20023 from erictune/secrets-doc
Auto commit by PR queue bot
This commit is contained in:
commit
ad9fa30e7e
@ -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)
|
- [Configuring Nodes to Authenticate to a Private Repository](#configuring-nodes-to-authenticate-to-a-private-repository)
|
||||||
- [Pre-pulling Images](#pre-pulling-images)
|
- [Pre-pulling Images](#pre-pulling-images)
|
||||||
- [Specifying ImagePullSecrets on a Pod](#specifying-imagepullsecrets-on-a-pod)
|
- [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)
|
- [Use Cases](#use-cases)
|
||||||
|
|
||||||
<!-- END MUNGE: GENERATED_TOC -->
|
<!-- END MUNGE: GENERATED_TOC -->
|
||||||
@ -207,42 +210,40 @@ where node creation is automated.
|
|||||||
|
|
||||||
Kubernetes supports specifying registry keys on a pod.
|
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
|
```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 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
|
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.
|
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`
|
Now, you can create pods which reference that secret by adding an `imagePullSecrets`
|
||||||
section to a pod definition.
|
section to a pod definition.
|
||||||
@ -261,6 +262,7 @@ spec:
|
|||||||
```
|
```
|
||||||
|
|
||||||
This needs to be done for each pod that is using a private registry.
|
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
|
However, setting of this field can be automated by setting the imagePullSecrets
|
||||||
in a [serviceAccount](service-accounts.md) resource.
|
in a [serviceAccount](service-accounts.md) resource.
|
||||||
|
|
||||||
|
@ -44,12 +44,19 @@ a docker image. See [Secrets design document](../design/secrets.md) for more inf
|
|||||||
|
|
||||||
- [Secrets](#secrets)
|
- [Secrets](#secrets)
|
||||||
- [Overview of Secrets](#overview-of-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 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)
|
- [Details](#details)
|
||||||
- [Restrictions](#restrictions)
|
- [Restrictions](#restrictions)
|
||||||
- [Consuming Secret Values](#consuming-secret-values)
|
- [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
|
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.
|
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
|
Kubernetes automatically creates secrets which contain credentials for
|
||||||
accessing the API and it automatically modifies your pods to use this type of
|
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
|
See the [Service Account](service-accounts.md) documentation for more
|
||||||
information on how Service Accounts work.
|
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
|
```yaml
|
||||||
apiVersion: v1
|
apiVersion: v1
|
||||||
@ -102,23 +172,57 @@ metadata:
|
|||||||
name: mysecret
|
name: mysecret
|
||||||
type: Opaque
|
type: Opaque
|
||||||
data:
|
data:
|
||||||
password: dmFsdWUtMg0K
|
password: MWYyZDFlMmU2N2RmCg==
|
||||||
username: dmFsdWUtMQ0K
|
username: YWRtaW4K
|
||||||
```
|
```
|
||||||
|
|
||||||
The data field is a map. Its keys must match
|
The data field is a map. Its keys must match
|
||||||
[`DNS_SUBDOMAIN`](../design/identifiers.md), except that leading dots are also
|
[`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
|
### 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:
|
This is an example of a pod that mounts a secret in a volume:
|
||||||
|
|
||||||
```json
|
```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/).
|
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)
|
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
|
You can manually create an imagePullSecret, and reference it from
|
||||||
a serviceAccount. Any pods created with that serviceAccount
|
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)
|
See [here](service-accounts.md#adding-imagepullsecrets-to-a-service-account)
|
||||||
for a detailed explanation of that process.
|
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
|
We plan to extend the service account behavior so that manually created
|
||||||
secrets (e.g. one containing a token for accessing a github account)
|
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
|
### 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
|
Now we can create a pod which references the secret with the ssh key and
|
||||||
consumes it in a volume:
|
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 and another pod which consumes a secret with test environment
|
||||||
credentials.
|
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
|
```json
|
||||||
{
|
{
|
||||||
|
Loading…
Reference in New Issue
Block a user