diff --git a/website/content/docs/k8s/installation/vault/data-integration/bootstrap-token.mdx b/website/content/docs/k8s/installation/vault/data-integration/bootstrap-token.mdx index aa132e4b3..3d5a3d39a 100644 --- a/website/content/docs/k8s/installation/vault/data-integration/bootstrap-token.mdx +++ b/website/content/docs/k8s/installation/vault/data-integration/bootstrap-token.mdx @@ -9,14 +9,13 @@ description: >- This topic describes how to configure the Consul Helm chart to use an ACL bootstrap token stored in Vault. ## Overview -To use an ACL bootstrap token stored in Vault, we will follow the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section: - -### One time setup in Vault +To use an ACL bootstrap token stored in Vault, follow the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section. +Complete the following steps once: 1. Store the secret in Vault. 1. Create a Vault policy that authorizes the desired level of access to the secret. -### Setup per Consul datacenter +Repeat the following steps for each datacenter in the cluster: 1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. 1. Update the Consul on Kubernetes helm chart. @@ -24,20 +23,20 @@ To use an ACL bootstrap token stored in Vault, we will follow the steps outlined Prior to setting up the data integration between Vault and Consul on Kubernetes, you will need to have: 1. Read and completed the steps in the [Systems Integration](/docs/k8s/installation/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). 2. Read the [Data Integration Overview](/docs/k8s/installation/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). -## One time setup in Vault -### Generate and Store the Secret in Vault -First, generate and store the ACL bootstrap token in Vault: +## Store the Secret in Vault + +First, generate and store the ACL bootstrap token in Vault. You will only need to perform this action once: ```shell-session $ vault kv put secret/consul/bootstrap-token token="$(uuidgen | tr '[:upper:]' '[:lower:]')" ``` -### Create a Vault policy that authorizes the desired level of access to the secret +## Create Vault policy --> **Note:** The secret path referenced by the Vault Policy below will be your `global.acls.bootstrapToken.secretName` Helm value. +Next, you will need to create a Vault policy that allows read access to this secret. -Next, you will need to create a Vault policy that allows read access to this secret: +The path to the secret referenced in the `path` resource is the same value that you will configure in the `global.acls.bootstrapToken.secretName` Helm configuration (refer to [Update Consul on Kubernetes Helm chart](#update-consul-on-kubernetes-helm-chart)). @@ -55,8 +54,7 @@ Apply the Vault policy by issuing the `vault policy write` CLI command: $ vault policy write bootstrap-token-policy bootstrap-token-policy.hcl ``` -## Setup per Consul datacenter -### Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access +## Create Vault Authorization Roles for Consul Next, you will create Kubernetes auth roles for the Consul `server-acl-init` container that runs as part of the Consul server statefulset: @@ -75,7 +73,7 @@ you can run the following `helm template` command with your Consul on Kubernetes $ helm template --release-name ${RELEASE_NAME} -s templates/server-acl-init-serviceaccount.yaml hashicorp/consul ``` -### Update the Consul on Kubernetes helm chart +## Update Consul on Kubernetes Helm chart Now that you have configured Vault, you can configure the Consul Helm chart to use the ACL bootstrap token in Vault: diff --git a/website/content/docs/k8s/installation/vault/data-integration/connect-ca.mdx b/website/content/docs/k8s/installation/vault/data-integration/connect-ca.mdx index 121bb3ee2..46f53ec97 100644 --- a/website/content/docs/k8s/installation/vault/data-integration/connect-ca.mdx +++ b/website/content/docs/k8s/installation/vault/data-integration/connect-ca.mdx @@ -14,12 +14,12 @@ Consul allows using Kubernetes auth methods to configure Connect CA. This allows for automatic token rotation once the renewal is no longer possible. ## Overview -To use an Vault as the Service Mesh Certificate Provider on Kubernetes, we will need to modify the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section: +To use Vault as the service mesh certificate provider on Kubernetes, you will complete a modified version of the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section. -### One time setup in Vault +Complete the following steps once: 1. Create a Vault policy that authorizes the desired level of access to the secret. -### Setup per Consul datacenter +Repeat the following steps for each datacenter in the cluster: 1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. 1. Update the Consul on Kubernetes helm chart. @@ -28,20 +28,14 @@ Prior to setting up the data integration between Vault and Consul on Kubernetes, 1. Read and completed the steps in the [Systems Integration](/docs/k8s/installation/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). 2. Read the [Data Integration Overview](/docs/k8s/installation/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). -## One time setup in Vault -### Store the secret in Vault - -This step is not valid to this use case as we are not storing any secrets for Service Mesh certificate, and we instead are Leveraging Vault CA as a provider to mint certificates on an ongoing basis. - -### Create a Vault policy that authorizes the desired level of access to the secret +## Create Vault policy To configure [Vault as the provider](/docs/connect/ca/vault) for the Consul service mesh certificates, you will first need to decide on the type of policy that is suitable for you. To see the permissions that Consul would need in Vault, please see [Vault ACL policies](/docs/connect/ca/vault#vault-acl-policies) documentation. -## Setup per Consul datacenter -### Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access +## Create Vault Authorization Roles for Consul Next, you will create Kubernetes auth roles for the Consul servers: @@ -60,7 +54,7 @@ you can run: $ helm template --release-name ${RELEASE_NAME} --show-only templates/server-serviceaccount.yaml hashicorp/consul ``` -### Update the Consul on Kubernetes helm chart +## Update Consul on Kubernetes Helm chart Now you can configure the Consul Helm chart to use Vault as the Connect CA provider: diff --git a/website/content/docs/k8s/installation/vault/data-integration/enterprise-license.mdx b/website/content/docs/k8s/installation/vault/data-integration/enterprise-license.mdx index 4333a7162..08d7e16f1 100644 --- a/website/content/docs/k8s/installation/vault/data-integration/enterprise-license.mdx +++ b/website/content/docs/k8s/installation/vault/data-integration/enterprise-license.mdx @@ -9,13 +9,13 @@ description: >- This topic describes how to configure the Consul Helm chart to use an enterprise license stored in Vault. ## Overview -To use an enterprise license stored in Vault, we will follow the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section: +Complete the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section to use an enterprise license stored in Vault. -### One time setup in Vault +Complete the following steps once: 1. Store the secret in Vault. 1. Create a Vault policy that authorizes the desired level of access to the secret. -### Setup per Consul datacenter +Repeat the following steps for each datacenter in the cluster: 1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. 1. Update the Consul on Kubernetes helm chart. @@ -24,8 +24,7 @@ Prior to setting up the data integration between Vault and Consul on Kubernetes, 1. Read and completed the steps in the [Systems Integration](/docs/k8s/installation/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). 2. Read the [Data Integration Overview](/docs/k8s/installation/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). -## One time setup in Vault -### Store the Secret in Vault +## Store the Secret in Vault First, store the enterprise license in Vault: @@ -33,11 +32,11 @@ First, store the enterprise license in Vault: $ vault kv put secret/consul/license key="" ``` -### Create a Vault policy that authorizes the desired level of access to the secret +## Create Vault policy --> **Note:** The secret path referenced by the Vault Policy below will be your `global.enterpriseLicense.secretName` Helm value. +Next, you will need to create a policy that allows read access to this secret. -Next, you will need to create a policy that allows read access to this secret: +The path to the secret referenced in the `path` resource is the same value that you will configure in the `global.enterpriseLicense.secretName` Helm configuration (refer to [Update Consul on Kubernetes Helm chart](#update-consul-on-kubernetes-helm-chart)). @@ -55,8 +54,7 @@ Apply the Vault policy by issuing the `vault policy write` CLI command: $ vault policy write license-policy license-policy.hcl ``` -## Setup per Consul datacenter -### Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access +## Create Vault Authorization Roles for Consul Next, you will create Kubernetes auth roles for the Consul server and client: @@ -89,7 +87,7 @@ you can run the following `helm template` commands with your Consul on Kubernete $ helm template --release-name ${RELEASE_NAME} -s templates/client-serviceaccount.yaml hashicorp/consul ``` -### Update the Consul on Kubernetes helm chart. +## Update Consul on Kubernetes Helm chart. Now that you have configured Vault, you can configure the Consul Helm chart to use the enterprise enterprise license in Vault: diff --git a/website/content/docs/k8s/installation/vault/data-integration/gossip.mdx b/website/content/docs/k8s/installation/vault/data-integration/gossip.mdx index 57480a9ec..828b19307 100644 --- a/website/content/docs/k8s/installation/vault/data-integration/gossip.mdx +++ b/website/content/docs/k8s/installation/vault/data-integration/gossip.mdx @@ -7,14 +7,16 @@ description: >- # Storing Gossip Encryption Key in Vault -## Overview -To use a gossip encryption key stored in Vault, we will follow the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section: +This topic describes how to configure the Consul Helm chart to use TLS certificates issued by Vault in the Consul controller and connect inject webhooks. -### One time setup in Vault +## Overview +Complete the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section to use a gossip encryption key stored in Vault. + +Complete the following steps once: 1. Store the secret in Vault. 1. Create a Vault policy that authorizes the desired level of access to the secret. -### Setup per Consul datacenter +Repeat the following steps for each datacenter in the cluster: 1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. 1. Update the Consul on Kubernetes helm chart. @@ -23,18 +25,17 @@ Prior to setting up the data integration between Vault and Consul on Kubernetes, 1. Read and completed the steps in the [Systems Integration](/docs/k8s/installation/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). 2. Read the [Data Integration Overview](/docs/k8s/installation/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). -## One time setup in Vault -### Store the Secret in Vault -First, generate and store the gossip key in Vault: +## Store the Secret in Vault +First, generate and store the gossip key in Vault. You will only need to perform this action once: ```shell-session $ vault kv put secret/consul/gossip key="$(consul keygen)" ``` -### Create a Vault policy that authorizes the desired level of access to the secret +## Create Vault policy --> **Note:** The secret path referenced by the Vault Policy below will be your `global.gossipEncryption.secretName` Helm value. +Next, create a policy that allows read access to this secret. -Next, we will need to create a policy that allows read access to this secret: +The path to the secret referenced in the `path` resource is the same value that you will configure in the `global.gossipEncryption.secretName` Helm configuration (refer to [Update Consul on Kubernetes Helm chart](#update-consul-on-kubernetes-helm-chart)). @@ -52,8 +53,7 @@ Apply the Vault policy by issuing the `vault policy write` CLI command: $ vault policy write gossip-policy gossip-policy.hcl ``` -## Setup per Consul datacenter -### Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access +## Create Vault Authorization Roles for Consul Next, we will create Kubernetes auth roles for the Consul server and client: @@ -86,7 +86,7 @@ you can run the following `helm template` commands with your Consul on Kubernete $ helm template --release-name ${RELEASE_NAME} -s templates/client-serviceaccount.yaml hashicorp/consul ``` -### Update the Consul on Kubernetes helm chart +## Update Consul on Kubernetes Helm chart Now that we've configured Vault, you can configure the Consul Helm chart to use the gossip key in Vault: diff --git a/website/content/docs/k8s/installation/vault/data-integration/index.mdx b/website/content/docs/k8s/installation/vault/data-integration/index.mdx index 5007fcfe9..a7669f549 100644 --- a/website/content/docs/k8s/installation/vault/data-integration/index.mdx +++ b/website/content/docs/k8s/installation/vault/data-integration/index.mdx @@ -13,13 +13,13 @@ This topic describes an overview of how to configure Vault and Consul in order t ### General Integration Steps -Generally, for each secret you wish to store in Vault, the process to integrate the data between Vault and Consul on Kubernetes is: +You must complete two general procedures for each secret you wish to store in Vault. -#### One time setup in Vault +Complete the following steps once: 1. Store the secret in Vault. 1. Create a Vault policy that authorizes the desired level of access to the secret. -#### Setup per Consul datacenter +Repeat the following steps for each datacenter in the cluster: 1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. 1. Update the Consul on Kubernetes helm chart. @@ -31,14 +31,13 @@ Prior to setting up the data integration between Vault and Consul on Kubernetes, Following the general integration steps, a more detailed workflow for integration of the [Gossip encryption key](/docs/k8s/installation/vault/data-integration/gossip) with the Vault Secrets backend would like the following: -#### One time setup in Vault +Complete the following steps once: 1. Store the secret in Vault. - Save the gossip encryption key in Vault at the path `secret/consul/gossip`. 1. Create a Vault policy that authorizes the desired level of access to the secret. - Create a Vault policy that you name `gossip-policy` which allows `read` access to the path `secret/consul/gossip`. -#### Setup per Consul datacenter - +Repeat the following steps for each datacenter in the cluster: 1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. - Both Consul servers and Consul clients need access to the gossip encryption key, so you create two Vault Kubernetes: - A role called `consul-server` that maps the Kubernetes namespace and service account name for your consul servers to the `gossip-policy` created in [step 2](#one-time-setup-in-vault) of One time setup in Vault. diff --git a/website/content/docs/k8s/installation/vault/data-integration/partition-token.mdx b/website/content/docs/k8s/installation/vault/data-integration/partition-token.mdx index 2e7c7e68c..98c764fc5 100644 --- a/website/content/docs/k8s/installation/vault/data-integration/partition-token.mdx +++ b/website/content/docs/k8s/installation/vault/data-integration/partition-token.mdx @@ -10,13 +10,13 @@ description: >- This topic describes how to configure the Consul Helm chart to use an ACL partition token stored in Vault. ## Overview -To use an ACL partition token stored in Vault, we will follow the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section: +Complete the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section to use an ACL partition token stored in Vault. -### One time setup in Vault +Complete the following steps once: 1. Store the secret in Vault. 1. Create a Vault policy that authorizes the desired level of access to the secret. -### Setup per Consul datacenter +Repeat the following steps for each datacenter in the cluster: 1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. 1. Update the Consul on Kubernetes helm chart. @@ -25,20 +25,19 @@ Prior to setting up the data integration between Vault and Consul on Kubernetes, 1. Read and completed the steps in the [Systems Integration](/docs/k8s/installation/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). 2. Read the [Data Integration Overview](/docs/k8s/installation/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). -## One time setup in Vault -### Generate and Store the Secret in Vault +## Store the Secret in Vault -First, generate and store the ACL partition token in Vault: +First, generate and store the ACL partition token in Vault. You will only need to perform this action once: ```shell-session $ vault kv put secret/consul/partition-token token="$(uuidgen | tr '[:upper:]' '[:lower:]')" ``` -### Create a Vault policy that authorizes the desired level of access to the secret +## Create Vault policy --> **Note:** The secret path referenced by the Vault Policy below will be your `global.acls.partitionToken.secretName` Helm value. +Next, you will need to create a policy that allows read access to this secret. -Next, you will need to create a policy that allows read access to this secret: +The path to the secret referenced in the `path` resource is the same value that you will configure in the `global.acls.partitionToken.secretName` Helm configuration (refer to [Update Consul on Kubernetes Helm chart](#update-consul-on-kubernetes-helm-chart)). @@ -56,8 +55,7 @@ Apply the Vault policy by issuing the `vault policy write` CLI command: $ vault policy write partition-token-policy partition-token-policy.hcl ``` -## Setup per Consul datacenter -### Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access +## Create Vault Authorization Roles for Consul Next, you will create Kubernetes auth roles for the Consul `server-acl-init` job: @@ -76,7 +74,7 @@ you can run the following `helm template` command with your Consul on Kubernetes $ helm template --release-name ${RELEASE_NAME} -s templates/server-acl-init-serviceaccount.yaml hashicorp/consul ``` -### Update the Consul on Kubernetes helm chart +## Update Consul on Kubernetes Helm chart Now that you have configured Vault, you can configure the Consul Helm chart to use the ACL partition token key in Vault: diff --git a/website/content/docs/k8s/installation/vault/data-integration/replication-token.mdx b/website/content/docs/k8s/installation/vault/data-integration/replication-token.mdx index ed40fdea5..f17c3fcb7 100644 --- a/website/content/docs/k8s/installation/vault/data-integration/replication-token.mdx +++ b/website/content/docs/k8s/installation/vault/data-integration/replication-token.mdx @@ -9,13 +9,13 @@ description: >- This topic describes how to configure the Consul Helm chart to use an ACL replication token stored in Vault. ## Overview -To use an ACL replication token stored in Vault, we will follow the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section: +To use an ACL replication token stored in Vault, follow the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section. -### One time setup in Vault +Complete the following steps once: 1. Store the secret in Vault. 1. Create a Vault policy that authorizes the desired level of access to the secret. -### Setup per Consul datacenter +Repeat the following steps for each datacenter in the cluster: 1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. 1. Update the Consul on Kubernetes helm chart. @@ -24,20 +24,19 @@ Prior to setting up the data integration between Vault and Consul on Kubernetes, 1. Read and completed the steps in the [Systems Integration](/docs/k8s/installation/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). 2. Read the [Data Integration Overview](/docs/k8s/installation/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). -## One time setup in Vault -### Generate and Store the Secret in Vault +## Store the Secret in Vault -First, generate and store the ACL replication token in Vault: +First, generate and store the ACL replication token in Vault. You will only need to perform this action once: ```shell-session $ vault kv put secret/consul/replication-token token="$(uuidgen | tr '[:upper:]' '[:lower:]')" ``` -### Create a Vault policy that authorizes the desired level of access to the secret +## Create Vault policy --> **Note:** The secret path referenced by the Vault Policy below will be your `global.acls.replicationToken.secretName` Helm value. +Next, you will need to create a policy that allows read access to this secret. -Next, you will need to create a policy that allows read access to this secret: +The path to the secret referenced in the `path` resource is the same value that you will configure in the `global.acls.replicationToken.secretName` Helm configuration (refer to [Update Consul on Kubernetes Helm chart](#update-consul-on-kubernetes-helm-chart)). @@ -55,8 +54,7 @@ Apply the Vault policy by issuing the `vault policy write` CLI command: $ vault policy write replication-token-policy replication-token-policy.hcl ``` -## Setup per Consul datacenter -### Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access +## Create Vault Authorization Roles for Consul Next, you will create Kubernetes auth roles for the Consul `server-acl-init` job: @@ -75,7 +73,7 @@ you can run the following `helm template` command with your Consul on Kubernetes $ helm template --release-name ${RELEASE_NAME} -s templates/server-acl-init-serviceaccount.yaml hashicorp/consul ``` -### Update the Consul on Kubernetes helm chart +## Update Consul on Kubernetes Helm chart Now that you have configured Vault, you can configure the Consul Helm chart to use the ACL replication token key in Vault: diff --git a/website/content/docs/k8s/installation/vault/data-integration/server-tls.mdx b/website/content/docs/k8s/installation/vault/data-integration/server-tls.mdx index 38626c9dd..382a53ed9 100644 --- a/website/content/docs/k8s/installation/vault/data-integration/server-tls.mdx +++ b/website/content/docs/k8s/installation/vault/data-integration/server-tls.mdx @@ -8,12 +8,12 @@ description: >- # Vault as the Server TLS Certificate Provider on Kubernetes ## Overview -To use an Vault as the Server TLS Certificate Provider on Kubernetes, we will need to modify the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section: +To use Vault as the server TLS certificate provider on Kubernetes, complete a modified version of the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section. -### One time setup in Vault +Complete the following steps once: 1. Create a Vault policy that authorizes the desired level of access to the secret. -### Setup per Consul datacenter +Repeat the following steps for each datacenter in the cluster: 1. (Added) Configure allowed domains for PKI certificates 1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. 1. Update the Consul on Kubernetes helm chart. @@ -24,11 +24,10 @@ Prior to setting up the data integration between Vault and Consul on Kubernetes, 2. Read the [Data Integration Overview](/docs/k8s/installation/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). 3. Complete the [Bootstrapping the PKI Engine](#bootstrapping-the-pki-engine) section. -### Bootstrapping the PKI Engine +## Bootstrapping the PKI Engine -First, we need to bootstrap the Vault cluster by enabling and configuring the PKI Secrets Engine to be able to serve -TLS certificates to Consul. The process can be as simple as the following, or more complicated such as in this [example](https://learn.hashicorp.com/tutorials/consul/vault-pki-consul-secure-tls) -which also uses an intermediate signing authority. +Issue the following commands to enable and configure the PKI Secrets Engine to server +TLS certificates to Consul. * Enable the PKI Secrets Engine: @@ -51,142 +50,128 @@ which also uses an intermediate signing authority. common_name="dc1.consul" \ ttl=87600h ``` -## One time setup in Vault -### Store the secret in Vault - -This step is not valid to this use case because we are not storing a single secret. We are configuring Vault as a provider to mint certificates on an ongoing basis. - -### Create a Vault policy that authorizes the desired level of access to the secret +## Create Vault policies To use Vault to issue Server TLS certificates, you will need to create the following: -1. Vault Policies that will allow the Consul server to access the certificate issuing url. -1. Vault Policies that will allow the Consul components, e.g. ingress gateways, controller, to access the CA url. +1. 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. -#### Create Vault Policies for the Server TLS Certificates + The path to the secret referenced in the `path` resource is the same value that you will configure in the `server.serverCert.secretName` Helm configuration (refer to [Update Consul on Kubernetes Helm chart](#update-consul-on-kubernetes-helm-chart)). --> **Note:** The PKI secret path referenced by the Vault Policy below will be your `server.serverCert.secretName` Helm value. + -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. + ```HCL + path "pki/issue/consul-server" { + capabilities = ["create", "update"] + } + ``` - + -```HCL -path "pki/issue/consul-server" { - capabilities = ["create", "update"] -} -``` +1. Apply the Vault policy by issuing the `vault policy write` CLI command: - + ```shell-session + $ vault policy write consul-server consul-server-policy.hcl + ``` -Apply the Vault policy by issuing the `vault policy write` CLI command: - -```shell-session -$ vault policy write consul-server consul-server-policy.hcl -``` - -#### Create Vault Policies for the CA URL - -Next, we will create a policy that allows `["read"]` access to the [CA URL](https://www.vaultproject.io/api/secret/pki#read-certificate), +1. 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. + + The path to the secret referenced in the `path` resource is the same value that you will configure in the `global.tls.caCert.secretName` Helm configuration (refer to [Update Consul on Kubernetes Helm chart](#update-consul-on-kubernetes-helm-chart)). - + -```HCL -path "pki/cert/ca" { - capabilities = ["read"] -} -``` + ```HCL + path "pki/cert/ca" { + capabilities = ["read"] + } + ``` - + -```shell-session -$ vault policy write ca-policy ca-policy.hcl -``` + ```shell-session + $ vault policy write ca-policy ca-policy.hcl + ``` --> **Note:** The PKI secret path referenced by the above Policy will be your `global.tls.caCert.secretName` Helm value. +1. Configure allowed domains for PKI certificates. -## Setup per Consul datacenter -### Configure allowed domains for PKI certificates + Next, a Vault role for the PKI engine will set the default certificate issuance parameters: -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" + ``` -```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" -``` + To generate the `` use the following script as a template: -To generate the `` use the following script as a template: + ```shell-session + #!/bin/sh -```shell-session -#!/bin/sh + # NAME is set to either the value from `global.name` from your Consul K8s value file, or your $HELM_RELEASE_NAME-consul + export NAME=consulk8s + # NAMESPACE is where the Consul on Kubernetes is installed + export NAMESPACE=consul + # DATACENTER is the value of `global.datacenter` from your Helm values config file + export DATACENTER=dc1 -# NAME is set to either the value from `global.name` from your Consul K8s value file, or your $HELM_RELEASE_NAME-consul -export NAME=consulk8s -# NAMESPACE is where the Consul on Kubernetes is installed -export NAMESPACE=consul -# DATACENTER is the value of `global.datacenter` from your Helm values config file -export DATACENTER=dc1 + echo allowed_domains=\"$DATACENTER.consul, $NAME-server, $NAME-server.$NAMESPACE, $NAME-server.$NAMESPACE.svc\" + ``` -echo allowed_domains=\"$DATACENTER.consul, $NAME-server, $NAME-server.$NAMESPACE, $NAME-server.$NAMESPACE.svc\" -``` +1. Finally, Kubernetes auth roles need to be created for servers, clients, and components. -### Link the Vault policies to Consul workloads -Create three Vault auth roles, one for the Consul servers, one for the Consul clients, and one for Consul components, that link the policy to each Consul workload on Kubernetes service account that requires access. + Role for Consul servers: + ```shell-session + $ vault write auth/kubernetes/role/consul-server \ + bound_service_account_names= \ + bound_service_account_namespaces= \ + policies=consul-server \ + ttl=1h + ``` -Role for Consul servers: -```shell-session -$ vault write auth/kubernetes/role/consul-server \ - bound_service_account_names= \ - bound_service_account_namespaces= \ - policies=consul-server \ - ttl=1h -``` + To find out the service account name of the Consul server, + you can run: -To find out the service account name of the Consul server, -you can run: + ```shell-session + $ helm template --release-name ${RELEASE_NAME} --show-only templates/server-serviceaccount.yaml hashicorp/consul + ``` -```shell-session - $ helm template --release-name ${RELEASE_NAME} --show-only templates/server-serviceaccount.yaml hashicorp/consul -``` + Role for Consul clients: -Role for Consul clients: + ```shell-session + $ vault write auth/kubernetes/role/consul-client \ + bound_service_account_names= \ + bound_service_account_namespaces=default \ + policies=ca-policy \ + ttl=1h + ``` -```shell-session -$ vault write auth/kubernetes/role/consul-client \ - bound_service_account_names= \ - bound_service_account_namespaces=default \ - policies=ca-policy \ - ttl=1h -``` + To find out the service account name of the Consul client, use the command below. + ```shell-session + $ helm template --release-name ${RELEASE_NAME} --show-only templates/client-serviceaccount.yaml hashicorp/consul + ``` -To find out the service account name of the Consul client, use the command below. -```shell-session - $ helm template --release-name ${RELEASE_NAME} --show-only templates/client-serviceaccount.yaml hashicorp/consul -``` + Role for CA components: + ```shell-session + $ vault write auth/kubernetes/role/consul-ca \ + bound_service_account_names="*" \ + bound_service_account_namespaces= \ + policies=ca-policy \ + ttl=1h + ``` -Role for CA components: -```shell-session -$ vault write auth/kubernetes/role/consul-ca \ - bound_service_account_names="*" \ - bound_service_account_namespaces= \ - policies=ca-policy \ - ttl=1h -``` + The above Vault Roles will now be your Helm values for `global.secretsBackend.vault.consulServerRole` and + `global.secretsBackend.vault.consulCARole` respectively. -The above Vault Roles will now be your Helm values for `global.secretsBackend.vault.consulServerRole` and -`global.secretsBackend.vault.consulCARole` respectively. +## Update Consul on Kubernetes Helm chart -### Update the Consul on Kubernetes helm chart - -Now that we've configured Vault, you can configure the Consul Helm chart to -use the Server TLS certificates from Vault: +Next, configure the Consul Helm chart to +use the server TLS certificates from Vault: diff --git a/website/content/docs/k8s/installation/vault/data-integration/snapshot-agent-config.mdx b/website/content/docs/k8s/installation/vault/data-integration/snapshot-agent-config.mdx index b8e4a1646..6a0d913cd 100644 --- a/website/content/docs/k8s/installation/vault/data-integration/snapshot-agent-config.mdx +++ b/website/content/docs/k8s/installation/vault/data-integration/snapshot-agent-config.mdx @@ -9,15 +9,13 @@ description: >- This topic describes how to configure the Consul Helm chart to use a snapshot agent config stored in Vault. ## Overview -To use an ACL replication token stored in Vault, we will follow the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section: - -### One time setup in Vault +To use an ACL replication token stored in Vault, follow the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section. +Complete the following steps once: 1. Store the secret in Vault. 1. Create a Vault policy that authorizes the desired level of access to the secret. -### Setup per Consul datacenter - +Repeat the following steps for each datacenter in the cluster: 1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. 1. Update the Consul on Kubernetes helm chart. @@ -26,8 +24,7 @@ Prior to setting up the data integration between Vault and Consul on Kubernetes, 1. Read and completed the steps in the [Systems Integration](/docs/k8s/installation/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). 2. Read the [Data Integration Overview](/docs/k8s/installation/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). -## One time setup in Vault -### Store the Secret in Vault +## Store the Secret in Vault First, store the snapshot agent config in Vault: @@ -35,11 +32,11 @@ First, store the snapshot agent config in Vault: $ vault kv put secret/consul/snapshot-agent-config key="" ``` -### Create a Vault policy that authorizes the desired level of access to the secret +## Create Vault policy --> **Note:** The secret path referenced by the Vault Policy below will be your `client.snapshotAgent.configSecret.secretName` Helm value. +Next, you will need to create a policy that allows read access to this secret. -Next, you will need to create a policy that allows read access to this secret: +The path to the secret referenced in the `path` resource is the same values that you will configure in the `client.snapshotAgent.configSecret.secretName` Helm configuration (refer to [Update Consul on Kubernetes Helm chart](#update-consul-on-kubernetes-helm-chart)). @@ -57,8 +54,7 @@ Apply the Vault policy by issuing the `vault policy write` CLI command: $ vault policy write snapshot-agent-config-policy snapshot-agent-config-policy.hcl ``` -## Setup per Consul datacenter -### Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access +## Create Vault Authorization Roles for Consul Next, you will create a Kubernetes auth role for the Consul snapshot agent: @@ -77,10 +73,10 @@ you can run the following `helm template` command with your Consul on Kubernetes $ helm template --release-name ${RELEASE_NAME} -s templates/client-snapshot-agent-serviceaccount.yaml hashicorp/consul ``` -### Update the Consul on Kubernetes helm chart +## Update Consul on Kubernetes Helm chart Now that you have configured Vault, you can configure the Consul Helm chart to -use the snapshot agent config in Vault: +use the snapshot agent configuration in Vault: diff --git a/website/content/docs/k8s/installation/vault/data-integration/webhook-certs.mdx b/website/content/docs/k8s/installation/vault/data-integration/webhook-certs.mdx index 028ebb496..4615a040c 100644 --- a/website/content/docs/k8s/installation/vault/data-integration/webhook-certs.mdx +++ b/website/content/docs/k8s/installation/vault/data-integration/webhook-certs.mdx @@ -21,7 +21,7 @@ When Vault is configured as the controller and connect inject Webhook Certificat To use Vault as the controller and connect inject Webhook Certificate Provider, we will need to modify the steps outlined in the [Data Integration](/docs/k8s/installation/vault/data-integration) section: -### Setup per Consul datacenter +These following steps will be repeated for each datacenter: 1. Create a Vault policy that authorizes the desired level of access to the secret. 1. (Added) Create Vault PKI roles for controller and connect inject each that establish the domains that each is allowed to issue certificates for. 1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. @@ -33,11 +33,9 @@ Complete the following prerequisites prior to implementing the integration descr 1. You should be familiar with the [Data Integration Overview](/docs/k8s/installation/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/installation/vault). 1. Configure [Vault as the Server TLS Certificate Provider on Kubernetes](/docs/k8s/installation/vault/data-integration/server-tls) 1. Configure [Vault as the Service Mesh Certificate Provider on Kubernetes](/docs/k8s/installation/vault/data-integration/connect-ca) -1. Complete the [Bootstrapping the PKI Engine for Controller and Connect Inject Webhooks](#bootstrapping-the-pki-engine-for-controller-and-connect-inject-webhooks) section. -### Bootstrapping the PKI Engine for Controller and Connect Inject Webhooks - -The first step is to bootstrap the Vault cluster. Issue the following commands to enable and configure the PKI Secrets Engine to serve TLS certificates for the controller and connect inject webhooks: +## Bootstrapping the PKI Engines +Issue the following commands to enable and configure the PKI Secrets Engine to serve TLS certificates for the controller and connect inject webhooks: * Mount the PKI Secrets Engine for each: @@ -72,138 +70,124 @@ The first step is to bootstrap the Vault cluster. Issue the following commands t common_name="-connect-injector" \ ttl=87600h ``` -## Setup per Consul datacenter -You will need to preform the following steps for each datacenter that you would like to manage controller and connect inject webhook certificates in Vault. You will want to take care to create different names per datacenter for every pki mount, role, and policy. +## Create Vault Policies +1. Create a policy that allows `["create", "update"]` access to the +[certificate issuing URL](https://www.vaultproject.io/api/secret/pki#generate-certificate) so Consul controller and connect inject can fetch a new certificate/key pair and provide it to the Kubernetes `mutatingwebhookconfiguration`. -### Create a Vault policy that authorizes the desired level of access to the secret -To use Vault to issue controller or connect inject webhook certificates, you will need to create the Vault policies that will allow either controller or connect inject to access its respective certificate-issuing URL. + The path to the secret referenced in the `path` resource is the same value that you will configure in the `global.secretsBackend.vault.controller.tlsCert.secretName` and `global.secretsBackend.vault.connectInject.tlsCert.secretName` Helm configuration (refer to [Update Consul on Kubernetes Helm chart](#update-consul-on-kubernetes-helm-chart)). -#### Create Vault Policies for the Controller and Connect Inject Webhook Certificates + ```shell-session + $ vault policy write controller-tls-policy - < **Note:** The PKI secret paths referenced by the Vault Policies below will be your `global.secretsBackend.vault.controller.tlsCert.secretName` and `global.secretsBackend.vault.connectInject.tlsCert.secretName` Helm values respectively. + ```shell-session + $ vault policy write connect-inject-policy - <` for each use the following script as a template: + + ```shell-session + #!/bin/sh + + # NAME is set to either the value from `global.name` from your Consul K8s value file, or your $HELM_RELEASE_NAME-consul + export NAME=consulk8s + # NAMESPACE is where the Consul on Kubernetes is installed + export NAMESPACE=consul + # DATACENTER is the value of `global.datacenter` from your Helm values config file + export DATACENTER=dc1 + + echo allowed_domains_controller=\"${NAME}-controller-webhook,${NAME}-controller-webhook.${NAMESPACE},${NAME}-controller-webhook.${NAMESPACE}.svc,${NAME}-controller-webhook.${NAMESPACE}.svc.cluster.local\"" + + echo allowed_domains_connect_inject=\"${NAME}-connect-injector,${NAME}-connect-injector.${NAMESPACE},${NAME}-connect-injector.${NAMESPACE}.svc,${NAME}-connect-injector.${NAMESPACE}.svc.cluster.local\"" + ``` + +1. Finally, Kubernetes auth roles need to be created for controller and connect inject webhooks. -```shell-session -$ vault policy write controller-tls-policy - < \ + bound_service_account_namespaces= \ + policies=controller-ca-policy \ + ttl=1h + ``` --> **Note:** The PKI secret paths referenced by the Vault Policies below will be your `global.secretsBackend.vault.controller.caCert.secretName` and `global.secretsBackend.vault.connectInject.caCert.secretName` Helm values respectively. + To find out the service account name of the Consul controller, + you can run: -Next, create a policy that allows `["read"]` access to the [CA URL](https://www.vaultproject.io/api/secret/pki#read-certificate). The policy is required so that Consul components can communicate with the Consul servers in order to fetch their auto-encryption certificates. Issue the following commands to create the policy: + ```shell-session + $ helm template --release-name ${RELEASE_NAME} --show-only templates/controller-serviceaccount.yaml hashicorp/consul + ``` -```shell-session -$ vault policy write controller-ca-policy - < \ + bound_service_account_namespaces= \ + policies=connect-inject-ca-policy \ + ttl=1h + ``` -Issue the following command to create a Vault role for the controller PKI engine and set the default parameters for issuing certificates: + To find out the service account name of the Consul connect inject, use the command below. + ```shell-session + $ helm template --release-name ${RELEASE_NAME} --show-only templates/connect-inject-serviceaccount.yaml hashicorp/consul + ``` -```shell-session -$ vault write controller/roles/controller-role \ - allowed_domains="" \ - allow_subdomains=true \ - allow_bare_domains=true \ - allow_localhost=true \ - generate_lease=true \ - max_ttl="720h" -``` - -Issue the following command to create a Vault role for the connect inject PKI engine and set the default parameters for issuing certificates: - -```shell-session -$ vault write connect-inject/roles/connect-inject-role \ - allowed_domains="" \ - allow_subdomains=true \ - allow_bare_domains=true \ - allow_localhost=true \ - generate_lease=true \ - max_ttl="720h" -``` - -To generate the `` for each use the following script as a template: - -```shell-session -#!/bin/sh - -# NAME is set to either the value from `global.name` from your Consul K8s value file, or your $HELM_RELEASE_NAME-consul -export NAME=consulk8s -# NAMESPACE is where the Consul on Kubernetes is installed -export NAMESPACE=consul -# DATACENTER is the value of `global.datacenter` from your Helm values config file -export DATACENTER=dc1 - -echo allowed_domains_controller=\"${NAME}-controller-webhook,${NAME}-controller-webhook.${NAMESPACE},${NAME}-controller-webhook.${NAMESPACE}.svc,${NAME}-controller-webhook.${NAMESPACE}.svc.cluster.local\"" - -echo allowed_domains_connect_inject=\"${NAME}-connect-injector,${NAME}-connect-injector.${NAMESPACE},${NAME}-connect-injector.${NAMESPACE}.svc,${NAME}-connect-injector.${NAMESPACE}.svc.cluster.local\"" -``` - -### Create a Vault auth roles that link the policy to each Consul on Kubernetes service account that requires access - --> **Note:** The Vault auth roles below will be your `global.secretsBackend.vault.controllerRole` and `global.secretsBackend.vault.connectInjectRole` Helm values respectively. - - -Finally, Kubernetes auth roles need to be created for controller and connect inject webhooks. - -Role for Consul controller webhooks: -```shell-session -$ vault write auth/kubernetes/role/controller-role \ - bound_service_account_names= \ - bound_service_account_namespaces= \ - policies=controller-ca-policy \ - ttl=1h -``` - -To find out the service account name of the Consul controller, -you can run: - -```shell-session - $ helm template --release-name ${RELEASE_NAME} --show-only templates/controller-serviceaccount.yaml hashicorp/consul -``` - -Role for Consul connect inject webhooks: - -```shell-session -$ vault write auth/kubernetes/role/connect-inject-role \ - bound_service_account_names= \ - bound_service_account_namespaces= \ - policies=connect-inject-ca-policy \ - ttl=1h -``` - -To find out the service account name of the Consul connect inject, use the command below. -```shell-session - $ helm template --release-name ${RELEASE_NAME} --show-only templates/connect-inject-serviceaccount.yaml hashicorp/consul -``` - -### Update the Consul on Kubernetes helm chart +## Update Consul on Kubernetes Helm chart Now that we've configured Vault, you can configure the Consul Helm chart to use the Server TLS certificates from Vault: diff --git a/website/content/docs/k8s/installation/vault/systems-integration.mdx b/website/content/docs/k8s/installation/vault/systems-integration.mdx index 02e01b971..a48bcdb45 100644 --- a/website/content/docs/k8s/installation/vault/systems-integration.mdx +++ b/website/content/docs/k8s/installation/vault/systems-integration.mdx @@ -8,24 +8,20 @@ description: >- # Vault as the Secrets Backend - Systems Integration ## Overview -At a high level, configuring a systems integration of Vault with Consul on Kubernetes consists of 1) a one time setup on Vault and 2) a setup of the secrets backend per Consul datacenter via Helm. +Integrating Vault with Consul on Kubernetes includes a one-time setup on Vault and setting up the secrets backend for each Consul datacenter via Helm. -### One time setup on Vault +Complete the following steps once: - Enabling Vault KV Secrets Engine - Version 2 to store arbitrary secrets - Enabling Vault PKI Engine if you are choosing to store and manage either [Consul Server TLS credentials](/docs/k8s/installation/vault/data-integration/server-tls) or [Service Mesh and Consul client TLS credentials](/docs/k8s/installation/vault/data-integration/connect-ca) -### Setup per Consul datacenter +Repeat the following steps for each datacenter in the cluster: - Installing the Vault Injector within the Consul datacenter installation - Configuring a Kubernetes Auth Method in Vault to authenticate and authorize operations from the Consul datacenter - Enable Vault as the Secrets Backend in the Consul datacenter -## One time setup on Vault - -A one time setup on a Vault deployment is necessary to enable both the Vault KV Secrets Engine and the Vault PKI Engine. These docs assume that you have already setup a Vault cluster for use with Consul on Kubernetes. - Please read [Run Vault on Kubernetes](https://www.vaultproject.io/docs/platform/k8s/helm/run) if instructions on setting up a Vault cluster are needed. -### Vault KV Secrets Engine - Version 2 +## Vault KV Secrets Engine - Version 2 The following secrets can be stored in Vault KV secrets engine, which is meant to handle arbitrary secrets: - ACL Bootstrap token ([`global.acls.bootstrapToken`](/docs/k8s/helm#v-global-acls-bootstraptoken)) @@ -41,7 +37,7 @@ In order to store any of these secrets, we must enable the [Vault KV secrets eng $ vault secrets enable -path=consul kv-v2 ``` -### Vault PKI Engine +## Vault PKI Engine The Vault PKI Engine must be enabled in order to leverage Vault for issuing Consul Server TLS certificates. More details for configuring the PKI Engine is found in [Bootstrapping the PKI Engine](/docs/k8s/installation/vault/data-integration/server-tls#bootstrapping-the-pki-engine) under the Server TLS section. @@ -49,61 +45,83 @@ The Vault PKI Engine must be enabled in order to leverage Vault for issuing Cons $ vault secrets enable pki ``` -## Setup per Consul datacenter - -After configuring Vault, Consul datacenters on Kubernetes must be deployed with the Vault Agent injector and configured to leverage the Vault Kubernetes Auth Method to read secrets from a Vault cluster. - -### Set Environment Variables to ensure integration consistency +## Set Environment Variables Before installing the Vault Injector and configuring the Vault Kubernetes Auth Method, some environment variables need to be set to better ensure consistent mapping between Vault and Consul on Kubernetes. -#### DATACENTER - - - **Recommended value:** value of `global.datacenter` in your Consul Helm values file. - ```shell-session - $ export DATACENTER=dc1 - ``` -#### VAULT_AUTH_METHOD_NAME - - - **Recommended value:** a concatenation of a `kubernetes-` prefix (to denote the auth method type) with `DATACENTER` environment variable. - ```shell-session - $ export VAULT_AUTH_METHOD_NAME=kubernetes-${DATACENTER} - ``` + - DATACENTER -#### VAULT_SERVER_HOST + We recommend using the value for `global.datacenter` in your Consul Helm values file for this variable. + ```shell-session + $ export DATACENTER=dc1 + ``` - - **Recommended value:** find the external IP address of your Vault cluster. - - If Vault is installed in a Kubernetes cluster, get the external IP or DNS name of the Vault server load balancer. - - On GKE or AKS, it'll be an IP: - ```shell-session - $ export VAULT_SERVER_HOST=$(kubectl get svc vault-dc1 -o jsonpath='{.status.loadBalancer.ingress[0].ip}') - ``` - - On EKS, it'll be a hostname: - ```shell-session - $ export VAULT_SERVER_HOST=$(kubectl get svc vault-dc1 -o jsonpath='{.status.loadBalancer.ingress[0].hostname}') - ``` - - If Vault is not running on Kubernetes, utilize the `api_addr` as defined in the Vault [High Availability Parameters](https://www.vaultproject.io/docs/configuration#high-availability-parameters) configuration: - ```shell-session - $ export VAULT_SERVER_HOST= - ``` + - VAULT_AUTH_METHOD_NAME + + We recommend using a concatenation of a `kubernetes-` prefix (to denote the auth method type) with the `DATACENTER` environment variable for this variable. + ```shell-session + $ export VAULT_AUTH_METHOD_NAME=kubernetes-${DATACENTER} + ``` -#### VAULT_ADDR + - VAULT_SERVER_HOST + + We recommend using the external IP address of your Vault cluster for this variable. + + If Vault is installed in a Kubernetes cluster, get the external IP or DNS name of the Vault server load balancer. + + + + On EKS, you can get the hostname of the Vault server's load balancer with the following command: - - **Recommended value:** Connecting to port 8200 of the Vault server + ```shell-session + $ export VAULT_SERVER_HOST=$(kubectl get svc vault-dc1 -o jsonpath='{.status.loadBalancer.ingress[0].hostname}') + ``` + + + + + + On GKE, you can get the IP address of the Vault server's load balancer with the following command: + + ```shell-session + $ export VAULT_SERVER_HOST=$(kubectl get svc vault-dc1 -o jsonpath='{.status.loadBalancer.ingress[0].ip}') + ``` + + + + + + On AKS, you can get the IP address of the Vault server's load balancer with the following command: + + ```shell-session + $ export VAULT_SERVER_HOST=$(kubectl get svc vault-dc1 --output jsonpath='{.status.loadBalancer.ingress[0].ip}') + ``` + + + + + If Vault is not running on Kubernetes, utilize the `api_addr` as defined in the Vault [High Availability Parameters](https://www.vaultproject.io/docs/configuration#high-availability-parameters) configuration: + ```shell-session + $ export VAULT_SERVER_HOST= + ``` + + - VAULT_AUTH_METHOD_NAME + + We recommend connecting to port 8200 of the Vault server. ```shell-session $ export VAULT_ADDR=http://${VAULT_SERVER_HOST}:8200 ``` - -> **Note:** If your vault installation is current exposed using SSL, this address will need to use `https` instead of `http`. You will also need to setup the [`VAULT_CACERT`](https://www.vaultproject.io/docs/commands#vault_cacert) environment variable. + If your vault installation is current exposed using SSL, this address will need to use `https` instead of `http`. You will also need to setup the [`VAULT_CACERT`](https://www.vaultproject.io/docs/commands#vault_cacert) environment variable. -#### VAULT_TOKEN - - - **Recommended value:** Your allocated Vault token. If running Vault in dev mode, this can be set to to `root`. + - VAULT_TOKEN + + We recommend using your allocated Vault token as the value for this variable. If running Vault in dev mode, this can be set to to `root`. ```shell-session - $ export VAULT_ADDR= + $ export VAULT_TOKEN= ``` -### Install Vault Injector in your Consul k8s cluster +## Install Vault Injector in Consul k8s cluster 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 with the [`injector.externalVaultAddr`](https://www.vaultproject.io/docs/platform/k8s/helm/configuration#externalvaultaddr) value in the Vault Helm Configuration. @@ -125,9 +143,7 @@ Issue the Helm `install` command to install the Vault agent injector using the H $ helm install vault-${DATACENTER} -f vault-injector.yaml hashicorp/vault --wait ``` -### Configure the Kubernetes Auth Method in Vault for the datacenter - -#### Enable the Auth Method +## Configure the Kubernetes Auth Method in Vault Ensure that the Vault Kubernetes Auth method is enabled. @@ -135,8 +151,6 @@ Ensure that the Vault Kubernetes Auth method is enabled. $ vault auth enable -path=kubernetes-${DATACENTER} kubernetes ``` -#### Configure Auth Method with JWT token of service account - After enabling the Kubernetes auth method, in Vault, ensure that you have configured the Kubernetes Auth method properly as described in [Kubernetes Auth Method Configuration](https://www.vaultproject.io/docs/auth/kubernetes#configuration). First, while targeting your Consul cluster, get the externally reachable address of the Consul Kubernetes cluster. @@ -157,7 +171,7 @@ $ vault write auth/kubernetes/config \ kubernetes_ca_cert=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt ``` -#### Enable Vault as the Secrets Backend in the Consul datacenter +## Update Vault Helm chart Finally, you will configure the Consul on Kubernetes helm chart for the datacenter to expect to receive the following values (if you have configured them) to be retrieved from Vault: - ACL Bootstrap token ([`global.acls.bootstrapToken`](/docs/k8s/helm#v-global-acls-bootstraptoken)) - ACL Partition token ([`global.acls.partitionToken`](/docs/k8s/helm#v-global-acls-partitiontoken)) diff --git a/website/content/docs/k8s/installation/vault/wan-federation.mdx b/website/content/docs/k8s/installation/vault/wan-federation.mdx index b454dbec7..37a13d64e 100644 --- a/website/content/docs/k8s/installation/vault/wan-federation.mdx +++ b/website/content/docs/k8s/installation/vault/wan-federation.mdx @@ -78,7 +78,7 @@ In this setup, you will deploy Vault server in the primary datacenter (dc1) Kube - On EKS, you can get the IP address of the Vault server's load balancer with the following command: + On EKS, you can get the hostname of the Vault server's load balancer with the following command: ```shell-session $ export VAULT_SERVER_HOST=$(kubectl get svc vault-dc1 -o jsonpath='{.status.loadBalancer.ingress[0].hostname}') @@ -114,17 +114,18 @@ In this setup, you will deploy Vault server in the primary datacenter (dc1) Kube ``` ## Systems Integration -### Overview -To use Vault as the Service Mesh Certificate Provider in Kubernetes, you must complete following systems integration actions: +There are two main procedures to enable Vault as the service mesh certificate provider in Kubernetes. -- One time setup in Vault +Complete the following steps once: 1. Enabling Vault KV Secrets Engine - Version 2. 1. Enabling Vault PKI Engine. -- Setup per Consul datacenter + +Repeat the following steps for each datacenter in the cluster: 1. Installing the Vault Injector within the Consul datacenter installation 1. Configuring a Kubernetes Auth Method in Vault to authenticate and authorize operations from the Consul datacenter 1. Enable Vault as the Secrets Backend in the Consul datacenter -### One time setup on Vault + +### Configure Vault Secrets engines 1. Enable [Vault KV secrets engine - Version 2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) in order to store the [Gossip Encryption Key](/docs/k8s/helm#v-global-acls-replicationtoken) and the ACL Replication token ([`global.acls.replicationToken`](/docs/k8s/helm#v-global-acls-replicationtoken)). ```shell-session @@ -141,8 +142,7 @@ To use Vault as the Service Mesh Certificate Provider in Kubernetes, you must co $ vault secrets tune -max-lease-ttl=87600h pki ``` -### Setup per Consul datacenter -#### Primary Datacenter (dc1) +### Primary Datacenter (dc1) 1. Install the Vault Injector in your Consul Kubernetes cluster (dc1), which is used for accessing secrets from Vault. -> **Note**: In the primary datacenter (dc1), you will not have to configure `injector.externalvaultaddr` value because the Vault server is in the same primary datacenter (dc1) cluster. @@ -198,7 +198,7 @@ To use Vault as the Service Mesh Certificate Provider in Kubernetes, you must co -#### Secondary Datacenter (dc2) +### Secondary Datacenter (dc2) 1. Install the Vault Injector in the secondary datacenter (dc2). In the secondary datacenter (dc2), you will configure the `externalvaultaddr` value point to the external address of the Vault server in the primary datacenter (dc1). @@ -300,18 +300,17 @@ To use Vault as the Service Mesh Certificate Provider in Kubernetes, you must co ## Data Integration -### Overview -To use Vault as the Service Mesh Certificate Provider in Kubernetes, you must complete following data integration actions: +There are two main procedures for using Vault as the service mesh certificate provider in Kubernetes. - -- One time setup in Vault +Complete the following steps once: 1. Store the secrets in Vault. 1. Create a Vault policy that authorizes the desired level of access to the secrets. -- Setup per Consul datacenter + +Repeat the following steps for each datacenter in the cluster: 1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. 1. Update the Consul on Kubernetes helm chart. -### One time setup in Vault +### Secrets and Policies 1. Store the ACL Replication Token, Gossip Encryption Key, and Root CA certificate secrets in Vault. ```shell-session @@ -351,13 +350,12 @@ To use Vault as the Service Mesh Certificate Provider in Kubernetes, you must co EOF ``` -### Setup per Consul datacenter -#### Pre-installation for Primary Datacenter (dc1) +### Pre-installation for Primary Datacenter (dc1) 1. Change your Kubernetes context to target the primary datacenter (dc1): ```shell-session $ kubectl config use-context ``` -#### Primary Datacenter (dc1) +### Primary Datacenter (dc1) 1. Create Server TLS and Service Mesh Cert Policies ```shell-session @@ -491,7 +489,7 @@ To use Vault as the Service Mesh Certificate Provider in Kubernetes, you must co $ helm install consul-dc1 --values consul-dc1.yaml hashicorp/consul ``` -#### Pre-installation for Secondary Datacenter (dc2) +### Pre-installation for Secondary Datacenter (dc2) 1. Update the Consul on Kubernetes helm chart. For secondary datacenter (dc2), you will need to get the address of the mesh gateway from the **primary datacenter (dc1)** cluster. Keep your Kubernetes context targeting dc1 and set the `MESH_GW_HOST` environment variable that you will use in the Consul Helm chart for secondary datacenter (dc2). @@ -532,7 +530,7 @@ To use Vault as the Service Mesh Certificate Provider in Kubernetes, you must co ```shell-session $ kubectl config use-context ``` -#### Secondary Datacenter (dc2) +### Secondary Datacenter (dc2) 1. Create Server TLS and Service Mesh Cert Policies