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

Select Status

RSS

zookeeper_bridge (3) Versions 0.3.0

Cookbook used to help integrating the Chef Run with ZooKeeper: chef handler, locks, semaphores, ...

Policyfile
Berkshelf
Knife
cookbook 'zookeeper_bridge', '~> 0.3.0', :supermarket
cookbook 'zookeeper_bridge', '~> 0.3.0'
knife supermarket install zookeeper_bridge
knife supermarket download zookeeper_bridge
README
Dependencies
Changelog
Quality 17%

ZooKeeper Bridge Cookbook

Cookbook Version
GitHub Source
Dependency Status
Code Climate
Build Status

Chef zookeeper_bridge cookbook, used to help integrating the Chef Run with ZooKeeper.

It can help in the following:

  • Installing and running Chef ZooKeeper Handler.
  • Reading or writing Chef Node attributes to and from ZooKeeper.
  • Running ZooKeeper Client commands.
  • Interacting with ZooKeeper read/write locks during the Chef Run.
  • Interacting with ZooKeeper semaphores during the Chef Run.
  • Wait until a ZooKeeper znode has the desired state or a certain event happens.

Some of the resources included in this cookbook have not been widely tested, so you should consider this cookbook as something experimental.

This cookbook is mainly used by calling the resources it provides. See their documentation below. The zookeeper_bridge::default recipe needs to be included before their use.

Requirements

Supported Platforms

This cookbook has been tested on the following platforms:

  • Amazon
  • CentOS
  • Debian
  • Ubuntu

Please, let us know if you use it successfully on any other platform.

Required Cookbooks

Required Applications

  • Ruby 1.9.3 or higher.
  • zk ruby gem.

Attributes

Attribute Default Description
node['zookeeper_bridge']['server'] '127.0.0.1:2181' ZooKeeper server address.
node['zookeeper_bridge']['chef_handler']['version'] nil (latest) chef-handler-zookeeper gem version to install.
node['zookeeper_bridge']['chef_handler']['znode'] "/chef/#{node.name}/status" chef-handler-zookeeper znode path. The path must be absolute.

Recipes

zookeeper_bridge::default

Recipe required before using the resources.

zookeeper_bridge::chef_handler

Installs and enables chef-handler-zookeeper gem.

zookeeper_bridge::chef_handler Example

The node['zookeeper_bridge']['chef_handler']['znode'] path must exist before calling this recipe:

$ ./zkCli.sh
[zk: localhost:2181(CONNECTED) 0] create /chef {}
[zk: localhost:2181(CONNECTED) 1] create /chef/server1.example.com {}
[zk: localhost:2181(CONNECTED) 2] create /chef/server1.example.com/status {}

Or using the recipe itself:

# We set the ZooKeeper server address
node.default['zookeeper_bridge']['server'] = 'zk.example.com'

# zookeeper_bridge_cli resource should ignore cli errors if they already exist
zookeeper_bridge_cli 'create /chef {}'
zookeeper_bridge_cli "create /chef/#{node.name} {}"
zookeeper_bridge_cli "create /chef/#{node.name}/status {}"

This is because the chef-handler-zookeeper requires that the znode exists.

Now we can install and enable the handler:

node.default['zookeeper_bridge']['chef_handler']['znode'] = "/chef/#{node.name}/status"
include_recipe 'zookeeper_bridge::chef_handler'

zookeeper_bridge::depends

Install some dependencies required by this cookbook. Used by the other recipes.

Resources

zookeeper_bridge_rdlock[path]

Runs a Read or Shared Lock inside ZooKeeper. This resource is intended to be used together with the zookeeper_bridge_wrlock resource.

zookeeper_bridge_rdlock Actions

  • run

zookeeper_bridge_rdlock Parameters

Parameter Default Description
path name Znode path. The path can be relative to '/_zklocking'.
server node['zookeeper_bridge']['server'] ZooKeeper server address.
wait true This can be an integer to wait a maximum of seconds and raise a timeout exception if this time is exceeded. By default is set to true, which will wait infinitely.
block nil The recipe code that will be run within the lock.

zookeeper_bridge_rdlock Examples

