kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Separating tasks from Secret concept 

There are many contents in the (*very big*) Secret concept page which
are actually tasks. This PR proposes a separation of some contents
into separate tasks, so that we have a (hopefully) better organization
of the content and we make room for improvement to the concept itself.

Note that the creation of the `configmap-secret` directory (instead of
`secret`) is an intent to create a folder for both ConfigMap and Secret,
both of which are about configurations though there are quite some
differences between them.
This commit is contained in:
Qiming Teng 2020-09-10 14:27:00 +08:00
parent 942fca9b29
commit 995b067fdb
5 changed files with 509 additions and 392 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

412
content/en/docs/concepts/configuration/secret.md
View File

@ -37,6 +37,12 @@ its containers.
- As [container environment variable](#using-secrets-as-environment-variables). - As [container environment variable](#using-secrets-as-environment-variables).
- By the [kubelet when pulling images](#using-imagepullsecrets) for the Pod. - By the [kubelet when pulling images](#using-imagepullsecrets) for the Pod.
The name of a Secret object must be a valid
[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
The keys of `data` and `stringData` must consist of alphanumeric characters,
`-`, `_` or `.`.
### 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
@ -52,401 +58,15 @@ this is the recommended workflow.
See the [ServiceAccount](/docs/tasks/configure-pod-container/configure-service-account/) See the [ServiceAccount](/docs/tasks/configure-pod-container/configure-service-account/)
documentation for more information on how service accounts work. documentation for more information on how service accounts work.
### Creating your own Secrets ### Creating a Secret
#### Creating a Secret Using `kubectl` There are several options to create a Secret:
Secrets can contain user credentials required by Pods to access a database. - [create Secret using `kubectl` command](/docs/tasks/configmap-secret/managing-secret-using-kubectl/)
For example, a database connection string - [create Secret from config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/)
consists of a username and password. You can store the username in a file `./username.txt` - [create Secret using kustomize](/docs/tasks/configmap-secret/managing-secret-using-kustomize/)
and the password in a file `./password.txt` on your local machine.
```shell ### Editing a Secret
# Create files needed for the rest of the example.
echo -n 'admin' > ./username.txt
echo -n '1f2d1e2e67df' > ./password.txt
```
The `kubectl create secret` command packages these files into a Secret and creates
the object on the API server.
The name of a Secret object must be a valid
[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
```shell
kubectl create secret generic db-user-pass --from-file=./username.txt --from-file=./password.txt
```
The output is similar to:
```
secret "db-user-pass" created
```
Default key name is the filename. You may optionally set the key name using `[--from-file=[key=]source]`.
```shell
kubectl create secret generic db-user-pass --from-file=username=./username.txt --from-file=password=./password.txt
```
{{< note >}}
Special characters such as `$`, `\`, `*`, `=`, and `!` will be interpreted by your [shell](https://en.wikipedia.org/wiki/Shell_(computing)) and require escaping.
In most shells, the easiest way to escape the password is to surround it with single quotes (`'`).
For example, if your actual password is `S!B\*d$zDsb=`, you should execute the command this way:
```shell
kubectl create secret generic dev-db-secret --from-literal=username=devuser --from-literal=password='S!B\*d$zDsb='
```
You do not need to escape special characters in passwords from files (`--from-file`).
{{< /note >}}
You can check that the secret was created:
```shell
kubectl get secrets
```
The output is similar to:
```
NAME TYPE DATA AGE
db-user-pass Opaque 2 51s
```
You can view a description of the secret:
```shell
kubectl describe secrets/db-user-pass
```
The output is similar to:
```
Name: db-user-pass
Namespace: default
Labels: <none>
Annotations: <none>
Type: Opaque
Data
====
password.txt: 12 bytes
username.txt: 5 bytes
```
{{< note >}}
The commands `kubectl get` and `kubectl describe` avoid showing the contents of a secret by
default. This is to protect the secret from being exposed accidentally to an onlooker,
or from being stored in a terminal log.
{{< /note >}}
See [decoding a secret](#decoding-a-secret) to learn how to view the contents of a secret.
#### Creating a Secret manually
You can also create a Secret in a file first, in JSON or YAML format,
and then create that object.
The name of a Secret object must be a valid
[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
The [Secret](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#secret-v1-core)
contains two maps:
`data` and `stringData`. The `data` field is used to store arbitrary data, encoded using
base64. The `stringData` field is provided for convenience, and allows you to provide
secret data as unencoded strings.
For example, to store two strings in a Secret using the `data` field, convert
the strings to base64 as follows:
```shell
echo -n 'admin' | base64
```
The output is similar to:
```
YWRtaW4=
```
```shell
echo -n '1f2d1e2e67df' | base64
```
The output is similar to:
```
MWYyZDFlMmU2N2Rm
```
Write a Secret that looks like this:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: mysecret
type: Opaque
data:
username: YWRtaW4=
password: MWYyZDFlMmU2N2Rm
```
Now create the Secret using [`kubectl apply`](/docs/reference/generated/kubectl/kubectl-commands#apply):
```shell
kubectl apply -f ./secret.yaml
```
The output is similar to:
```
secret "mysecret" created
```
For certain scenarios, you may wish to use the `stringData` field instead. This
field allows you to put a non-base64 encoded string directly into the Secret,
and the string will be encoded for you when the Secret is created or updated.
A practical example of this might be where you are deploying an application
that uses a Secret to store a configuration file, and you want to populate
parts of that configuration file during your deployment process.
For example, if your application uses the following configuration file:
```yaml
apiUrl: "https://my.api.com/api/v1"
username: "user"
password: "password"
```
You could store this in a Secret using the following definition:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: mysecret
type: Opaque
stringData:
config.yaml: |-
apiUrl: "https://my.api.com/api/v1"
username: {{username}}
password: {{password}}
```
Your deployment tool could then replace the `{{username}}` and `{{password}}`
template variables before running `kubectl apply`.
The `stringData` field is a write-only convenience field. It is never output when
retrieving Secrets. For example, if you run the following command:
```shell
kubectl get secret mysecret -o yaml
```
The output is similar to:
```yaml
apiVersion: v1
kind: Secret
metadata:
creationTimestamp: 2018-11-15T20:40:59Z
name: mysecret
namespace: default
resourceVersion: "7225"
uid: c280ad2e-e916-11e8-98f2-025000000001
type: Opaque
data:
config.yaml: YXBpVXJsOiAiaHR0cHM6Ly9teS5hcGkuY29tL2FwaS92MSIKdXNlcm5hbWU6IHt7dXNlcm5hbWV9fQpwYXNzd29yZDoge3twYXNzd29yZH19
```
If a field, such as `username`, is specified in both `data` and `stringData`,
the value from `stringData` is used. For example, the following Secret definition:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: mysecret
type: Opaque
data:
username: YWRtaW4=
stringData:
username: administrator
```
Results in the following Secret:
```yaml
apiVersion: v1
kind: Secret
metadata:
creationTimestamp: 2018-11-15T20:46:46Z
name: mysecret
namespace: default
resourceVersion: "7579"
uid: 91460ecb-e917-11e8-98f2-025000000001
type: Opaque
data:
username: YWRtaW5pc3RyYXRvcg==
```
Where `YWRtaW5pc3RyYXRvcg==` decodes to `administrator`.
The keys of `data` and `stringData` must consist of alphanumeric characters,
'-', '_' or '.'.
{{< 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. When using the `base64` utility on Darwin/macOS, users should avoid
using the `-b` option to split long lines. Conversely, Linux users *should* add
the option `-w 0` to `base64` commands or the pipeline `base64 | tr -d '\n'` if
the `-w` option is not available.
{{< /note >}}
#### Creating a Secret from a generator
Since Kubernetes v1.14, `kubectl` supports [managing objects using Kustomize](/docs/tasks/manage-kubernetes-objects/kustomization/). Kustomize provides resource Generators to
create Secrets and ConfigMaps. The Kustomize generators should be specified in a
`kustomization.yaml` file inside a directory. After generating the Secret,
you can create the Secret on the API server with `kubectl apply`.
#### Generating a Secret from files
You can generate a Secret by defining a `secretGenerator` from the
files ./username.txt and ./password.txt:
```shell
cat <<EOF >./kustomization.yaml
secretGenerator:
- name: db-user-pass
files:
- username.txt
- password.txt
EOF
```
Apply the directory, containing the `kustomization.yaml`, to create the Secret.
```shell
kubectl apply -k .
```
The output is similar to:
```
secret/db-user-pass-96mffmfh4k created
```
You can check that the secret was created:
```shell
kubectl get secrets
```
The output is similar to:
```
NAME TYPE DATA AGE
db-user-pass-96mffmfh4k Opaque 2 51s
```
You can view a description of the secret:
```shell
kubectl describe secrets/db-user-pass-96mffmfh4k
```
The output is similar to:
```
Name: db-user-pass
Namespace: default
Labels: <none>
Annotations: <none>
Type: Opaque
Data
====
password.txt: 12 bytes
username.txt: 5 bytes
```
#### Generating a Secret from string literals
You can create a Secret by defining a `secretGenerator`
from literals `username=admin` and `password=secret`:
```shell
cat <<EOF >./kustomization.yaml
secretGenerator:
- name: db-user-pass
literals:
- username=admin
- password=secret
EOF
```
Apply the directory, containing the `kustomization.yaml`, to create the Secret.
```shell
kubectl apply -k .
```
The output is similar to:
```
secret/db-user-pass-dddghtt9b5 created
```
{{< note >}}
When a Secret is generated, the Secret name is created by hashing
the Secret data and appending this value to the name. This ensures that
a new Secret is generated each time the data is modified.
{{< /note >}}
#### Decoding a Secret
Secrets can be retrieved by running `kubectl get secret`.
For example, you can view the Secret created in the previous section by
running the following command:
```shell
kubectl get secret mysecret -o yaml
```
The output is similar to:
```yaml
apiVersion: v1
kind: Secret
metadata:
creationTimestamp: 2016-01-22T18:41:56Z
name: mysecret
namespace: default
resourceVersion: "164619"
uid: cfee02d6-c137-11e5-8d73-42010af00002
type: Opaque
data:
username: YWRtaW4=
password: MWYyZDFlMmU2N2Rm
```
Decode the `password` field:
```shell
echo 'MWYyZDFlMmU2N2Rm' | base64 --decode
```
The output is similar to:
```
1f2d1e2e67df
```
#### Editing a Secret
An existing Secret may be edited with the following command: An existing Secret may be edited with the following command:
@ -1273,3 +893,11 @@ for secret data, so that the secrets are not stored in the clear into {{< glossa
by impersonating the kubelet. It is a planned feature to only send secrets to by impersonating the kubelet. It is a planned feature to only send secrets to
nodes that actually require them, to restrict the impact of a root exploit on a nodes that actually require them, to restrict the impact of a root exploit on a
single node. single node.
## {{% heading "whatsnext" %}}
- Learn how to [manage Secret using `kubectl`](/docs/tasks/configmap-secret/managing-secret-using-kubectl/)
- Learn how to [manage Secret using config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/)
- Learn how to [manage Secret using kustomize](/docs/tasks/configmap-secret/managing-secret-using-kustomize/)

6
content/en/docs/tasks/configmap-secret/_index.md Executable file
View File

@ -0,0 +1,6 @@
---
title: "Managing Secrets"
weight: 28
description: Managing confidential settings data using Secrets.
---

198
content/en/docs/tasks/configmap-secret/managing-secret-using-config-file.md Normal file
View File

@ -0,0 +1,198 @@
---
title: Managing Secret using Configuration File
content_type: task
weight: 20
description: Creating Secret objects using resource configuration file.
---
<!-- overview -->
## {{% heading "prerequisites" %}}
{{< include "task-tutorial-prereqs.md" >}}
<!-- steps -->
## Create the Config file
You can create a Secret in a file first, in JSON or YAML format, and then
create that object. The
[Secret](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#secret-v1-core)
resource contains two maps: `data` and `stringData`.
The `data` field is used to store arbitrary data, encoded using base64. The
`stringData` field is provided for convenience, and it allows you to provide
Secret data as unencoded strings.
The keys of `data` and `stringData` must consist of alphanumeric characters,
`-`, `_` or `.`.
For example, to store two strings in a Secret using the `data` field, convert
the strings to base64 as follows:
```shell
echo -n 'admin' | base64
```
The output is similar to:
```
YWRtaW4=
```
```shell
echo -n '1f2d1e2e67df' | base64
```
The output is similar to:
```
MWYyZDFlMmU2N2Rm
```
Write a Secret config file that looks like this:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: mysecret
type: Opaque
data:
username: YWRtaW4=
password: MWYyZDFlMmU2N2Rm
```
Note that the name of a Secret object must be a valid
[DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
{{< 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. When
using the `base64` utility on Darwin/macOS, users should avoid using the `-b`
option to split long lines. Conversely, Linux users *should* add the option
`-w 0` to `base64` commands or the pipeline `base64 | tr -d '\n'` if the `-w`
option is not available.
{{< /note >}}
For certain scenarios, you may wish to use the `stringData` field instead. This
field allows you to put a non-base64 encoded string directly into the Secret,
and the string will be encoded for you when the Secret is created or updated.
A practical example of this might be where you are deploying an application
that uses a Secret to store a configuration file, and you want to populate
parts of that configuration file during your deployment process.
For example, if your application uses the following configuration file:
```yaml
apiUrl: "https://my.api.com/api/v1"
username: "<user>"
password: "<password>"
```
You could store this in a Secret using the following definition:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: mysecret
type: Opaque
stringData:
config.yaml: |
apiUrl: "https://my.api.com/api/v1"
username: <user>
password: <password>
```
## Create the Secret object
Now create the Secret using [`kubectl apply`](/docs/reference/generated/kubectl/kubectl-commands#apply):
```shell
kubectl apply -f ./secret.yaml
```
The output is similar to:
```
secret/mysecret created
```
## Check the Secret
The `stringData` field is a write-only convenience field. It is never output when
retrieving Secrets. For example, if you run the following command:
```shell
kubectl get secret mysecret -o yaml
```
The output is similar to:
```yaml
apiVersion: v1
kind: Secret
metadata:
creationTimestamp: 2018-11-15T20:40:59Z
name: mysecret
namespace: default
resourceVersion: "7225"
uid: c280ad2e-e916-11e8-98f2-025000000001
type: Opaque
data:
config.yaml: YXBpVXJsOiAiaHR0cHM6Ly9teS5hcGkuY29tL2FwaS92MSIKdXNlcm5hbWU6IHt7dXNlcm5hbWV9fQpwYXNzd29yZDoge3twYXNzd29yZH19
```
The commands `kubectl get` and `kubectl describe` avoid showing the contents of a `Secret` by
default. This is to protect the `Secret` from being exposed accidentally to an onlooker,
or from being stored in a terminal log.
To check the actual content of the encoded data, please refer to
[decoding secret](/docs/tasks/configmap-secret/managing-secret-using-kubectl/#decoding-secret).
If a field, such as `username`, is specified in both `data` and `stringData`,
the value from `stringData` is used. For example, the following Secret definition:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: mysecret
type: Opaque
data:
username: YWRtaW4=
stringData:
username: administrator
```
Results in the following Secret:
```yaml
apiVersion: v1
kind: Secret
metadata:
creationTimestamp: 2018-11-15T20:46:46Z
name: mysecret
namespace: default
resourceVersion: "7579"
uid: 91460ecb-e917-11e8-98f2-025000000001
type: Opaque
data:
username: YWRtaW5pc3RyYXRvcg==
```
Where `YWRtaW5pc3RyYXRvcg==` decodes to `administrator`.
## Clean Up
To delete the Secret you have just created:
```shell
kubectl delete secret db-user-pass
```
## {{% heading "whatsnext" %}}
- Read more about the [Secret concept](/docs/concepts/configuration/secret/)
- Learn how to [manage Secret with the `kubectl` command](/docs/tasks/configmap-secret/managing-secret-using-kubectl/)
- Learn how to [manage Secret using kustomizae](/docs/tasks/configmap-secret/managing-secret-using-kustomize/)

157
content/en/docs/tasks/configmap-secret/managing-secret-using-kubectl.md Normal file
View File

@ -0,0 +1,157 @@
---
title: Managing Secret using `kubectl`
content_type: task
weight: 10
description: Creating Secret objects using kubectl command line.
---
<!-- overview -->
## {{% heading "prerequisites" %}}
{{< include "task-tutorial-prereqs.md" >}}
<!-- steps -->
## Create a Secret
A `Secret` can contain user credentials required by Pods to access a database.
For example, a database connection string consists of a username and password.
You can store the username in a file `./username.txt` and the password in a
file `./password.txt` on your local machine.
```shell
echo -n 'admin' > ./username.txt
echo -n '1f2d1e2e67df' > ./password.txt
```
The `-n` flag in the above two commands ensures that the generated files will
not contain an extra newline character at the end of the text. This is
important because when `kubectl` reads a file and encode the content into
base64 string, the extra newline character gets encoded too.
The `kubectl create secret` command packages these files into a Secret and creates
the object on the API server.
```shell
kubectl create secret generic db-user-pass \
--from-file=./username.txt \
--from-file=./password.txt
```
The output is similar to:
```
secret/db-user-pass created
```
Default key name is the filename. You may optionally set the key name using
`--from-file=[key=]source`. For example:
```shell
kubectl create secret generic db-user-pass \
--from-file=username=./username.txt \
--from-file=password=./password.txt
```
You do not need to escape special characters in passwords from files
(`--from-file`).
You can also provide Secret data using the `--from-literal=<key>=<value>` tag.
This tag can be specified more than once to provide multiple key-value pairs.
Note that special characters such as `$`, `\`, `*`, `=`, and `!` will be
interpreted by your [shell](https://en.wikipedia.org/wiki/Shell_(computing))
and require escaping.
In most shells, the easiest way to escape the password is to surround it with
single quotes (`'`). For example, if your actual password is `S!B\*d$zDsb=`,
you should execute the command this way:
```shell
kubectl create secret generic dev-db-secret \
--from-literal=username=devuser \
--from-literal=password='S!B\*d$zDsb='
```
## Verify the Secret
You can check that the secret was created:
```shell
kubectl get secrets
```
The output is similar to:
```
NAME TYPE DATA AGE
db-user-pass Opaque 2 51s
```
You can view a description of the `Secret`:
```shell
kubectl describe secrets/db-user-pass
```
The output is similar to:
```
Name: db-user-pass
Namespace: default
Labels: <none>
Annotations: <none>
Type: Opaque
Data
====
password.txt: 12 bytes
username.txt: 5 bytes
```
The commands `kubectl get` and `kubectl describe` avoid showing the contents
of a `Secret` by default. This is to protect the `Secret` from being exposed
accidentally to an onlooker, or from being stored in a terminal log.
## Decoding the Secret {#decoding-secret}
To view the contents of the Secret we just created, you can run the following
command:
```shell
kubectl get secret db-user-pass -o jsonpath='{.data}'
```
The output is similar to:
```json
{"password.txt":"MWYyZDFlMmU2N2Rm","username.txt":"YWRtaW4="}
```
Now you can decode the `password.txt` data:
```shell
echo 'MWYyZDFlMmU2N2Rm' | base64 --decode
```
The output is similar to:
```
1f2d1e2e67df
```
## Clean Up
To delete the Secret you have just created:
```shell
kubectl delete secret db-user-pass
```
<!-- discussion -->
## {{% heading "whatsnext" %}}
- Read more about the [Secret concept](/docs/concepts/configuration/secret/)
- Learn how to [manage Secret using config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/)
- Learn how to [manage Secret using kustomize](/docs/tasks/configmap-secret/managing-secret-using-kustomize/)

128
content/en/docs/tasks/configmap-secret/managing-secret-using-kustomize.md Normal file
View File

@ -0,0 +1,128 @@
---
title: Managing Secret using Kustomize
content_type: task
weight: 30
description: Creating Secret objects using kustomization.yaml file.
---
<!-- overview -->
Since Kubernetes v1.14, `kubectl` supports
[managing objects using Kustomize](/docs/tasks/manage-kubernetes-objects/kustomization/).
Kustomize provides resource Generators to create Secrets and ConfigMaps. The
Kustomize generators should be specified in a `kustomization.yaml` file inside
a directory. After generating the Secret, you can create the Secret on the API
server with `kubectl apply`.
## {{% heading "prerequisites" %}}
{{< include "task-tutorial-prereqs.md" >}}
<!-- steps -->
## Create the Kustomization file
You can generate a Secret by defining a `secretGenerator` in a
`kustomization.yaml` file that references other existing files.
For example, the following kustomization file references the
`./username.txt` and the `./password.txt` files:
```yaml
secretGenerator:
- name: db-user-pass
files:
- username.txt
- password.txt
```
You can also define the `secretGenerator` in the `kustomization.yaml`
file by providing some literals.
For example, the following `kustomization.yaml` file contains two literals
for `username` and `password` respectively:
```yaml
secretGenerator:
- name: db-user-pass
literals:
- username=admin
- password=1f2d1e2e67df
```
Note that in both cases, you don't need to base64 encode the values.
## Create the Secret
Apply the directory containing the `kustomization.yaml` to create the Secret.
```shell
kubectl apply -k .
```
The output is similar to:
```
secret/db-user-pass-96mffmfh4k created
```
Note that when a Secret is generated, the Secret name is created by hashing
the Secret data and appending the hash value to the name. This ensures that
a new Secret is generated each time the data is modified.
## Check the Secret created
You can check that the secret was created:
```shell
kubectl get secrets
```
The output is similar to:
```
NAME TYPE DATA AGE
db-user-pass-96mffmfh4k Opaque 2 51s
```
You can view a description of the secret:
```shell
kubectl describe secrets/db-user-pass-96mffmfh4k
```
The output is similar to:
```
Name: db-user-pass
Namespace: default
Labels: <none>
Annotations: <none>
Type: Opaque
Data
====
password.txt: 12 bytes
username.txt: 5 bytes
```
The commands `kubectl get` and `kubectl describe` avoid showing the contents of a `Secret` by
default. This is to protect the `Secret` from being exposed accidentally to an onlooker,
or from being stored in a terminal log.
To check the actual content of the encoded data, please refer to
[decoding secret](/docs/tasks/configmap-secret/managing-secret-using-kubectl/#decoding-secret).
## Clean Up
To delete the Secret you have just created:
```shell
kubectl delete secret db-user-pass-96mffmfh4k
```
<!-- Optional section; add links to information related to this topic. -->
## {{% heading "whatsnext" %}}
- Read more about the [Secret concept](/docs/concepts/configuration/secret/)
- Learn how to [manage Secret with the `kubectl` command](/docs/tasks/configmap-secret/managing-secret-using-kubectl/)
- Learn how to [manage Secret using config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/)