Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Backport of Feature/document tls servername into release/1.14.x #23023

Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
@@ -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"