Merge pull request #34291 from shannonxtreme/secrets-good-practices

Add good practices page for secrets

content/en/docs/concepts/configuration/secret.md

@@ -36,11 +36,12 @@ Additionally, anyone who is authorized to create a Pod in a namespace can use th
 In order to safely use Secrets, take at least the following steps:
 
 1. [Enable Encryption at Rest](/docs/tasks/administer-cluster/encrypt-data/) for Secrets.
-1. [Enable or configure RBAC rules](/docs/reference/access-authn-authz/authorization/) that
+1. [Enable or configure RBAC rules](/docs/reference/access-authn-authz/authorization/) with least-privilege access to Secrets.
-   restrict reading and writing the Secret. Be aware that secrets can be obtained
+1. Restrict Secret access to specific containers.
-   implicitly by anyone with the permission to create a Pod.
+1. [Consider using external Secret store providers](https://secrets-store-csi-driver.sigs.k8s.io/concepts.html#provider-for-the-secrets-store-csi-driver).
-1. Where appropriate, also use mechanisms such as RBAC to limit which principals are allowed
+
-   to create new Secrets or replace existing ones.
+For more guidelines to manage and improve the security of your Secrets, refer to
+[Good practices for Kubernetes Secrets](/docs/concepts/security/secrets-good-practices).
 
 {{< /caution >}}
 
@@ -1280,61 +1281,15 @@ Secrets that a Pod requests are potentially visible within its containers.
 Therefore, one Pod does not have access to the Secrets of another Pod.
 
 {{< warning >}}
-Any privileged containers on a node are liable to have access to all Secrets used
+Any containers that run with `privileged: true` on a node can access all
-on that node.
+Secrets used on that node.
 {{< /warning >}}
 
 
-### Security recommendations for developers
-
-- Applications still need to protect the value of confidential information after reading it
-  from an environment variable or volume. For example, your application must avoid logging
-  the secret data in the clear or transmitting it to an untrusted party.
-- If you are defining multiple containers in a Pod, and only one of those
-  containers needs access to a Secret, define the volume mount or environment
-  variable configuration so that the other containers do not have access to that
-  Secret.
-- If you configure a Secret through a {{< glossary_tooltip text="manifest" term_id="manifest" >}},
-  with the secret data encoded as base64, sharing this file or checking it in to a
-  source repository means the secret is available to everyone who can read the manifest.
-  Base64 encoding is _not_ an encryption method, it provides no additional confidentiality
-  over plain text.
-- When deploying applications that interact with the Secret API, you should
-  limit access using
-  [authorization policies](/docs/reference/access-authn-authz/authorization/) such as
-  [RBAC](/docs/reference/access-authn-authz/rbac/).
-- In the Kubernetes API, `watch` and `list` requests for Secrets within a namespace
-  are extremely powerful capabilities. Avoid granting this access where feasible, since
-  listing Secrets allows the clients to inspect the values of every Secret in that
-  namespace.
-
-### Security recommendations for cluster administrators
-
-{{< caution >}}
-A user who can create a Pod that uses a Secret can also see the value of that Secret. Even
-if cluster policies do not allow a user to read the Secret directly, the same user could
-have access to run a Pod that then exposes the Secret.
-{{< /caution >}}
-
-- Reserve the ability to `watch` or `list` all secrets in a cluster (using the Kubernetes
-  API), so that only the most privileged, system-level components can perform this action.
-- When deploying applications that interact with the Secret API, you should
-  limit access using
-  [authorization policies](/docs/reference/access-authn-authz/authorization/) such as
-  [RBAC](/docs/reference/access-authn-authz/rbac/).
-- In the API server, objects (including Secrets) are persisted into
-  {{< glossary_tooltip term_id="etcd" >}}; therefore:
-  - only allow cluster administrators to access etcd (this includes read-only access);
-  - enable [encryption at rest](/docs/tasks/administer-cluster/encrypt-data/)
-    for Secret objects, so that the data of these Secrets are not stored in the clear
-    into {{< glossary_tooltip term_id="etcd" >}};
-  - consider wiping / shredding the durable storage used by etcd once it is
-    no longer in use;
-  - if there are multiple etcd instances, make sure that etcd is
-    using SSL/TLS for communication between etcd peers.
-
 ## {{% heading "whatsnext" %}}
 
+- For guidelines to manage and improve the security of your Secrets, refer to
+  [Good practices for Kubernetes Secrets](/docs/concepts/security/secrets-good-practices).
 - Learn how to [manage Secrets using `kubectl`](/docs/tasks/configmap-secret/managing-secret-using-kubectl/)
 - Learn how to [manage Secrets using config file](/docs/tasks/configmap-secret/managing-secret-using-config-file/)
 - Learn how to [manage Secrets using kustomize](/docs/tasks/configmap-secret/managing-secret-using-kustomize/)

content/en/docs/concepts/security/multi-tenancy.md

@@ -1,7 +1,7 @@
 ---
 title: Multi-tenancy
 content_type: concept
-weight: 70
+weight: 80
 ---
 
 <!-- overview -->
@@ -513,4 +513,3 @@ project provides an implementation of virtual control planes.
 
 * [Kamaji](https://github.com/clastix/kamaji)
 * [vcluster](https://github.com/loft-sh/vcluster)
-

content/en/docs/concepts/security/secrets-good-practices.md

@@ -0,0 +1,116 @@
+---
+title: Good practices for Kubernetes Secrets
+description: >
+  Principles and practices for good Secret management for cluster administrators and application developers.
+content_type: concept
+weight: 70
+---
+
+<!-- overview -->
+
+{{<glossary_definition prepend="In Kubernetes, a Secret is an object that"
+term_id="secret" length="all">}}
+
+The following good practices are intended for both cluster administrators and
+application developers. Use these guidelines to improve the security of your
+sensitive information in Secret objects, as well as to more effectively manage
+your Secrets.
+
+<!-- body -->
+
+## Cluster administrators
+
+This section provides good practices that cluster administrators can use to
+improve the security of confidential information in the cluster.
+
+### Configure encryption at rest
+
+By default, Secret objects are stored unencrypted in {{<glossary_tooltip
+term_id="etcd" text="etcd">}}. You should configure encryption of your Secret
+data in `etcd`. For instructions, refer to
+[Encrypt Secret Data at Rest](/docs/tasks/administer-cluster/encrypt-data/).
+
+### Configure least-privilege access to Secrets {#least-privilege-secrets}
+
+When planning your access control mechanism, such as Kubernetes
+{{<glossary_tooltip term_id="rbac" text="Role-based Access Control">}} [(RBAC)](/docs/reference/access-authn-authz/rbac/),
+consider the following guidelines for access to `Secret` objects. You should
+also follow the other guidelines in
+[RBAC good practices](/docs/concepts/security/rbac-good-practices).
+
+- **Components**: Restrict `watch` or `list` access to only the most
+  privileged, system-level components. Only grant `get` access for Secrets if
+  the component's normal behavior requires it.
+- **Humans**: Restrict `get`, `watch`, or `list` access to Secrets. Only allow
+  cluster admistrators to access `etcd`. This includes read-only access. For
+  more complex access control, such as restricting access to Secrets with
+  specific annotations, consider using third-party authorization mechanisms.
+
+{{< caution >}}
+Granting `list` access to Secrets implicitly lets the subject fetch the
+contents of the Secrets.
+{{< /caution >}}
+
+A user who can create a Pod that uses a Secret can also see the value of that
+Secret. Even if cluster policies do not allow a user to read the Secret
+directly, the same user could have access to run a Pod that then exposes the
+Secret. You can detect or limit the impact caused by Secret data being exposed,
+either intentionally or unintentionally, by a user with this access. Some
+recommendations include:
+
+*  Use short-lived Secrets
+*  Implement audit rules that alert on specific events, such as concurrent
+   reading of multiple Secrets by a single user
+
+### Improve etcd management policies
+
+Consider wiping or shredding the durable storage used by `etcd` once it is
+no longer in use.
+
+If there are multiple `etcd` instances, configure encrypted SSL/TLS
+communication between the instances to protect the Secret data in transit.
+
+### Configure access to external Secrets
+
+{{% thirdparty-content %}}
+
+You can use third-party Secrets store providers to keep your confidential data
+outside your cluster and then configure Pods to access that information.
+The [Kubernetes Secrets Store CSI Driver](https://secrets-store-csi-driver.sigs.k8s.io/)
+is a DaemonSet that lets the kubelet retrieve Secrets from external stores, and
+mount the Secrets as a volume into specific Pods that you authorize to access
+the data.
+
+For a list of supported providers, refer to
+[Providers for the Secret Store CSI Driver](https://secrets-store-csi-driver.sigs.k8s.io/concepts.html#provider-for-the-secrets-store-csi-driver).
+
+## Developers
+
+This section provides good practices for developers to use to improve the
+security of confidential data when building and deploying Kubernetes resources.
+
+### Restrict Secret access to specific containers
+
+If you are defining multiple containers in a Pod, and only one of those
+containers needs access to a Secret, define the volume mount or environment
+variable configuration so that the other containers do not have access to that
+Secret.
+
+### Protect Secret data after reading
+
+Applications still need to protect the value of confidential information after
+reading it from an environment variable or volume. For example, your
+application must avoid logging the secret data in the clear or transmitting it
+to an untrusted party.
+
+### Avoid sharing Secret manifests
+
+If you configure a Secret through a
+{{< glossary_tooltip text="manifest" term_id="manifest" >}}, with the secret
+data encoded as base64, sharing this file or checking it in to a source
+repository means the secret is available to everyone who can read the manifest.
+
+{{<caution>}}
+Base64 encoding is _not_ an encryption method, it provides no additional
+confidentiality over plain text.
+{{</caution>}}

content/en/docs/reference/glossary/secret.md

@@ -11,8 +11,17 @@ tags:
 - core-object
 - security
 ---
- Stores sensitive information, such as passwords, OAuth tokens, and ssh keys.
+ Stores sensitive information, such as passwords, OAuth tokens, and SSH keys.
 
 <!--more-->
 
-Allows for more control over how sensitive information is used and reduces the risk of accidental exposure. Secret values are encoded as base64 strings and stored unencrypted by default, but can be configured to be [encrypted at rest](/docs/tasks/administer-cluster/encrypt-data/#ensure-all-secrets-are-encrypted). A {{< glossary_tooltip text="Pod" term_id="pod" >}} references the secret as a file in a volume mount or by the kubelet pulling images for a pod. Secrets are great for confidential data and [ConfigMaps](/docs/tasks/configure-pod-container/configure-pod-configmap/) for non-confidential data.
+Secrets give you more control over how sensitive information is used and reduces
+the risk of accidental exposure. Secret values are encoded as base64 strings and
+are stored unencrypted by default, but can be configured to be
+[encrypted at rest](/docs/tasks/administer-cluster/encrypt-data/#ensure-all-secrets-are-encrypted).
+
+A {{< glossary_tooltip text="Pod" term_id="pod" >}} can reference the Secret in
+a variety of ways, such as in a volume mount or as an environment variable.
+Secrets are designed for confidential data and
+[ConfigMaps](/docs/tasks/configure-pod-container/configure-pod-configmap/) are
+designed for non-confidential data.