consul/website/content/docs/k8s/deployment-configurations/vault/data-integration/index.mdx

---
layout: docs
page_title: Vault as the Secrets Backend Data Integration Overview
description: >-
  Overview of the data integration aspects to using Vault as the secrets backend for Consul on Kubernetes.
---

# Vault as the Secrets Backend - Data Integration

This topic describes how to configure Vault and Consul in order to share secrets for use within Consul.

## Prerequisites

Before you set up the data integration between Vault and Consul on Kubernetes, read and complete the steps in the [Systems Integration](/consul/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault).

## General integration steps

For each secret you want to store in Vault, you must complete two multi-step procedures.

Complete the following steps once:
  1. Store the secret in Vault.
  1. Create a Vault policy that authorizes the desired level of access to the secret.

Repeat the following steps for each datacenter in the cluster:
  1. Create Vault Kubernetes auth roles that link the policy to each Consul on Kubernetes service account that requires access.
  1. Update the Consul on Kubernetes Helm chart.

## Secrets-to-service account mapping

At the most basic level, the goal of this configuration is to authorize a Consul on Kubernetes service account to access a secret in Vault.

The following table associates Vault secrets and the Consul on Kubernetes service accounts that require access.
(NOTE: `Consul components` refers to all other services and jobs that are not Consul servers or clients.
It includes things like terminating gateways, ingress gateways, etc.)

### Primary datacenter

