Skip to content

Commit 7f3038c

Browse files
author
John Bellone
committed
Updates the documentation to prepare for a release.
1 parent 89f3735 commit 7f3038c

File tree

3 files changed

+100
-121
lines changed

3 files changed

+100
-121
lines changed

‎CHANGELOG.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# 1.0.0
22

3+
# 0.11
4+
35
# 0.10
46
Fixes several bugs, minor enhancements and changes default version of
57
Consul to 0.5.2.

‎CONTRIBUTING.md

-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,4 @@
11
# How To Contribute
2-
3-
## Contributing
4-
52
1. Fork the repository on Github
63
2. Create a named feature branch (i.e. `add-new-recipe`)
74
3. Write you change

‎README.md

+98-118
Original file line numberDiff line numberDiff line change
@@ -7,151 +7,131 @@ consul-cookbook
77

88
[Application cookbook][0] which installs and configures [Consul][1].
99

10-
This is a hybrid cookbook which provides resources/providers to
11-
install and configure the [Consul agent][1]. A default recipe exists
12-
to show off the most common usage - writing out a Consul configuration
13-
and creating the Consul service - from node attributes. It is important
14-
to note that this cookbook is essentially a [Library cookbook][3] which
15-
provides an default example recipe (e.g. application cookbook).
16-
17-
## Platforms
18-
- CentOS >= 6.4 (RHEL)
19-
- Ubuntu >= 12.04
10+
Consul is a tool for discovering and configuring services within your
11+
infrastructure. This is an application cookbook which takes a
12+
simplified approach to configuring and installing
13+
Consul. Additionally, it provides Chef primitives for more advanced
14+
configuration.
15+
16+
## Basic Usage
17+
For most infrastructure we suggest first starting with the default
18+
recipe. This installs and configures Consul from the latest supported
19+
release. It is also what is used to certify platform support through
20+
the use of our integration tests.
21+
22+
This cookbook provides node attributes which are used to fine tune
23+
the default recipe which installs and configures Consul. These values
24+
are passed directly into the Chef resource/providers which are exposed
25+
for more advanced configuration.
26+
27+
Out of the box the following platforms are certified to work and are
28+
tested using our [Test Kitchen][8] configuration. Additional platforms
29+
_may_ work, but your mileage may vary.
30+
- CentOS (RHEL) 6.6, 7.1
31+
- Ubuntu 12.04, 14.04
2032
- Windows
2133

22-
## Dependencies
23-
This cookbook has a few dependencies which are pulled in and required
24-
when uploaded to a Chef Server. Not all recipes (or resources, for
25-
that matter) will run unless certain functionality is configured. For
26-
example, the Golang cookbook default recipe is only included when
27-
install method is from source.
28-
29-
| Cookbook Name | Description |
30-
| ------------- | ----------- |
31-
| Chef Vault | Provides HWRP for managing secrets for TLS certificates/keys. |
32-
| Golang | Provides recipes for installing Go language for source compliation. |
33-
| libartifact | Provids HWRP for managing versions of artifacts on disk. |
34-
| Poise | Provides helpers for writing reusable HWRP code. |
35-
| Poise Service | Provides helpers for abstracting service lifecycle management. |
36-
| SELinux | Provides recipes for configuring SELinux subsystem. |
37-
38-
## Attributes
39-
This cookbook provides node attributes which can be used to fine tune
40-
how the recipes install and configure the Consul client, server and
41-
UI. These values are passed into the resource/providers for
42-
validation prior to converging.
43-
44-
All of the attribute keys are nested immediately under
45-
`node['consul']` and thus are accessible like
46-
`node.default['consul']['version'] = '0.5.1'`.
47-
48-
| Key | Type | Description | Default |
49-
|---------|--------|----------------|-----------|
50-
| version | String | Installation version | 0.5.2 |
51-
| remote_url | String | Remote URL for download. | https://dl.bintray.com/mitchellh/consul |
52-
| service_name | String | Name of the service (operating system) | consul |
53-
| service_user | String | Name of the service user | consul |
54-
| service_group | String | Name of the service group | consul |
55-
56-
## Resources/Providers
57-
This cookbook provides resource and provider primitives to manage the
58-
Consul client, server and UI. These primitives are what is used in the
59-
recipes, and should be used in your own [wrapper cookbooks][2].
60-
61-
### consul_config
62-
| Parameter | Type | Description | Default |
63-
| --------- | ---- | ----------- | ------- |
64-
| path | String | File system path to write configuration. | name |
65-
| user | String | System username for configuration ownership. | consul |
66-
| group | String | System groupname for configuration ownership. | consul |
67-
| bag_name | String | Name of the chef-vault data bag for TLS configuration. | secrets |
68-
| bag_item | String | Item of the chef-vault data bag for TLS configuration. | consul |
34+
## Advanced Usage
35+
As explained above this cookbook provides Chef primitives in the form
36+
of resource/provider to further manage the install and configuration
37+
of Consul. These primitives are what is used in the default recipe,
38+
and should be used in your own [wrapper cookbooks][2] for more
39+
advanced configurations.
6940

