Merge pull request #1896 from steveperry-53/secrets

Write new Task: Distributing Credentials Securely.

_data/tasks.yml

@@ -14,6 +14,8 @@ toc:
     path: /docs/tasks/configure-pod-container/assign-cpu-ram-container/
   - title: Configuring a Pod to Use a Volume for Storage
     path: /docs/tasks/configure-pod-container/configure-volume-storage/
+  - title: Distributing Credentials Securely
+    path: /docs/tasks/configure-pod-container/distribute-credentials-secure/
 
 - title: Accessing Applications in a Cluster
   section:
@@ -34,6 +36,7 @@ toc:
   section:
   - title: Assigning Pods to Nodes
     path: /docs/tasks/administer-cluster/assign-pods-nodes/
+
   - title: Autoscaling the DNS Service in a Cluster
     path: /docs/tasks/administer-cluster/dns-horizontal-autoscaling/
   - title: Safely Draining a Node while Respecting Application SLOs

docs/tasks/configure-pod-container/distribute-credentials-secure.md

@@ -0,0 +1,170 @@
+---
+---
+
+{% capture overview %}
+This page shows how to securely inject sensitive data, such as passwords and
+encryption keys, into Pods.
+{% endcapture %}
+
+{% capture prerequisites %}
+
+{% include task-tutorial-prereqs.md %}
+
+{% endcapture %}
+
+{% capture steps %}
+
+### Converting your secret data to a base-64 representation
+
+Suppose you want to have two pieces of secret data: a username `my-app` and a password
+`39528$vdg7Jb`. First, use [Base64 encoding](https://www.base64encode.org/) to
+convert your username and password to a base-64 representation. Here's a Linux
+example:
+
+    echo 'my-app' | base64
+    echo '39528$vdg7Jb' | base64
+
+The output shows that the base-64 representation of your username is `bXktYXBwCg==`,
+and the base-64 representation of your password is `Mzk1MjgkdmRnN0piCg==`.
+
+### Creating a Secret
+
+Here is a configuration file you can use to create a Secret that holds your
+username and password:
+
+{% include code.html language="yaml" file="secret.yaml" ghlink="/docs/tasks/administer-cluster/secret.yaml" %}
+
+1. Create the Secret
+
+        kubectl create -f http://k8s.io/docs/tasks/administer-cluster/secret.yaml
+
+    **Note:** If you want to skip the Base64 encoding step, you can create a Secret
+    by using the `kubectl create secret` command:
+
+        kubectl create secret generic test-secret --from-literal=username="my-app",password="39528$vdg7Jb"
+
+1. View information about the Secret:
+
+        kubectl get secret test-secret
+
+    Output:
+
+        NAME          TYPE      DATA      AGE
+        test-secret   Opaque    2         1m
+
+
+1. View more detailed information about the Secret:
+
+        kubectl describe secret test-secret
+
+    Output:
+
+        Name:       test-secret
+        Namespace:  default
+        Labels:     <none>
+        Annotations:    <none>
+
+        Type:   Opaque
+
+        Data
+        ====
+        password:   13 bytes
+        username:   7 bytes
+
+### Creating a Pod that has access to the secret data through a Volume
+
+Here is a configuration file you can use to create a Pod:
+
+{% include code.html language="yaml" file="secret-pod.yaml" ghlink="/docs/tasks/administer-cluster/secret-pod.yaml" %}
+
+1. Create the Pod:
+
+        kubectl create -f http://k8s.io/docs/tasks/administer-cluster/secret-pod.yaml
+
+1. Verify that your Pod is running:
+
+        kubectl get pod secret-test-pod
+
+    Output:
+
+        NAME              READY     STATUS    RESTARTS   AGE
+        secret-test-pod   1/1       Running   0          42m
+
+
+1. Get a shell into the Container that is running in your Pod:
+
+        kubectl exec -it secret-test-pod -- /bin/bash
+
+1. The secret data is exposed to the Container through a Volume mounted under
+`/etc/secret-volume`. In your shell, go to the directory where the secret data
+is exposed:
+
+        root@secret-test-pod:/# cd /etc/secret-volume
+
+1. In your shell, list the files in the `/etc/secret-volume` directory:
+
+        root@secret-test-pod:/etc/secret-volume# ls
+
+    The output shows two files, one for each piece of secret data:
+
+        password username
+
+1. In your shell, display the contents of the `username` and `password` files:
+
+        root@secret-test-pod:/etc/secret-volume# cat username password
+
+    The output is your username and password:
+
+        my-app
+        39528$vdg7Jb
+
+### Creating a Pod that has access to the secret data through environment variables
+
+Here is a configuration file you can use to create a Pod:
+
+{% include code.html language="yaml" file="secret-envars-pod.yaml" ghlink="/docs/tasks/administer-cluster/secret-envars-pod.yaml" %}
+
+1. Create the Pod:
+
+        kubectl create -f http://k8s.io/docs/tasks/administer-cluster/secret-envars-pod.yaml
+
+1. Verify that your Pod is running:
+
+        kubectl get pod secret-envars-test-pod
+
+    Output:
+
+        NAME                     READY     STATUS    RESTARTS   AGE
+        secret-envars-test-pod   1/1       Running   0          4m
+
+1. Get a shell into the Container that is running in your Pod:
+
+        kubectl exec -it secret-envars-test-pod -- /bin/bash
+
+1. In your shell, display the environment variables:
+
+        root@secret-envars-test-pod:/# printenv
+
+    The output includes your username and password:
+
+        ...
+        SECRET_USERNAME=my-app
+        ...
+        SECRET_PASSWORD=39528$vdg7Jb
+
+{% endcapture %}
+
+{% capture whatsnext %}
+
+* Learn more about [Secrets](/docs/user-guide/secrets/).
+* Learn about [Volumes](/docs/user-guide/volumes/).
+
+#### Reference
+
+* [Secret](docs/api-reference/v1/definitions/#_v1_secret)
+* [Volume](docs/api-reference/v1/definitions/#_v1_volume)
+* [Pod](docs/api-reference/v1/definitions/#_v1_pod)
+
+{% endcapture %}
+
+{% include templates/task.md %}

docs/tasks/configure-pod-container/secret-envars-pod.yaml

@@ -0,0 +1,19 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: secret-envars-test-pod
+spec:
+  containers:
+  - name: envars-test-container
+    image: nginx
+    env:
+    - name: SECRET_USERNAME
+      valueFrom:
+        secretKeyRef:
+          name: test-secret
+          key: username
+    - name: SECRET_PASSWORD
+      valueFrom:
+        secretKeyRef:
+          name: test-secret
+          key: password

docs/tasks/configure-pod-container/secret-pod.yaml

@@ -0,0 +1,17 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: secret-test-pod
+spec:
+  containers:
+    - name: test-container
+      image: nginx
+      volumeMounts:
+          # name must match the volume name below
+          - name: secret-volume
+            mountPath: /etc/secret-volume
+  # The secret data is exposed to Containers in the Pod through a Volume.
+  volumes:
+    - name: secret-volume
+      secret:
+        secretName: test-secret

docs/tasks/configure-pod-container/secret.yaml

@@ -0,0 +1,7 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: test-secret
+data:
+  username: bXktYXBwCg==
+  password: Mzk1MjgkdmRnN0piCg==

docs/tasks/index.md

@@ -10,6 +10,7 @@ single thing, typically by giving a short sequence of steps.
 * [Defining Environment Variables for a Container](/docs/tasks/configure-pod-container/define-environment-variable-container/)
 * [Defining a Command and Arguments for a Container](/docs/tasks/configure-pod-container/define-command-argument-container/)
 * [Assigning CPU and RAM Resources to a Container](/docs/tasks/configure-pod-container/assign-cpu-ram-container/)
+* [Distributing Credentials Securely](/docs/tasks/configure-pod-container/distribute-credentials-secure/)
 
 #### Accessing Applications in a Cluster