zookeeper_bridge_rdlock 'lock1' do
  server 'zk.example.com'
  block do
    # recipe code can be used here
    execute '...'
  end
end

Then we can use an exclusive lock from another node:

zookeeper_bridge_wrlock 'lock1' do
  server 'zk.example.com'
  block do
    # recipe code can be used here
    execute '...'
  end
end

zookeeper_bridge_wrlock[path]

Runs a Write or Exclusive Lock inside ZooKeeper. This resource is intended to be used together with the zookeeper_bridge_rdlock resource.

zookeeper_bridge_wrlock Actions

  • run

zookeeper_bridge_wrlock Parameters

Parameter Default Description
path name Znode path. The path can be relative to '/_zklocking'.
server node['zookeeper_bridge']['server'] ZooKeeper server address.
wait true This can be an integer to wait a maximum of seconds and raise a timeout exception if this time is exceeded. By default is set to true, which will wait infinitely.
block nil The recipe code that will be run within the lock.

zookeeper_bridge_wrlock Examples

The following block will only be running by a maximum of one node at a particular instant:

zookeeper_bridge_wrlock 'lock1' do
  server 'zk.example.com'
  block do
    # recipe code can be used here
    execute '...'
  end
end

zookeeper_bridge_sem[path]

Runs a Semaphore inside ZooKeeper.

zookeeper_bridge_sem Actions

  • run

zookeeper_bridge_sem Parameters

Parameter Default Description
path name Znode path. The path can be relative to '/_zksemaphore'.
server node['zookeeper_bridge']['server'] ZooKeeper server address.
size nil Semaphore size: the maximum number of nodes that will be able to run the block at the same time.
block nil The recipe code that will be run within the semaphore.
wait true This can be an integer to wait a maximum of seconds and raise a timeout exception if this time is exceeded. By default is set to true, which will wait infinitely.

zookeeper_bridge_sem Examples

You can call this from multiple nodes. The code within the following block will be running by a maximum of three nodes at the same time:

zookeeper_bridge_sem 'sem1' do
  server 'zk.example.com'
  size 3
  block do
    # recipe code can be used here
    execute '...'
  end
end

zookeeper_bridge_attrs[path]

Used to read or write Chef Node attributes from or to ZooKeeper znode paths. The attributes are saved into the znode using JSON format.

zookeeper_bridge_attrs Actions

  • read: Read Node attributes from a znode.
  • write: Write Node attributes to a znode.

zookeeper_bridge_attrs Parameters

Parameter Default Description
path name Znode path. The path must be absolute.
server node['zookeeper_bridge']['server'] ZooKeeper server address.
attribute nil Node attribute object or a Ruby Hash. This should be something like node['foo'] for reading and node.normal['foo'] for writing.
merge calculated Whether to merge hashes. This is true by default for :read action, which will merge the current node attributes with the attributes read from ZooKeeper. For :write is false by default, which will not merge the current attributes saved in ZooKeeper with the node attributes to write, the data in ZooKeeper will be completely overwritten.
force_encoding nil Force character encoding. For example: 'UTF-8'.

zookeeper_bridge_attrs Examples

Reading All Node Attributes

The znode to read attributes from must exist before reading it. For writing, at least the parent znode must exist:

$ ./zkCli.sh
[zk: localhost:2181(CONNECTED) 0] create /chef {}
[zk: localhost:2181(CONNECTED) 1] create /chef/server1.example.com {}
[zk: localhost:2181(CONNECTED) 2] create /chef/server1.example.com/read_attributes {"attr1":"value1"}

We can also create them from a recipe using zookeeper_bridge_cli:

# We set the ZooKeeper server address
node.default['zookeeper_bridge']['server'] = 'zk.example.com'

# zookeeper_bridge_cli resource should ignore cli errors if they already exist
zookeeper_bridge_cli('create /chef {}').run_action(:run)
zookeeper_bridge_cli("create /chef/#{node.name} {}").run_action(:run)
# zkCli.sh does not support spaces in the data:
zookeeper_bridge_cli("create /chef/#{node.name}/read_attributes {\"attr1\":\"value1\"}")
  .run_action(:run)

Now we can read and write all node attributes from and to ZooKeeper:

