From 82516e383f7b5c6ddfae4b9078da1228789151e5 Mon Sep 17 00:00:00 2001 From: danielehc Date: Thu, 20 Nov 2025 17:52:01 +0100 Subject: [PATCH 1/7] Consul TLS with vault --- .../automate/consul-template/vault/mtls.mdx | 252 +++++++++++------- 1 file changed, 161 insertions(+), 91 deletions(-) diff --git a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx index f6327757e0..fb60993f03 100644 --- a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx +++ b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx @@ -7,74 +7,57 @@ description: >- # Generate mTLS Certificates for Consul with Vault and Consul Template -This page describes the process to use Vault's [PKI Secrets Engine](/vault/docs/secrets/pki) to generate and renew dynamic X.509 certificates, using [Consul Template](/consul/docs/automate/consul-template) to rotate your certificates. +This page describes how to use Vault's [PKI Secrets Engine](/vault/docs/secrets/pki) to generate and renew dynamic X.509 certificates, using [Consul Template](/consul/docs/automate/consul-template) to rotate your certificates. This method enables each agent in the Consul datacenter to have a unique certificate, with a relatively short time-to-live (TTL), that is automatically rotated, which allows you to safely and securely scale your datacenter while using mutual TLS (mTLS). +If you want ot use Vault as Consul service mesh certification authority, refer to [Vault as Consul service mesh certification authority](/consul/tutorials/operate-consul/vault-pki-consul-connect-ca). + ## Prerequisites -- **Consul:** to complete this guide, you need at least a node to install a Consul server agent and ideally another node to install a Consul client agent. Follow [Deploy Consul on VMs](/consul/tutorials/get-started-vms/virtual-machine-gs-deploy) to learn how to deploy a Consul agent. This page will provide you with the necessary specific configuration to apply for the scenario. +- **Consul:** you need at least a Consul server node and ideally another node to install a Consul client agent. Follow [Deploy Consul on VMs](/consul/tutorials/get-started-vms/virtual-machine-gs-deploy) to learn how to deploy a Consul agent. This page will provide you with the necessary specific configuration to apply for the scenario. -- **Vault:** this guide assumes you have a running Vault cluster in your network. You can use a [local Vault dev server](/vault/tutorials/get-started/setup#set-up-the-lab) or an existing Vault deployment. +- **Vault:** you need a running Vault cluster in your network. You can use a [local Vault dev server](/vault/tutorials/get-started/setup#set-up-the-lab) or an existing Vault deployment. You also need to configure your terminal to interact with Vault cluster by setting `VAULT_ADDR`, `VAULT_CACERT`, and `VAUKT_TOKEN`. -- **Consul Template:** to interact with your Consul agent you will need to [install the `consul-template` binary](/consul/docs/automate/consul-template/install) on a node. To rotate gossip keys you need the binary to be installed on one node only; changes will be automatically propagated across the Consul datacenter. +- **Consul Template:** to interact with your Consul agent you will need to [install the `consul-template` binary](/consul/docs/automate/consul-template/install) on the agent's node. The diagram below shows the minimal architecture needed to demonstrate the functionality. ![Architectural diagram showing a Client server and a Vault server with an operator issuing a command to start an automation](/img/consul-template/consul-vault-tls.png) -## Configure Vault's PKI secrets engine - -Before you can initialize the secrets engine, you need to set the `VAULT_ADDR` and `VAULT_TOKEN` environment variables so that you can connect to your local instance of Vault. - -The `VAULT_ADDR` environment variable should be set to the target Vault server address you want to connect to. +To configure Vault as Consul's certification authority you need to follow these steps: -```shell-session -$ export VAULT_ADDR='http://127.0.0.1:8200' -``` +1. [Configure the root certification authority (CA).](#configure-the-root-certification-authority-ca) +1. [Configure an intermediate CA.](#configure-an-intermediate-ca) +1. [Create a Vault role.](#create-a-vault-role) +1. [Generate certificates for Consul.](#generate-certificates-for-consul) +1. (Optional) [Automate certificate rotation with consul-template.](#automate-certificate-rotation-with-consul-template) -The `VAULT_TOKEN` environment variable should store your client token (e.g. `root`). +## Configure the root certification authority (CA) -```shell-session -$ export VAULT_TOKEN="root" -``` +In this page we follow the recommended practice to have one mount point, the `pki` in this example, to act as the root CA. The root CA is used only to sign intermediate Certificate Signing Requests (CSRs) from other PKI secrets engines. This allows you to use an external CA, in case you already have one in your network, and to use Vault's PKI engine only as an intermediate CA. Enable Vault's PKI secrets engine at the `pki` path. ```shell-session $ vault secrets enable pki - Success! Enabled the pki secrets engine at: pki/ ``` -Tune the PKI secrets engine to issue certificates with a maximum time-to-live (TTL) of `87600` hours. +Tune the PKI secrets engine to issue certificates with a maximum time-to-live (TTL) of `87600` hours (10 years). ```shell-session $ vault secrets tune -max-lease-ttl=87600h pki - Success! Tuned the secrets engine at: pki/ ``` - - -This tutorial uses a common and recommended pattern which is to have one mount act as the root CA and to use this CA only to sign intermediate CA CSRs from other PKI secrets engines (which you will create in the next few steps). For tighter security, you can store your CA outside of Vault and use the PKI engine only as an intermediate CA. - - - -## Configure Vault as Consul's CA - -Consul requires that all servers and clients have key pairs that are generated by a single Certificate Authority (CA). - -You will use Vault's PKI secrets engine to generate the necessary CA and certificates. - -#### 1. Generate the root CA - Generate the root certificate and save the certificate in `CA_cert.crt`. ```shell-session $ vault write -field=certificate pki/root/generate/internal \ - common_name="dc1.consul" \ - ttl=87600h > CA_cert.crt + common_name="consul" \ + issuer_name="root-CA" \ + ttl=87600h > CA_cert.crt ``` This generates a new self-signed CA certificate and private key. Vault will automatically revoke the generated root at the end of its lease period (TTL); the CA certificate will sign its own Certificate Revocation List (CRL). @@ -91,8 +74,8 @@ Configure the CA and CRL URLs. ```shell-session $ vault write pki/config/urls \ - issuing_certificates="http://127.0.0.1:8200/v1/pki/ca" \ - crl_distribution_points="http://127.0.0.1:8200/v1/pki/crl" + issuing_certificates="${VAULT_ADDR}/v1/pki/ca" \ + crl_distribution_points="${VAULT_ADDR}/v1/pki/crl" ``` Example output: @@ -100,26 +83,34 @@ Example output: ```plaintext -Success! Data written to: pki/config/urls +Key Value +--- ----- +crl_distribution_points [https://127.0.0.1:8200/v1/pki/crl] +delta_crl_distribution_points [] +enable_templating false +issuing_certificates [https://127.0.0.1:8200/v1/pki/ca] +ocsp_servers ``` -#### 2. Generate an intermediate CA +## Configure an intermediate CA + +You want the certificates signed by the intermediate CA to be also signed by the root CA, to do so you will generate a Certificate Signing Request (CSR) and sign it with the root CA to generate the intermediate CA certificate. In this way, in case of security breaches, you can revoke all certificates issued by the intermediate CA directly from the root CA. + +### Enable Vault secret engine for the intermediate CA Enable the PKI secrets engine at the `pki_int` path. ```shell-session $ vault secrets enable -path=pki_int pki - Success! Enabled the pki secrets engine at: pki_int/ ``` -Tune the `pki_int` secrets engine to issue certificates with a maximum time-to-live (TTL) of `43800` hours. +Tune the `pki_int` secrets engine to issue certificates with a maximum time-to-live (TTL) of `43800` hours (5 years). ```shell-session $ vault secrets tune -max-lease-ttl=43800h pki_int - Success! Tuned the secrets engine at: pki_int/ ``` @@ -129,22 +120,29 @@ You can adapt the TTL to comply with your internal policies on certificate lifec -Request an intermediate certificate signing request (CSR) and save request as `pki_intermediate.csr`. +### Request a CSR for the intermediate CA + +Request a certificate signing request (CSR) for the intermediate CA and save request as `pki_intermediate.csr`. ```shell-session $ vault write -format=json pki_int/intermediate/generate/internal \ - common_name="dc1.consul Intermediate Authority" \ - | jq -r '.data.csr' > pki_intermediate.csr + common_name="dc1.consul Intermediate Authority" \ + issuer_name="intermediate-CA" \ + | jq -r '.data.csr' > pki_intermediate.csr ``` The command has no output. -#### 3. Sign the CSR and import the certificate into Vault +### Sign the CSR and import the certificate into Vault + +First, sign the CSR producing a a `pem` file. ```shell-session -$ vault write -format=json pki/root/sign-intermediate csr=@pki_intermediate.csr \ - format=pem_bundle ttl="43800h" \ - | jq -r '.data.certificate' > intermediate.cert.pem +$ vault write -format=json pki/root/sign-intermediate \ + issuer_ref="root-CA" \ + csr=@pki_intermediate.csr \ + format=pem_bundle ttl="43800h" \ + | jq -r '.data.certificate' > intermediate.cert.pem ``` The command has no output. @@ -153,11 +151,25 @@ Once the CSR is signed, and the root CA returns a certificate, it can be importe ```shell-session $ vault write pki_int/intermediate/set-signed certificate=@intermediate.cert.pem +``` + +Example output: + + -Success! Data written to: pki_int/intermediate/set-signed +```plaintext +Key Value +--- ----- +existing_issuers +existing_keys +imported_issuers [44d38d6c-14f4-38f4-1a40-95cd8cc04815 09a129d4-b853-ff48-efe9-3700f6b941cf] +imported_keys +mapping map[09a129d4-b853-ff48-efe9-3700f6b941cf: 44d38d6c-14f4-38f4-1a40-95cd8cc04815:48418626-88f5-22f4-348c-1841be4b3cc4] ``` -#### 4. Create a Vault role + + +## Create a Vault role A role is a logical name that maps to a policy used to generate credentials. @@ -174,12 +186,61 @@ Example output: ```plaintext -Success! Data written to: pki_int/roles/consul-dc1 +Key Value +--- ----- +allow_any_name false +allow_bare_domains false +allow_glob_domains false +allow_ip_sans true +allow_localhost true +allow_subdomains true +allow_token_displayname false +allow_wildcard_certificates true +allowed_domains [dc1.consul] +allowed_domains_template false +allowed_other_sans [] +allowed_serial_numbers [] +allowed_uri_sans [] +allowed_uri_sans_template false +allowed_user_ids [] +basic_constraints_valid_for_non_ca false +client_flag true +cn_validations [email hostname] +code_signing_flag false +country [] +email_protection_flag false +enforce_hostnames true +ext_key_usage [] +ext_key_usage_oids [] +generate_lease true +issuer_ref default +key_bits 2048 +key_type rsa +key_usage [DigitalSignature KeyAgreement KeyEncipherment] +locality [] +max_ttl 720h +no_store false +not_after n/a +not_before_duration 30s +organization [] +ou [] +policy_identifiers [] +postal_code [] +province [] +require_cn true +serial_number_source json-csr +server_flag true +signature_bits 256 +street_address [] +ttl 0s +use_csr_common_name true +use_csr_sans true +use_pss false ``` -For this guide, you are using the following options for the role: +You are using the following options for the role: - `allowed_domains`: Specifies the domains of the role. The command uses `dc1.consul` as the domain, which is the default configuration you are going to use for Consul. - `allow_subdomains`: Specifies if clients can request certificates with CNs that are subdomains of the CNs allowed by the other role options @@ -194,7 +255,7 @@ For this guide, you are using the following options for the role: This completes the Vault configuration as a CA. -## Generate a server certificate +## Generate certificates for Consul You can test the `pki` engine is configured correctly by generating your first certificate. @@ -217,34 +278,43 @@ Example output: ```plaintext Key Value --- ----- -lease_id pki_int/issue/consul-dc1/lFfKfpxtM0xY0AHDlr9pJ2GM +lease_id pki_int/issue/consul-dc1/Oip6uSVy9A4Y6RbPdEv7WuUf lease_duration 23h59m59s lease_renewable false ca_chain [-----BEGIN CERTIFICATE----- -##... +MIIDojCCAoqgAwIBAgIUBHQpzIb+3nN64cjTXhyHwTkz+G0wDQYJKoZIhvcNAQEL +BQAwETEPMA0GA1UEAxMGY29uc3VsMB4XDTI1MTEyMDE0NTYyOVoXDTMwMTExOTE0 +NTY1OVowLDEqMCgGA1UEAxMhZGMxLmNvbnN1bCBJbnRlcm1lZGlhdGUgQXV0aG9y +aXR5MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApu82Atvb913IGMZM +6vGu8ZkvqAVvGjqsj1/ciIyR55LSD6Wt9jknMWovX2YvIW5xN36ApEpWeQpccRzc +## ... +-----END CERTIFICATE----- -----BEGIN CERTIFICATE----- +## ... -----END CERTIFICATE-----] certificate -----BEGIN CERTIFICATE----- -##... +## ... -----END CERTIFICATE----- -expiration 1599645187 +expiration 1763737500 issuing_ca -----BEGIN CERTIFICATE----- -##... +## ... -----END CERTIFICATE----- private_key -----BEGIN RSA PRIVATE KEY----- -##... +## ... -----END RSA PRIVATE KEY----- private_key_type rsa -serial_number 3f:ec:bd:ea:01:a6:35:49:a7:6d:17:ba:13:88:c1:b8:35:b4:fc:4c +serial_number 48:91:a9:7b:d0:a6:10:93:98:0f:ca:dc:ea:83:14:42:8e:c8:ef:e0 ``` -## Configure Consul +### Configure Consul + +With the certificate generated you can configure Consul agents. -Configure Consul TLS using the following configuration: +Configure Consul server TLS stanza using the following configuration: @@ -254,9 +324,9 @@ tls { verify_incoming = true verify_outgoing = true verify_server_hostname = true - ca_file = "/opt/consul/agent-certs/ca.crt" - cert_file = "/opt/consul/agent-certs/agent.crt" - key_file = "/opt/consul/agent-certs/agent.key" + ca_file = "/etc/consul.d/ca.crt" + cert_file = "/etc/consul.d/agent.crt" + key_file = "/etc/consul.d/agent.key" } } @@ -272,9 +342,9 @@ auto_encrypt { "verify_incoming": true, "verify_outgoing": true, "verify_server_hostname": true, - "ca_file": "/opt/consul/agent-certs/ca.crt", - "cert_file": "/opt/consul/agent-certs/agent.crt", - "key_file": "/opt/consul/agent-certs/agent.key" + "ca_file": "/etc/consul.d/ca.crt", + "cert_file": "/etc/consul.d/agent.crt", + "key_file": "/etc/consul.d/agent.key" } }, "auto_encrypt": { @@ -299,25 +369,25 @@ Use the following commands to extract the two certificates and private key from Create the certificates folder. ```shell-session -$ mkdir -p /opt/consul/agent-certs +$ mkdir -p /etc/consul.d ``` Extract the root CA certificate. ```shell-session -$ grep -Pzo "(?s)(?<=issuing_ca)[^\-]*.*?END CERTIFICATE[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /opt/consul/agent-certs/ca.crt +$ grep -Pzo "(?s)(?<=issuing_ca)[^\-]*.*?END CERTIFICATE[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /etc/consul.d/ca.crt ``` Extract the agent certificate. ```shell-session -$ grep -Pzo "(?s)(?<=certificate)[^\-]*.*?END CERTIFICATE[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /opt/consul/agent-certs/agent.crt +$ grep -Pzo "(?s)(?<=certificate)[^\-]*.*?END CERTIFICATE[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /etc/consul.d/agent.crt ``` Extract the agent key. ```shell-session -$ grep -Pzo "(?s)(?<=private_key)[^\-]*.*?END RSA PRIVATE KEY[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /opt/consul/agent-certs/agent.key +$ grep -Pzo "(?s)(?<=private_key)[^\-]*.*?END RSA PRIVATE KEY[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /etc/consul.d/agent.key ``` @@ -341,7 +411,7 @@ tls { verify_incoming = true verify_outgoing = true verify_server_hostname = true - ca_file = "/opt/consul/agent-certs/ca.crt" + ca_file = "/etc/consul.d/ca.crt" } } @@ -357,7 +427,7 @@ auto_encrypt { "verify_incoming": true, "verify_outgoing": true, "verify_server_hostname": true, - "ca_file": "/opt/consul/agent-certs/ca.crt", + "ca_file": "/etc/consul.d/ca.crt", } }, "auto_encrypt": { @@ -378,19 +448,19 @@ Use the following commands to extract the certificate from the `certs.txt` and p Create the certificates folder. ```shell-session -$ mkdir -p /opt/consul/agent-certs +$ mkdir -p /etc/consul.d ``` Extract the root CA certificate. ```shell-session -$ grep -Pzo "(?s)(?<=certificate)[^\-]*.*?END CERTIFICATE[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /opt/consul/agent-certs/agent.crt +$ grep -Pzo "(?s)(?<=certificate)[^\-]*.*?END CERTIFICATE[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /etc/consul.d/agent.crt ``` -## Configure Consul Template +## Automate certificate rotation with consul-template The guide steps used `ttl="24h"` ad a parameter during certificate creation, meaning that this certificates will be valid only for 24 hours before expiring. @@ -434,11 +504,10 @@ The same endpoint also exposes the CA certificate under the `.Data.issuing_ca` p - Copy the newly created files into `/opt/consul/templates`. ```shell-session -$ cp *.tpl /opt/consul/templates/ +$ cp *.tpl /opt/consul-template/ ``` ### Create Consul Template configuration @@ -456,7 +525,7 @@ Create a configuration file, `consul_template.hcl`, that will instruct Consul Te vault { # This is the address of the Vault leader. The protocol (http(s)) portion # of the address is required. - address = "http://localhost:8200" + address = "https://localhost:8200" # This value can also be specified via the environment variable VAULT_TOKEN. token = "root" @@ -471,12 +540,12 @@ vault { template { # This is the source file on disk to use as the input template. This is often # called the "consul-template template". - source = "agent.crt.tpl" + source = "/opt/consul-template/agent.crt.tpl" # This is the destination path on disk where the source template will render. # If the parent directories do not exist, consul-template will attempt to # create them, unless create_dest_dirs is false. - destination = "/opt/consul/agent-certs/agent.crt" + destination = "/etc/consul.d/agent.crt" # This is the permission to render the file. If this option is left # unspecified, consul-template will attempt to match the permissions of the @@ -490,15 +559,15 @@ template { } template { - source = "agent.key.tpl" - destination = "/opt/consul/agent-certs/agent.key" + source = "/opt/consul-template/agent.key.tpl" + destination = "/etc/consul.d/agent.key" perms = 0700 command = "sh -c 'date && consul reload'" } template { - source = "ca.crt.tpl" - destination = "/opt/consul/agent-certs/ca.crt" + source = "/opt/consul-template/ca.crt.tpl" + destination = "/etc/consul.d/ca.crt" command = "sh -c 'date && consul reload'" } ``` @@ -520,7 +589,7 @@ CA certificate as well as the certificate/key pair for the server agent. vault { # This is the address of the Vault leader. The protocol (http(s)) portion # of the address is required. - address = "http://localhost:8200" + address = "https://localhost:8200" # This value can also be specified via the environment variable VAULT_TOKEN. token = "root" @@ -531,8 +600,8 @@ vault { } template { - source = "ca.crt.tpl" - destination = "/opt/consul/agent-certs/ca.crt" + source = "/opt/consul-template/ca.crt.tpl" + destination = "/etc/consul.d/ca.crt" command = "sh -c 'date && consul reload'" } ``` @@ -583,7 +652,7 @@ Configuration reload triggered You can also use `openssl` to verify the certificate content: ```shell-session -$ openssl x509 -text -noout -in /opt/consul/agent-certs/agent.crt +$ openssl x509 -text -noout -in /etc/consul.d/agent.crt Certificate: Data: @@ -600,3 +669,4 @@ Certificate: ``` and verify that the `Not Before` and `Not After` values are being updated to reflect the new certificate. + From 4849242e4d144146f07fc86cec38a70eb0579918 Mon Sep 17 00:00:00 2001 From: danielehc Date: Tue, 25 Nov 2025 13:02:00 +0100 Subject: [PATCH 2/7] Fix spacing and outputs --- .../automate/consul-template/vault/mtls.mdx | 58 +++++++++++-------- 1 file changed, 33 insertions(+), 25 deletions(-) diff --git a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx index fb60993f03..ecad56d2ed 100644 --- a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx +++ b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx @@ -7,19 +7,19 @@ description: >- # Generate mTLS Certificates for Consul with Vault and Consul Template -This page describes how to use Vault's [PKI Secrets Engine](/vault/docs/secrets/pki) to generate and renew dynamic X.509 certificates, using [Consul Template](/consul/docs/automate/consul-template) to rotate your certificates. +This page describes how to use Vault's [PKI Secrets Engine](/vault/docs/secrets/pki) to generate and renew dynamic X.509 certificates, using [Consul Template](/consul/docs/automate/consul-template) to automatically rotate your certificates. This method enables each agent in the Consul datacenter to have a unique certificate, with a relatively short time-to-live (TTL), that is automatically rotated, which allows you to safely and securely scale your datacenter while using mutual TLS (mTLS). -If you want ot use Vault as Consul service mesh certification authority, refer to [Vault as Consul service mesh certification authority](/consul/tutorials/operate-consul/vault-pki-consul-connect-ca). +If you want to use Vault as Consul service mesh certification authority, refer to [Vault as Consul service mesh certification authority](/consul/tutorials/operate-consul/vault-pki-consul-connect-ca). ## Prerequisites -- **Consul:** you need at least a Consul server node and ideally another node to install a Consul client agent. Follow [Deploy Consul on VMs](/consul/tutorials/get-started-vms/virtual-machine-gs-deploy) to learn how to deploy a Consul agent. This page will provide you with the necessary specific configuration to apply for the scenario. +- **Consul:** you need at least one Consul server node and, ideally, a Consul client agent node. Follow [Deploy Consul on VMs](/consul/tutorials/get-started-vms/virtual-machine-gs-deploy) to learn how to deploy a Consul agent. This page will provide you with the necessary specific configuration to apply for the scenario. - **Vault:** you need a running Vault cluster in your network. You can use a [local Vault dev server](/vault/tutorials/get-started/setup#set-up-the-lab) or an existing Vault deployment. You also need to configure your terminal to interact with Vault cluster by setting `VAULT_ADDR`, `VAULT_CACERT`, and `VAUKT_TOKEN`. -- **Consul Template:** to interact with your Consul agent you will need to [install the `consul-template` binary](/consul/docs/automate/consul-template/install) on the agent's node. +- **Consul Template:** to automate certificate generation and distribution you need [the `consul-template` binary installed](/consul/docs/automate/consul-template/install) on the agent's node. The diagram below shows the minimal architecture needed to demonstrate the functionality. @@ -74,8 +74,8 @@ Configure the CA and CRL URLs. ```shell-session $ vault write pki/config/urls \ - issuing_certificates="${VAULT_ADDR}/v1/pki/ca" \ - crl_distribution_points="${VAULT_ADDR}/v1/pki/crl" + issuing_certificates="${VAULT_ADDR}/v1/pki/ca" \ + crl_distribution_points="${VAULT_ADDR}/v1/pki/crl" ``` Example output: @@ -96,7 +96,7 @@ ocsp_servers ## Configure an intermediate CA -You want the certificates signed by the intermediate CA to be also signed by the root CA, to do so you will generate a Certificate Signing Request (CSR) and sign it with the root CA to generate the intermediate CA certificate. In this way, in case of security breaches, you can revoke all certificates issued by the intermediate CA directly from the root CA. +You want the certificates signed by the intermediate CA to be also signed by the root CA. Generate a Certificate Signing Request (CSR) and sign it with the root CA to generate the intermediate CA certificate. In this way, in case of security breaches, you can revoke all certificates issued by the intermediate CA directly from the root CA. ### Enable Vault secret engine for the intermediate CA @@ -147,7 +147,7 @@ $ vault write -format=json pki/root/sign-intermediate \ The command has no output. -Once the CSR is signed, and the root CA returns a certificate, it can be imported back into Vault. +Once the CSR is signed, and the root CA returns a certificate, import it back into Vault. ```shell-session $ vault write pki_int/intermediate/set-signed certificate=@intermediate.cert.pem @@ -257,17 +257,17 @@ This completes the Vault configuration as a CA. ## Generate certificates for Consul -You can test the `pki` engine is configured correctly by generating your first certificate. +Test the `pki` engine configuration by generating your first certificate. ```shell-session $ vault write pki_int/issue/consul-dc1 \ - common_name="server.dc1.consul" \ - ttl="24h" | tee certs.txt + common_name="server.dc1.consul" \ + ttl="24h" | tee certs.txt ``` -The TTL for the certificate is being set to 24 hours in this guide, meaning that this certificate will be valid only for 24 hours before expiring. You can try using a shorter TTL on a test environment to ensure certificates are revoked properly after TTL is expired. +The TTL for the certificate is being set to 24 hours in this guide, meaning that this certificate will be valid only for 24 hours before expiring. Try using a shorter TTL on a test environment to ensure certificates are revoked properly after TTL is expired. @@ -309,12 +309,12 @@ serial_number 48:91:a9:7b:d0:a6:10:93:98:0f:ca:dc:ea:83:14:42:8e:c8:ef:e0 ### Configure Consul -With the certificate generated you can configure Consul agents. +Use the certificate to configure Consul agents. -Configure Consul server TLS stanza using the following configuration: +Configure Consul server TLS stanza using the following `tls` stanza: @@ -399,9 +399,9 @@ This section describes the automated [client certificate deployment process](/co -With auto-encryption, you can configure the Consul servers to automatically distribute certificates to the clients. To use this feature, you will need to configure clients to automatically get the certificates from the server. +With auto-encryption, you can configure the Consul servers to automatically distribute certificates to the clients. To use this feature, configure clients to automatically get the certificates from the server. -Configure Consul client TLS using the following configuration: +Configure Consul client TLS using the following `tls` stanza: @@ -468,7 +468,7 @@ Deciding the right trade-off for certificate lifespan is always a compromise bet ### Create template files -You can instruct Consul Template to generate and retrieve those files from Vault using the following templates: +Instruct Consul Template to generate and retrieve those files from Vault using the following templates: @@ -643,30 +643,38 @@ The certificate you created manually for the Consul server had a TTL of 24 hours This means that after the certificate expires Vault will renew it and Consul Template will update the files on your agent it reload Consul configuration automatically to make it pick up the new files. -You can verify the rotation by checking that Consul Template keeps listing, every 24 hours, a timestamp and the log line: +Verify the rotation by checking that Consul Template keeps listing, every 24 hours, a timestamp and the log line: ```plaintext hideClipboard Configuration reload triggered ``` -You can also use `openssl` to verify the certificate content: +Use `openssl` to verify the certificate content: ```shell-session $ openssl x509 -text -noout -in /etc/consul.d/agent.crt +``` + +Verify in the output that the `Not Before` and `Not After` values are being updated to reflect the new certificate. + + +```plaintext Certificate: Data: Version: 3 (0x2) Serial Number: - 1b:2d:d6:5d:63:9b:aa:05:84:7b:be:3b:6f:e1:95:bb:1c:36:8c:a4 - Signature Algorithm: sha256WithRSAEncryption + 0a:06:b2:62:56:d1:7d:e6:5c:67:f7:89:06:8a:3e:5b:f1:fa:7e:00 + Signature Algorithm: sha256WithRSAEncryption Issuer: CN=dc1.consul Intermediate Authority Validity - Not Before: Sep 16 16:03:45 2020 GMT - Not After : Sep 16 16:06:15 2020 GMT + Not Before: Nov 25 11:48:06 2025 GMT + Not After : Nov 25 12:48:06 2025 GMT Subject: CN=server.dc1.consul -... +## ... ``` -and verify that the `Not Before` and `Not After` values are being updated to reflect the new certificate. + + + From 30b045d9b396170fa11365b37507adea66ac6c2b Mon Sep 17 00:00:00 2001 From: danielehc Date: Tue, 25 Nov 2025 13:03:48 +0100 Subject: [PATCH 3/7] Add next steps --- .../content/docs/automate/consul-template/vault/mtls.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx index ecad56d2ed..f33e7d4c15 100644 --- a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx +++ b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx @@ -676,5 +676,13 @@ Certificate: +## Next steps +In this page, you learned how to generate Consul TLS certificates using Vault's PKI secret engine and to automatically rotate them using consul-template. + +If you want to automate Consul's gossip encryption using Vault and consul-template refer to [Generate and manage gossip encryption for Consul with Vault and Consul Template](/consul/docs/automate/consul-template/vault/gossip). + +To learn how to use Vault to manage Consul's ACL token generation refer to [Use Vault for ACL management with Consul on VMs](/consul/docs/secure/acl/vault/vm). + +If you are running Consul in Kubernetes, you can [use Vault for secrets management with Consul on Kubernetes](/consul/docs/integrate/vault/k8s). From ef9ec9eb9cc304200a3a92257110f5a4c0f8fa0e Mon Sep 17 00:00:00 2001 From: danielehc <40759828+danielehc@users.noreply.github.com> Date: Wed, 26 Nov 2025 16:37:00 +0100 Subject: [PATCH 4/7] Update content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --- .../docs/automate/consul-template/vault/mtls.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx index f33e7d4c15..2a7d35c978 100644 --- a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx +++ b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx @@ -27,11 +27,11 @@ The diagram below shows the minimal architecture needed to demonstrate the funct To configure Vault as Consul's certification authority you need to follow these steps: -1. [Configure the root certification authority (CA).](#configure-the-root-certification-authority-ca) -1. [Configure an intermediate CA.](#configure-an-intermediate-ca) -1. [Create a Vault role.](#create-a-vault-role) -1. [Generate certificates for Consul.](#generate-certificates-for-consul) -1. (Optional) [Automate certificate rotation with consul-template.](#automate-certificate-rotation-with-consul-template) +1. [Configure the root certification authority (CA)](#configure-the-root-certification-authority-ca) +1. [Configure an intermediate CA](#configure-an-intermediate-ca) +1. [Create a Vault role](#create-a-vault-role) +1. [Generate certificates for Consul](#generate-certificates-for-consul) +1. (Optional) [Automate certificate rotation with consul-template](#automate-certificate-rotation-with-consul-template) ## Configure the root certification authority (CA) From 1ec6ae6580a2fc3ef9aa58da80732cf706889911 Mon Sep 17 00:00:00 2001 From: danielehc <40759828+danielehc@users.noreply.github.com> Date: Wed, 26 Nov 2025 16:38:35 +0100 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --- .../docs/automate/consul-template/vault/mtls.mdx | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx index 2a7d35c978..df60a2d5bb 100644 --- a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx +++ b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx @@ -35,7 +35,9 @@ To configure Vault as Consul's certification authority you need to follow these ## Configure the root certification authority (CA) -In this page we follow the recommended practice to have one mount point, the `pki` in this example, to act as the root CA. The root CA is used only to sign intermediate Certificate Signing Requests (CSRs) from other PKI secrets engines. This allows you to use an external CA, in case you already have one in your network, and to use Vault's PKI engine only as an intermediate CA. +We recommend that you have a single mount point to act as the root CA. The root CA signs intermediate Certificate Signing Requests (CSRs) from other PKI secrets engines. This setup allows you to use an external CA, in case you already have one in your network, and to use Vault's PKI engine only as an intermediate CA. + +In these instructions, the `pki` path is the mount point for the root CA. Enable Vault's PKI secrets engine at the `pki` path. @@ -96,7 +98,9 @@ ocsp_servers ## Configure an intermediate CA -You want the certificates signed by the intermediate CA to be also signed by the root CA. Generate a Certificate Signing Request (CSR) and sign it with the root CA to generate the intermediate CA certificate. In this way, in case of security breaches, you can revoke all certificates issued by the intermediate CA directly from the root CA. +You want the certificates signed by the intermediate CA to be signed by the root CA as well. + +Generate a Certificate Signing Request (CSR) and sign it with the root CA to generate the intermediate CA certificate. This way, if a security breach occurs, you can revoke all certificates issued by the intermediate CA directly from the root CA. ### Enable Vault secret engine for the intermediate CA @@ -678,11 +682,11 @@ Certificate: ## Next steps -In this page, you learned how to generate Consul TLS certificates using Vault's PKI secret engine and to automatically rotate them using consul-template. +In this page, you learned how to generate Consul TLS certificates using Vault's PKI secret engine and to automatically rotate them using Consul Template. -If you want to automate Consul's gossip encryption using Vault and consul-template refer to [Generate and manage gossip encryption for Consul with Vault and Consul Template](/consul/docs/automate/consul-template/vault/gossip). +If you want to automate Consul's gossip encryption using Vault and `consul-template` refer to [Generate and manage gossip encryption for Consul with Vault and Consul Template](/consul/docs/automate/consul-template/vault/gossip). -To learn how to use Vault to manage Consul's ACL token generation refer to [Use Vault for ACL management with Consul on VMs](/consul/docs/secure/acl/vault/vm). +To learn how to use Vault to generate and manage Consul's ACL tokens, refer to [Use Vault for ACL management with Consul on VMs](/consul/docs/secure/acl/vault/vm). If you are running Consul in Kubernetes, you can [use Vault for secrets management with Consul on Kubernetes](/consul/docs/integrate/vault/k8s). From 288b099d9f0bed947f8537ca26760c1496116e06 Mon Sep 17 00:00:00 2001 From: danielehc <40759828+danielehc@users.noreply.github.com> Date: Wed, 26 Nov 2025 16:48:06 +0100 Subject: [PATCH 6/7] Update content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx --- .../content/docs/automate/consul-template/vault/mtls.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx index df60a2d5bb..6ad694be6f 100644 --- a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx +++ b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx @@ -17,7 +17,7 @@ If you want to use Vault as Consul service mesh certification authority, refer t - **Consul:** you need at least one Consul server node and, ideally, a Consul client agent node. Follow [Deploy Consul on VMs](/consul/tutorials/get-started-vms/virtual-machine-gs-deploy) to learn how to deploy a Consul agent. This page will provide you with the necessary specific configuration to apply for the scenario. -- **Vault:** you need a running Vault cluster in your network. You can use a [local Vault dev server](/vault/tutorials/get-started/setup#set-up-the-lab) or an existing Vault deployment. You also need to configure your terminal to interact with Vault cluster by setting `VAULT_ADDR`, `VAULT_CACERT`, and `VAUKT_TOKEN`. +- **Vault:** you need a running Vault cluster in your network. You can use a [local Vault dev server](/vault/tutorials/get-started/setup#set-up-the-lab) or an existing Vault deployment. You also need to configure your terminal to interact with Vault cluster by setting `VAULT_ADDR`, `VAULT_CACERT`, and `VAULT_TOKEN`. - **Consul Template:** to automate certificate generation and distribution you need [the `consul-template` binary installed](/consul/docs/automate/consul-template/install) on the agent's node. From 13d50c973895981958841b22043d6c16f20def83 Mon Sep 17 00:00:00 2001 From: danielehc Date: Thu, 27 Nov 2025 18:17:38 +0100 Subject: [PATCH 7/7] Backport 1.21 --- .../automate/consul-template/vault/mtls.mdx | 308 +++++++++++------- .../automate/consul-template/vault/mtls.mdx | 6 +- 2 files changed, 200 insertions(+), 114 deletions(-) diff --git a/content/consul/v1.21.x/content/docs/automate/consul-template/vault/mtls.mdx b/content/consul/v1.21.x/content/docs/automate/consul-template/vault/mtls.mdx index f6327757e0..1d773486dc 100644 --- a/content/consul/v1.21.x/content/docs/automate/consul-template/vault/mtls.mdx +++ b/content/consul/v1.21.x/content/docs/automate/consul-template/vault/mtls.mdx @@ -7,74 +7,59 @@ description: >- # Generate mTLS Certificates for Consul with Vault and Consul Template -This page describes the process to use Vault's [PKI Secrets Engine](/vault/docs/secrets/pki) to generate and renew dynamic X.509 certificates, using [Consul Template](/consul/docs/automate/consul-template) to rotate your certificates. +This page describes how to use Vault's [PKI Secrets Engine](/vault/docs/secrets/pki) to generate and renew dynamic X.509 certificates, using [Consul Template](/consul/docs/automate/consul-template) to automatically rotate your certificates. This method enables each agent in the Consul datacenter to have a unique certificate, with a relatively short time-to-live (TTL), that is automatically rotated, which allows you to safely and securely scale your datacenter while using mutual TLS (mTLS). +If you want to use Vault as Consul service mesh certification authority, refer to [Vault as Consul service mesh certification authority](/consul/tutorials/operate-consul/vault-pki-consul-connect-ca). + ## Prerequisites -- **Consul:** to complete this guide, you need at least a node to install a Consul server agent and ideally another node to install a Consul client agent. Follow [Deploy Consul on VMs](/consul/tutorials/get-started-vms/virtual-machine-gs-deploy) to learn how to deploy a Consul agent. This page will provide you with the necessary specific configuration to apply for the scenario. +- **Consul:** you need at least one Consul server node and, ideally, a Consul client agent node. Follow [Deploy Consul on VMs](/consul/tutorials/get-started-vms/virtual-machine-gs-deploy) to learn how to deploy a Consul agent. This page will provide you with the necessary specific configuration to apply for the scenario. -- **Vault:** this guide assumes you have a running Vault cluster in your network. You can use a [local Vault dev server](/vault/tutorials/get-started/setup#set-up-the-lab) or an existing Vault deployment. +- **Vault:** you need a running Vault cluster in your network. You can use a [local Vault dev server](/vault/tutorials/get-started/setup#set-up-the-lab) or an existing Vault deployment. You also need to configure your terminal to interact with Vault cluster by setting `VAULT_ADDR`, `VAULT_CACERT`, and `VAULT_TOKEN`. -- **Consul Template:** to interact with your Consul agent you will need to [install the `consul-template` binary](/consul/docs/automate/consul-template/install) on a node. To rotate gossip keys you need the binary to be installed on one node only; changes will be automatically propagated across the Consul datacenter. +- **Consul Template:** to automate certificate generation and distribution you need [the `consul-template` binary installed](/consul/docs/automate/consul-template/install) on the agent's node. The diagram below shows the minimal architecture needed to demonstrate the functionality. ![Architectural diagram showing a Client server and a Vault server with an operator issuing a command to start an automation](/img/consul-template/consul-vault-tls.png) -## Configure Vault's PKI secrets engine - -Before you can initialize the secrets engine, you need to set the `VAULT_ADDR` and `VAULT_TOKEN` environment variables so that you can connect to your local instance of Vault. +To configure Vault as Consul's certification authority you need to follow these steps: -The `VAULT_ADDR` environment variable should be set to the target Vault server address you want to connect to. +1. [Configure the root certification authority (CA)](#configure-the-root-certification-authority-ca) +1. [Configure an intermediate CA](#configure-an-intermediate-ca) +1. [Create a Vault role](#create-a-vault-role) +1. [Generate certificates for Consul](#generate-certificates-for-consul) +1. (Optional) [Automate certificate rotation with consul-template](#automate-certificate-rotation-with-consul-template) -```shell-session -$ export VAULT_ADDR='http://127.0.0.1:8200' -``` +## Configure the root certification authority (CA) -The `VAULT_TOKEN` environment variable should store your client token (e.g. `root`). +We recommend that you have a single mount point to act as the root CA. The root CA signs intermediate Certificate Signing Requests (CSRs) from other PKI secrets engines. This setup allows you to use an external CA, in case you already have one in your network, and to use Vault's PKI engine only as an intermediate CA. -```shell-session -$ export VAULT_TOKEN="root" -``` +In these instructions, the `pki` path is the mount point for the root CA. Enable Vault's PKI secrets engine at the `pki` path. ```shell-session $ vault secrets enable pki - Success! Enabled the pki secrets engine at: pki/ ``` -Tune the PKI secrets engine to issue certificates with a maximum time-to-live (TTL) of `87600` hours. +Tune the PKI secrets engine to issue certificates with a maximum time-to-live (TTL) of `87600` hours (10 years). ```shell-session $ vault secrets tune -max-lease-ttl=87600h pki - Success! Tuned the secrets engine at: pki/ ``` - - -This tutorial uses a common and recommended pattern which is to have one mount act as the root CA and to use this CA only to sign intermediate CA CSRs from other PKI secrets engines (which you will create in the next few steps). For tighter security, you can store your CA outside of Vault and use the PKI engine only as an intermediate CA. - - - -## Configure Vault as Consul's CA - -Consul requires that all servers and clients have key pairs that are generated by a single Certificate Authority (CA). - -You will use Vault's PKI secrets engine to generate the necessary CA and certificates. - -#### 1. Generate the root CA - Generate the root certificate and save the certificate in `CA_cert.crt`. ```shell-session $ vault write -field=certificate pki/root/generate/internal \ - common_name="dc1.consul" \ - ttl=87600h > CA_cert.crt + common_name="consul" \ + issuer_name="root-CA" \ + ttl=87600h > CA_cert.crt ``` This generates a new self-signed CA certificate and private key. Vault will automatically revoke the generated root at the end of its lease period (TTL); the CA certificate will sign its own Certificate Revocation List (CRL). @@ -91,8 +76,8 @@ Configure the CA and CRL URLs. ```shell-session $ vault write pki/config/urls \ - issuing_certificates="http://127.0.0.1:8200/v1/pki/ca" \ - crl_distribution_points="http://127.0.0.1:8200/v1/pki/crl" + issuing_certificates="${VAULT_ADDR}/v1/pki/ca" \ + crl_distribution_points="${VAULT_ADDR}/v1/pki/crl" ``` Example output: @@ -100,26 +85,36 @@ Example output: ```plaintext -Success! Data written to: pki/config/urls +Key Value +--- ----- +crl_distribution_points [https://127.0.0.1:8200/v1/pki/crl] +delta_crl_distribution_points [] +enable_templating false +issuing_certificates [https://127.0.0.1:8200/v1/pki/ca] +ocsp_servers ``` -#### 2. Generate an intermediate CA +## Configure an intermediate CA + +You want the certificates signed by the intermediate CA to be signed by the root CA as well. + +Generate a Certificate Signing Request (CSR) and sign it with the root CA to generate the intermediate CA certificate. This way, if a security breach occurs, you can revoke all certificates issued by the intermediate CA directly from the root CA. + +### Enable Vault secret engine for the intermediate CA Enable the PKI secrets engine at the `pki_int` path. ```shell-session $ vault secrets enable -path=pki_int pki - Success! Enabled the pki secrets engine at: pki_int/ ``` -Tune the `pki_int` secrets engine to issue certificates with a maximum time-to-live (TTL) of `43800` hours. +Tune the `pki_int` secrets engine to issue certificates with a maximum time-to-live (TTL) of `43800` hours (5 years). ```shell-session $ vault secrets tune -max-lease-ttl=43800h pki_int - Success! Tuned the secrets engine at: pki_int/ ``` @@ -129,35 +124,56 @@ You can adapt the TTL to comply with your internal policies on certificate lifec -Request an intermediate certificate signing request (CSR) and save request as `pki_intermediate.csr`. +### Request a CSR for the intermediate CA + +Request a certificate signing request (CSR) for the intermediate CA and save request as `pki_intermediate.csr`. ```shell-session $ vault write -format=json pki_int/intermediate/generate/internal \ - common_name="dc1.consul Intermediate Authority" \ - | jq -r '.data.csr' > pki_intermediate.csr + common_name="dc1.consul Intermediate Authority" \ + issuer_name="intermediate-CA" \ + | jq -r '.data.csr' > pki_intermediate.csr ``` The command has no output. -#### 3. Sign the CSR and import the certificate into Vault +### Sign the CSR and import the certificate into Vault + +First, sign the CSR producing a a `pem` file. ```shell-session -$ vault write -format=json pki/root/sign-intermediate csr=@pki_intermediate.csr \ - format=pem_bundle ttl="43800h" \ - | jq -r '.data.certificate' > intermediate.cert.pem +$ vault write -format=json pki/root/sign-intermediate \ + issuer_ref="root-CA" \ + csr=@pki_intermediate.csr \ + format=pem_bundle ttl="43800h" \ + | jq -r '.data.certificate' > intermediate.cert.pem ``` The command has no output. -Once the CSR is signed, and the root CA returns a certificate, it can be imported back into Vault. +Once the CSR is signed, and the root CA returns a certificate, import it back into Vault. ```shell-session $ vault write pki_int/intermediate/set-signed certificate=@intermediate.cert.pem +``` + +Example output: -Success! Data written to: pki_int/intermediate/set-signed + + +```plaintext +Key Value +--- ----- +existing_issuers +existing_keys +imported_issuers [44d38d6c-14f4-38f4-1a40-95cd8cc04815 09a129d4-b853-ff48-efe9-3700f6b941cf] +imported_keys +mapping map[09a129d4-b853-ff48-efe9-3700f6b941cf: 44d38d6c-14f4-38f4-1a40-95cd8cc04815:48418626-88f5-22f4-348c-1841be4b3cc4] ``` -#### 4. Create a Vault role + + +## Create a Vault role A role is a logical name that maps to a policy used to generate credentials. @@ -174,12 +190,61 @@ Example output: ```plaintext -Success! Data written to: pki_int/roles/consul-dc1 +Key Value +--- ----- +allow_any_name false +allow_bare_domains false +allow_glob_domains false +allow_ip_sans true +allow_localhost true +allow_subdomains true +allow_token_displayname false +allow_wildcard_certificates true +allowed_domains [dc1.consul] +allowed_domains_template false +allowed_other_sans [] +allowed_serial_numbers [] +allowed_uri_sans [] +allowed_uri_sans_template false +allowed_user_ids [] +basic_constraints_valid_for_non_ca false +client_flag true +cn_validations [email hostname] +code_signing_flag false +country [] +email_protection_flag false +enforce_hostnames true +ext_key_usage [] +ext_key_usage_oids [] +generate_lease true +issuer_ref default +key_bits 2048 +key_type rsa +key_usage [DigitalSignature KeyAgreement KeyEncipherment] +locality [] +max_ttl 720h +no_store false +not_after n/a +not_before_duration 30s +organization [] +ou [] +policy_identifiers [] +postal_code [] +province [] +require_cn true +serial_number_source json-csr +server_flag true +signature_bits 256 +street_address [] +ttl 0s +use_csr_common_name true +use_csr_sans true +use_pss false ``` -For this guide, you are using the following options for the role: +You are using the following options for the role: - `allowed_domains`: Specifies the domains of the role. The command uses `dc1.consul` as the domain, which is the default configuration you are going to use for Consul. - `allow_subdomains`: Specifies if clients can request certificates with CNs that are subdomains of the CNs allowed by the other role options @@ -194,19 +259,19 @@ For this guide, you are using the following options for the role: This completes the Vault configuration as a CA. -## Generate a server certificate +## Generate certificates for Consul -You can test the `pki` engine is configured correctly by generating your first certificate. +Test the `pki` engine configuration by generating your first certificate. ```shell-session $ vault write pki_int/issue/consul-dc1 \ - common_name="server.dc1.consul" \ - ttl="24h" | tee certs.txt + common_name="server.dc1.consul" \ + ttl="24h" | tee certs.txt ``` -The TTL for the certificate is being set to 24 hours in this guide, meaning that this certificate will be valid only for 24 hours before expiring. You can try using a shorter TTL on a test environment to ensure certificates are revoked properly after TTL is expired. +The TTL for the certificate is being set to 24 hours in this guide, meaning that this certificate will be valid only for 24 hours before expiring. Try using a shorter TTL on a test environment to ensure certificates are revoked properly after TTL is expired. @@ -217,34 +282,43 @@ Example output: ```plaintext Key Value --- ----- -lease_id pki_int/issue/consul-dc1/lFfKfpxtM0xY0AHDlr9pJ2GM +lease_id pki_int/issue/consul-dc1/Oip6uSVy9A4Y6RbPdEv7WuUf lease_duration 23h59m59s lease_renewable false ca_chain [-----BEGIN CERTIFICATE----- -##... +MIIDojCCAoqgAwIBAgIUBHQpzIb+3nN64cjTXhyHwTkz+G0wDQYJKoZIhvcNAQEL +BQAwETEPMA0GA1UEAxMGY29uc3VsMB4XDTI1MTEyMDE0NTYyOVoXDTMwMTExOTE0 +NTY1OVowLDEqMCgGA1UEAxMhZGMxLmNvbnN1bCBJbnRlcm1lZGlhdGUgQXV0aG9y +aXR5MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApu82Atvb913IGMZM +6vGu8ZkvqAVvGjqsj1/ciIyR55LSD6Wt9jknMWovX2YvIW5xN36ApEpWeQpccRzc +## ... +-----END CERTIFICATE----- -----BEGIN CERTIFICATE----- +## ... -----END CERTIFICATE-----] certificate -----BEGIN CERTIFICATE----- -##... +## ... -----END CERTIFICATE----- -expiration 1599645187 +expiration 1763737500 issuing_ca -----BEGIN CERTIFICATE----- -##... +## ... -----END CERTIFICATE----- private_key -----BEGIN RSA PRIVATE KEY----- -##... +## ... -----END RSA PRIVATE KEY----- private_key_type rsa -serial_number 3f:ec:bd:ea:01:a6:35:49:a7:6d:17:ba:13:88:c1:b8:35:b4:fc:4c +serial_number 48:91:a9:7b:d0:a6:10:93:98:0f:ca:dc:ea:83:14:42:8e:c8:ef:e0 ``` -## Configure Consul +### Configure Consul + +Use the certificate to configure Consul agents. -Configure Consul TLS using the following configuration: +Configure Consul server TLS stanza using the following `tls` stanza: @@ -254,9 +328,9 @@ tls { verify_incoming = true verify_outgoing = true verify_server_hostname = true - ca_file = "/opt/consul/agent-certs/ca.crt" - cert_file = "/opt/consul/agent-certs/agent.crt" - key_file = "/opt/consul/agent-certs/agent.key" + ca_file = "/etc/consul.d/ca.crt" + cert_file = "/etc/consul.d/agent.crt" + key_file = "/etc/consul.d/agent.key" } } @@ -272,9 +346,9 @@ auto_encrypt { "verify_incoming": true, "verify_outgoing": true, "verify_server_hostname": true, - "ca_file": "/opt/consul/agent-certs/ca.crt", - "cert_file": "/opt/consul/agent-certs/agent.crt", - "key_file": "/opt/consul/agent-certs/agent.key" + "ca_file": "/etc/consul.d/ca.crt", + "cert_file": "/etc/consul.d/agent.crt", + "key_file": "/etc/consul.d/agent.key" } }, "auto_encrypt": { @@ -299,25 +373,25 @@ Use the following commands to extract the two certificates and private key from Create the certificates folder. ```shell-session -$ mkdir -p /opt/consul/agent-certs +$ mkdir -p /etc/consul.d ``` Extract the root CA certificate. ```shell-session -$ grep -Pzo "(?s)(?<=issuing_ca)[^\-]*.*?END CERTIFICATE[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /opt/consul/agent-certs/ca.crt +$ grep -Pzo "(?s)(?<=issuing_ca)[^\-]*.*?END CERTIFICATE[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /etc/consul.d/ca.crt ``` Extract the agent certificate. ```shell-session -$ grep -Pzo "(?s)(?<=certificate)[^\-]*.*?END CERTIFICATE[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /opt/consul/agent-certs/agent.crt +$ grep -Pzo "(?s)(?<=certificate)[^\-]*.*?END CERTIFICATE[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /etc/consul.d/agent.crt ``` Extract the agent key. ```shell-session -$ grep -Pzo "(?s)(?<=private_key)[^\-]*.*?END RSA PRIVATE KEY[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /opt/consul/agent-certs/agent.key +$ grep -Pzo "(?s)(?<=private_key)[^\-]*.*?END RSA PRIVATE KEY[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /etc/consul.d/agent.key ``` @@ -329,9 +403,9 @@ This section describes the automated [client certificate deployment process](/co -With auto-encryption, you can configure the Consul servers to automatically distribute certificates to the clients. To use this feature, you will need to configure clients to automatically get the certificates from the server. +With auto-encryption, you can configure the Consul servers to automatically distribute certificates to the clients. To use this feature, configure clients to automatically get the certificates from the server. -Configure Consul client TLS using the following configuration: +Configure Consul client TLS using the following `tls` stanza: @@ -341,7 +415,7 @@ tls { verify_incoming = true verify_outgoing = true verify_server_hostname = true - ca_file = "/opt/consul/agent-certs/ca.crt" + ca_file = "/etc/consul.d/ca.crt" } } @@ -357,7 +431,7 @@ auto_encrypt { "verify_incoming": true, "verify_outgoing": true, "verify_server_hostname": true, - "ca_file": "/opt/consul/agent-certs/ca.crt", + "ca_file": "/etc/consul.d/ca.crt", } }, "auto_encrypt": { @@ -378,19 +452,19 @@ Use the following commands to extract the certificate from the `certs.txt` and p Create the certificates folder. ```shell-session -$ mkdir -p /opt/consul/agent-certs +$ mkdir -p /etc/consul.d ``` Extract the root CA certificate. ```shell-session -$ grep -Pzo "(?s)(?<=certificate)[^\-]*.*?END CERTIFICATE[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /opt/consul/agent-certs/agent.crt +$ grep -Pzo "(?s)(?<=certificate)[^\-]*.*?END CERTIFICATE[^\n]*\n" certs.txt | sed 's/^\s*-/-/g' > /etc/consul.d/agent.crt ``` -## Configure Consul Template +## Automate certificate rotation with consul-template The guide steps used `ttl="24h"` ad a parameter during certificate creation, meaning that this certificates will be valid only for 24 hours before expiring. @@ -398,7 +472,7 @@ Deciding the right trade-off for certificate lifespan is always a compromise bet ### Create template files -You can instruct Consul Template to generate and retrieve those files from Vault using the following templates: +Instruct Consul Template to generate and retrieve those files from Vault using the following templates: @@ -434,11 +508,10 @@ The same endpoint also exposes the CA certificate under the `.Data.issuing_ca` p - Copy the newly created files into `/opt/consul/templates`. ```shell-session -$ cp *.tpl /opt/consul/templates/ +$ cp *.tpl /opt/consul-template/ ``` ### Create Consul Template configuration @@ -456,7 +529,7 @@ Create a configuration file, `consul_template.hcl`, that will instruct Consul Te vault { # This is the address of the Vault leader. The protocol (http(s)) portion # of the address is required. - address = "http://localhost:8200" + address = "https://localhost:8200" # This value can also be specified via the environment variable VAULT_TOKEN. token = "root" @@ -471,12 +544,12 @@ vault { template { # This is the source file on disk to use as the input template. This is often # called the "consul-template template". - source = "agent.crt.tpl" + source = "/opt/consul-template/agent.crt.tpl" # This is the destination path on disk where the source template will render. # If the parent directories do not exist, consul-template will attempt to # create them, unless create_dest_dirs is false. - destination = "/opt/consul/agent-certs/agent.crt" + destination = "/etc/consul.d/agent.crt" # This is the permission to render the file. If this option is left # unspecified, consul-template will attempt to match the permissions of the @@ -490,23 +563,22 @@ template { } template { - source = "agent.key.tpl" - destination = "/opt/consul/agent-certs/agent.key" + source = "/opt/consul-template/agent.key.tpl" + destination = "/etc/consul.d/agent.key" perms = 0700 command = "sh -c 'date && consul reload'" } template { - source = "ca.crt.tpl" - destination = "/opt/consul/agent-certs/ca.crt" + source = "/opt/consul-template/ca.crt.tpl" + destination = "/etc/consul.d/ca.crt" command = "sh -c 'date && consul reload'" } ``` -The configuration file for the server contains the information to retrieve the -CA certificate as well as the certificate/key pair for the server agent. +The configuration file for the server contains the information to retrieve the CA certificate as well as the certificate/key pair for the server agent. @@ -520,7 +592,7 @@ CA certificate as well as the certificate/key pair for the server agent. vault { # This is the address of the Vault leader. The protocol (http(s)) portion # of the address is required. - address = "http://localhost:8200" + address = "https://localhost:8200" # This value can also be specified via the environment variable VAULT_TOKEN. token = "root" @@ -531,16 +603,15 @@ vault { } template { - source = "ca.crt.tpl" - destination = "/opt/consul/agent-certs/ca.crt" + source = "/opt/consul-template/ca.crt.tpl" + destination = "/etc/consul.d/ca.crt" command = "sh -c 'date && consul reload'" } ``` -The configuration file for the client contains the information to retrieve the CA certificate only, the certificates for client agents are automatically -generated from Consul when using the `auto_encrypt` setting. +The configuration file for the client contains the information to retrieve the CA certificate only, the certificates for client agents are automatically generated from Consul when using the `auto_encrypt` setting. @@ -574,29 +645,46 @@ The certificate you created manually for the Consul server had a TTL of 24 hours This means that after the certificate expires Vault will renew it and Consul Template will update the files on your agent it reload Consul configuration automatically to make it pick up the new files. -You can verify the rotation by checking that Consul Template keeps listing, every 24 hours, a timestamp and the log line: +Verify the rotation by checking that Consul Template keeps listing, every 24 hours, a timestamp and the log line: ```plaintext hideClipboard Configuration reload triggered ``` -You can also use `openssl` to verify the certificate content: +Use `openssl` to verify the certificate content: ```shell-session -$ openssl x509 -text -noout -in /opt/consul/agent-certs/agent.crt +$ openssl x509 -text -noout -in /etc/consul.d/agent.crt +``` + +Verify in the output that the `Not Before` and `Not After` values are being updated to reflect the new certificate. + + +```plaintext Certificate: Data: Version: 3 (0x2) Serial Number: - 1b:2d:d6:5d:63:9b:aa:05:84:7b:be:3b:6f:e1:95:bb:1c:36:8c:a4 - Signature Algorithm: sha256WithRSAEncryption + 0a:06:b2:62:56:d1:7d:e6:5c:67:f7:89:06:8a:3e:5b:f1:fa:7e:00 + Signature Algorithm: sha256WithRSAEncryption Issuer: CN=dc1.consul Intermediate Authority Validity - Not Before: Sep 16 16:03:45 2020 GMT - Not After : Sep 16 16:06:15 2020 GMT + Not Before: Nov 25 11:48:06 2025 GMT + Not After : Nov 25 12:48:06 2025 GMT Subject: CN=server.dc1.consul -... +## ... ``` -and verify that the `Not Before` and `Not After` values are being updated to reflect the new certificate. + + +## Next steps + +In this page, you learned how to generate Consul TLS certificates using Vault's PKI secret engine and to automatically rotate them using Consul Template. + +If you want to automate Consul's gossip encryption using Vault and `consul-template` refer to [Generate and manage gossip encryption for Consul with Vault and Consul Template](/consul/docs/automate/consul-template/vault/gossip). + +To learn how to use Vault to generate and manage Consul's ACL tokens, refer to [Use Vault for ACL management with Consul on VMs](/consul/docs/secure/acl/vault/vm). + +If you are running Consul in Kubernetes, you can [use Vault for secrets management with Consul on Kubernetes](/consul/docs/integrate/vault/k8s). + diff --git a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx index 6ad694be6f..1d773486dc 100644 --- a/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx +++ b/content/consul/v1.22.x/content/docs/automate/consul-template/vault/mtls.mdx @@ -578,8 +578,7 @@ template { -The configuration file for the server contains the information to retrieve the -CA certificate as well as the certificate/key pair for the server agent. +The configuration file for the server contains the information to retrieve the CA certificate as well as the certificate/key pair for the server agent. @@ -612,8 +611,7 @@ template { -The configuration file for the client contains the information to retrieve the CA certificate only, the certificates for client agents are automatically -generated from Consul when using the `auto_encrypt` setting. +The configuration file for the client contains the information to retrieve the CA certificate only, the certificates for client agents are automatically generated from Consul when using the `auto_encrypt` setting.