diff --git a/website/content/docs/platform/k8s/helm/examples/ha-tls.mdx b/website/content/docs/platform/k8s/helm/examples/ha-tls.mdx new file mode 100644 index 000000000000..46fa12b47bc0 --- /dev/null +++ b/website/content/docs/platform/k8s/helm/examples/ha-tls.mdx @@ -0,0 +1,100 @@ +--- +layout: 'docs' +page_title: 'HA Cluster with Raft and TLS' +sidebar_current: 'docs-platform-k8s-examples-ha-tls' +description: |- + Describes how to set up a Raft HA Vault cluster with TLS certificate +--- + +# HA Cluster with Raft and TLS + +The overview for [Integrated Storage and +TLS](/vault/docs/concepts/integrated-storage#integrated-storage-and-tls) covers +the various options for mitigating TLS verification warnings and bootstrapping +your Raft cluster. + +Without proper configuration, you will see the following warning before cluster +initialization: +```shell +core: join attempt failed: error="error during raft bootstrap init call: Put "https://vault-${N}.${SERVICE}:8200/v1/sys/storage/raft/bootstrap/challenge": x509: certificate is valid for ${SERVICE}, ${SERVICE}.${NAMESPACE}, ${SERVICE}.${NAMESPACE}.svc, ${SERVICE}.${NAMESPACE}.svc.cluster.local, not vault-${N}.${SERVICE}" +``` + +The examples below demonstrate two specific solutions. Both solutions ensure +that the common name (CN) used for the `leader_api_addr` in the Raft stanza +matches the name(s) listed in the TLS certificate. + +## Before you start + +1. Follow the steps from the example [HA Vault Cluster with Integrated +Storage](/vault/docs/platform/k8s/helm/examples/ha-with-raft) to build the cluster. + +2. Follow the examples and instructions in [Standalone Server with +TLS](/vault/docs/platform/k8s/helm/examples/standalone-tls) to create a TLS +certificate. + +## Solution 1: Use auto-join and set the TLS server in your Raft configuration + +The join warning disappears if you use auto-join and set the expected TLS +server name (`${CN}`) with +[`leader_tls_servername`](/vault/docs/configuration/storage/raft#leader_tls_servername) +in the Raft stanza for your Vault configuration. + +For example: + + +```hcl +storage "raft" { + path = "/vault/data" + + retry_join { + leader_api_addr = "https://vault-0.${SERVICE}:8200" + leader_tls_servername = "${CN}" + leader_client_cert_file = "/vault/tls/vault.crt" + leader_client_key_file = "/vault/tls/vault.key" + leader_ca_cert_file = "/vault/tls/vault.ca" + } + + retry_join { + leader_api_addr = "https://vault-1.${SERVICE}:8200" + leader_tls_servername = "${CN}" + leader_client_cert_file = "/vault/tls/vault.crt" + leader_client_key_file = "/vault/tls/vault.key" + leader_ca_cert_file = "/vault/tls/vault.ca" + } + + retry_join { + leader_api_addr = "https://vault-2.${SERVICE}:8200" + leader_tls_servername = "${CN}" + leader_client_cert_file = "/vault/tls/vault.crt" + leader_client_key_file = "/vault/tls/vault.key" + leader_ca_cert_file = "/vault/tls/vault.ca" + } +} +``` + + + +## Solution 2: Add a load balancer to your Raft configuration + +If you have a load balancer for your Vault cluster, you can add a single +`retry_join` stanza to your Raft configuration and use the load balancer +address for `leader_api_addr`. + +For example: + + +```hcl +storage "raft" { + path = "/vault/data" + + retry_join { + leader_api_addr = "https://vault-active:8200" + leader_client_cert_file = "/vault/tls/vault.crt" + leader_client_key_file = "/vault/tls/vault.key" + leader_ca_cert_file = "/vault/tls/vault.ca" + } +} +``` + + + diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 6666feb6e9fb..30140572feac 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1783,6 +1783,10 @@ "title": "HA Cluster with Raft", "path": "platform/k8s/helm/examples/ha-with-raft" }, + { + "title": "HA Cluster with Raft and TLS", + "path": "platform/k8s/helm/examples/ha-tls" + }, { "title": "HA Enterprise Cluster with Raft", "path": "platform/k8s/helm/examples/enterprise-with-raft"