whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reword /docs/concepts/configuration/secret/ (#12670)

Browse Source 
* Use glossary terms when explaining Secret concept

* Tidy up advice on keeping Secrets secret

* Reformat note on how Secrets are displayed

* Use mebibytes
This commit is contained in:
Tim Bannister
2019-02-18 01:51:15 +00:00
committed by Kubernetes Prow Robot
parent c613b54671
commit eb5cac382d
1 changed files with 45 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/concepts/configuration/secret.md
+45 -37
View File
@@ -13,10 +13,10 @@ weight: 50
{{% capture overview %}} {{% capture overview %}}
Objects of type `secret` are intended to hold sensitive information, such as Kubernetes `secret` objects let you store and manage sensitive information, such
passwords, OAuth tokens, and ssh keys. Putting this information in a `secret` as passwords, OAuth tokens, and ssh keys. Putting this information in a `secret`
is safer and more flexible than putting it verbatim in a `pod` definition or in is safer and more flexible than putting it verbatim in a
a docker image. See [Secrets design document](https://git.k8s.io/community/contributors/design-proposals/auth/secrets.md) for more information. {{< glossary_tooltip term_id="pod" >}} definition or in a {{< glossary_tooltip text="container image" term_id="image" >}}. See [Secrets design document](https://git.k8s.io/community/contributors/design-proposals/auth/secrets.md) for more information.
{{% /capture %}} {{% /capture %}}
@@ -32,7 +32,8 @@ more control over how it is used, and reduces the risk of accidental exposure.
Users can create secrets, and the system also creates some secrets. Users can create secrets, and the system also creates some secrets.
To use a secret, a pod needs to reference the secret. To use a secret, a pod needs to reference the secret.
A secret can be used with a pod in two ways: as files in a [volume](/docs/concepts/storage/volumes/) mounted on one or more of A secret can be used with a pod in two ways: as files in a
{{< glossary_tooltip text="volume" term_id="volume" >}} 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.
### Built-in Secrets ### Built-in Secrets
@@ -94,11 +95,14 @@ password.txt: 12 bytes
username.txt: 5 bytes username.txt: 5 bytes
``` ```
Note that neither `get` nor `describe` shows the contents of the file by default. {{< note >}}
This is to protect the secret from being exposed accidentally to someone looking `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. or from being stored in a terminal log.
{{< /note >}}
See [decoding a secret](#decoding-a-secret) for how to see the contents. See [decoding a secret](#decoding-a-secret) for how to see the contents of a secret.
#### Creating a Secret Manually #### Creating a Secret Manually
@@ -271,8 +275,9 @@ $ echo 'MWYyZDFlMmU2N2Rm' | base64 --decode
### Using Secrets ### Using Secrets
Secrets can be mounted as data volumes or be exposed as environment variables to Secrets can be mounted as data volumes or be exposed as
be used by a container in a pod. They can also be used by other parts of the {{< glossary_tooltip text="environment variables" term_id="container-env-variables" >}}
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 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 credentials that other parts of the system should use to interact with external
systems on your behalf. systems on your behalf.
@@ -458,7 +463,8 @@ Secret updates.
#### Using Secrets as Environment Variables #### Using Secrets as Environment Variables
To use a secret in an environment variable in a pod: To use a secret in an {{< glossary_tooltip text="environment variable" term_id="container-env-variables" >}}
in a pod:
1. Create a secret or use an existing one. Multiple pods can reference the same secret. 1. Create a secret or use an existing one. Multiple pods can reference the same secret.
1. Modify your Pod definition in each container that you wish to consume the value of a secret key to add an environment variable for each secret key you wish to consume. The environment variable that consumes the secret key should populate the secret's name and key in `env[].valueFrom.secretKeyRef`. 1. Modify your Pod definition in each container that you wish to consume the value of a secret key to add an environment variable for each secret key you wish to consume. The environment variable that consumes the secret key should populate the secret's name and key in `env[].valueFrom.secretKeyRef`.
@@ -534,10 +540,10 @@ Secret volume sources are validated to ensure that the specified object
reference actually points to an object of type `Secret`. Therefore, a secret reference actually points to an object of type `Secret`. Therefore, a secret
needs to be created before any pods that depend on it. needs to be created before any pods that depend on it.
Secret API objects reside in a namespace. They can only be referenced by pods Secret API objects reside in a {{< glossary_tooltip text="namespace" term_id="namespace" >}}.
in that same 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 Individual secrets are limited to 1MiB in size. This is to discourage creation
of very large secrets which would exhaust apiserver and kubelet memory. of very large secrets which would exhaust apiserver and kubelet memory.
However, creation of many smaller secrets could also exhaust memory. More However, creation of many smaller secrets could also exhaust memory. More
comprehensive limits on memory usage due to secrets is a planned feature. comprehensive limits on memory usage due to secrets is a planned feature.
@@ -549,8 +555,8 @@ controller. It does not include pods created via the kubelets
not common ways to create pods.) not common ways to create pods.)
Secrets must be created before they are consumed in pods as environment Secrets must be created before they are consumed in pods as environment
variables unless they are marked as optional. References to Secrets that do not exist will prevent variables unless they are marked as optional. References to Secrets that do
the pod from starting. not exist will prevent the pod from starting.
References via `secretKeyRef` to keys that do not exist in a named Secret References via `secretKeyRef` to keys that do not exist in a named Secret
will prevent the pod from starting. will prevent the pod from starting.
@@ -821,6 +827,7 @@ be available in future releases of Kubernetes.
## Security Properties ## Security Properties
### Protections ### Protections
Because `secret` objects can be created independently of the `pods` that use Because `secret` objects can be created independently of the `pods` that use
@@ -829,51 +836,52 @@ creating, viewing, and editing pods. The system can also take additional
precautions with `secret` objects, such as avoiding writing them to disk where precautions with `secret` objects, such as avoiding writing them to disk where
possible. possible.
A secret is only sent to a node if a pod on that node requires it. It is not A secret is only sent to a node if a pod on that node requires it.
written to disk. It is stored in a tmpfs. It is deleted once the pod that Kubelet stores the secret into a `tmpfs` so that the secret is not written
depends on it is deleted. to disk storage. Once the Pod that depends on the secret is deleted, kubelet
will delete its local copy of the secret data as well.
On most Kubernetes-project-maintained distributions, communication between user
to the apiserver, and from apiserver to the kubelets, is protected by SSL/TLS.
Secrets are protected when transmitted over these channels.
Secret data on nodes is stored in tmpfs volumes and thus does not come to rest
on the node.
There may be secrets for several pods on the same node. However, only the There may be secrets for several pods on the same node. However, only the
secrets that a pod requests are potentially visible within its containers. secrets that a pod requests are potentially visible within its containers.
Therefore, one Pod does not have access to the secrets of another pod. Therefore, one Pod does not have access to the secrets of another Pod.
There may be several containers in a pod. However, each container in a pod has There may be several containers in a pod. However, each container in a pod has
to request the secret volume in its `volumeMounts` for it to be visible within to request the secret volume in its `volumeMounts` for it to be visible within
the container. This can be used to construct useful [security partitions at the the container. This can be used to construct useful [security partitions at the
Pod level](#use-case-secret-visible-to-one-container-in-a-pod). Pod level](#use-case-secret-visible-to-one-container-in-a-pod).
On most Kubernetes-project-maintained distributions, communication between user
to the apiserver, and from apiserver to the kubelets, is protected by SSL/TLS.
Secrets are protected when transmitted over these channels.
{{< feature-state for_k8s_version="v1.13" state="beta" >}}
You can enable [encryption at rest](/docs/tasks/administer-cluster/encrypt-data/)
for secret data, so that the secrets are not stored in the clear into {{< glossary_tooltip term_id="etcd" >}}.
### Risks ### Risks
- In the API server secret data is stored as plaintext in etcd; therefore: - In the API server secret data is stored in {{< glossary_tooltip term_id="etcd" >}};
therefore:
- Administrators should enable encryption at rest for cluster data (requires v1.13 or later)
- Administrators should limit access to etcd to admin users - Administrators should limit access to etcd to admin users
- Secret data in the API server is at rest on the disk that etcd uses; admins may want to wipe/shred disks - Administrators may want to wipe/shred disks used by etcd when no longer in use
used by etcd when no longer in use - If running etcd in a cluster, administrators should make sure to use SSL/TLS
for etcd peer-to-peer communication.
- If you configure the secret through a manifest (JSON or YAML) file which has - If you configure the secret through a manifest (JSON or YAML) file which has
the secret data encoded as base64, sharing this file or checking it in to a the secret data encoded as base64, sharing this file or checking it in to a
source repository means the secret is compromised. Base64 encoding is not an source repository means the secret is compromised. Base64 encoding is _not_ an
encryption method and is considered the same as plain text. encryption method and is considered the same as plain text.
- Applications still need to protect the value of secret after reading it from the volume, - Applications still need to protect the value of secret after reading it from the volume,
such as not accidentally logging it or transmitting it to an untrusted party. such as not accidentally logging it or transmitting it to an untrusted party.
- A user who can create a pod that uses a secret can also see the value of that secret. Even - A user who can create a pod that uses a secret can also see the value of that secret. Even
if apiserver policy does not allow that user to read the secret object, the user could if apiserver policy does not allow that user to read the secret object, the user could
run a pod which exposes the secret. run a pod which exposes the secret.
- If multiple replicas of etcd are run, then the secrets will be shared between them. - Currently, anyone with root on any node can read _any_ secret from the apiserver,
By default, etcd does not secure peer-to-peer communication with SSL/TLS, though this can be configured.
- Currently, anyone with root on any node can read any secret from the apiserver,
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.
{{< note >}}
As of 1.7 [encryption of secret data at rest is supported](/docs/tasks/administer-cluster/encrypt-data/).
{{< /note >}}
{{% capture whatsnext %}} {{% capture whatsnext %}}