From 30807cea60499e84204ca6545e2a7f39d1adff5f Mon Sep 17 00:00:00 2001 From: bfallonf Date: Fri, 19 Jun 2015 11:51:08 +1000 Subject: [PATCH 1/2] initial information added --- dev_guide/secrets.adoc | 90 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 81 insertions(+), 9 deletions(-) diff --git a/dev_guide/secrets.adoc b/dev_guide/secrets.adoc index 17fbcbaef3d9..b57ea1024423 100644 --- a/dev_guide/secrets.adoc +++ b/dev_guide/secrets.adoc @@ -11,29 +11,101 @@ toc::[] == Overview -The `Secrets` resource provides a mechanism to hold sensitive information such as passwords, -client config files for OpenShift, `dockercfg`s, etc. Secrets decouple sensitive content from -the pods that use it and can be mounted into containers using a volume plugin or used by the -system to perform actions on behalf of a pod. This topic discusses important properties of -secrets and provides an overview on how developers can use them. +The `Secret` object type provides a mechanism to hold sensitive information such +as passwords, OpenShift client config files, `dockercfg` files, etc. Secrets +decouple sensitive content from the pods that use it and can be mounted into +containers using a volume plug-in or used by the system to perform actions on +behalf of a pod. This topic discusses important properties of secrets and +provides an overview on how developers can use them. + +==== +---- +{ + "apiVersion": "v1", + "kind": "Secret", + "name": "mysecret", + "namespace": "myns", + "data": { <1> + "username": "dmFsdWUtMQ0K", + "password": "dmFsdWUtMg0KDQo=" + } +} +---- +<1> The `data` field must match the keys in the the "DNS_SUBDOMAIN" value in `_docs/design/identifiers.md_`. +==== == Properties of secrets === Secrets and the Pod Lifecycle +A secret must be created before the pods that depend on it. -== Restrictions +Container programs are responsible for reading the secret(s) from the files. If +a program expects a secret to be stored in an environment variable, then you +must modify the image to populate the environment variable from the file before +running the main program. Future versions of Kubernetes are expected to provide +more automation for populating environment variables from files. -=== Secret data keys +Once a pod is created, its secret volumes do not change, even if the secret +resource is modified. To change the secret used, the original pod must be +deleted, and a new pod (perhaps with an identical PodSpec) must be created. +Therefore, updating a secret follows the same workflow as deploying a new +container image. The +link:https://www.mankier.com/1/kubectl-rollingupdate[`kubectl rollingupdate` +command] can be used. -=== Secrets and ServiceAccounts +The `resourceVersion` of a secret is not specified when it is referenced. +Therefore, if a secret is updated at the same time as pods are starting, +then version of the secret will be used for the pod is not defined. + +[NOTE] +It is currently not possible to check the resource version of a secret object +that was used when a pod was created. It is planned that pods will report this +information, so that a controller could restart ones using a old +`resourceVersion`. In the interim, if this is a concern, it is recommended to +not update the data of existing secrets, but to create new ones with distinct +names. == Creating and Using Secrets +Using secrets requires at least two steps: + +- Creating a secret object with secret data +- Creating a pod with a volume of type `secret` and a container to mount the volume + +=== Creating Secrets +To create a secret object, use the following command, where the json file is a +predefined secret: + +==== +---- +$ oc create -f secret.json +---- +==== === Secrets in Volumes === Image Pull Secrets +See link:dev_guide/image_pull_secrets.html[the image pull secrets] documentation +for more information. -=== Working with Secrets with `oc` +== Restrictions +Secret volume sources are validated to ensure that the specified object +reference actually points to a `Secret` object. Therefore, a secret +needs to be created before the pods that depend on it. + +Secret API objects reside in a namespace. They can only be referenced by pods in +that same namespace. + +Individual secrets are limited to 1MB in size. This is to discourage creation of +large secrets that would exhaust apiserver and kubelet memory. However, +creation of a number of smaller secrets could also exhaust memory. + +Currently, when mounting a secret, the service account for a pod must have the +secret in the list of mountable secrets. If a secret is in a template pods will +be rejected until my service account is updated. + +=== Secret data keys + +=== Secrets and ServiceAccounts == Examples From 41377f7eb7eb25d3d1f77395cc466d4edf816e1e Mon Sep 17 00:00:00 2001 From: bfallonf Date: Fri, 19 Jun 2015 16:40:40 +1000 Subject: [PATCH 2/2] more information after review --- dev_guide/secrets.adoc | 82 +++++++++++++++++++++++++++--------------- 1 file changed, 54 insertions(+), 28 deletions(-) diff --git a/dev_guide/secrets.adoc b/dev_guide/secrets.adoc index b57ea1024423..0728be36f4dd 100644 --- a/dev_guide/secrets.adoc +++ b/dev_guide/secrets.adoc @@ -35,41 +35,46 @@ provides an overview on how developers can use them. ==== == Properties of secrets +Key properties include: + +- Secret data can be referenced independently from its definition. +- Secret data never comes to rest on the node. Volumes are backed by temporary file-storage facilities (tmpfs). +- Secret data can be shared within a namespace. === Secrets and the Pod Lifecycle A secret must be created before the pods that depend on it. -Container programs are responsible for reading the secret(s) from the files. If -a program expects a secret to be stored in an environment variable, then you +Containers read the secret from the files. If +a secret is expected to be stored in an environment variable, then you must modify the image to populate the environment variable from the file before -running the main program. Future versions of Kubernetes are expected to provide -more automation for populating environment variables from files. +running the main program. Once a pod is created, its secret volumes do not change, even if the secret resource is modified. To change the secret used, the original pod must be -deleted, and a new pod (perhaps with an identical PodSpec) must be created. -Therefore, updating a secret follows the same workflow as deploying a new -container image. The -link:https://www.mankier.com/1/kubectl-rollingupdate[`kubectl rollingupdate` -command] can be used. - -The `resourceVersion` of a secret is not specified when it is referenced. +deleted, and a new pod (perhaps with an identical PodSpec) must be created. An +exception to this is when a node is rebooted and the secret data must be re-read +from the API server. Updating a secret follows the same workflow as deploying a +new container image. The +link:https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/kubectl_rolling-update.md[`kubectl +rollingupdate` command] can be used. + +The `resourceVersion` value in a secret is not specified when it is referenced. Therefore, if a secret is updated at the same time as pods are starting, -then version of the secret will be used for the pod is not defined. +then the version of the secret will be used for the pod will not be defined. [NOTE] -It is currently not possible to check the resource version of a secret object +Currently, it is not possible to check the resource version of a secret object that was used when a pod was created. It is planned that pods will report this information, so that a controller could restart ones using a old -`resourceVersion`. In the interim, if this is a concern, it is recommended to -not update the data of existing secrets, but to create new ones with distinct -names. +`resourceVersion`. In the interim, do not update the data of existing secrets, +but create new ones with distinct names. == Creating and Using Secrets -Using secrets requires at least two steps: +When creating secrets: -- Creating a secret object with secret data -- Creating a pod with a volume of type `secret` and a container to mount the volume +- Create a secret object with secret data +- Create a pod with a volume of type `secret` and a container to mount the volume +- Update the pod's service account to allow the reference to the secret. === Creating Secrets To create a secret object, use the following command, where the json file is a @@ -89,26 +94,47 @@ for more information. == Restrictions Secret volume sources are validated to ensure that the specified object -reference actually points to a `Secret` object. Therefore, a secret -needs to be created before the pods that depend on it. +reference points to a `Secret` object. Therefore, a secret needs to be created +before the pods that depend on it. Secret API objects reside in a namespace. They can only be referenced by pods in that same namespace. -Individual secrets are limited to 1MB in size. This is to discourage creation of -large secrets that would exhaust apiserver and kubelet memory. However, -creation of a number of smaller secrets could also exhaust memory. +Individual secrets are limited to 1MB in size. This is to discourage the +creation of large secrets that would exhaust apiserver and kubelet memory. +However, creation of a number of smaller secrets could also exhaust memory. Currently, when mounting a secret, the service account for a pod must have the secret in the list of mountable secrets. If a secret is in a template pods will -be rejected until my service account is updated. +be rejected until the pod's service account is updated. === Secret data keys - -=== Secrets and ServiceAccounts +Secret keys have to be in a DNS subdomain. == Examples === Example: Pod consuming secret data in volume +The following is an example yaml of a pod comsuming data in a volume: -=== Example: Pod with Image Pull Secret +==== +---- +apiVersion: v1 +kind: Pod +metadata: + name: secret-example-pod +spec: + containers: + - name: secret-test-container + image: busybox + command: [ "/bin/sh", "-c", "cat /etc/secret-volume/*" ] + volumeMounts: + # name must match the volume name below + - name: secret-volume + mountPath: /etc/secret-volume + volumes: + - name: secret-volume + secret: + secretName: test-secret + restartPolicy: Never +---- +====