Skip to content
Wrapper cookbook which installs and configures a Consul cluster.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
attributes add ssl_chain name attribute which is needed to create file Jun 13, 2016
recipes Update cookbook readme for release. Apr 19, 2016
.foodcritic Initial commit of the consul-cluster cookbook. Aug 12, 2015
.gitignore Remove binstubs from the project. Apr 19, 2016
.rubocop.yml Add ssl_certificate cookbook for managing tls. Mar 29, 2016
Gemfile Update integration testing harness and such. Apr 14, 2016
LICENSE Fix name of cluster in example for policyfile. Apr 19, 2016
Rakefile Add ssl_certificate cookbook for managing tls. Mar 29, 2016
metadata.rb Bump cookbook version to 2.1 (#6) Mar 21, 2018

consul-cluster cookbook

Cluster cookbook which installs and configures a Consul cluster with TLS certificates.

This cookbook utilizies the Consul application cookbook to bootstrap and maintain Consul server infrastructure. It is intended as an example usage of the wrapper cookbook pattern and should hopefully serve as a basis for production infrastructure.


The default recipe in this cookbook is designed to install and configure the Consul agent to bootstrap a cluster. The minimum number of nodes necessary for the infrastructure is three. After three nodes have been setup and configured Consul will bootstrap the Cluster.

Chef Vault and TLS

By default, the Consul Cluster cookbook uses Chef Vault to encrypt the TLS certificates and keys that are deployed to the nodes. This data should only be capable of being decrypted by the nodes the Consul Cluster itself.

    "ca_certificate": "-----BEGIN CERTIFICATE-----\nMIIE [...]",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIE [...]",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIE [...]"

Preparing the Instance

There are many configuration options that are exposed using the Consul application cookbook that can be set in either a wrapper cookbook, a Chef environment or a Policyfile. But it is good form to not keep secret information inside of a repository (or not encrypted in the Chef Server).

The following configuration file can be written to the instances to set cluster's datacenter and encryption key for the gossip protocol. This file should be written to /etc/consul/conf.d/server.json on each of the nodes.

    "datacenter": "us-east-1",
    "encrypt": "RxNBbMMl3m/cSOdjKDhATg=="

Using Policyfiles

It is extremely simple to use Chef Policyfiles to configure your three nodes which formulates your Consul cluster. Using the chef update and chef push commands you can push the below policy to a Chef Server. A more detailed explanation of how to use these commands is for the chef CLI documentation.

name consul-cluster'
default_source :community
cookbook 'consul-cluster', '~> 2.0'
run_list 'consul-cluster::default'

override['consul']['version'] = '0.6.4'
override['consul']['config']['bootstrap_expect'] = 3
override['consul']['config']['start_join'] = %w{}

Test Kitchen

If you are looking to execute the integration tests you must first configure the policyfile that ships with the test fixtures.

~/Projects/consul-cluster-cookbook % chef install test/fixtures/policies/default.rb
~/Projects/consul-cluster-cookbook % kitchen converge ubuntu-1404
You can’t perform that action at this time.