Add docs for updated Citadel namespace targeting mechanism (#4746)

* Add docs for updated Citadel namespace targeting mechanism

* Make doc voicing and audience pronouns fit rest of docs

content/en/docs/concepts/security/index.md

@@ -210,6 +210,55 @@ In this setup, Kubernetes can isolate the operator privileges on managing the se
 Istio manages certificates and keys in all namespaces
 and enforces different access control rules to the services.
 
+### How Citadel determines whether to create Service Account secrets
+
+When a Citadel instance notices that a `ServiceAccount` is created in a namespace, it must decide whether it should generate an `istio.io/key-and-cert` secret for that `ServiceAccount`. In order to make that decision, Citadel considers three inputs (note: there can be multiple Citadel instances deployed in a single cluster, and the following targeting rules are applied to each instance):
+
+1. `ca.istio.io/env` namespace label: *string valued* label containing the namespace of the desired Citadel instance
+
+1. `ca.istio.io/override` namespace label: *boolean valued* label which overrides all other configurations and forces all Citadel instances either to target or ignore a namespace
+
+1. [`enableNamespacesByDefault` security configuration](/docs/reference/config/installation-options/#security-options): default behavior if no labels are found on the `ServiceAccount`'s namespace
+
+From these three values, the decision process mirrors that of the [`Sidecar Injection Webhook`](/docs/ops/setup/injection-concepts/). The detailed behavior is that:
+
+- If `ca.istio.io/override` exists and is `true`, generate key/cert secrets for workloads.
+
+- Otherwise, if `ca.istio.io/override` exists and is `false`, don't generate key/cert secrets for workloads.
+
+- Otherwise, if a `ca.istio.io/env: "ns-foo"` label is defined in the service account's namespace, the Citadel instance in namespace `ns-foo` will be used for generating key/cert secrets for workloads in the `ServiceAccount`'s namespace.
+
+- Otherwise, follow the `enableNamespacesByDefault` Helm flag. If it is `true`, the default Citadel instance will be used for generating key/cert secrets for workloads in the `ServiceAccount`'s namespace.
+
+- Otherwise, no secrets are created for the `ServiceAccount`'s namespace.
+
+This logic is captured in the truth table below:
+
+| `ca.istio.io/override` value | `ca.istio.io/env` match | `enableNamespacesByDefault` configuration | Workload secret created |
+|------------------------------|-------------------------|-------------------------------------------|-------------------------|
+|`true`|yes|`true`|yes|
+|`true`|yes|`false`|yes|
+|`true`|no|`true`|yes|
+|`true`|no|`false`|yes|
+|`true`|unset|`true`|yes|
+|`true`|unset|`false`|yes|
+|`false`|yes|`true`|no|
+|`false`|yes|`false`|no|
+|`false`|no|`true`|no|
+|`false`|no|`false`|no|
+|`false`|unset|`true`|no|
+|`false`|unset|`false`|no|
+|unset|yes|`true`|yes|
+|unset|yes|`false`|yes|
+|unset|no|`true`|no|
+|unset|no|`false`|no|
+|unset|unset|`true`|yes|
+|unset|unset|`false`|no|
+
+{{< idea >}}
+When a namespace transitions from _disabled_ to _enabled_, Citadel will retroactively generate secrets for all `ServiceAccounts` in that namespace. When transitioning from _enabled_ to _disabled_, however, Citadel will not delete the namespace's generated secrets until the root certificate is renewed.
+{{< /idea >}}
+
 ## Authentication
 
 Istio provides two types of authentication:

content/en/docs/reference/config/installation-options/index.md

@@ -472,6 +472,7 @@ To customize Istio install using Helm, use the `--set <key>=<value>` option in H
 | `security.replicaCount` | `1` |  |
 | `security.rollingMaxSurge` | `100%` |  |
 | `security.rollingMaxUnavailable` | `25%` |  |
+| `security.enableNamespacesByDefault` | `true` | `determines whether namespaces without the ca.istio.io/env and ca.istio.io/override labels should be targeted by the Citadel instance for secret creation` |
 | `security.image` | `citadel` |  |
 | `security.selfSigned` | `true` | `indicate if self-signed CA is used.` |
 | `security.createMeshPolicy` | `true` |  |

content/en/docs/tasks/security/ca-namespace-targeting/index.md

@@ -0,0 +1,114 @@
+---
+title: Configure Citadel Service Account Secret Generation
+description: Configure which namespaces Citadel should generate service account secrets for.
+weight: 80
+---
+
+A cluster operator might decide not to generate `ServiceAccount` secrets for some subset of namespaces, or to make `ServiceAccount` secret generation opt-in per namespace. This task describes how an operator can configure their cluster for these situations. Full documentation of the Citadel namespace targeting mechanism can be found [here](/docs/concepts/security/#how-citadel-determines-whether-to-create-service-account-secrets).
+
+## Before you begin
+
+To complete this task, you should first take the following actions:
+
+* Read the [security concept](/docs/concepts/security/#how-citadel-determines-whether-to-create-service-account-secrets).
+
+* Follow the [Kubernetes quick start](/docs/setup/install/kubernetes/) to install Istio using the **strict mutual TLS profile**.
+
+### Deactivating Service Account secret generation for a single namespace
+
+To create a new sample namespace `foo`, run:
+
+{{< text bash >}}
+$ kubectl create ns foo
+{{< /text >}}
+
+Service account secrets are created following the default behavior. To verify that Citadel has generated a key/cert secret for the default service account in the `foo` namespace, run (note that this may take up to 1 minute):
+
+{{< text bash >}}
+$ kubectl get secrets -n foo | grep istio.io
+NAME                    TYPE                           DATA      AGE
+istio.default           istio.io/key-and-cert          3         13s
+{{< /text >}}
+
+To label the namespace to prevent Citadel from creating `ServiceAccount` secrets in target namespace `foo`, run:
+
+{{< text bash >}}
+$ kubectl label ns foo ca.istio.io/override=false
+{{< /text >}}
+
+To create a new `ServiceAccount` in this namespace, run:
+
+{{< text bash >}}
+$ kubectl apply -f - <<EOF
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: sample-service-account
+  namespace: foo
+EOF
+{{< /text >}}
+
+To check the namespace's secrets again, run:
+
+{{< text bash >}}
+$ kubectl get secrets -n foo | grep istio.io
+NAME                    TYPE                           DATA      AGE
+istio.default           istio.io/key-and-cert          3         11m
+{{< /text >}}
+
+You can observe that no new `istio.io/key-and-cert` secret was generated for the `sample-service-account` service account.
+
+### Opt-in Service Account secret generation
+
+To make `ServiceAcount` secret generation opt-in (i.e. to disable generating secrets unless otherwise specified)., set the `enableNamespacesByDefault` Helm value to `false`:
+
+{{< text yaml >}}
+...
+security:
+    enableNamespacesByDefault: false
+...
+{{< /text >}}
+
+Once this mesh configuration is applied, to create a namespace `foo` and check the secrets present in that namespace, run:
+
+{{< text bash >}}
+$ kubectl create ns foo
+$ kubectl get secrets -n foo | grep istio.io
+{{< /text >}}
+
+You can observe that no secrets have been created. To override this value for the `foo` namespace, add a `ca.istio.io/override=true` label in that namespace:
+
+{{< text bash >}}
+$ kubectl label ns foo ca.istio.io/override=true
+{{< /text >}}
+
+To create a new service account in the `foo` namespace, run:
+
+{{< text bash >}}
+$ kubectl apply -f - <<EOF
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: sample-service-account
+  namespace: foo
+EOF
+{{< /text >}}
+
+To check the secrets in the `foo` namespace again, run:
+
+{{< text bash >}}
+$ kubectl get secrets -n foo | grep istio.io
+NAME                                 TYPE                                  DATA   AGE
+istio.default                        istio.io/key-and-cert                 3      47s
+istio.sample-service-account         istio.io/key-and-cert                 3      6s
+{{< /text >}}
+
+You can observe that an `istio.io/key-and-cert` secret has been created for the `default` service account in addition to the `sample-service-account`. This is due to the retroactive secret generation feature, which will create secrets for all service accounts in a namespace once it transitions from inactive to active.
+
+## Cleanup
+
+To delete the `foo` test namespace and all its resources, run:
+
+{{< text bash >}}
+$ kubectl delete ns foo
+{{< /text >}}