Skip to content

Commit

Permalink
Feature/document tls servername (hashicorp#22714)
Browse files Browse the repository at this point in the history
* Add Raft TLS Helm examples

Co-authored-by: Pascal Reeb <[email protected]>
---------
  • Loading branch information
Andreas Gruhler authored Sep 12, 2023
1 parent 5a83838 commit c63a84d
Show file tree
Hide file tree
Showing 2 changed files with 104 additions and 0 deletions.
100 changes: 100 additions & 0 deletions website/content/docs/platform/k8s/helm/examples/ha-tls.mdx
Original file line number Diff line number Diff line change
@@ -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:
<CodeBlockConfig highlight="6,14,22">

```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"
}
}
```

</CodeBlockConfig>

## 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:
<CodeBlockConfig highlight="5">

```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"
}
}
```

</CodeBlockConfig>

4 changes: 4 additions & 0 deletions website/data/docs-nav-data.json
Original file line number Diff line number Diff line change
Expand Up @@ -1796,6 +1796,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"
Expand Down

0 comments on commit c63a84d

Please sign in to comment.