The Etcd Cookbook is a library cookbook that provides custom resources for use in recipes.
This cookbook is concerned with the Etcd distributed key/value store as distributed by CoreOS, Inc.
- Chef 12.11+
- Network accessible web server hosting the etcd binary.
The following platforms have been tested with Test Kitchen. It will most likely work on other platforms as well
|---------------+-------+
| | 3.2.6 |
|---------------+-------+
| amazonlinux | X |
|---------------+-------+
| centos-6 | X |
|---------------+-------+
| centos-7 | X |
|---------------+-------+
| debian-8 | X |
|---------------+-------+
| debian-9 | X |
|---------------+-------+
| fedora | X |
|---------------+-------+
| ubuntu-14.04 | X |
|---------------+-------+
| ubuntu-16.04 | X |
|---------------+-------+
| opensuse-leap | X |
|---------------+-------+
- Add
depends 'etcd'
to your cookbook's metadata.rb - Use the resources shipped in cookbook in a recipe, the same way you'd use core Chef resources (file, template, directory, package, etc).
etcd_service 'etcd0' do
advertise_client_urls 'http://127.0.0.1:2379'
listen_client_urls 'http://0.0.0.0:2379'
initial_advertise_peer_urls 'http://127.0.0.1:2380'
listen_peer_urls 'http://0.0.0.0:2380'
initial_cluster_token 'etcd-cluster-1'
initial_cluster 'etcd0=http://127.0.0.1:2380,etcd1=http://127.0.0.1:3380,etcd2=http://127.0.0.1:4380'
initial_cluster_state 'new'
action :start
ignore_failure true # required for the first cluster build
end
etcd_service 'etcd1' do
advertise_client_urls 'http://127.0.0.1:3379'
listen_client_urls 'http://0.0.0.0:3379'
initial_advertise_peer_urls 'http://127.0.0.1:3380'
listen_peer_urls 'http://0.0.0.0:3380'
initial_cluster_token 'etcd-cluster-1'
initial_cluster 'etcd0=http://127.0.0.1:2380,etcd1=http://127.0.0.1:3380,etcd2=http://127.0.0.1:4380'
initial_cluster_state 'new'
action :start
ignore_failure true
end
etcd_service 'etcd2' do
advertise_client_urls 'http://127.0.0.1:4379'
listen_client_urls 'http://0.0.0.0:4379'
initial_advertise_peer_urls 'http://127.0.0.1:4380'
listen_peer_urls 'http://0.0.0.0:4380'
initial_cluster_token 'etcd-cluster-1'
initial_cluster 'etcd0=http://127.0.0.1:2380,etcd1=http://127.0.0.1:3380,etcd2=http://127.0.0.1:4380'
initial_cluster_state 'new'
action :start
ignore_failure true
end
The cookbooks ran under test-kitchen make excellent usage examples.
The test recipes are found at:
test/cookbooks/etcd_test/
etcd_service
: composite resource that uses etcd_installation and etcd_service_manageretcd_installation
: automatically selects an installation methodetcd_service_manager
: automatically selects a service manageretcd_key
: manages keys in etcdetcd_installation_binary
: copies a pre-compiled etcd binary onto disketcd_installation_docker
: pulls a docker image to the DOCKER_HOSTetcd_service_manager_sysvinit
: manage etcd daemon with a sysvinit scriptetcd_service_manager_upstart
: manage etcd daemon with upstart scriptetcd_service_manager_systemd
: manage etcd daemon with systemd unit filesetcd_service_manager_docker
: starts a docker process on the DOCKER_HOST
The etcd_installation
resource auto-selects one of the below resources with the provider resolution system. Currently only the binary installation is available. Packages will be supported in the future versions.
etcd_installation 'default' do
action :create
end
The etcd_installation_binary
resource copies the precompiled Go binary onto the disk.
etcd_installation_binary 'default' do
version '3.2.6'
source 'https://my.computers.biz/dist/etcd'
checksum '90aff7364caa43932fd46974825af20e0ecb70fe7e01981e2d3a496106f147e7'
action :create
end
The etcd_installation_docker
resource uses the docker_image
resource to pull an image to the DOCKER_HOST.
repo
- The image name to pull. Defaults to 'quay.io/coreos/etcd'tag
- The image tag to pull.version
- String used to calculate tag string when tag is omitted. Defaults to '2.3.7'
The etcd_service_manager
resource auto-selects one of the below resources with the provider resolution system. The etcd_service
family all share a common set of properties, which are listed under the etcd_service
composite resource.
etcd startup behavior is a bit quirky. etcd loops indefinitely on startup until quorum can be established. Due to this the first nodes service start will fail unless all nodes come up at the same time. Due to this there is an ignore_failure property for the upstart / systemd service managers which allows you to continue on in the chef run if the service fails to start. Upstart / systemd will automatically keep restarting the service until all nodes are up and the cluster is healthy. For sys-v init you're on your own.
etcd_service_manager 'default' do
action :start
end
etcd_service_manager_sysvinit 'default' do
action :stop
end
etcd_service_manager_upstart 'default' do
action :start
end
- ignore_failure - Ignore failures starting the etcd service. Before quorum is established nodes will loop indefinitely and never successfully start. This can help ensure all instances are up when init systems can handle restart on failure. Default: false
etcd_service_manager_systemd 'default' do
action :start
end
- service_timeout - The time in seconds before the service start fails. Default: 20
- ignore_failure - Ignore failures starting the etcd service. Before quorum is established nodes will loop indefinitely and never successfully start. This can help ensure all instances are up when init systems can handle restart on failure. Default: false
etcd_service_manager_docker 'default' do
action :start
end
- repo - defaults to 'quay.io/coreos/etcd'
- tag - default calculated from version
- version - defaults to '3.2.6',
- container_name - defaults to resource name
- port - defaults to ['2379/tcp4:2379', '2380/tcp4:2380']
The etcd_service
: resource is a composite resource that uses etcd_installation
and etcd_service_manager
resources.
- The
:create
action uses anetcd_installation
- The
:delete
action uses anetcd_installation
- The
:start
action uses anetcd_service_manager
- The
:stop
action uses anetcd_service_manager
The service management strategy for the host platform is dynamically chosen based on platform, but can be overridden.
The etcd_service
resource property list corresponds to the options found in
Etcd Configuration Flags documentation
source
node_name
data_dir
wal_dir
snapshot_count
snapshot to disk.heartbeat_interval
election_timeout
listen_peer_urls
listen_client_urls
max_snapshots
max_wals
cors
quota_backend_bytes
initial
initial_advertise_peer_urls
initial_cluster
initial_cluster_state
initial_cluster_token
advertise_client_urls
discovery
discovery_srv
discovery_fallback
discovery_proxy
strict_reconfig_check
auto_compaction_retention
enable_v2
proxy
proxy_failure_wait
proxy_refresh_interval
proxy_dial_timeout
proxy_write_timeout
proxy_read_timeout
cert_file
key_file
client_cert_auth
trusted_ca_file
auto_tls
peer_cert_file
peer_key_file
peer_client_cert_auth
peer_trusted_ca_file
peer_auto_tls
etcdctl_client_cert_file
etcdctl_client_key_file
debug
log_package_levels
enable_pprof
metrics
auth_token
force_new_cluster
http_proxy
https_proxy
no_proxy
auto_restart
The etcd_key
resource sets, watches and deletes keys in etcd.
- The
:set
action sets a key - The
:delete
action deletes a key - The
:watch
action waits for a key to update
key
- The key namevalue
- The desired valuettl
- The ttl for the key (optional)host
- The hostname of the etcd server, defaults to127.0.0.1
port
- The port that etcd is listening on, defaults to2379
etcd_key "/test" do
value "a_test_value"
action :set
end
This cookbook is maintained by Chef's Community Cookbook Engineering team. Our goal is to improve cookbook quality and to aid the community in contributing to cookbooks. To learn more about our team, process, and design goals see our team documentation. To learn more about contributing to cookbooks like this see our contributing documentation, or if you have general questions about this cookbook come chat with us in #cookbok-engineering on the Chef Community Slack
Copyright | 2013, Jesse Nelson
Copyright | 2015-2017, Chef Software, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.