Security Configuration for Consul

Page last updated: December 11, 2015

As of cf-release v217, Cloud Foundry enables secure traffic between Consul agents by default using encryption and mutual authentication. Follow the instructions below to configure security for Consul. You can configure Consul to be secure or insecure, but we strongly recommend that you configure Consul to be secure.

Configure Secure Mode

1. Generate SSL Certificates and Keys:

   To generate the certificates and keys that you need for Consul, we recommend using certstrap. The cf-release repository contains a helper script, scripts/generate-consul-certs. This script uses certstrap to initialize a certificate authority (CA), and generate the certificates and keys for Consul.
   
   If you already have a CA, you may have an existing workflow. You can modify the generate-consul-certs script to use your existing CA instead of generating a new one.
   
   The generate-consul-certs script outputs files to the ./consul-certs directory.

2. Generate Gossip Encryption Keys:

   Run cat /dev/urandom | head -c 16 | base64 to generate and display a random 16-byte Base64-encoded value.

   $ cat /dev/urandom | head -c 16 | base64
   8b9IJjXH5aN2Z9A5H8HAmg==
   

3. Update Your Stub File:

   Copy the contents of the files in the ./consul-certs directory, as well as the value for your Gossip encryption key, into your stub.

Configure Insecure Mode

1. Remove all the key- and ceritificate-related properties for Consul in your stub.

2. Add the following property to your stub:

   properties:
     ...
     consul:
       ...
       require_ssl: false
   

SSL Certificate, Key, and Certificate Authority Rotation

To rotate your SSL certificates, keys, and certificate authorities, you must perform the following steps.

1. Add the certificates, keys, and certificate authorities that you want to rotate to your stub file.
   
   You must add your new agent_key, server_key, and ca_cert above the existing certificates. Do not remove the existing certificates.

   ...
   properties:
     ...
     consul:
       ...
       encrypt_keys:
       - RANDOM-16-BYTE-BASE64-ENCODED-VALUE
       ca_cert: |
         -----BEGIN CERTIFICATE-----
         ###########################################################
         #######           Your New CA Certificate           #######
         ###########################################################
         -----END CERTIFICATE-----
         -----BEGIN CERTIFICATE-----
         ###########################################################
         #######           Your Old CA Certificate           #######
         ###########################################################
         -----END CERTIFICATE-----
       agent_cert: |
         ----BEGIN CERTIFICATE----
         ###########################################################
         #######           Your New Agent Certificate        #######
         ###########################################################
         ----END CERTIFICATE----
         ----BEGIN CERTIFICATE----
         ###########################################################
         #######           Your Old Agent Certificate        #######
         ###########################################################
         ----END CERTIFICATE----
       agent_key: |
         ----BEGIN CERTIFICATE----
         ###########################################################
         #######           Your New Agent Key                #######
         ###########################################################
         ----END CERTIFICATE----
         ----BEGIN CERTIFICATE----
         ###########################################################
         #######           Your Old Agent Key                #######
         ###########################################################
         ----END CERTIFICATE----
       server_cert: |
         ----BEGIN CERTIFICATE----
         ###########################################################
         #######           Your New Server Certificate       #######
         ###########################################################
         ----END CERTIFICATE----
         ----BEGIN CERTIFICATE----
         ###########################################################
         #######           Your Old Server Certificate       #######
         ###########################################################
       server_key: |
         ----BEGIN CERTIFICATE----
         ###########################################################
         #######           Your New Server Key               #######
         ###########################################################
         ----END CERTIFICATE----
         ----BEGIN CERTIFICATE----
         ###########################################################
         #######           Your Old Server Key               #######
         ###########################################################
         ----END CERTIFICATE----
   

2. Use the instructions for your infrastructure to generate a deployment manifest with your edited stub file.

3. Deploy Cloud Foundry using this deployment manifest.

4. After you have deployed Cloud Foundry with the new manifest, remove the old certificates and keys.

   properties:
     consul:
       encrypt_keys:
       - RANDOM-16-BYTE-BASE64-ENCODED-VALUE
       ca_cert: |
         -----BEGIN CERTIFICATE-----
         ###########################################################
         #######           Your New CA Certificate           #######
         ###########################################################
         -----END CERTIFICATE-----
       agent_cert: |
         ----BEGIN CERTIFICATE----
         ###########################################################
         #######           Your New Agent Certificate        #######
         ###########################################################
         ----END CERTIFICATE----
       agent_key: |
         ----BEGIN CERTIFICATE----
         ###########################################################
         #######           Your New Agent Key                #######
         ###########################################################
         ----END CERTIFICATE----
       server_cert: |
         ----BEGIN CERTIFICATE----
         ###########################################################
         #######           Your New Server Certificate       #######
         ###########################################################
         ----END CERTIFICATE----
         ----BEGIN CERTIFICATE----
         ###########################################################
         #######           Your New CA Certificate           #######
         ###########################################################
         ----END CERTIFICATE----
       server_key: |
         ----BEGIN CERTIFICATE----
         ###########################################################
         #######           Your New Server Key               #######
         ###########################################################
         ----END CERTIFICATE----