78 lines
4.5 KiB
Plaintext
78 lines
4.5 KiB
Plaintext
|
---
|
||
|
|
layout: docs
|
||
|
|
page_title: Vault as Secrets Backend Overview
|
||
|
|
description: >-
|
||
|
|
Using Vault as secrets backend for Consul on Kubernetes.
|
||
|
|
---
|
||
|
|
|
||
|
|
# Vault as Secrets Backend Overview
|
||
|
|
|
||
|
|
By default, Consul Helm chart will expect that any credentials it needs are stored as Kubernetes secrets.
|
||
|
|
As of Consul 1.11 and Consul Helm chart v0.38.0, we integrate more natively with Vault making it easier
|
||
|
|
to use Consul Helm chart with Vault as the secrets storage backend.
|
||
|
|
|
||
|
|
At a high level, there are two points of integration with Vault:
|
||
|
|
- **Gossip encryption** - The encryption key for gossip communication is stored in Vault.
|
||
|
|
- **TLS certificates and keys**:
|
||
|
|
- **Consul Server TLS credentials** - TLS certificate and key for the Consul server is stored in Vault and issued from Vault.
|
||
|
|
- **Service Mesh and Consul client TLS credentials** - Consul uses Vault as the provider for mTLS certificates and keys for the service mesh services
|
||
|
|
and TLS certificates and keys for the Consul clients.
|
||
|
|
|
||
|
|
## Requirements
|
||
|
|
|
||
|
|
1. Vault 1.9+ and Vault-k8s 0.14+ is required.
|
||
|
|
1. Vault must be installed and accessible to the Consul on Kubernetes installation.
|
||
|
|
1. `global.tls.enableAutoencrypt=true` is required if TLS is enabled for the Consul installation when using the Vault secrets backend.
|
||
|
|
1. The Vault installation must have been initialized, unsealed and the KV2 and PKI secrets engines enabled and the Kubernetes Auth Method enabled.
|
||
|
|
|
||
|
|
A minimal valid installation of Vault must include the Agent Injector:
|
||
|
|
```yaml
|
||
|
|
injector:
|
||
|
|
enabled: "true"
|
||
|
|
```
|
||
|
|
|
||
|
|
## Known Limitations
|
||
|
|
|
||
|
|
- TLS
|
||
|
|
- `global.tls.serverAdditionalDNSSans` is not currently configurable and must be manually added to the server certificate in Vault.
|
||
|
|
- `global.tls.serverAdditionalIPSans` is not currently configurable and must be manually added to the server certificate in Vault.
|
||
|
|
- Mesh gateway is not currently supported.
|
||
|
|
- Multi-DC Federation is not currently supported.
|
||
|
|
- Certificate rotation is not currently supported, ensure the TTL for your certificates is sufficiently long. Should your certificates
|
||
|
|
expire it will be necessary to issue a `consul reload` on each server.
|
||
|
|
- CA rotation is not currently supported.
|
||
|
|
|
||
|
|
## Next Steps
|
||
|
|
|
||
|
|
To utilize Vault as a secrets backend with Consul it is necessary to add several configuration fields to the Vault installation
|
||
|
|
which bootstrap Vault Auth roles and Policies for Consul to use. For the supported Vault secrets please see the individual secret
|
||
|
|
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 \
|
||
|
|
bound_service_account_names=<Consul server service account> \
|
||
|
|
bound_service_account_namespaces=<Consul installation namespace> \
|
||
|
|
policies=gossip-policy,consul-ca,consul-server \
|
||
|
|
ttl=1h
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
## Troubleshooting
|
||
|
|
|
||
|
|
The Vault integration with Consul on Kubernetes makes use of the Vault Agent Injectors. Kubernetes annotations are added to the
|
||
|
|
deployments of the Consul components which cause the Vault Agent Injector to be added as an init-container that will then attach
|
||
|
|
Vault secrets to Consul's pods at startup. Additionally the Vault Agent sidecar is added to the Consul component pods which
|
||
|
|
is responsible for synchronizing and reissuing secrets at runtime.
|
||
|
|
As a result of these additional sidecar containers the typical location for logging is expanded in the Consul components.
|
||
|
|
|
||
|
|
As a general rule the best way to troubleshoot startup issues for your Consul installation when using the Vault integration
|
||
|
|
is to establish if the `vault-agent-init` container has completed or not via `kubectl logs -f <your-consul-component> -c vault-agent-int`
|
||
|
|
and checking to see if the secrets have completed rendering.
|
||
|
|
* If the secrets are not properly rendered the underlying problem will be logged in `vault-agent-init` init-container
|
||
|
|
and generally is related to the Vault Kube Auth Role not having the correct policies for the specific secret
|
||
|
|
e.g. `global.secretsBackend.vault.consulServerRole` not having the correct policies for TLS.
|
||
|
|
* If the secrets are rendered and the `vault-agent-init` container has completed AND the Consul component has not become `Ready`,
|
||
|
|
this generally points to an issue with Consul being unable to utilize the Vault secret. This can occur if, for example, the Vault Role
|
||
|
|
created for the PKI engine does not have the correct `alt_names` or otherwise is not properly configured. The best logs for this
|
||
|
|
circumstance are the Consul container logs: `kubectl logs -f <your-consul-component> -c consul`.
|