sous-chefs elasticsearch: a Chef cookbook that installs and configures Elasticsearch

Services start by default but are never restarted for you

The first thing the readme explains is the behaviour that will surprise anyone used to a resource that just works. The resources provided in the cookbook do not automatically restart services when changes have occurred, though they do start services by default when configuring a new service. The stated reason is to protect you from accidental data loss and service outages, since nodes might restart simultaneously, or might not restart at all when bad configuration values are supplied. There is an escape hatch for the first case. The service resource has a service_actions parameter for specifying what state the underlying service should be in on each Chef run, defaulting to enabled and started, and it passes through the standard service resource actions to the underlying service resource if you want to notify it. But the readme is blunt about the second point. You must supply your desired notifications when using each resource if you want Chef to automatically restart services, and it says again that it does not recommend this unless you know what you are doing. That is a defensible default for a search index, where a rolling restart of every node at once is a genuine outage, but it does mean a configuration change does not take effect until you do something about it.

The resource naming scheme is how you run two instances on one host

Many of the resources need to share configuration values, and the mechanism is the resource name. The service resource needs to know the path to the configuration files generated by the configure resource and the path to the actual Elasticsearch binary installed by the install resource, and both need to know the system user and group defined by the user resource. The cookbook resolves that with a search order applied to every resource. First come resources that share the same resource name, then resources that share the same value for the instance name attribute, then resources named default or resources named elasticsearch, and that last step fails if both a default and an elasticsearch resource exist. The typical recipe therefore looks like this:

elasticsearch_user 'elasticsearch'
elasticsearch_install 'elasticsearch'
elasticsearch_configure 'elasticsearch'
elasticsearch_service 'elasticsearch'
elasticsearch_plugin 'x-pack'

Naming everything the same is what threads the paths and the user through the four resources. The alternative, giving the instance a distinct name so that several Elasticsearch setups can live on one machine, is what the instance name attribute is for.

Three install types, and a remove action that is not there

The install resource downloads the Elasticsearch software and unpacks it on the system, and there are three ways to do it. The repository type is the default and creates an apt or yum repository and installs from there. The package type downloads the appropriate package from elasticsearch.org and uses the package manager to install it. The tarball type downloads a tarball from elasticsearch.org and unpacks it. You can always specify a download URL and a download checksum, and the URL may include a placeholder that is replaced by the version you supply, which is how the same recipe works across versions. The attribute section is the one that controls how the version, the URL and the checksum are determined when you leave them out. The gap is in the removal side. The readme states plainly that the remove action has not been implemented yet, and that pull requests are welcome for it. So a rollback or a teardown of an Elasticsearch installed by this resource currently needs a different mechanism, and that is worth knowing before you make it responsible for a node.

The configure resource writes three files and takes two hashes

The configure resource sets up an Elasticsearch instance, creating the directories for configuration, logs and data, and writing the files for the logging properties, the environment script and the YAML configuration. The main attribute is configuration, a hash of Elasticsearch configuration directives, and the other important one is default_configuration, which holds the minimal set of required defaults. There is a constraint on how you write that hash, and it is called out in italics in the readme: both attributes are not a Chef mash, everything must be in a single level of keys and values, so a nested structure is not accepted. Anything you pass in configuration is merged into, and can overwrite, the defaults. The paths themselves are settable, and the example shows the usual set of home, configuration, data, logs, pid, plugins and binary directories, along with the two logging properties that point at a wrapper cookbook's template, which is the pattern for a site that wants its own logging configuration rather than the default.

The cookbook layout, the test harness and the release flow

The repository is laid out the way a well-run Chef cookbook tends to be. There are resources and libraries directories holding the resource definitions, templates for the files the configure resource writes, files for anything shipped as static content, a spec directory for the unit tests, a test directory for the integration tests, and a documentation directory. The test setup has several kitchen configurations, one for dokken, one for exec, one global and one main, which is the usual arrangement for running the suite against containers and against real machines. There are also policy files, a chefignore, a metadata file and a mise configuration for the toolchain, along with an overcommit configuration for pre-commit hooks, a rubocop configuration, a markdown lint configuration, a yamllint setup and a renovate configuration for dependency updates. Releases go through release-please with a manifest and a config, and there is a changelog directory and a release notes directory. The contributing guidelines and the frequently asked questions are both linked from the top of the readme, with an explicit request to review them before opening an issue or submitting a pull request, which is a reasonable request for a project with this many moving parts.

Version pinning, the older releases and the state of the project

There is a clear warning at the top for anyone on an older Elasticsearch, and it is worth reading because it describes how the versioning has moved. If you are looking for Elasticsearch 5.x or 6.x, the previous 3.x.x releases of the cookbook are the ones to use, with the advice to pin to the 3.0 range for support for Elasticsearch 6 and earlier, or to the 4.0 release for Elasticsearch 6 and beyond. The current release line is 6.x, with v6.0.1 published on 2026-03-21, v6.0.0 on 2026-03-16 and v5.2.0 on 2025-11-20, so the major versions track the Elasticsearch generation rather than the cookbook's own feature set. The default branch is main, and the last push was on 2026-10-19, so the branch is being worked on between releases. The licence field recorded for the repository says GitHub cannot classify it and points to the LICENSE file, which is the term to read if you intend to redistribute or modify the cookbook, and the project is published on the Chef Supermarket under the elasticsearch name.

Editorial conclusion

The sous-chefs elasticsearch cookbook is a good fit for a platform team that has standardised on Chef and wants Elasticsearch installed and configured from recipes rather than from a hand-written role, and for a group running more than one Elasticsearch instance on a host, because the instance name scheme is what makes that work. It is the wrong choice if you use Ansible, Puppet, Terraform or a container platform, since the resources are Chef specific, and it is the wrong choice if you need the service to restart itself when the configuration changes, because the resources deliberately do not do that. It is also the wrong choice if you need an idempotent uninstall, since the remove action for the install resource is not implemented. Before adopting it, read the frequently asked questions and the contributing guidelines, which the project asks you to do before opening an issue, and pin the cookbook version rather than tracking the main branch. The licence field for the repository says GitHub cannot classify it, so the LICENSE file is the place to look, the last push was on 2026-10-19, and the current release is v6.0.1 from 2026-03-21.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. sous-chefs/elasticsearch on GitHub