zookeeper_bridge_attrs "/chef/#{node.name}/read_attributes" do
  attribute node.normal
  action :nothing
end.run_action(:read)

# [...]

zookeeper_bridge_attrs "/chef/#{node.name}/write_attributes" do
  attribute node.attributes
  action :write
end

Note: You need to understand how compile and converge phases work on Chef Run to know when to use #run_action.

Reading and Writing Apache Cookbook Attributes

As in the previous example, we create the necessary znodes:

$ ./zkCli.sh
[zk: localhost:2181(CONNECTED) 0] create /chef {}
[zk: localhost:2181(CONNECTED) 1] create /chef/server1.example.com {}
[zk: localhost:2181(CONNECTED) 2] create /chef/server1.example.com/apache_attributes {}

We can also create them from a recipe using zookeeper_bridge_cli:

# We set the ZooKeeper server address
node.default['zookeeper_bridge']['server'] = 'zk.example.com'

# zookeeper_bridge_cli resource should ignore cli errors if they already exist
zookeeper_bridge_cli 'create /chef {}'
zookeeper_bridge_cli "create /chef/#{node.name} {}"
zookeeper_bridge_cli "create /chef/#{node.name}/apache_attributes {}"

Now we can read and write apache attributes:

# We use override in this case to overwrite default and normal values, why not?
zookeeper_bridge_attrs "/chef/#{node.name}/apache_attributes" do
  attribute node.override['apache']
  action :nothing
end.run_action(:read)

# [...]

zookeeper_bridge_attrs "/chef/#{node.name}/apache_attributes" do
  attribute node['apache']
  action :write
end

zookeeper_bridge_wait[path]

Waits until a given ZooKeeper znode path exists, does not exist or changes its state.

zookeeper_bridge_wait Actions

  • run

zookeeper_bridge_wait Parameters

Parameter Default Description
path name Znode path. The path must be absolute.
server node['zookeeper_bridge']['server'] ZooKeeper server address.
status :any Wait until znode has this status. Possible values: :any, :created or :deleted.. :any means to ignore the status, normally used when the event parameter below is set.
event :none Wait until specific znode event occurs. Possible values: :none, :created, :deleted., :changed, :child or an array of multiple values. :none means to ignore the events, normally used when the status parameter is set. :child is for znode child events.

zookeeper_bridge_wait Examples

Wait until host znode is created (at compile time, to avoid compiling the next resources):

zookeeper_bridge_wait "/chef/#{node.name}" do
  status :created
  event :none
  action :nothing
end.run_action(:run)

Wait until the attributes exists before reading them:

zookeeper_bridge_wait "/chef/#{node.name}/attributes" do
  status :created
  event :none
  action :nothing
end.run_action(:run)

zookeeper_bridge_attrs "/chef/#{node.name}/attributes" do
  attribute node.normal
  action :nothing
end.run_action(:read)

Continue the Chef Run convergence only when the stop znode does not exist:

zookeeper_bridge_wait "/chef/#{node.name}/chef_stop" do
  status :deleted
  event :none
end

Continue the Chef Run convergence only when the continue znode is updated:

zookeeper_bridge_wait "/chef/#{node.name}/chef_continue" do
  status :any
  event :changed
end

zookeeper_bridge_cli[path]

Runs a ZooKeeper command using the zkCli.sh script. This resource should be run from the ZooKeeper server node, because zkCli.sh connects to localhost (connecting to remote server is not supported yet).

Remember that this script has some limitations, so use it with caution.

zookeeper_bridge_cli Actions

  • run: Runs a command.

zookeeper_bridge_cli Parameters

Parameter Default Description
command name ZooKeeper zkCli.sh command.
base_path calculated ZooKeeper installation path.
sleep nil Time to sleep in seconds before the command is run (type Float).
background false Whether to run the command in background.

zookeeper_bridge_cli Examples

zookeeper_bridge_cli 'create /test some_random_data'

This resource is currently used in the integration tests. See the zookeeper_bridge_test cookbook recipes for more usage examples.

Testing

See TESTING.md.

ChefSpec Matchers

zookeeper_bridge_attrs(path)

