Adoptable Cookbooks List

Looking for a cookbook to adopt? You can now see a list of cookbooks available for adoption!
List of Adoptable Cookbooks

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

Select Badges

Select Supported Platforms

RSS

consul (40) Versions 1.5.0

Application cookbook which installs and configures Consul.

Berkshelf/Librarian
Policyfile
Knife
cookbook 'consul', '= 1.5.0'
cookbook 'consul', '= 1.5.0', :supermarket
knife cookbook site install consul
knife cookbook site download consul
README
Dependencies
Changelog
Quality

consul-cookbook

Build Status Code Quality Test Coverage Cookbook Version License

Application cookbook which installs and configures Consul.

Consul is a tool for discovering and configuring services within your infrastructure. This is an application cookbook which takes a simplified approach to configuring and installing Consul. Additionally, it provides Chef primitives for more advanced configuration.

Basic Usage

For most infrastructure we suggest first starting with the default recipe. This installs and configures Consul from the latest supported release. It is also what is used to certify platform support through the use of our integration tests.

This cookbook provides node attributes which are used to fine tune the default recipe which installs and configures Consul. These values are passed directly into the Chef resource/providers which are exposed for more advanced configuration.

Out of the box the following platforms are certified to work and are tested using our Test Kitchen configuration. Additional platforms may work, but your mileage may vary.

  • CentOS (RHEL) 5.11, 6.7, 7.2
  • Ubuntu 12.04, 14.04
  • Windows 2012

Client

Out of the box the default recipe installs and configures the Consul agent to run as a service in client mode. The intent here is that your infrastructure already has a quorum of servers. In order to configure Consul to connect to your cluster you would supply an array of addresses for the Consul agent to join. This would be done in your wrapper cookbook: ruby node.default['consul']['config']['start_join'] = %w{c1.internal.corporate.com c2.internal.corporate.com c3.internal.corporate.com}

Server

This cookbook is designed to allow for the flexibility to bootstrap a new cluster. The best way to do this is through the use of a wrapper cookbook which tunes specific node attributes for a production server deployment.

The Consul cluster cookbook is provided as an example.

Advanced Usage

As explained above this cookbook provides Chef primitives in the form of resource/provider to further manage the install and configuration of Consul. These primitives are what is used in the default recipe, and should be used in your own wrapper cookbooks for more advanced configurations.

Configuration

It is very important to understand that each resource/provider has defaults for some properties. Any changes to a resource's default properties may need to be also changed in other resources. The best example is the Consul configuration directory.

In the example below we're going to change the configuration file from the default (/etc/consul.json) to one that may be on a special volume. It is obvious that we need to change the path where consul_config writes its file to, but it is less obvious that this needs to be passed into consul_service.

Inside of a recipe in your wrapper cookbook you'll want to do something like the following block of code. It uses the validated input from the configuration resource and passes it into the service resource. This ensures that we're using the same data. ruby config = consul_config '/data/consul/default.json' consul_service 'consul' do config_file config.path end

Watches/Definitions

In order to provide an idempotent implementation of Consul watches and definitions. We write these out as a separate configuration file in the JSON file format. The provider for both of these resources are identical in functionality.

Below is an example of writing a Consul service definition for the master instance of Redis. We pass in several parameters and tell the resource to notify the proper instance of the Consul service to reload. ruby consul_definition 'redis' do type 'service' parameters(tags: %w{master}, address: '127.0.0.1', port: 6379) notifies :reload, 'consul_service[consul]', :delayed end

A check definition can easily be added as well. You simply have to change the type and pass in the correct parameters. The definition below checks memory utilization using a script on a ten second interval. ruby consul_definition 'mem-util' do type 'check' parameters(script: '/usr/local/bin/check_mem.py', interval: '10s') notifies :reload, 'consul_service[consul]', :delayed end

A service definition with an integrated check can also be created. You will have to define a regular service and then add a check as a an additional parameter. The definition below checks if the vault service is healthy on a 10 second interval and 5 second timeout. ruby consul_definition 'vault' do type 'service' parameters( port: 8200, address: '127.0.0.1', tags: ['vault', 'http'], check: { interval: '10s', timeout: '5s', http: 'http://127.0.0.1:8200/v1/sys/health' } ) notifies :reload, 'consul_service[consul]', :delayed end

Finally, a watch is created below to tell the agent to monitor to see if an application has been deployed. Once that application is deployed a script is run locally. This can be used, for example, as a lazy way to clear a HTTP disk cache. ruby consul_watch 'app-deploy' do type 'event' parameters(handler: '/usr/local/bin/clear-disk-cache.sh') notifies :reload, 'consul_service[consul]', :delayed end

A keen eye would notice that we are delaying the reload of the Consul service instance. The reason we do this is to minimize the number of times we need to tell Consul to actually reload configurations. If there are several definitions this may save a little time off your Chef run.

ACLs

The consul_acl resource allows management of Consul ACL rules. Supported actions are :create and :delete. The :create action will update/insert as necessary.

The consul_acl resource requires the Diplomat Ruby API gem to be installed and available to Chef before using the resource. This can be accomplished by including consul::client_gem recipe in your run list.

In order to make the resource idempotent and only notify when necessary, the id field is always required (defaults to the name of the resource). If type is not provided, it will default to "client". The acl_name and rules attributes are also optional; if not included they will be empty in the resulting ACL.

