consul-cookbook

Installs and configures Consul client, server and UI.

Supported Platforms

• CentOS 6.5, 7.0
• RHEL 6.5, 7.0
• Ubuntu 12.04, 14.04
• Arch Linux

Attributes

Key	Type	Description	Default
['consul']['version']	String	Version to install	0.5.0
['consul']['base_url']	String	Base URL for binary downloads	https://dl.bintray.com/mitchellh/consul/
['consul']['encrypt']	String	Encryption string for consul cluster.	nil
['consul']['install_method']	String	Method to install consul with when using default recipe: binary or source	binary
['consul']['install_dir']	String	Directory to install binary to.	/usr/local/bin
['consul']['service_mode']	String	Mode to run consul as: bootstrap, cluster, server, or client	bootstrap
['consul']['bootstrap_expect']	String	When bootstrapping a cluster, the number of server nodes to expect.	nil
['consul']['data_dir']	String	Location to store consul's data in	/var/lib/consul
['consul']['config_dir']	String	Location to read service definitions from (directoy will be created)	/etc/consul.d
['consul']['servers']	Array Strings	Consul servers to join	[]
['consul']['retry_on_join']	Boolean	Set to true to wait for servers to be up before try to elect a leader	false
['consul']['bind_addr']	String	address that should be bound to for internal cluster communications	0.0.0.0
['consul']['datacenter']	String	Name of Datacenter	dc1
['consul']['domain']	String	Domain for service lookup dns queries	.consul
['consul']['enable_syslog']	Boolean	enables logging to syslog	nil
['consul']['log_level']	String	The level of logging to show after the Consul agent has started. Available: "trace", "debug", "info", "warn", "err"	info
['consul']['node_name']	String	The name of this node in the cluster	hostname of the machine
['consul']['advertise_addr']	String	address that we advertise to other nodes in the cluster	Value of bind_addr
['consul']['init_style']	String	Service init mode for running consul as: init, runit or systemd	init
['consul']['service_user']	String	For runit/systemd service: run consul as this user (init uses 'root')	consul
['consul']['service_group']	String	For runit/systemd service: run consul as this group (init uses 'root')	consul
['consul']['bind_interface']	String	Interface to bind to, such as 'eth1'. Sets bind_addr attribute to the IP of the specified interface if it exists.	nil
['consul']['advertise_interface']	String	Interface to advertise, such as 'eth1'. Sets advertise_addr attribute to the IP of the specified interface if it exists.	nil
['consul']['extra_params']	hash	Pass a hash of extra params to the default.json config file	{}
['consul']['encrypt_enabled']	Boolean	To enable Consul gossip encryption	false
['consul']['verify_incoming']	Boolean	If set to True, Consul requires that all incoming connections make use of TLS.	false
['consul']['verify_outgoing']	Boolean	If set to True, Consul requires that all outgoing connections make use of TLS.	false
['consul']['key_file']	String	The content of PEM encoded private key	nil
['consul']['key_file_path']	String	Path where the private key is stored on the disk	/etc/consul.d/key.pem
['consul']['ca_file']	String	The content of PEM encoded ca cert	nil
['consul']['ca_file_path']	String	Path where ca is stored on the disk	/etc/consul.d/ca.pem
['consul']['cert_file']	String	The content of PEM encoded cert. It should only contain the public key.	nil
['consul']['cert_file_path']	String	Path where cert is stored on the disk	/etc/consul.d/cert.pem
['consul']['statsd_addr']	String	This provides the address of a statsd instance (UDP).	nil
['consul']['atlas_autojoin']	Boolean	Determines whether Consul attempts to auto-join the cluster provided by atlas_cluster using the value of atlas_token	false
['consul']['atlas_cluster']	String	Name of Atlas cluster to auto-join	nil
['consul']['atlas_token']	String	API token used for Atlas integration	nil

Databag Attributes (optional)

Following attributes, if exist in the encrypted databag, override the node attributes