Helper method for locating a zookeeper_bridge_attrs resource in the collection.

resource = chef_run.zookeeper_bridge_attrs("/chef/#{node['fqdn']}/attributes")
expect(resource).to notify('service[apache2]').to(:reload)

read_zookeeper_bridge_attrs(path)

Assert that the Chef Run reads zookeeper_bridge_attrs at compile time.

expect(chef_run).to read_zookeeper_bridge_attrs("/chef/#{node['fqdn']}/attributes").at_compile_time

write_zookeeper_bridge_attrs(path)

Assert that the Chef Run writes zookeeper_bridge_attrs.

expect(chef_run).to write_zookeeper_bridge_attrs("/chef/#{node['fqdn']}/attributes")

zookeeper_bridge_cli(command)

Helper method for locating a zookeeper_bridge_cli resource in the collection.

resource = chef_run.zookeeper_bridge_cli('ls /chef')
expect(resource).to notify('service[apache2]').to(:reload)

run_zookeeper_bridge_cli(command)

Assert that the Chef Run runs zookeeper_bridge_cli.

expect(chef_run).to run_zookeeper_bridge_cli('create /test some_random_data')

zookeeper_bridge_rdlock(path)

Helper method for locating a zookeeper_bridge_rdlock resource in the collection.

resource = chef_run.zookeeper_bridge_rdlock('my_lock')
expect(resource).to notify('service[apache2]').to(:reload)

run_zookeeper_bridge_rdlock(path)

Assert that the Chef Run runs zookeeper_bridge_rdlock.

expect(chef_run).to run_zookeeper_bridge_rdlock('my_lock')

zookeeper_bridge_sem(path)

Helper method for locating a zookeeper_bridge_sem resource in the collection.

resource = chef_run.zookeeper_bridge_sem('my_semaphore')
expect(resource).to notify('service[apache2]').to(:reload)

run_zookeeper_bridge_sem(path)

Assert that the Chef Run runs zookeeper_bridge_sem.

expect(chef_run).to run_zookeeper_bridge_sem('my_semaphore')
  .with_size(1)

zookeeper_bridge_wait(path)

Helper method for locating a zookeeper_bridge_wait resource in the collection.

resource = chef_run.zookeeper_bridge_wait("/chef/#{node['fqdn']}/attributes")
expect(resource).to notify('service[apache2]').to(:reload)

run_zookeeper_bridge_wait(path)

Assert that the Chef Run runs zookeeper_bridge_wait.

# ensure waits until the attributes file exists
expect(chef_run).to run_zookeeper_bridge_wait("/chef/#{node['fqdn']}/attributes")
  .with_status(:created)
  .with_event(:none)

zookeeper_bridge_wrlock(path)

Helper method for locating a zookeeper_bridge_wrlock resource in the collection.

resource = chef_run.zookeeper_bridge_wrlock('my_lock')
expect(resource).to notify('service[apache2]').to(:reload)

run_zookeeper_bridge_wrlock(path)

Assert that the Chef Run runs zookeeper_bridge_wrlock.

expect(chef_run).to run_zookeeper_bridge_wrlock('my_lock')

Contributing

Please do not hesitate to open an issue with any questions or problems.

See CONTRIBUTING.md.

TODO

See TODO.md.

License and Author

Author: Xabier de Zuazo (xabier@zuazo.org)
Copyright: Copyright (c) 2015, Xabier de Zuazo
Copyright: Copyright (c) 2013-2014, Onddo Labs, SL.
License: Apache License, Version 2.0
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.

Dependent cookbooks

build-essential ~> 2.0
chef_handler >= 0.0.0

Contingent cookbooks

There are no cookbooks that are contingent upon this one.

CHANGELOG for zookeeper_bridge

This file is used to list changes made in each version of the zookeeper_bridge cookbook.

