mirror of https://github.com/istio/istio.io.git
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
This commit is contained in:
Sam Naser
Istio Automation
parent
1222c37629
commit
9ff424c3ec
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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` | |
|
||||
|
|
|
|||
|
|
@ -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 >}}
|
||||
Loading…
Reference in New Issue