70-
```ruby
71-
consul_config '/etc/consul.json' do
72-
user 'jbellone'
73-
group 'staff'
74-
end
75-
```
76-
### consul_service
77-
| Parameter | Type | Description | Default |
78-
| --------- | ---- | ----------- | ------- |
79-
| user | String | System username for configuration ownership. | consul |
80-
| group | String | System groupname for configuration ownership. | consul |
81-
| install_method | String | Determines method of installing Consul agent on node. | source, binary, package |
82-
| install_path | String | Absolute path to where Consul agent is unpacked. | /srv |
83-
| version | String | The version of Consul agent to install. | nil |
84-
| config_file | String | Absolute path to the Consul agent's configuration file. | /etc/consul.json |
85-
| config_dir | String | Absolute path to configuration directory (for definitions, watches). | /etc/consul |
86-
| data_dir | String | Absolute path to the Consul agent's data directory. | /var/lib/consul |
41+
### Configuration
42+
It is very important to understand that each resource/provider has
43+
defaults for some properties. Any changes to a resource's default
44+
properties may need to be also changed in other resources. The best
45+
example is the Consul configuration directory.
46+
47+
In the example below we're going to change the configuration file from
48+
the default (/etc/consul.json) to one that may be on a special volume.
49+
It is obvious that we need to change the path where `consul_config`
50+
writes its file to, but it is less obvious that this needs to be
51+
passed into `consul_service`.
8752

53+
Inside of a recipe in your [wrapper cookbook][2] you'll want to do
54+
something like the following block of code. It uses the validated
55+
input from the configuration resource and passes it into the service
56+
resource. This ensures that we're using the _same data_.
8857
```ruby
58+
config = consul_config '/data/consul/default.json'
8959
consul_service 'consul' do
90-
user 'consul'
91-
group 'consul'
92-
install_method 'binary'
93-
binary_url node['consul']['binary_url']
60+
config_file config.path
9461
end
9562
```
96-
### consul_watch
97-
| Parameter | Type | Description | Default |
98-
| --------- | ---- | ----------- | ------- |
99-
| path | String | File system path to write configuration. | name |
100-
| user | String | System username for configuration ownership. | consul |
101-
| group | String | System groupname for configuration ownership. | consul |
102-
| type | String | Type of the Consul watch to configure. | key, keyprefix, service, event |
103-
| parameters | Hash | Parameters to configure; depends on type of watch. | {} |
63+
### Watches/Definitions
64+
In order to provide an idempotent implementation of Consul
65+
watches and definitions. We write these out as
66+
a separate configuration file in the JSON file format. The provider
67+
for both of these resources are identical in functionality.
10468

