From 662fb1b919b55b970d8fc5dd7b76fb030a6290a5 Mon Sep 17 00:00:00 2001 From: David Yu Date: Fri, 21 Jan 2022 11:01:48 -0800 Subject: [PATCH] docs: Formatting Consul K8s Vault docs (#12148) * Update index.mdx * Update gossip.mdx * Update install-cli.mdx * Update gossip.mdx * Update website/content/docs/k8s/installation/vault/gossip.mdx Co-authored-by: Bryce Kalow * fix MDX formatting * local changes * adding formatting changes * Update website/content/docs/k8s/installation/vault/connect-ca.mdx Co-authored-by: mrspanishviking * adding shell-session to service mesh certs Co-authored-by: Bryce Kalow Co-authored-by: mrspanishviking --- .../docs/k8s/installation/install-cli.mdx | 2 +- .../k8s/installation/vault/connect-ca.mdx | 18 +++++-- .../docs/k8s/installation/vault/gossip.mdx | 44 ++++++++++----- .../docs/k8s/installation/vault/index.mdx | 6 ++- .../k8s/installation/vault/server-tls.mdx | 53 +++++++++++++------ 5 files changed, 87 insertions(+), 36 deletions(-) diff --git a/website/content/docs/k8s/installation/install-cli.mdx b/website/content/docs/k8s/installation/install-cli.mdx index 5a4016776e..2959404451 100644 --- a/website/content/docs/k8s/installation/install-cli.mdx +++ b/website/content/docs/k8s/installation/install-cli.mdx @@ -17,7 +17,7 @@ These instructions describe how to install the latest version of the CLI dependi -The [Homebrew](https://brew.sh) package manager is required to complete the following installation instructions. The Homebrew formulae will always install the latest version of a binary. If you are looking to install a specific version of the CLI please follow [Install a specific version of Consul K8s CLI](#install-a-specific-version-of-consul-k8s-cli). +The [Homebrew](https://brew.sh) package manager is required to complete the following installation instructions. The Homebrew formulae will always install the latest version of a binary. If you are looking to install a specific version of the CLI please follow [Install a specific version of Consul K8s CLI](#install-a-specific-version-of-the-cli). 1. Install the HashiCorp `tap`, which is a repository of all Homebrew packages for HashiCorp: ```shell-session diff --git a/website/content/docs/k8s/installation/vault/connect-ca.mdx b/website/content/docs/k8s/installation/vault/connect-ca.mdx index 97d4e0db70..7a96e9b083 100644 --- a/website/content/docs/k8s/installation/vault/connect-ca.mdx +++ b/website/content/docs/k8s/installation/vault/connect-ca.mdx @@ -21,7 +21,7 @@ documentation. Once you have a policy, you will need to link that policy to the Consul server service account. ```shell-session -vault write auth/kubernetes/role/consul-server \ +$ vault write auth/kubernetes/role/consul-server \ bound_service_account_names= \ bound_service_account_namespaces= \ policies= \ @@ -32,10 +32,14 @@ To find out the service account name of the Consul server, you can run: ```shell-session -$ helm template --release-name --show-only templates/server-serviceaccount.yaml hashicorp/consul +$ helm template --release-name ${RELEASE_NAME} --show-only templates/server-serviceaccount.yaml hashicorp/consul ``` -Now we can configure the Consul Helm chart to use Vault as the Connect CA provider: +Now you can configure the Consul Helm chart to use Vault as the Connect CA provider: + + + + ```yaml global: @@ -53,6 +57,10 @@ global: secretName: ``` + + + + The `address` you provide to the `connectCA` configuration can be a Kubernetes DNS address if the Vault cluster is running the same Kubernetes cluster. The `rootPKIPath` and `intermediatePKIPath` should be the same as the ones @@ -62,8 +70,8 @@ generate a new Vault token. The `vaultCASecret` is the Kubernetes secret that stores the CA Certificate that is used for Vault communication. 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: -``` -kubectl create secret generic vault-ca --from-file vault.ca=/path/to/your/vault/ca +```shell-session +$ kubectl create secret generic vault-ca --from-file vault.ca=/path/to/your/vault/ca ``` ### Secondary Datacenters diff --git a/website/content/docs/k8s/installation/vault/gossip.mdx b/website/content/docs/k8s/installation/vault/gossip.mdx index 4e1422d583..aff1a4d8ce 100644 --- a/website/content/docs/k8s/installation/vault/gossip.mdx +++ b/website/content/docs/k8s/installation/vault/gossip.mdx @@ -18,20 +18,28 @@ To use a gossip encryption key stored in Vault we need the following: First, generate and store the gossip key in Vault: ```shell-session -vault kv put secret/consul/gossip key="$(consul keygen)" +$ vault kv put secret/consul/gossip key="$(consul keygen)" ``` Next, we will need to create a policy that allows read access to this secret: -```shell-session -# gossip-policy.hcl + + + + + +```HCL path "secret/data/consul/gossip" { capabilities = ["read"] } ``` + + + + ```shell-session -vault policy write gossip-policy gossip-policy.hcl +$ vault policy write gossip-policy gossip-policy.hcl ``` Prior to creating Vault auth roles for the Consul servers and clients, ensure that the Vault Kubernetes auth method is enabled as described in [Vault Kubernetes Auth Method](/docs/k8s/installation/vault#vault-kubernetes-auth-method). @@ -39,7 +47,7 @@ Prior to creating Vault auth roles for the Consul servers and clients, ensure th Next, we will create Kubernetes auth roles for the Consul server and client: ```shell-session -vault write auth/kubernetes/role/consul-server \ +$ vault write auth/kubernetes/role/consul-server \ bound_service_account_names= \ bound_service_account_namespaces= \ policies=gossip-policy \ @@ -47,7 +55,7 @@ vault write auth/kubernetes/role/consul-server \ ``` ```shell-session -vault write auth/kubernetes/role/consul-client \ +$ vault write auth/kubernetes/role/consul-client \ bound_service_account_names= \ bound_service_account_namespaces= \ policies=gossip-policy \ @@ -57,18 +65,25 @@ vault write auth/kubernetes/role/consul-client \ To find out the service account names of the Consul server and client, you can run the following `helm template` commands with your Consul on Kubernetes values file: -``` -# Generate Consul server service account name -helm template --release-name -s templates/server-serviceaccount.yaml hashicorp/consul -# Generate Consul client service account name -helm template --release-name -s templates/client-serviceaccount.yaml hashicorp/consul -``` +- Generate Consul server service account name + ```shell-session + $ helm template --release-name ${RELEASE_NAME} -s templates/server-serviceaccount.yaml hashicorp/consul + ``` + +- Generate Consul client service account name + ```shell-session + $ helm template --release-name ${RELEASE_NAME} -s templates/client-serviceaccount.yaml hashicorp/consul + ``` ## Deploying the Consul Helm chart Now that we've configured Vault, you can configure the Consul Helm chart to use the gossip key in Vault: + + + + ```yaml global: secretsBackend: @@ -81,8 +96,11 @@ global: secretKey: key ``` + + + + Note that `global.gossipEncryption.secretName` is the path of the secret in Vault. This should be the same path as the one you'd include in your Vault policy. `global.gossipEncryption.secretKey` is the key inside the secret data. This should be the same as the key we passed when we created the gossip secret in Vault. - diff --git a/website/content/docs/k8s/installation/vault/index.mdx b/website/content/docs/k8s/installation/vault/index.mdx index 4c978eed73..1d9dd1caf1 100644 --- a/website/content/docs/k8s/installation/vault/index.mdx +++ b/website/content/docs/k8s/installation/vault/index.mdx @@ -27,7 +27,9 @@ At a high level, there are two points of integration with Vault: ### Vault Helm Config -A minimal valid installation of Vault must include the Agent Injector: +A minimal valid installation of Vault Kubernetes must include the Agent Injector which is utilized for accessing secrets from Vault. Vault servers could be deployed +external to Vault on Kubernetes as described via the [`externalvaultaddr`](https://www.vaultproject.io/docs/platform/k8s/helm/configuration#externalvaultaddr) value in the Vault Helm Configuration + ```yaml injector: enabled: "true" @@ -83,7 +85,7 @@ which bootstrap Vault Auth roles and Policies for Consul to use. For the support guides and ensure to, when combining the secrets, append the Vault Policies to your Vault Kube Auth Roles via a comma separated value (i.e. `policies=gossip-policy,consul-ca,consul-server,custom-policy`). Ex: ```shell-session -vault write auth/kubernetes/role/consul-server \ +$ vault write auth/kubernetes/role/consul-server \ bound_service_account_names= \ bound_service_account_namespaces= \ policies=gossip-policy,consul-ca,consul-server \ diff --git a/website/content/docs/k8s/installation/vault/server-tls.mdx b/website/content/docs/k8s/installation/vault/server-tls.mdx index 7ace8c2e22..4f07f7b265 100644 --- a/website/content/docs/k8s/installation/vault/server-tls.mdx +++ b/website/content/docs/k8s/installation/vault/server-tls.mdx @@ -48,13 +48,20 @@ Next we will create a policy that allows `["create", "update"]` access to the [certificate issuing URL](https://www.vaultproject.io/api/secret/pki#generate-certificate) so the Consul servers can fetch a new certificate/key pair. -```shell-session -# consul-server-policy.hcl + + + + +```HCL path "pki/issue/consul-server" { capabilities = ["create", "update"] } ``` + + + + ```shell-session $ vault policy write consul-server consul-server-policy.hcl ``` @@ -66,13 +73,21 @@ $ vault policy write consul-server consul-server-policy.hcl Next, we will create a policy that allows `["read"]` access to the [CA URL](https://www.vaultproject.io/api/secret/pki#read-certificate), this is required for the Consul components to communicate with the Consul servers in order to fetch their auto-encryption certificates. -```shell-session -# ca-policy.hcl + + + + + +```HCL path "pki/cert/ca" { capabilities = ["read"] } ``` + + + + ```shell-session $ vault policy write ca-policy ca-policy.hcl ``` @@ -84,13 +99,13 @@ $ vault policy write ca-policy ca-policy.hcl Next, a Vault role for the PKI engine will set the default certificate issuance parameters: ```shell-session -vault write pki/roles/consul-server \ - allowed_domains="" \ - allow_subdomains=true \ - allow_bare_domains=true \ - allow_localhost=true \ - generate_lease=true \ - max_ttl="720h" +$ vault write pki/roles/consul-server \ + allowed_domains="" \ + allow_subdomains=true \ + allow_bare_domains=true \ + allow_localhost=true \ + generate_lease=true \ + max_ttl="720h" ``` To generate the `` use the following script as a template: @@ -125,7 +140,7 @@ To find out the service account name of the Consul server, you can run: ```shell-session - $ helm template --release-name --show-only templates/server-serviceaccount.yaml hashicorp/consul + $ helm template --release-name ${RELEASE_NAME} --show-only templates/server-serviceaccount.yaml hashicorp/consul ``` -> **Note:** Should you enable other supported features such as gossip-encryption be sure to append additional policies to @@ -143,7 +158,7 @@ $ vault write auth/kubernetes/role/consul-client \ To find out the service account name of the Consul client, use the command below. ```shell-session - $ helm template --release-name --show-only templates/client-serviceaccount.yaml hashicorp/consul + $ helm template --release-name ${RELEASE_NAME} --show-only templates/client-serviceaccount.yaml hashicorp/consul ``` -> **Note:** Should you enable other supported features such as gossip-encryption, ensure you append additional policies to @@ -166,6 +181,10 @@ The above Vault Roles will now be your Helm values for `global.secretsBackend.va Now that we've configured Vault, you can configure the Consul Helm chart to use the Server TLS certificates from Vault: + + + + ```yaml global: secretsBackend: @@ -188,8 +207,12 @@ server: load: "false" ``` + + + + The `vaultCASecret` is the Kubernetes secret that stores the CA Certificate that is used for Vault communication. 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: -``` -kubectl create secret generic vault-ca --from-file vault.ca=/path/to/your/vault/ +```shell-session +$ kubectl create secret generic vault-ca --from-file vault.ca=/path/to/your/vault/ ```