| Secret | Service Account For | Configurable Role in Consul k8s Helm |
| ------ | ------------------- | ------------------------------------ |
|[ACL Bootstrap token](/consul/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token) | Consul server-acl-init job | [`global.secretsBackend.vault.manageSystemACLsRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)|
|[ACL Partition token](/consul/docs/k8s/deployment-configurations/vault/data-integration/partition-token) | Consul server-acl-init job | [`global.secretsBackend.vault.manageSystemACLsRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)|
|[ACL Replication token](/consul/docs/k8s/deployment-configurations/vault/data-integration/replication-token) | Consul server-acl-init job | [`global.secretsBackend.vault.manageSystemACLsRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)|
|[Enterprise license](/consul/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license) | Consul servers<br/>Consul clients | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)<br/>[`global.secretsBackend.vault.consulClientRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)|
|[Gossip encryption key](/consul/docs/k8s/deployment-configurations/vault/data-integration/gossip) | Consul servers<br/>Consul clients | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)<br/>[`global.secretsBackend.vault.consulClientRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)|
|[Snapshot Agent config](/consul/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config) | Consul servers | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)|
|[Server TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/server-tls) | Consul servers<br/>Consul clients<br/>Consul components | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)<br/>[`global.secretsBackend.vault.consulClientRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)<br/>[`global.secretsBackend.vault.consulCARole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulcarole)|
|[Service Mesh and Consul client TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) | Consul servers | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)|
|[Webhook TLS certificates for controller and connect inject](/consul/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) | Consul controllers<br/>Consul connect inject | [`global.secretsBackend.vault.controllerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-controllerrole)<br />[`global.secretsBackend.vault.connectInjectRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-controllerrole)|

### Secondary datacenters

The mapping for secondary data centers is similar with the following differences:

- There is no use of bootstrap token because ACLs would have been bootstrapped in the primary datacenter.
- ACL Partition token is mapped to both the `server-acl-init` job and the `partition-init` job service accounts.
- ACL Replication token is mapped to both the `server-acl-init` job and Consul service accounts.

| Secret | Service Account For | Configurable Role in Consul k8s Helm |
| ------ | ------------------- | ------------------------------------ |
|[ACL Partition token](/consul/docs/k8s/deployment-configurations/vault/data-integration/partition-token) | Consul server-acl-init job<br/>Consul partition-init job | [`global.secretsBackend.vault.manageSystemACLsRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)<br/>[`global.secretsBackend.vault.adminPartitionsRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-adminpartitionsrole)|
|[ACL Replication token](/consul/docs/k8s/deployment-configurations/vault/data-integration/replication-token) | Consul server-acl-init job<br/>Consul servers | [`global.secretsBackend.vault.manageSystemACLsRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)<br/>[`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)|
|[Enterprise license](/consul/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license) | Consul servers<br/>Consul clients | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)<br/>[`global.secretsBackend.vault.consulClientRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)|
|[Gossip encryption key](/consul/docs/k8s/deployment-configurations/vault/data-integration/gossip) | Consul servers<br/>Consul clients | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)<br/>[`global.secretsBackend.vault.consulClientRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)|
|[Snapshot Agent config](/consul/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config) | Consul servers | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)|
|[Server TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/server-tls) | Consul servers<br/>Consul clients<br/>Consul components | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)<br/>[`global.secretsBackend.vault.consulClientRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)<br/>[`global.secretsBackend.vault.consulCARole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulcarole)|
|[Service Mesh and Consul client TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) | Consul servers | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)|
|[Webhook TLS certificates for controller and connect inject](/consul/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) | Consul controllers<br/>Consul connect inject | [`global.secretsBackend.vault.controllerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-controllerrole)<br />[`global.secretsBackend.vault.connectInjectRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-controllerrole)|

### Combining policies within roles

Depending upon your needs, a Consul on Kubernetes service account may need to request more than one secret.  To request multiple secrets, create one role for the Consul on Kubernetes service account that is mapped to multiple policies associated with the required secrets.

For example, if your Consul on Kubernetes servers need access to [Consul Server TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/server-tls) and an [Enterprise license](/consul/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license):

1. Create a policy for each secret.

    1. Consul Server TLS credentials

      <CodeBlockConfig filename="ca-policy.hcl">

      ```HCL
      path "pki/cert/ca" {
        capabilities = ["read"]
      }
      ```

      </CodeBlockConfig>

      ```shell-session
      $ vault policy write ca-policy ca-policy.hcl
      ```

    1. Enterprise License

      <Note>
      Vault API calls to version 2 of the Key-Value secrets engine require the `data` field in the path configuration. In the following example, the key-value data in `consul-kv/secret/enterpriselicense` becomes accessible for Vault API calls on the `consul-kv/data/secret/enterpriselicense` path.
      </Note>

      <CodeBlockConfig filename="license-policy.hcl">

      ```HCL
      path "consul-kv/data/secret/enterpriselicense" {
        capabilities = ["read"]
      }
      ```

      </CodeBlockConfig>

      ```shell-session
      $ vault policy write license-policy license-policy.hcl
      ```

1. Create one role that maps the Consul on Kubernetes service account to the 3 policies.
    ```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=ca-policy,license-policy \
        ttl=1h
    ```

## Detailed data integration guides

The following secrets can be stored in Vault KV secrets engine, which is meant to handle arbitrary secrets:

- [ACL Bootstrap token](/consul/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token)
- [ACL Partition token](/consul/docs/k8s/deployment-configurations/vault/data-integration/partition-token)
- [ACL Replication token](/consul/docs/k8s/deployment-configurations/vault/data-integration/replication-token)
- [Enterprise license](/consul/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license)
- [Gossip encryption key](/consul/docs/k8s/deployment-configurations/vault/data-integration/gossip)
- [Snapshot Agent config](/consul/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config)

The following TLS certificates and keys can generated and managed by Vault the Vault PKI Engine, which is meant to handle things like certificate expiration and rotation:

- [Server TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/server-tls)
- [Service Mesh and Consul client TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/connect-ca)
- [Vault as the Webhook Certificate Provider for Consul Controller and Connect Inject on Kubernetes](/consul/docs/k8s/deployment-configurations/vault/data-integration/webhook-certs)

## Secrets-to-service account mapping

Read through the [detailed data integration guides](#detailed-data-integration-guides) that are pertinent to your environment.