From 9ff424c3ecff000028e06c0ac266ad1422f2e4df Mon Sep 17 00:00:00 2001 From: Sam Naser Date: Tue, 10 Sep 2019 07:51:56 -0700 Subject: [PATCH] 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 | 49 ++++++++ .../config/installation-options/index.md | 1 + .../security/ca-namespace-targeting/index.md | 114 ++++++++++++++++++ 3 files changed, 164 insertions(+) create mode 100644 content/en/docs/tasks/security/ca-namespace-targeting/index.md diff --git a/content/en/docs/concepts/security/index.md b/content/en/docs/concepts/security/index.md index a382fe7d89..8dd88dddef 100644 --- a/content/en/docs/concepts/security/index.md +++ b/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: diff --git a/content/en/docs/reference/config/installation-options/index.md b/content/en/docs/reference/config/installation-options/index.md index fbad18ffff..79c83b27b9 100644 --- a/content/en/docs/reference/config/installation-options/index.md +++ b/content/en/docs/reference/config/installation-options/index.md @@ -472,6 +472,7 @@ To customize Istio install using Helm, use the `--set =` 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` | | diff --git a/content/en/docs/tasks/security/ca-namespace-targeting/index.md b/content/en/docs/tasks/security/ca-namespace-targeting/index.md new file mode 100644 index 0000000000..3834216e2c --- /dev/null +++ b/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 - <}} + +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 - <}} + +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 >}} \ No newline at end of file