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 |
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 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.
- Bootstrap a few (preferablly 3 nodes) to be your consul servers, these will be the KV masters.
- Put
node['consul']['servers'] =["Array of the bootstrapped servers ips or dns names"]
in your environment. - Apply the consul cookbook to these nodes with
node['consul']['service_mode'] = 'cluster'
(I put this in this in a CONSUL_MASTER role). - Let these machines converge, once you can run
consul members
and get a list of all of the servers your ready to move on - Apply the consul cookbook to the rest of your nodes with
node['consul']['service_mode'] = 'client'
(I put this in the environment) - Start added services and checks to your cookbooks.
- 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.