Adoptable Cookbooks List

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.

Elasticsearch - This cookbook is being written and tested to support Elasticsearch 5.x and greater. If you must have a cookbook that works with older versions of Elasticsearch, please test and then pin to a specific, older major.minor version of this cookbook and only leave the patch release to float. Older versions can be found via Git tags or on Chef Supermarket. We also maintain bugfix branches for major released lines (0.x, 1.x, 2.x) of this cookbook so that we can still release fixes for older cookbooks.

Chef - The latest release of this cookbook is intended to support the three most recent releases of Chef, and tests against those. Earlier versions may also be supported, though we suggest that you use Chef 12.x at a minimum. It implements support for CI as well as more modern testing with chefspec and test-kitchen. It no longer supports some of the more extraneous features such as discovery (use chef search in your wrapper cookbook) or EBS device creation (use the aws cookbook).

Previous versions of this cookbook may be found using the git tags on this repository.

Attributes

Please consult attributes/default.rb for a large list
of checksums for many different archives and package files of different
elasticsearch versions. Both recipes and resources/providers here use those
default values.

You may use %s in your URL and this cookbook will use sprintf/format to insert
the version parameter as a string into your download_url.

For example, this will pass a username 'foo' to elasticsearch_user and set a uid to 1234:
default['elasticsearch']['user']['username'] = 'foo'
default['elasticsearch']['user']['uid'] = '1234'

Recipes

Resources are the intended way to consume this cookbook, however we have
provided a single recipe that configures Elasticsearch by downloading an archive
containing a distribution of Elasticsearch, and extracting that into /usr/share.

See the attributes section above to for what defaults you can adjust.

default

The default recipe creates an elasticsearch user, group, package installation,
configuration files, and service with all of the default options.

Resources

Notifications and Service Start/Restart

The resources provided in this cookbook do not automatically restart services when changes have occurred. They do start services by default when configuring a new service This has been done to protect you from accidental data loss and service outages, as nodes might restart simultaneously or may not restart at all when bad configuration values are supplied.

elasticsearch_service has a special service_actions parameter you can use to specify what state the underlying service should be in on each chef run (defaults to :enabled and :started). It will also pass through all of the standard service resource
actions to the underlying service resource if you wish to notify it.

You must supply your desired notifications when using each resource if you want Chef to automatically restart services. Again, we don't recommend this unless you know what you're doing.

Resource names

Many of the resources provided in this cookbook need to share configuration
values. For example, the elasticsearch_service resource needs to know the path
to the configuration file(s) generated by elasticsearch_configure and the path
to the actual ES binary installed by elasticsearch_install. And they both need
to know the appropriate system user and group defined by elasticsearch_user.

Search order: In order to make this easy, all resources in this cookbook use the following
search order to locate resources that apply to the same overall
Elasticsearch setup:

Resources that share the same resource name

Resources that share the same value for instance_name

Resources named default or resources named elasticsearch

This fails if both default and elasticsearch resources exist

Examples of more complicated resource names are left to the reader, but here we
present a typical example that should work in most cases:

elasticsearch_install

Actions: :install, :remove

Downloads the elasticsearch software, and unpacks it on the system. There are
currently three ways to install -- 'repository' (the default), which creates an
apt or yum repo and installs from there, 'package', which downloads the appropriate
package from elasticsearch.org and uses the package manager to install it, and
'tarball' which downloads a tarball from elasticsearch.org and unpacks it.
This resource also comes with a :remove action which will remove the package
or directory elasticsearch was unpacked into.

You may always specify a download_url and/or download_checksum, and you may
include %s which will be replaced by the version parameter you supply.

Please be sure to consult the above attribute section as that controls how
Elasticsearch version, download URL and checksum are determined if you omit
them.

Examples:

elasticsearch_install 'elasticsearch'

elasticsearch_install 'my_es_installation' do
type 'package' # type of install
version "5.0.0"
action :install # could be :remove as well
end

elasticsearch_configure

The main attribute for this resource is configuration,
which is a hash of any elasticsearch configuration directives. The
other important attribute is default_configuration -- this contains the
minimal set of required defaults.

Note that these are both not a Chef mash, everything must be in a single level
of keys and values. Any settings you pass in configuration will be merged into
(and potentially overwrite) any default settings.

elasticsearch_service

Actions: :configure, :remove

