Security Configuration for Consul

Page last updated:

Cloud Foundry requires traffic to be secure between Consul agents by using encryption and mutual authentication. Follow the instructions below to configure security for Consul.

Configure Security

To configure security for Consul, you must generate SSL certificates and keys, create Gossip encryption keys, and update your stub file.

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.

The generate-consul-certs script outputs files to the ./consul-certs directory.

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 creating a new one.

Create Gossip Encryption Keys

To create an encryption key for use in the Serf gossip protocol, provide an arbitrary string value. The consul agent job template transforms the string you provide into a 16-byte Base64-encoded value for consumption by the consul process.

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.

Rotate SSL Certificate, Key, and Certificate Authority

Perform the steps below to rotate your SSL certificates, keys, and certificate authorities.

  1. Append the CA certificate to the ca_cert field of your manifest file. Do not remove any existing CA certificates. Deploy Cloud Foundry using your updated manifest.

    ...
    properties:
      ...
      consul:
        ...
        encrypt_keys:
        - RANDOM-SECRET-VALUE
        ca_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your Old CA Certificate           #######
          ###########################################################
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New CA Certificate           #######
          ###########################################################
          -----END CERTIFICATE-----
        agent_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your Old Agent Certificate        #######
          ###########################################################
          -----END CERTIFICATE-----
        agent_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ###########################################################
          #######           Your Old Agent Key                #######
          ###########################################################
          -----END RSA PRIVATE KEY-----
        server_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your Old Server Certificate       #######
          ###########################################################
          -----END CERTIFICATE-----
        server_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ###########################################################
          #######           Your Old Server Key               #######
          ###########################################################
          -----END RSA PRIVATE KEY-----
    
  2. Replace the old server and agent certificates and keys with the new certificates and keys. Deploy Cloud Foundry using your updated manifest.

    ...
    properties:
      ...
      consul:
        ...
        encrypt_keys:
        - RANDOM-SECRET-VALUE
        ca_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your Old CA Certificate           #######
          ###########################################################
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New CA Certificate           #######
          ###########################################################
          -----END CERTIFICATE-----
        agent_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New Agent Certificate        #######
          ###########################################################
          -----END CERTIFICATE-----
        agent_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ###########################################################
          #######           Your New Agent Key                #######
          ###########################################################
          -----END RSA PRIVATE KEY-----
        server_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New Server Certificate       #######
          ###########################################################
          -----END CERTIFICATE-----
        server_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ###########################################################
          #######           Your New Server Key               #######
          ###########################################################
          -----END RSA PRIVATE KEY-----
    
  3. Remove your old CA Certificate. Deploy Cloud Foundry using your updated manifest.

    ...
    properties:
      ...
      consul:
        ...
        encrypt_keys:
        - RANDOM-SECRET-VALUE
        ca_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New CA Certificate           #######
          ###########################################################
          -----END CERTIFICATE-----
        agent_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New Agent Certificate        #######
          ###########################################################
          -----END CERTIFICATE-----
        agent_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ###########################################################
          #######           Your New Agent Key                #######
          ###########################################################
          -----END RSA PRIVATE KEY-----
        server_cert: |
          -----BEGIN CERTIFICATE-----
          ###########################################################
          #######           Your New Server Certificate       #######
          ###########################################################
          -----END CERTIFICATE-----
        server_key: |
          -----BEGIN RSA PRIVATE KEY-----
          ###########################################################
          #######           Your New Server Key               #######
          ###########################################################
          -----END RSA PRIVATE KEY-----
    

Rotate Encryption Key

To rotate your encryption key, perform the steps below.

  1. In the encrypt_keys field of your manifest, insert the new encryption key above the old encryption key. Do not remove old encryption key.

    ...
    properties:
      ...
      consul:
        ...
        encrypt_keys:
        - NEW-ENCRYPT-KEY
        - OLD-ENCRYPT-KEY
        ...
    
  2. Deploy Cloud Foundry using your updated manifest.

  3. Remove the old encryption key from your manifest.

    ...
    properties:
      ...
      consul:
        ...
        encrypt_keys:
        - NEW-ENCRYPT-KEY
        ...
    
  4. Deploy Cloud Foundry using your updated manifest.

Create a pull request or raise an issue on the source for this page in GitHub