Merge pull request #505 from tam7t/tam7t/docs-namespace

docs: kube-system, upgrades, best-practices

Author: k8s-ci-robot

docs/book/src/SUMMARY.md

@@ -5,11 +5,13 @@
 - [Getting Started](./getting-started/getting-started.md)
     - [Installation](./getting-started/installation.md)
     - [Usage](./getting-started/usage.md)
+    - [Upgrades](./getting-started/upgrades.md)
 - [Topics](./topics/topics.md)
     - [Metrics](./topics/metrics.md)
     - [Secret Auto Rotation](./topics/secret-auto-rotation.md)
     - [Sync as Kubernetes Secret](./topics/sync-as-kubernetes-secret.md)
     - [Set as ENV var](./topics/set-as-env-var.md)
+    - [Best Practices](./topics/best-practices.md)
 - [Providers](./providers.md)
 - [Troubleshooting](./troubleshooting.md)
 - [Load tests](./load-tests.md)

docs/book/src/getting-started/installation.md

@@ -19,10 +19,11 @@ Secrets Store CSI Driver allows users to customize their installation via Helm.
 
 ```bash
 helm repo add secrets-store-csi-driver https://raw.githubusercontent.com/kubernetes-sigs/secrets-store-csi-driver/master/charts
-helm install csi-secrets-store secrets-store-csi-driver/secrets-store-csi-driver
+helm install csi-secrets-store secrets-store-csi-driver/secrets-store-csi-driver --namespace kube-system
 ```
 
-Running the above `helm install` command will install the Secrets Store CSI Driver on Linux nodes.
+Running the above `helm install` command will install the Secrets Store CSI Driver on Linux nodes in the `kube-system`
+namespace.
 
 #### Values
 
@@ -67,23 +68,6 @@ secretproviderclasses.secrets-store.csi.x-k8s.io
 secretproviderclasspodstatuses.secrets-store.csi.x-k8s.io
 ```
 
-<aside class="note warning">
-<h1>Warning</h1>
-
-**v0.0.17** and earlier installed the driver to the `default` namespace.
-Newer versions of the driver will install the driver to the `kube-system`
-namespace. After applying the new YAML files to your cluster run the following
-to clean up old resources:
-
-```bash
-kubectl delete daemonset csi-secrets-store --namespace=default
-kubectl delete daemonset csi-secrets-store-windows --namespace=default
-kubectl delete serviceaccount secrets-store-csi-driver --namespace=default
-```
-
-</aside>
-</details>
-
 ## Use the Secrets Store CSI Driver with a Provider
 
 Now that the Secrets Store CSI Driver has been deployed, select a provider from the supported provider list, then follow the installation steps for the provider:

docs/book/src/getting-started/upgrades.md

@@ -0,0 +1,41 @@
+# Upgrades
+
+This page includes instructions for upgrading the driver to the latest version.
+
+```bash
+helm upgrade csi-secrets-store secrets-store-csi-driver/secrets-store-csi-driver --namespace=NAMESPACE
+```
+
+Set `NAMESPACE` to the same namespace where the driver was originally installed,
+(i.e. `kube-system`)
+
+If you are upgrading from one of the following versions there may be additional
+steps that you should take.
+
+## pre `v0.0.20`
+
+`v0.0.20` removed support for non-gRPC based providers. Follow your provider
+documentation to upgrade providers to use gRPC before upgrading the driver to
+`v0.0.20` or greater.
+
+## pre `v0.0.18`
+
+`v0.0.17` and earlier installed the driver to the `default` namespace when using
+the YAML based install. Newer versions of the driver YAML files install the
+driver to the `kube-system` namespace. After applying the new YAML files to your
+cluster run the following to clean up old resources:
+
+```bash
+kubectl delete daemonset csi-secrets-store --namespace=default
+kubectl delete daemonset csi-secrets-store-windows --namespace=default
+kubectl delete serviceaccount secrets-store-csi-driver --namespace=default
+```
+
+## pre `v0.0.12`
+
+The `SecretProviderClass` needs to be in the same namespace as the pod
+referencing it as of `v0.0.12`.
+
+Defining driver configuration and provider-specific parameters to the CSI driver
+in `pod.Spec[].Volumes` has been deprecated in `v0.0.12`. It is now mandatory to
+use `SecretProviderClass` custom resource.

docs/book/src/topics/best-practices.md

@@ -0,0 +1,61 @@
+# Best Practices
+
+1. Deploy the driver and providers into the `kube-system` or a separate
+  dedicated namespace.
+
+    The driver is installed as a `DaemonSet` with the ability mount kubelet
+    `hostPath` volumes and view pod service account tokens. It should be treated
+    as privileged and regular cluster users should not have permissions to
+    deploy or modify the driver.
+
+1. Do not grant regular cluster users permissions to modify
+  `SecretProviderClassPodStatus` resources.
+
+    The `SecretProviderClassPodStatus` CRD is used by the driver to keep track
+    of mounted resources. Manually editing this resource could have unexpected
+    consequences to the system health and in particular modifying
+    `SecretProviderClassPodStatus/status` may have security implications.
+
+1. Disable `Secret` sync if not needed.
+
+    If you do not intend to use the `Secret` syncing feature, do not install the
+    RBAC permissions that allow the driver to access cluster `Secret` objects.
+
+    This can be done by setting `syncSecret.enabled = false` when installing
+    with helm.
+
+1. Enable KMS application wrapping if using `Secret` sync.
+
+    If you need to synchronise your external secrets to Kubernetes `Secret`s
+    consider configuring
+    [encryption of data at rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/)
+
+    This will ensure that data is encrypted before it is stored in `etcd`.
+
+1. Keep the driver up to date.
+
+    Subscribe to the
+    [`kubernetes-secrets-store-csi-driver`](https://groups.google.com/forum/#!forum/kubernetes-secrets-store-csi-driver)
+    mailing list to be notified of new releases and security announcements.
+
+    Consider using the
+    [Github Watch](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/viewing-your-subscriptions)
+    feature to subscribe to releases as well.
+
+    Always be sure to review the [release notes](https://github.com/kubernetes-sigs/secrets-store-csi-driver/releases)
+    before upgrading.
+
+1. When evaluating this driver consider the following threats:
+
+    * When a secret is accessible on the **filesystem**, application
+      vulnerabilities like directory traversal attacks can become higher
+      severity as the attacker may gain the ability read the secret material.
+    * When a secret is consumed through **environment variables**,
+      misconfigurations such as enabling a debug endpoints
+      or including dependencies that log process environment details may leak
+      secrets.
+    * When syncing secret material to Kubernetes Secrets, consider whether the
+      access controls on that data store are sufficiently narrow in scope.
+
+    If possible, directly integrating with a purpose built secrets API may offer
+    the best security tradeoffs.