Writes out a system service configuration of the appropriate type, and enables
it to start on boot. You can override almost all of the relevant settings in
such a way that you may run multiple instances. Most settings will be taken from
a matching elasticsearch_config resource in the collection.

elasticsearch_service 'elasticsearch'

elasticsearch_plugin

Actions: :install, :remove

Installs or removes a plugin to a given elasticsearch instance and plugin
directory. Please note that there is currently no way to upgrade an existing
plugin using commandline tools, so we haven't exposed that feature here either.
Furthermore, there isn't a way to determine if a plugin is compatible with ES or
even what version it is. So once we install a plugin to a directory, we
generally assume that is the desired one and we don't touch it further.

Testing

This cookbook is equipped with both unit tests (chefspec) and integration tests
(test-kitchen and serverspec). It also comes with rubocop and foodcritic tasks
in the supplied Rakefile. Contributions to this cookbook should include tests
for new features or bugfixes, with a preference for unit tests over integration
tests to ensure speedy testing runs. All tests and most other commands here
should be run using bundler and our standard Gemfile. This ensures that
contributions and changes are made in a standardized way against the same
versions of gems. We recommend installing rubygems-bundler so that bundler is
automatically inserting bundle exec in front of commands run in a directory
that contains a Gemfile.

A full test run of all tests and style checks would look like:
bash
$ bundle exec rake style
$ bundle exec rake spec
$ bundle exec rake integration
$ bundle exec rake destroy
The final destroy is intended to clean up any systems that failed a test, and is
mostly useful when running with kitchen drivers for cloud providers, so that no
machines are left orphaned and costing you money.

Fixtures

This cookbook supplies a few different test fixtures (under test/fixtures/)
that can be shared amongst any number of unit or integration tests: cookbooks,
environments, and nodes. Environments and nodes are automatically loaded into
chef-zero for both chefspec tests that run locally and serverspec tests that run
from test-kitchen.

It also contains 'platform data' that can be used to drive unit testing, for
example, you might read httpd for some platforms and apache2 for others,
allowing you to write a single test for the Apache webserver. Unfortunately,
without further modifications to busser and busser-serverspec, the platform
data will not be available to serverspec tests.

Style and Best Practices

Rubocop and Foodcritic evaluations may be made by running rake style. There
are no overrides for foodcritic rules, however the adjustments to
rubocop are made using the supplied .rubocop.yml file and have been documented
by comments within. Most notably, rubocop has been restricted to only apply to
.rb files.

Rubocop and foodcritic tests can be executed using rake style.

Unit testing

Unit testing is done using the latest versions of Chefspec. The current default
test layout includes running against all supported platforms, as well as
stubbing data into chef-zero. This allows us to also test against chef search.
As is currently a best practice in the community, we will avoid the use of
chef-solo, but not create barriers to explicitly fail for chef-solo.

Unit tests can be executed using rake spec.

Integration testing

Integration testing is accomplished using the latest versions of test-kitchen
and serverspec. Currently, this cookbook uses the busser-serverspec plugin for
copying serverspec files to the system being tested. There is some debate in the
community about whether this should be done using busser-rspec instead, and each
busser plugin has a slightly different feature set.

While the default test-kitchen configuration uses the vagrant driver, you may
override this using ~/.kitchen/config.yml or by placing a .kitchen.local.yml
in the current directory. This allows you to run these integration tests using
any supported test-kitchen driver (ec2, rackspace, docker, etc).

Integration tests can be executed using rake integration or kitchen test.

License

This software is licensed under the Apache 2 license, quoted below.

Copyright (c) 2015 Elasticsearch <https://www.elastic.co/>
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.

Change Log

Breaking changes that were needed for v5.0.0 support (#497, #512, #424, #478, #503):
- We dropped the fancy logic for figuring out the requested version of Elasticsearch to be installed. You should pass it on the resource or in the recipe, but we no longer do a bunch of logic to figure out what you meant -- we favor being explicit now.
- We now start the service by default, instead of only :enable but not :start.
- Dropped gc_options parameter of elasticsearch_configure, and now have jvm.options. We've also dropped thread_stack_size and env_options, as they aren't used in the upstream packaging as defaults anymore.
- Install the tarball and package files into the same locations. There's no more /usr/local.
- Install types are now 'strings', not :symbols. node['elasticsearch'][<resource>][<param>] sets any elasticsearch::default recipe.