From 7f8e723dc2c55747c97319b86838c66a4b7ed093 Mon Sep 17 00:00:00 2001 From: Iryna Shustava Date: Thu, 13 Aug 2020 14:29:59 -0700 Subject: [PATCH] docs: add docs to use Connect CA providers with Helm (#8464) --- website/data/docs-navigation.js | 2 +- .../docs/k8s/connect/connect-ca-provider.mdx | 167 ++++++++++++++++++ website/pages/docs/k8s/connect/overview.mdx | 11 +- 3 files changed, 170 insertions(+), 10 deletions(-) create mode 100644 website/pages/docs/k8s/connect/connect-ca-provider.mdx diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index a52b238d2b..0086d9db49 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -235,7 +235,7 @@ export default [ { category: 'connect', name: 'Connect Service Mesh', - content: ['overview', 'ingress-gateways', 'terminating-gateways'], + content: ['overview', 'ingress-gateways', 'terminating-gateways', 'connect-ca-provider'], }, 'service-sync', 'dns', diff --git a/website/pages/docs/k8s/connect/connect-ca-provider.mdx b/website/pages/docs/k8s/connect/connect-ca-provider.mdx new file mode 100644 index 0000000000..e0cf04b2be --- /dev/null +++ b/website/pages/docs/k8s/connect/connect-ca-provider.mdx @@ -0,0 +1,167 @@ +--- +layout: docs +page_title: Configuring a Connect CA Provider +sidebar_title: Configuring a Connect CA Provider +description: Configuring a Connect CA Provider +--- + +# Configuring a Connect CA Provider + +~> NOTE: Instructions below should only be used for initially bootstrapping a cluster. +To update the Connect CA provider on an existing cluster or to update any properties, such as tokens, of the CA provider, +please use the [Update CA Configuration Endpoint](/api/connect/ca#update-ca-configuration). + +Consul has support for different certificate authority (CA) providers to be used with the Consul Service Mesh. +Please see [Connect Certificate Management](/docs/connect/ca) for the information on the providers +we currently support. + +Generally, to configure a provider via the Consul Helm chart, you need to follow three steps: + +1. Create a configuration file containing your provider information. +1. Create a Kubernetes secret containing the configuration file. +1. Reference the Kubernetes secret in the [`server.extraVolumes`](/docs/k8s/helm#v-server-extravolumes) value in the Helm chart. + +Below we will go over this process for configuring Vault as the Connect CA. +However, other providers can be configured similarly by providing the appropriate `ca_config` +and `ca_provider` values for the provider you're using. + +## Configuring Vault as a Connect CA + +### Primary Datacenter + +To configure Vault as a CA provider for Consul Connect, +first, create a provider configuration JSON file. +Please refer to [Vault as a Connect CA](/docs/connect/ca/vault) for the configuration options. +You will need to provide a Vault token to the `token` property. +Please refer to [these docs](/docs/connect/ca/vault#token) for the permissions that the token needs to have. +To provide a CA, you first need to create a Kubernetes secret containing the CA. +For example, you may create a secret with the Vault CA like so: + +```shell-session +kubectl create secret generic vault-ca --from-file vault.ca=/path/to/your/vault/ca +``` + +And then reference it like this in the provider configuration: + +```shell-session +$ cat vault-config.json +{ + "connect": [ + { + "ca_config": [ + { + "address": "https://vault:8200", + "intermediate_pki_path": "dc1/connect-intermediate", + "root_pki_path": "connect-root", + "token": "s.VgQvaXl8xGFO1RUxAPbPbsfN", + "ca_file": "/consul/userconfig/vault-ca/vault.ca" + } + ], + "ca_provider": "vault" + } + ] +} +``` + +This example configuration file is pointing to a Vault instance running in the same Kubernetes cluster, +which has been deployed with TLS enabled. Note that the `ca_file` is pointing to the file location +based on the Kubernetes secret for the Vault CA that we have created before. +We will provide that secret later in the Helm values for our Consul cluster. + +~> NOTE: If you have used Kubernetes CA to sign Vault's certificate, +such as shown in [Standalone Server with TLS](https://www.vaultproject.io/docs/platform/k8s/helm/examples/standalone-tls), +you don't need to create a Kubernetes secret with Vault's CA and can reference the CA directly +by setting `ca_file` to `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`. + +Next, create a Kubernetes secret with this configuration file. + +```shell-session +$ kubectl create secret generic vault-config --from-file=config=vault-config.json +``` + +We will provide this secret and the Vault CA secret, to the Consul server via the +`server.extraVolumes` Helm value. + +```yaml +# config.yaml +global: + name: consul +server: + extraVolumes: + - type: secret + name: vault-config + load: true + items: + - key: config + path: vault-config.json + - type: secret + name: vault-ca + load: false +connectInject: + enabled: true +``` + +Finally, [install](/docs/k8s/installation/overview#installing-consul) the Helm chart using the above config file: + +```shell-session +$ helm install consul -f config.yaml hashicorp/consul +``` + +Verify that the CA provider is set correctly: + +```shell-session +$ kubectl exec consul-server-0 -- curl -s http://localhost:8500/v1/connect/ca/configuration | jq . +{ + "Provider": "vault", + "Config": { + "Address": "https://vault:8200", + "CAFile": "/consul/userconfig/vault-server-tls/vault.ca", + "IntermediateCertTTL": "8760h", + "IntermediatePKIPath": "connect-intermediate", + "LeafCertTTL": "72h", + "RootPKIPath": "connect-root", + "RotationPeriod": "2160h", + "Token": "s.VgQvaXl8xGFO1RUxAPbPbsfN" + }, + "State": null, + "ForceWithoutCrossSigning": false, + "CreateIndex": 5, + "ModifyIndex": 5 +} +``` + +### Secondary Datacenters + +To configure Vault as the Connect CA in secondary datacenters, you need to make sure that the Root CA is the same, +but the intermediate is different for each datacenter. In the `connect` configuration for a secondary datacenter, +you can specify a `intermediate_pki_path` that is, for example, prefixed with the datacenter +for which this configuration is intended. +You will similarly need to create a Vault token and a Kubernetes secret with +Vault's CA in each secondary Kubernetes cluster. + +```json +{ + "connect": [ + { + "ca_config": [ + { + "address": "https://vault:8200", + "intermediate_pki_path": "dc2/connect-intermediate", + "root_pki_path": "connect-root", + "token": "s.VgQvaXl8xGFO1RUxAPbPbsfN", + "ca_file": "/consul/userconfig/vault-ca/vault.ca" + } + ], + "ca_provider": "vault" + } + ] +} +``` + +Note that all secondary datacenters need to have access to the same Vault instance as the primary. + +### Rotating Vault Tokens + +Once the cluster is running, subsequent changes to the `ca_provider` config are **ignored**–even if `consul reload` is run or the servers are restarted. + +To update any settings under this key, you must use Consul's [Update CA Configuration](/api/connect/ca#update-ca-configuration) API or the [`consul connect ca set-config`](https://www.consul.io/docs/commands/connect/ca#set-config) command. diff --git a/website/pages/docs/k8s/connect/overview.mdx b/website/pages/docs/k8s/connect/overview.mdx index 7b2538fb7b..6cd816d396 100644 --- a/website/pages/docs/k8s/connect/overview.mdx +++ b/website/pages/docs/k8s/connect/overview.mdx @@ -421,10 +421,10 @@ If you wish to enable injection in every namespace _except_ specific namespaces, use `*` in the allow list to allow all namespaces and then specify the namespaces to exclude in the deny list: ```yaml -syncCatalog: +connectInject: enabled: true k8sAllowNamespaces: ['*'] - k8sDenyNamespaces: ['no-sync-ns-1', 'no-sync-ns-2'] + k8sDenyNamespaces: ['no-inject-ns-1', 'no-inject-ns-2'] ``` -> **NOTE:** The deny list takes precedence over the allow list. If a namespace @@ -432,13 +432,6 @@ is listed in both lists, it will **not** be synced. ~> **NOTE:** The `kube-system` and `kube-public` namespaces will never be injected. -### Consul Clients Required - -Connect injection requires that local client agents -are running on each Kubernetes node. These client agents must be joined to a Consul -server cluster. -The Consul server cluster can run either in or out of a Kubernetes cluster. - ### Consul Enterprise Namespaces Consul Enterprise 1.7+ supports Consul namespaces. When Kubernetes pods are registered