Key	Databag item	Type	Description
key_file	['consul']['encrypt']	String	The content of PEM encoded private key
key_file_{fqdn}	['consul']['encrypt']	String	Node's(identified by fqdn) unique PEM encoded private key. If it exists, it will override the databag and node key_file attribute
ca_file	['consul']['encrypt']	String	The content of PEM encoded ca cert
encrypt	['consul']['encrypt']	String	Consul Gossip encryption key
cert_file	['consul']['encrypt']	String	The content of PEM encoded cert
cert_file_{fqdn}	['consul']['encrypt']	String	Node's(identified by fqdn) unique PEM encoded cert. If it exists, it will override the databag and node cert_file attribute

Consul UI Attributes

Key	Type	Description	Default
['consul']['client_addr']	String	Address to bind to	0.0.0.0
['consul']['client_interface']	String	Interface to advertise, such as 'eth1'. Sets advertise_addr attribute to the IP of the specified interface if it exists.	nil
['consul']['serve_ui']	Boolean	Determines whether the consul service also serve's the UI	false

Usage

The easiest way to bootstrap a cluster is to use the cluster recipe and use Chef provisioning which is a relatively new extension. This extension allows you to use any driver and easily stand up a cluster. Once the Chef Development Kit has been installed you can run the following command to provision a cluster.

gem install chef-provisioning chef-provisioning-fog
export CHEF_DRIVER=fog:AWS
chef-client -z cluster.rb

Please follow the Chef provisioning README which provides more detailed information about provisioning. You'll need to configure your credentials prior to provisioning.

consul::default

The default recipe will install the Consul agent using the consul::install_binary recipe. It will also configure and start consul at the machine boot.

consul::install_binary

If you only wish to simply install the binary from the official mirror you simply include consul::install_binary in your node's run_list:

{
  "run_list": [
    "recipe[consul::install_binary]"
  ]
}

consul::install_source

Instead if you wish to install Consul from source you simply need to include consul::install_source in your node's run_list. This will also configure the Go language framework on the node to build the application.

{
  "run_list": [
    "recipe[consul::install_source]"
  ]
}

consul::ui

Installing the separate Consul UI simply requires you to include the consul::ui recipe in your node's run_list.

{
  "run_list": [
    "recipe[consul::ui]"
  ]
}

LWRP

Adding key watch

consul_key_watch_def 'key-watch-name' do
  key "/key/path"
  handler "chef-client"
end

Adding event watch

consul_event_watch_def 'event-name' do
  handler "chef-client"
end

Adding services watch

consul_services_watch_def 'services-name' do
  handler "chef-client"
end

Adding service watch

consul_service_watch_def 'service-name' do
	  passingonly true
  handler "chef-client"
end

Adding service without check

consul_service_def 'voice1' do
  port 5060
  tags ['_sip._udp']
  notifies :reload, 'service[consul]'
end

Adding services with checks

consul_service_def 'voice1' do
  port 5060
  tags ['_sip._udp']
  check(
    interval: '10s',
    script: 'echo ok'
  )
  notifies :reload, 'service[consul]'
end

consul_service_def 'server1' do
  port 80
  tags ['http']
  check(
    interval: '10s',
    http: 'http://localhost:80'
  )
  notifies :reload, 'service[consul]'
end

Removing service

consul_service_def 'voice1' do
  action :delete
  notifies :reload, 'service[consul]'
end

Be sure to notify the Consul resource to restart when your service def changes.

Getting Started

To bootstrap a consul cluster follow the following steps: 0. Make sure that ports 8300-8302 (by default, if you configured different ones open those) UDP/TCP are all open.

1. Bootstrap a few (preferablly 3 nodes) to be your consul servers, these will be the KV masters.
2. Put node['consul']['servers'] =["Array of the bootstrapped servers ips or dns names"] in your environment.
3. Apply the consul cookbook to these nodes with node['consul']['service_mode'] = 'cluster' (I put this in this in a CONSUL_MASTER role).
4. Let these machines converge, once you can run consul members and get a list of all of the servers your ready to move on
5. Apply the consul cookbook to the rest of your nodes with node['consul']['service_mode'] = 'client' (I put this in the environment)
6. Start adding services and checks to your cookbooks.
7. If you want to get values out of consul to power your chef, curl localhost:8500/v1/kv/key/path?raw in your cookbook.

Authors

Created and maintained by John Bellone @johnbellone (jbellone@bloomberg.net) and a growing community of contributors.