~> **Note**: This topic requires familiarity with [Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters), [WAN Federation Via Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways).
This page describes how you can federate multiple Kubernetes clusters using Vault as the secrets backend. See the [Multi-Cluster Overview](/consul/docs/k8s/deployment-configurations/multi-cluster) for more information on use cases and how it works.
The [Federation Between Kubernetes Clusters](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes) page provides an overview of WAN Federation using Mesh Gateways with Kubernetes secrets as the secret backend. When using Vault as the secrets backend, there are different systems and data integration configuration that will be explained in the [Usage](#usage) section of this page. The other main difference is that when using Vault, there is no need for you to export and import a [Federation Secret](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes#federation-secret) in each datacenter.
The expected use case is to create WAN Federation on Kubernetes clusters. The following procedure results in a WAN Federation with Vault as the secrets backend between two clusters, dc1 and dc2. dc1 acts as the primary Consul cluster and also contains the Vault server installation. dc2 is the secondary Consul cluster.
![Consul on Kubernetes with Vault as the Secrets Backend](/img/k8s/consul-vault-wan-federation-topology.svg 'Consul on Kubernetes with Vault as the Secrets Backend')
The Vault Injectors in each cluster will ensure that every pod in cluster has a Vault agent inject into the pod.
![Vault Injectors inject Vault agents into pods](/img/k8s/consul-vault-wan-federation-vault-injector.svg 'Vault Injectors inject Vault agents into pods')
The Vault Agents on each Consul pod will communicate directly with Vault on its externally accessible endpoint. Consul pods are also configured with Vault annotations that configure the secrets that the pod needs as well as the path that the Vault agent should locally store those secrets.
![Vault agent and server communication](/img/k8s/consul-vault-wan-federation-vault-communication.svg 'Vault agent and server communication')
The two data centers will federated using mesh gateways. This communication topology is also described in the [WAN Federation Via Mesh Gateways](/consul/docs/k8s/deployment-configurations/multi-cluster#wan-federation-via-mesh-gateways) section of [Multi-Cluster Federation Overview](/consul/docs/k8s/deployment-configurations/multi-cluster).
![Mesh Federation via Mesh Gateways](/img/k8s/consul-vault-wan-federation-mesh-communication.svg 'Mesh Federation via Mesh Gateways')
### Install Vault
In this setup, you will deploy Vault server in the primary datacenter (dc1) Kubernetes cluster, which is also the primary Consul datacenter. You will configure your Vault Helm installation in the secondary datacenter (dc2) Kubernetes cluster to use it as an external server. This way there will be a single vault server cluster that will be used by both Consul datacenters.
~> **Note**: For demonstration purposes, the following example deploys a Vault server in dev mode. Do not use dev mode for production installations. Refer to the [Vault Deployment Guide](/vault/tutorials/day-one-raft/raft-deployment-guide) for guidance on how to install Vault in a production setting.
1. Install Consul locally so that you can generate the gossip key. Please see the [Precompiled Binaries](/consul/docs/install#precompiled-binaries) section of the [Install Consul page](/consul/docs/install#precompiled-binaries).
1. Enable [Vault KV secrets engine - Version 2](/vault/docs/secrets/kv/kv-v2) in order to store the [Gossip Encryption Key](/consul/docs/k8s/helm#v-global-acls-replicationtoken) and the ACL Replication token ([`global.acls.replicationToken`](/consul/docs/k8s/helm#v-global-acls-replicationtoken)).
-> **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.
Because Consul is in the same datacenter cluster as Vault, the Vault Auth Method can use its own CA Cert and JWT to authenticate Consul dc1 service account requests. Therefore, you do not need to set `token_reviewer` and `kubernetes_ca_cert` on the dc1 Kubernetes Auth Method.
1. Enable Vault as the secrets backend in the primary datacenter (dc1). However, you will not yet apply the Helm install command. You will issue the Helm upgrade command after the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/wan-federation#setup-per-consul-datacenter-1) section.
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).
1. Create a service account with access to the Kubernetes API in the secondary datacenter (dc2). For the secondary datacenter (dc2) auth method, you first need to create a service account that allows the Vault server in the primary datacenter (dc1) cluster to talk to the Kubernetes API in the secondary datacenter (dc2) cluster.
1. Configure the auth method with the JWT token of service account. First, get the externally reachable address of the secondary Consul datacenter (dc2) in the secondary Kubernetes cluster. Then set `kubernetes_host` in the auth method configuration.
1. Enable Vault as the secrets backend in the secondary Consul datacenter (dc2). However, you will not yet apply the Helm install command. You will issue the Helm upgrade command after the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/wan-federation#setup-per-consul-datacenter-1) section.
1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. For each auth method in Vault, you will need roles for the Consul server, Consul client, the `server-acl-init` job, and Consul server CA.
1. Update the Consul on Kubernetes Helm chart. For secondary datacenter (dc2), you 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).
```shell-session
$ kubectl config use-context <context for dc1>
```
Next, get mesh gateway address:
<Tabs>
<Tab heading="EKS">
```shell-session
$ export MESH_GW_HOST=$(kubectl get svc consul-mesh-gateway --output jsonpath='{.status.loadBalancer.ingress[0].hostname}')
```
</Tab>
<Tab heading="GKE">
```shell-session
$ export MESH_GW_HOST=$(kubectl get svc consul-mesh-gateway --output jsonpath='{.status.loadBalancer.ingress[0].ip}')
```
</Tab>
<Tab heading="AKS">
```shell-session
$ export MESH_GW_HOST=$(kubectl get svc consul-mesh-gateway --output jsonpath='{.status.loadBalancer.ingress[0].ip}')
```
</Tab>
</Tabs>
1. Change your Kubernetes context to target the primary datacenter (dc2):
1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access. For each auth method in Vault, you will need roles for the Consul server, Consul client, the server-acl-init job, and Consul server CA.
-> **Note**: To configure Vault as the service mesh (connect) CA in secondary datacenters, you need to make sure that the Root CA path is the same. The intermediate path is different for each datacenter. In the `connectCA` Helm configuration for a secondary datacenter, you can specify a `intermediatePKIPath` that is, for example, prefixed with the datacenter for which this configuration is intended (e.g. `dc2/connect-intermediate`).
You have completed the process of federating the secondary datacenter (dc2) with the primary datacenter (dc1) using Vault as the Secrets backend. To validate that everything is configured properly, please confirm that all pods within both datacenters are in a running state.
For additional information about specific Consul secrets that you can store in Vault, refer to [Data Integration](/consul/docs/k8s/deployment-configurations/vault/data-integration) in the [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault) documentation.