Security Configuration for Consul

Page last updated:

This topic describes how to configure security for the Consul agents that run on all Cloud Foundry VMs. Consul secures traffic between VMs by using encryption and mutual authentication.

Configure Security

To configure security for Consul, you must generate SSL certificates and keys, create Gossip encryption keys, and update your deployment manifest or manifest stub file by including the new keys.

Generate SSL Certificates and Keys

To generate the certificates and keys that you need for Consul, we recommend that you use the generate-consul-certs script in the scripts subdirectory of the cf-release repository.

The generate-consul-certs script uses certstrap to create a certificate authority (CA) and generate the certificates and keys that Consul needs. It then saves the files to the ./consul-certs directory.

If you already have a CA that you want to use, 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. Run bosh deployments to get a list of all the deployments that BOSH is running.

  2. For each deployment:

    1. Run bosh manifest (bosh download manifest for BOSH v1) to retrieve the manifest file for the deployment.
    2. Append the CA certificate to the ca_cert field of your manifest file. Do not remove any existing CA certificates.

      ...
      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-----
      
    3. Deploy Cloud Foundry using your updated manifest.

  3. After redeploying all deployments with the new CA certificates, you can rotate all the SSL certs and keys. For each deployment:

    1. Replace the old server and agent certificates and keys with the new certificates and keys.

      ...
      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-----
      
    2. Deploy Cloud Foundry using your updated manifest.

    3. Remove your old CA Certificate.

      ...
      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-----
      
    4. Deploy Cloud Foundry using your updated manifest.

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