69+
Below is an example of writing a [Consul service definition][11] for
70+
the master instance of Redis. We pass in several parameters and tell
71+
the resource to notify the proper instance of the Consul service to
72+
reload.
10573
```ruby
106-
consul_watch 'foobarbaz' do
107-
type 'key'
108-
parameters(key: 'foo/bar/baz', handler: '/bin/false')
109-
notifies :reload, 'consul_service[consul]', :delayed
110-
end
111-
```
112-
```ruby
113-
consul_watch 'foobarbaz' do
114-
type 'keyprefix'
115-
parameters(prefix: 'foo/', handler: '/bin/false')
116-
notifies :reload, 'consul_service[consul]', :delayed
117-
end
118-
```
119-
```ruby
120-
consul_watch 'foobarbaz' do
74+
consul_definition 'redis' do
12175
type 'service'
122-
parameters(service: 'redis', handler: '/bin/false')
76+
parameters(tags: %w{master}, address: '127.0.0.1', port: 6379, interval: '30s')
12377
notifies :reload, 'consul_service[consul]', :delayed
12478
end
12579
```
80+
81+
A [check definition][12] can easily be added as well. You simply have
82+
to change the type and pass in the correct parameters. The definition
83+
below checks memory utilization using a script on a ten second interval.
12684
```ruby
127-
consul_watch 'foobarbaz' do
128-
type 'event'
129-
parameters(event: 'web-deploy', handler: '/bin/false')
85+
consul_definition 'mem-util' do
86+
type 'check'
87+
parameters(script: '/usr/local/bin/check_mem.py', interval: '10s')
13088
notifies :reload, 'consul_service[consul]', :delayed
13189
end
13290
```
133-
### consul_definition
134-
| Parameter | Type | Description | Default |
135-
| --------- | ---- | ----------- | ------- |
136-
| path | String | File system path to write configuration. | name |
137-
| user | String | System username for configuration ownership. | consul |
138-
| group | String | System groupname for configuration ownership. | consul |
139-
| type | String | Type of definition | service, check |
91+
92+
Finally, a [watch][9] is created below to tell the agent to monitor to
93+
see if an application has been deployed. Once that application is
94+
deployed a script is run locally. This can be used, for example, as a
95+
lazy way to clear a HTTP disk cache.
14096
```ruby
141-
consul_definition 'redis' do
142-
type 'service'
143-
parameters(tags: %w{master}, address: '127.0.0.1', port: 6379, interval: '30s')
97+
consul_watch 'app-deploy' do
98+
type 'event'
99+
parameters(handler: '/usr/local/bin/clear-disk-cache.sh')
144100
notifies :reload, 'consul_service[consul]', :delayed
145101
end
146102
```
147-
### consul_execute
103+
104+
A keen eye would notice that we are _delaying the reload of the Consul
105+
service instance_. The reason we do this is to minimize the number of
106+
times we need to tell Consul to actually reload configurations. If
107+
there are several definitions this may save a little time off your
108+
Chef run.
109+
110+
## Execute
111+
The command-line agent provides a mechanism to facilitate remote
112+
execution. For example, this can be used to run the `uptime` command
113+
across your fleet of nodes which are hosting a particular API service.
148114
```ruby
149115
consul_execute 'uptime' do
150-
options(service: 'web')
116+
options(service: 'api')
151117
end
152118
```
153119

120+
All of the [options available on the command-line][12] can be passed
121+
into the resource. This could potentially be a *very dangerous*
122+
operation. You should absolutely understand what you are doing. By the
123+
nature of this command it is _impossible_ for it to be idempotent.
124+
154125
[0]: http://blog.vialstudios.com/the-environment-cookbook-pattern/#theapplicationcookbook
155126
[1]: http://consul.io
156127
[2]: http://blog.vialstudios.com/the-environment-cookbook-pattern#thewrappercookbook
157-
[3]: http://blog.vialstudios.com/the-environment-cookbook-pattern/#thelibrarycookbook
128+
[3]: http://blog.vialstudios.com/the-environment-cookbook-pattern#thelibrarycookbook
129+
[4]: https://github.com/johnbellone/libartifact-cookbook
130+
[5]: https://github.com/poise/poise
131+
[6]: https://github.com/poise/poise-service
132+
[7]: https://github.com/skottler/selinux
133+
[8]: https://github.com/test-kitchen/test-kitchen
134+
[9]: https://consul.io/docs/agent/watches.html
135+
[10]: https://consul.io/docs/agent/services.html
136+
[11]: https://consul.io/docs/agent/checks.html
137+
[12]: https://consul.io/docs/commands/exec.html

0 commit comments

Comments
 (0)