v0.3.0 (2015-09-09)

  • Install tar package.
  • Update chef links to use chef.io domain.
  • Update contact information and links after migration.
  • metadata: Add source_url and issues_url links.
  • Remove Fedora and RedHat support.

  • Documentation:

    • Move ChefSpec matchers documentation to the README.
    • README:
    • Improve title and description.
    • Add GitHub badge.
  • Testing:

    • Test files updates: Berksfile, Gemfile, Guardfile, Rakefile, RuboCop 0.34.0.
    • Move ChefSpec tests to test/unit.
    • Travis CI: Run tests against Chef 11 and Chef 12.
    • .kitchen.yml: Update platform versions.
    • Use runit cookbook 1.6.0 to avoid issue hw-cookbooks/runit#142.

v0.2.0 (2014-10-25)

  • Add zookeeper_bridge_attrs#merge property.
  • Remove zookeeper_bridge_attrs#key property (breaking change).
  • Fix deep attribute merge in zookeeper_bridge_attrs#read (breaking change).
  • Fix deep attribute merge in zookeeper_bridge_attrs#write (breaking change).
  • ZooKeeperBridge::Attributes: fix encoding force on write.
  • Fix a RuboCop offense.
  • Set apt cookbook compile time update.
  • Add rubocop.yml file.
  • Use a descriptive name in unit tests instead of subject.
  • Integrate tests with should_not gem.
  • ChefSpec matchers: Add helper methods to locate LWRP resources.
  • Update to ChefSpec 4.1.
  • Update to Berkshelf 3.1.
  • Use generic Berksfile template.
  • travis.yml: exclude some gemfile groups.
  • Rakefile:
    • Include kitchen gem only if required.
    • Add documentation link.
  • Refactor Gemfile to use style, unit and integration groups.
  • Add Guardfile.
  • Documentation: use single quotes in examples.
  • README:
    • Fix apache attributes example.
    • Fix some typos.
    • Use markdown tables.
  • TODO: use checkboxes.
  • TESTING.md:
    • Some improvements.
    • Update to use Digital Ocean Access Token.
  • Homogenize license headers.
  • kitchen.yml update.
  • kitchen.cloud.yml: use one line run_list to include apt cookbook.

v0.1.0 (2014-08-18)

  • Initial release of zookeeper_bridge.

Collaborator Number Metric
            

0.3.0 failed this metric

Failure: Cookbook has 1 collaborators. A cookbook must have at least 2 collaborators to pass this metric.

Contributing File Metric
            

0.3.0 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a CONTRIBUTING.md file

Foodcritic Metric
            

0.3.0 failed this metric

FC066: Ensure chef_version is set in metadata: zookeeper_bridge/metadata.rb:1
FC069: Ensure standardized license defined in metadata: zookeeper_bridge/metadata.rb:1
FC072: Metadata should not contain "attribute" keyword: zookeeper_bridge/metadata.rb:1
FC074: LWRP should use DSL to define resource's default action: zookeeper_bridge/resources/attrs.rb:1
FC074: LWRP should use DSL to define resource's default action: zookeeper_bridge/resources/cli.rb:1
FC074: LWRP should use DSL to define resource's default action: zookeeper_bridge/resources/rdlock.rb:1
FC074: LWRP should use DSL to define resource's default action: zookeeper_bridge/resources/sem.rb:1
FC074: LWRP should use DSL to define resource's default action: zookeeper_bridge/resources/wait.rb:1
FC074: LWRP should use DSL to define resource's default action: zookeeper_bridge/resources/wrlock.rb:1
FC085: Resource using new_resource.updated_by_last_action to converge resource: zookeeper_bridge/providers/attrs.rb:33
FC085: Resource using new_resource.updated_by_last_action to converge resource: zookeeper_bridge/providers/attrs.rb:58
FC121: Cookbook depends on cookbook made obsolete by Chef 14: zookeeper_bridge/metadata.rb:1
FC122: Use the build_essential resource instead of the recipe: zookeeper_bridge/recipes/depends.rb:26
Run with Foodcritic Version 16.3.0 with tags metadata,correctness ~FC031 ~FC045 and failure tags any

No Binaries Metric
            

0.3.0 passed this metric

Testing File Metric
            

0.3.0 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must contain a TESTING.md file

Version Tag Metric
            

0.3.0 failed this metric

Failure: To pass this metric, your cookbook metadata must include a source url, the source url must be in the form of https://github.com/user/repo, and your repo must include a tag that matches this cookbook version number