diff --git a/content/en/docs/concepts/configuration/secret.md b/content/en/docs/concepts/configuration/secret.md index 651e90f270..2c710ac652 100644 --- a/content/en/docs/concepts/configuration/secret.md +++ b/content/en/docs/concepts/configuration/secret.md @@ -37,6 +37,12 @@ its containers. - As [container environment variable](#using-secrets-as-environment-variables). - 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 #### 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/) 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. -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. +- [create Secret using `kubectl` command](/docs/tasks/configmap-secret/managing-secret-using-kubectl/) +- [create Secret from config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/) +- [create Secret using kustomize](/docs/tasks/configmap-secret/managing-secret-using-kustomize/) -```shell -# 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: -Annotations: - -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 <./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: -Annotations: - -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 <./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 +### Editing a Secret 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 nodes that actually require them, to restrict the impact of a root exploit on a 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/) + diff --git a/content/en/docs/tasks/configmap-secret/_index.md b/content/en/docs/tasks/configmap-secret/_index.md new file mode 100755 index 0000000000..d80692c967 --- /dev/null +++ b/content/en/docs/tasks/configmap-secret/_index.md @@ -0,0 +1,6 @@ +--- +title: "Managing Secrets" +weight: 28 +description: Managing confidential settings data using Secrets. +--- + diff --git a/content/en/docs/tasks/configmap-secret/managing-secret-using-config-file.md b/content/en/docs/tasks/configmap-secret/managing-secret-using-config-file.md new file mode 100644 index 0000000000..13ffa70b3c --- /dev/null +++ b/content/en/docs/tasks/configmap-secret/managing-secret-using-config-file.md @@ -0,0 +1,198 @@ +--- +title: Managing Secret using Configuration File +content_type: task +weight: 20 +description: Creating Secret objects using resource configuration file. +--- + + + +## {{% heading "prerequisites" %}} + +{{< include "task-tutorial-prereqs.md" >}} + + + +## 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: "" +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: + 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/) + diff --git a/content/en/docs/tasks/configmap-secret/managing-secret-using-kubectl.md b/content/en/docs/tasks/configmap-secret/managing-secret-using-kubectl.md new file mode 100644 index 0000000000..22828d77a3 --- /dev/null +++ b/content/en/docs/tasks/configmap-secret/managing-secret-using-kubectl.md @@ -0,0 +1,157 @@ +--- +title: Managing Secret using `kubectl` +content_type: task +weight: 10 +description: Creating Secret objects using kubectl command line. +--- + + + +## {{% heading "prerequisites" %}} + +{{< include "task-tutorial-prereqs.md" >}} + + + +## 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==` 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: +Annotations: + +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 +``` + + + +## {{% 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/) diff --git a/content/en/docs/tasks/configmap-secret/managing-secret-using-kustomize.md b/content/en/docs/tasks/configmap-secret/managing-secret-using-kustomize.md new file mode 100644 index 0000000000..d7b1f48a4a --- /dev/null +++ b/content/en/docs/tasks/configmap-secret/managing-secret-using-kustomize.md @@ -0,0 +1,128 @@ +--- +title: Managing Secret using Kustomize +content_type: task +weight: 30 +description: Creating Secret objects using kustomization.yaml file. +--- + + + +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" >}} + + + +## 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: +Annotations: + +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 +``` + + +## {{% 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/) +