The example below will create a client ACL token with an ID of the given UUID, Name of "AwesomeApp Token", and Rules of the given string. ruby consul_acl '49f06aa9-782f-465a-becf-44f0aaefd335' do acl_name 'AwesomeApp Token' type 'client' rules <<-EOS.gsub(/^\s{4}/, '') key "" { policy = "read" } service "" { policy = "write" } EOS auth_token node['consul']['config']['acl_master_token'] end

Execute

The command-line agent provides a mechanism to facilitate remote execution. For example, this can be used to run the uptime command across your fleet of nodes which are hosting a particular API service. ruby consul_execute 'uptime' do options(service: 'api') end

All of the options available on the command-line can be passed into the resource. This could potentially be a very dangerous operation. You should absolutely understand what you are doing. By the nature of this command it is impossible for it to be idempotent.

UI

consul_ui resource can be used to download and extract the consul web UI. It can be done with a block like this:

consul_ui 'consul-ui' do
  owner node['consul']['service_user']
  group node['consul']['service_group']
  version node['consul']['version']
end

Assuming consul version 0.5.2 above block would create /srv/consul-ui/0.5.2 and symlink /srv/consul-ui/current.

It does not change agent's configuration by itself. consul_config resource should be modified explicitly in order to host the web page.

consul_config 'consul' do
  ...
  ui_dir '/srv/consul-ui/current/dist'
end

This is optional, because consul UI can be hosted by any web server.

Change Log

1.5.0 (2016-03-07)

Full Changelog

Closed issues:

  • consul_acl (or Diplomat gem) misbehaving #283
  • Service definition with an integrated check #280
  • Atlas Integration go away with v1? #277
  • default['consul']['config']['bag_name'] broke consul_config #276

v1.4.3 (2016-02-08)

Full Changelog

v1.4.2 (2016-02-08)

Full Changelog

Fixed bugs:

  • Windows Consul service does not start up #273

v1.4.1 (2016-02-05)

Full Changelog

Fixed bugs:

  • consul service user /bin/false shell ? #271

Closed issues:

  • consul_ui resource does not work #255

v1.4.0 (2016-02-03)

Full Changelog

Implemented enhancements:

  • Consul ACL custom resource #240

Fixed bugs:

  • Unable to override databag attributes #239
  • does not start at boot on CentOS 6 #235

Closed issues:

  • Idempotency #262
  • retry_interval should be a string #244
  • Configuring TLS for RPC #230
  • Question: Configuring Consul #229

v1.3.1 (2015-10-07)

Full Changelog

Closed issues:

  • Cut a new release? #225

v1.3.0 (2015-10-07)

Full Changelog

v1.2.0 (2015-08-24)

Full Changelog

Closed issues:

  • How to pass extra options since refactor? #209
  • golang upgrade? #207

v1.1.1 (2015-08-13)

Full Changelog

v1.1.0 (2015-08-13)

Full Changelog

v1.0.0 (2015-08-06)

Full Changelog

v0.11.1 (2015-07-25)

Full Changelog

v0.11.0 (2015-07-23)

Full Changelog

Closed issues:

  • Anything chef-brigade can do to help? #197
  • Kitchen tests failing on master (commit a8d3060) #194

v0.10.1 (2015-07-10)

Full Changelog

Implemented enhancements:

  • consul systemd hangs at 'create symlink at /etc/service/consul to /etc/sv/consul' on Centos70 #168

Fixed bugs:

  • Missing package on RHEL7 AWS #165

Closed issues:

  • HTML tables are garbage, use markdown #186
  • Gossip/TLS encryption node attributes still requires consul data_bag, encrypt item, secret #151
  • server v cluster semantics unclear to new user / "Getting Started" under-discoverable #149

v0.10 (2015-06-04)

Full Changelog

v0.10.0 (2015-06-04)

Full Changelog

Closed issues:

  • consul::ui doesn't start with UI process #175

v0.9.1 (2015-03-30)

Full Changelog

0.9.0 (2015-03-17)

Full Changelog

Closed issues:

  • Consul fails to restart with access denied error if the consul user is change #140
  • Add 0.5.0 checksums #136
  • consul::ui recipe is failing to converge with Errno::EISDIR #133

v0.8.3 (2015-02-14)

Full Changelog

v0.8.2 (2015-02-11)

Full Changelog

v0.8.1 (2015-02-06)

Full Changelog

v0.8.0 (2015-02-06)

Full Changelog

v0.7.1 (2015-01-24)

Full Changelog

v0.7.0 (2015-01-23)

Full Changelog

v0.6.0 (2014-12-11)

Full Changelog

0.5.1 (2014-11-06)

Full Changelog

v0.4.3 (2014-09-19)

Full Changelog

0.4.3 (2014-09-19)

Full Changelog

v0.4.2 (2014-09-15)

Full Changelog

v0.3.1 (2014-08-29)

Full Changelog

v0.3.0 (2014-07-04)

Full Changelog

v0.2.2 (2014-05-31)

Full Changelog

v0.2.0 (2014-05-09)

* This Change Log was automatically generated by github_changelog_generator

Foodcritic Metric
            

1.5.0 failed this metric

FC019: Access node attributes in a consistent manner: /tmp/cook/751400a3c77f2a51e0dd24bd/consul/libraries/consul_service.rb:164
FC023: Prefer conditional attributes: /tmp/cook/751400a3c77f2a51e0dd24bd/consul/libraries/consul_service_windows.rb:76
FC044: Avoid bare attribute keys: /tmp/cook/751400a3c77f2a51e0dd24bd/consul/attributes/default.rb:17