Vault as secrets management for Consul
A secure Consul datacenter requires you to distribute a number of secrets to your Consul agents before you can perform any operations. This includes a gossip encryption key, TLS certificates for the servers, and ACL tokens for all configuration. You will also need a valid license if you use Consul Enterprise.
If you are deploying Consul on Kubernetes, you have different options to provide these secrets to your Consul agents, including:
- store secrets in plain text in your configuration files. This is the most straightforward method, however, you may expose your secrets if someone compromises your Consul agents.
- leverage Kubernetes secrets. This reduces some risk, but may lead to secrets or credentials sprawl as you adopt new platforms and scale your workloads.
- use a secrets management system, like HashiCorp's Vault, to centrally manage and protect sensitive data (for example: tokens, passwords, certificates, encryption keys, and more).
Vault is HashiCorp's secrets and encryption management system that helps you securely manage secrets and protect sensitive data (for example, tokens, passwords, certificates, encryption keys, and more)
You can use HashiCorp Vault to authenticate your applications with a Kubernetes
Service Account token. The kubernetes
authentication method automatically
injects a Vault token into a Kubernetes pod. This lets you use Vault to store
all the other secrets, including the ones required by Consul.
In this tutorial, you will use Vault with Kubernetes to store and manage secrets required for a Consul datacenter. Then, you will use these secrets to deploy and configure the Consul datacenter on Kubernetes
Specifically you will:
- Configure Vault secrets engines to store and generate Consul secrets.
- Configure Kubernetes authentication engine for Vault. This lets you authenticate using a Kubernetes service account.
- Configure the Consul helm chart to retrieve the secrets from Vault during deploy.
- Deploy Consul on Kubernetes and verify the deployment completes correctly.
The following architecture diagram depicts the desired outcome.
Prerequisites
You can configure the scenario to deploy either Consul OSS or Consul Enterprise. Select your learning path by clicking one of the following tabs.
kubectl
to interact with your Kubernetes cluster.Vault (CLI) to interact with your Vault cluster
jq to manipulate json output
An AWS account with AWS Credentials configured for use with Terraform.
An HCP account configured for use with Terraform
The Terraform 1.0.6+ CLI installed locally.
git to clone the code repository locally
helm v3.2.1+ to deploy Consul and Vault agent injector.
Note
Some of the infrastructure in this tutorial may not qualify for the AWS free tier. Destroy the infrastructure at the end of the guide to avoid unnecessary charges. We are not responsible for any charges that you incur.
Deploy Kubernetes and Vault
The scenario requires a Kubernetes cluster deployed, either locally or on a Cloud provider, and a Vault cluster deployed, either on the Kubernetes cluster or on the HashiCorp Cloud Platform (HCP).
The tutorial provides example code and steps for a scenario using HCP Vault Dedicated and an Amazon Elastic Kubernetes Service (EKS) Cluster.
Deploy HCP Vault Dedicated cluster and EKS cluster
To begin, clone the repository. This repository contains all the Terraform configuration required to complete this tutorial.
Navigate into the repository folder.
Fetch the tags from the git remote server, and checkout the tag for this tutorial.
Navigate into the project folder for this tutorial.
The Terraform configuration deploys an Vault Dedicated Cluster, an Amazon Elastic Kubernetes Service (EKS) Cluster, and the underlying networking components for HCP and AWS to communicate with each other.
Initialize the Terraform project.
Apply the configuration to deploy the resources. Respond yes
to the prompt to confirm.
The deployment can take up to 20 minutes to complete. When Terraform completes successfully, it will display something similar to the following outputs:
The Terraform configuration configures your local kubectl
so you can interact
with the deployed Amazon EKS cluster.
Setup your environment to interact with Vault
Once the Vault Dedicated instance is deployed, use the vault
CLI to interact
with it.
Use the output from the terraform apply
command to retrieve the info for your
Vault Dedicated cluster.
First, configure Vault Dedicated token for your environment.
Next, configure the Vault endpoint for your environment, using the public address of the Vault Dedicated instance.
Security note
Using an HCP Vault Dedicated cluster with a public endpoint is not recommended for use in production. Read more in the HCP Vault Dedicated Security Overview.
Your Vault Dedicated instance is also exposed on a private address accessible from your AWS resources, in this case an EKS cluster, over the HVN peering connection. You will use this address to configure the Kubernetes integration with Vault.
Finally, since Vault Dedicated uses namespaces, set the VAULT_NAMESPACE
environment variable to admin
.
Install Vault agent injector on Amazon EKS
Create a vault-values.yaml
file that sets the external servers to Vault Dedicated.
This will deploy a Vault agent injector into the EKS cluster.
To get more info on the available helm values configuration options, check Helm Chart Configuration page.
Validate that the values file is populated correctly. You should find the Vault Dedicated private address in the file.
You will use the official vault-helm
chart
to install the Vault agents to your EKS cluster.
Add the HashiCorp's Helm chart repository.
Install the HashiCorp Vault Helm chart.
Once the installation is complete, verify the Vault agent injector pod
deploys by issuing kubectl get pods
.
At this point, Vault is ready to use and for you to configure it as the secret manager for Consul.
Configure Vault as Consul secret manager
You will need to generate tokens for the different nodes and servers to securely configure Consul. In order to generate these tokens, you will need a key for gossip encryption, a Consul Enterprise license, TLS certificates for the Consul servers and ACL policies
Since you are using Vault as secrets management for your Consul datacenter, all the secrets will be stored inside Vault.
Vault provides a kv
secrets engine that can be used to store arbitrary secrets.
You will use this engine to store the encryption key and the enterprise license.
First, enable key/value v2 secrets engine (kv-v2
).
Store Consul gossip key in Vault
Once the secret engine is enabled, store the encryption key in Vault.
Setup PKI secrets engine for TLS and service mesh CA
Vault provides a pki
secrets engine that you can use to generate TLS certificates.
You will use this engine to configure CAs for TLS encryption for servers and
service mesh leaf certificates for services.
Enable Vault's PKI secrets engine at the pki
path.
You can tune the PKI secrets engine to issue certificates with a maximum time-to-live (TTL). In this tutorial, you will set a TTL of 10 years (87600 hours).
Generate the root certificate for Consul CA. This command saves the certificate
in a file named consul_ca.crt
. You will use it to configure environment
variables for Consul CLI when you need to interact with your Consul datacenter.
Note
This command sets common_name
to dc1.consul
, which
matches the Consul datacenter and domain configuration. If you are
deploying Consul with different datacenter and domain values, use the
common_name="<datacenter.domain>"
schema to generate the certificate.
The command should return an output similar to the following.
Next, create a role that defines the configuration for the certificates.
The command should return an output similar to the following.
Note
This command sets common_name
to dc1.consul
, which
matches the Consul datacenter and domain configuration. If you are
deploying Consul with different datacenter and domain values, use values that reflect the
allowed domains for the consul-server
pki role.
Finally, enable Vault's PKI secrets engine at the connect-root
path to be used
as root CA for Consul service mesh.
Configure Kubernetes authentication
Vault provides a Kubernetes authentication method that enables clients to authenticate with a Kubernetes Service Account Token.
Using the Kubernetes authentication, Vault identifies your Consul agents using their service account and gives them access to the secrets they need to join your Consul datacenter.
Enable the Kubernetes authentication method.
Vault accepts service tokens from any client from within the Kubernetes cluster. During authentication, Vault verifies that the service account token is valid by querying a configured Kubernetes endpoint. In order to do that, configure the Kubernetes auth method with the JSON web token (JWT) for the service account, the Kubernetes CA certificate, and the Kubernetes host URL.
The chart configures a Kubernetes service account named vault
that you will use
to enable Vault communication with Kubernetes. Retrieve the JSON Web Token (JWT) for
the vault
service account and set it to the token_reviewer_jwt
environment
variable.
Retrieve the Kubernetes certificate authority for the service account and set it to
the kubernetes_ca_cert
environment variable.
Retrieve the Kubernetes cluster endpoint and set it to the kubernetes_host_url
environment variable.
Configure the Vault Kubernetes auth method to use the service account token.
The command should return an output similar to the following.
Verify the configuration for the Kubernetes auth method changed in Vault.
Generate Vault policies
Next, you must define the different Vault policies that will let the Consul agents generate or retrieve the different secrets.
You will create Vault policies to grant access to:
- The gossip encryption key.
- Consul server policy.
- Consul CA access policy.
- Consul service mesh CA policy.
- Optionally, if you are using Consul Enterprise, Consul enterprise license.
Gossip encryption key
Earlier in the tutorial, you stored the gossip encryption in the Vault kv
secret engine. Define a policy that grants access to the path where you stored
the gossip encryption.
The command should return an output similar to the following.
Consul server policy
Consul servers need to generate TLS certificates (pki/issue/consul-server
) and
retrieve the CA certificate (pki/cert/ca
).
The command should return an output similar to the following.
Consul CA access policy
The policy ca-policy
grants access to the Consul root CA so that Consul agents
and services can verify the certificates used in the service mesh are authentic.
The command should return an output similar to the following.
Consul service mesh CA policy
The following Vault policy allows Consul to create and manage the root and intermediate PKI secrets engines for generating service mesh certificates. If you would prefer to control PKI secrets engine creation and configuration from Vault rather than delegating full control to Consul, refer to the Vault CA provider documentation.
The following Vault policy applies to Consul 1.12 and later. For use with earlier Consul versions, refer to the Vault CA provider documentation and select your version from the version dropdown.
In this example, the RootPKIPath
is connect-root
and the IntermediatePKIPath
is connect-intermediate-dc1
. Update these values to reflect your environment.
The command should return an output similar to the following.
Configure Kubernetes authentication roles in Vault
You have configured the Kubernetes authentication method and defined the different policies to grant access to the resources. You can now define the associations between Kubernetes service accounts and Vault policies.
You will create Vault roles to associate the necessary policies to:
- Consul server agents.
- Consul client agents.
- Consul CA certificate access.
Consul server role
Create a Kubernetes authentication role in Vault named consul-server
that
connects the Kubernetes service account (consul-server
) and namespace (consul
)
with the Vault policies: gossip-policy
,consul-server
and connect
.
The tokens returned after authentication are valid for 24 hours.
The command should return an output similar to the following.
Consul client role
Create a Kubernetes authentication role in Vault named consul-client
that
connects the Kubernetes service account (consul-client
) and namespace (consul
)
with the Vault policies: gossip-policy
and ca-policy
.
The tokens returned after authentication are valid for 24 hours.
The command should return an output similar to the following.
Define access to Consul CA root certificate
Create a Kubernetes authentication role in Vault named consul-ca
that connects
all Kubernetes service account in namespace (consul
) with the Vault policy ca-policy
.
The tokens returned after authentication are valid for 1 hour.
The command should return an output similar to the following.
With the creation of the roles you completed the Vault configuration necessary. The following diagram provides a summary of the configuration you created.
Deploy Consul datacenter
Now that you have completed configuring Vault, you are ready to deploy Consul datacenter on the Kubernetes cluster.
The repository contains a configuration file for your Helm chart, named consul-values.yaml
.
Open the file and modify the configuration to use your $VAULT_PRIVATE_ADDR
.
Note
Content should resemble the example below. This example is not guaranteed to be up to date. Always refer to the values file provided in the repository.
To get more info on the available Helm values configuration options, check out the Helm Chart Configuration page.
Once the configuration is complete, install Consul on your EKS cluster.
The deployment can take up to 10 minutes to complete. When finished, you will get something similar to the following:
Verify configuration
Once the installation is complete, verify all the Consul pods are running using kubectl
.
The configuration enables Consul UI as a service in your EKS cluster.
Retrieve the address from Kubernetes services.
Access the Consul UI using the consul-ui
external address on port 443
.
Clean up environment
Now that you are finished with the tutorial, clean up your environment.
Respond yes
to the prompt to confirm
Next steps
Using Vault as a centralized secret management, you can simplify your Consul deployments and avoid secret sprawl across multiple Kubernetes instances. Vault helps you scale your deployments without having to trade off between security and manageability.
In this tutorial you learned how to use Vault as secret manager for your Consul datacenter installed in Kubernetes.
Specifically you:
- Configured Vault secrets engines to store or generate Consul secrets.
- Configured Kubernetes auth engine for Vault to allow authentication using a k8s service account.
- Configured Consul helm chart to retrieve the secrets from Vault during deploy.
- Deployed Consul on Kubernetes and verify that secrets are being generated or retrieved from Vault.
You can read more on Consul Helm chart configuration value, to tune your Consul installation at Helm Chart Configuration.
To learn more on Vault Kubernetes authentication check Vault Agent with Kubernetes and HCP Vault Dedicated with Amazon Elastic Kubernetes Service.