{"id":13512329,"url":"https://github.com/voxpupuli/puppet-elasticsearch","last_synced_at":"2025-12-11T21:38:08.194Z","repository":{"id":5755669,"uuid":"6968490","full_name":"voxpupuli/puppet-elasticsearch","owner":"voxpupuli","description":"Elasticsearch Puppet module","archived":false,"fork":false,"pushed_at":"2025-10-17T14:48:08.000Z","size":3073,"stargazers_count":401,"open_issues_count":99,"forks_count":469,"subscribers_count":290,"default_branch":"master","last_synced_at":"2025-12-11T02:45:34.531Z","etag":null,"topics":["centos-puppet-module","debian-puppet-module","elasticsearch","hacktoberfest","linux-puppet-module","oraclelinux-puppet-module","puppet","redhat-puppet-module","ruby","scientific-puppet-module","sles-puppet-module","ubuntu-puppet-module"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voxpupuli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"open_collective":"vox-pupuli","github":"voxpupuli"}},"created_at":"2012-12-02T15:09:34.000Z","updated_at":"2025-11-19T18:09:12.000Z","dependencies_parsed_at":"2024-04-15T07:13:27.261Z","dependency_job_id":"ac60010b-21a5-4493-92fa-af239ff53ea9","html_url":"https://github.com/voxpupuli/puppet-elasticsearch","commit_stats":{"total_commits":1823,"total_committers":140,"mean_commits":"13.021428571428572","dds":0.4975315414152496,"last_synced_commit":"543c5821bd9fa58f122443efa123e4a90381c63f"},"previous_names":["elastic/puppet-elasticsearch","elasticsearch/puppet-elasticsearch"],"tags_count":74,"template":false,"template_full_name":null,"purl":"pkg:github/voxpupuli/puppet-elasticsearch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-elasticsearch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-elasticsearch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-elasticsearch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-elasticsearch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voxpupuli","download_url":"https://codeload.github.com/voxpupuli/puppet-elasticsearch/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxpupuli%2Fpuppet-elasticsearch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27670522,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-11T02:00:11.302Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["centos-puppet-module","debian-puppet-module","elasticsearch","hacktoberfest","linux-puppet-module","oraclelinux-puppet-module","puppet","redhat-puppet-module","ruby","scientific-puppet-module","sles-puppet-module","ubuntu-puppet-module"],"created_at":"2024-08-01T03:01:44.121Z","updated_at":"2025-12-11T21:38:08.172Z","avatar_url":"https://github.com/voxpupuli.png","language":"Ruby","funding_links":["https://opencollective.com/vox-pupuli","https://github.com/sponsors/voxpupuli"],"categories":["Ruby","Configuration Management"],"sub_categories":[],"readme":"# Elasticsearch Puppet Module\n[![Build Status](https://github.com/voxpupuli/puppet-elasticsearch/workflows/CI/badge.svg)](https://github.com/voxpupuli/puppet-elasticsearch/actions?query=workflow%3ACI)\n[![Release](https://github.com/voxpupuli/puppet-elasticsearch/actions/workflows/release.yml/badge.svg)](https://github.com/voxpupuli/puppet-elasticsearch/actions/workflows/release.yml)\n[![Puppet Forge](https://img.shields.io/puppetforge/v/puppet/elasticsearch.svg)](https://forge.puppetlabs.com/puppet/elasticsearch)\n[![Puppet Forge - downloads](https://img.shields.io/puppetforge/dt/puppet/elasticsearch.svg)](https://forge.puppetlabs.com/puppet/elasticsearch)\n[![Puppet Forge - endorsement](https://img.shields.io/puppetforge/e/puppet/elasticsearch.svg)](https://forge.puppetlabs.com/puppet/elasticsearch)\n[![Puppet Forge - scores](https://img.shields.io/puppetforge/f/puppet/elasticsearch.svg)](https://forge.puppetlabs.com/puppet/elasticsearch)\n[![puppetmodule.info docs](http://www.puppetmodule.info/images/badge.png)](http://www.puppetmodule.info/m/puppet-elasticsearch)\n[![Apache-2 License](https://img.shields.io/github/license/voxpupuli/puppet-elasticsearch.svg)](LICENSE)\n[![Donated by Elastic](https://img.shields.io/badge/donated%20by-Elastic-fb7047.svg)](#transfer-notice)\n\n#### Table of Contents\n\n1. [Module description - What the module does and why it is useful](#module-description)\n2. [Setup - The basics of getting started with Elasticsearch](#setup)\n  * [The module manages the following](#the-module-manages-the-following)\n  * [Requirements](#requirements)\n3. [Usage - Configuration options and additional functionality](#usage)\n4. [Advanced features - Extra information on advanced usage](#advanced-features)\n5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\n6. [Limitations - OS compatibility, etc.](#limitations)\n7. [Development - Guide for contributing to the module](#development)\n8. [Support - When you need help with this module](#support)\n9. [Transfer Notice](#transfer-notice)\n\n## Module description\n\nThis module sets up [Elasticsearch](https://www.elastic.co/overview/elasticsearch/) instances with additional resource for plugins, templates, and more.\n\nThis module is actively tested against Elasticsearch 2.x, 5.x, and 6.x.\n\n# WARNING: The 7.x major release of this module contains breaking changes!\n\nIn order to simplify the management of Elasticsearch moving forward, and add support for both Elasticsearch 6.x and 7.x, support for\nrunning multiple instances of Elasticsearch has been removed.\n\nThis module also does not currently handle the migration from the instance based configuration to the new single deployment model.\nTherefore in-place upgrades from version 6.x of this module to 7.x, or migrations from multi-instance to single deployment is not currently supported.\nWe hope to add support for this in a future release.\n\nTherefore please ensure that you test this major release in your environment before using it in production!\n\n## Setup\n\n### The module manages the following\n\n* Elasticsearch repository files.\n* Elasticsearch package.\n* Elasticsearch configuration file.\n* Elasticsearch service.\n* Elasticsearch plugins.\n* Elasticsearch snapshot repositories.\n* Elasticsearch templates.\n* Elasticsearch ingest pipelines.\n* Elasticsearch index settings.\n* Elasticsearch users, roles, and certificates.\n* Elasticsearch licenses.\n* Elasticsearch keystores.\n\n### Requirements\n\n* The [stdlib](https://forge.puppetlabs.com/puppetlabs/stdlib) Puppet library.\n* [Augeas](http://augeas.net/)\n* [puppetlabs-java_ks](https://forge.puppetlabs.com/puppetlabs/java_ks) for certificate management (optional).\n\nBeginning with Elasticsearch 7.0.0, a Java JDK has been bundled as part of the elasticsearch package.\nHowever there still needs to be a version of Java present on the system being managed in order for Puppet to be able to run various utilities.\nWe recommend managing your Java installation with the [puppetlabs-java](https://forge.puppetlabs.com/puppetlabs/java) module.\n\n#### Repository management\n\nWhen using the repository management, the following module dependencies are required:\n\n* General: [Puppet/elastic_stack](https://forge.puppet.com/puppet/elastic_stack)\n* Debian/Ubuntu: [Puppetlabs/apt](https://forge.puppetlabs.com/puppetlabs/apt)\n* openSUSE/SLES: [puppet/zypprepo](https://forge.puppetlabs.com/puppet/zypprepo)\n\n### Beginning with Elasticsearch\n\nDeclare the top-level `elasticsearch` class (managing repositories) and set up an instance:\n\n```puppet\ninclude ::java\n\nclass { 'elasticsearch': }\n```\n\n## Usage\n\n### Main class\n\nMost top-level parameters in the `elasticsearch` class are set to reasonable defaults.\nThe following are some parameters that may be useful to override:\n\n#### Install a specific version\n\n```puppet\nclass { 'elasticsearch':\n  version =\u003e '7.9.3'\n}\n```\n\nNote: This will only work when using the repository.\n\n#### Automatically restarting the service (default set to false)\n\nBy default, the module will not restart Elasticsearch when the configuration file, package, or plugins change.\nThis can be overridden globally with the following option:\n\n```puppet\nclass { 'elasticsearch':\n  restart_on_change =\u003e true\n}\n```\n\nOr controlled with the more granular options: `restart_config_change`, `restart_package_change`, and `restart_plugin_change.`\n\n#### Automatic upgrades (default set to false)\n\n```puppet\nclass { 'elasticsearch':\n  autoupgrade =\u003e true\n}\n```\n\n#### Removal/Decommissioning\n\n```puppet\nclass { 'elasticsearch':\n  ensure =\u003e 'absent'\n}\n```\n\n#### Install everything but disable service(s) afterwards\n\n```puppet\nclass { 'elasticsearch':\n  status =\u003e 'disabled'\n}\n```\n\n#### API Settings\n\nSome resources, such as `elasticsearch::template`, require communicating with the Elasticsearch REST API.\nBy default, these API settings are set to:\n\n```puppet\nclass { 'elasticsearch':\n  api_protocol            =\u003e 'http',\n  api_host                =\u003e 'localhost',\n  api_port                =\u003e 9200,\n  api_timeout             =\u003e 10,\n  api_basic_auth_username =\u003e undef,\n  api_basic_auth_password =\u003e undef,\n  api_ca_file             =\u003e undef,\n  api_ca_path             =\u003e undef,\n  validate_tls            =\u003e true,\n}\n```\n\nEach of these can be set at the top-level `elasticsearch` class and inherited for each resource or overridden on a per-resource basis.\n\n#### Dynamically Created Resources\n\nThis module supports managing all of its defined types through top-level parameters to better support Hiera and Puppet Enterprise.\nFor example, to manage an index template directly from the `elasticsearch` class:\n\n```puppet\nclass { 'elasticsearch':\n  templates =\u003e {\n    'logstash' =\u003e {\n      'content' =\u003e {\n        'template' =\u003e 'logstash-*',\n        'settings' =\u003e {\n          'number_of_replicas' =\u003e 0\n        }\n      }\n    }\n  }\n}\n```\n### Plugins\n\nThis module can help manage [a variety of plugins](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-plugins.html#known-plugins).\nNote that `module_dir` is where the plugin will install itself to and must match that published by the plugin author; it is not where you would like to install it yourself.\n\n#### From an official repository\n\n```puppet\nelasticsearch::plugin { 'x-pack': }\n```\n\n#### From a custom url\n\n```puppet\nelasticsearch::plugin { 'jetty':\n  url =\u003e 'https://oss-es-plugins.s3.amazonaws.com/elasticsearch-jetty/elasticsearch-jetty-1.2.1.zip'\n}\n```\n\n#### Using a proxy\n\nYou can also use a proxy if required by setting the `proxy_host` and `proxy_port` options:\n```puppet\nelasticsearch::plugin { 'lmenezes/elasticsearch-kopf',\n  proxy_host =\u003e 'proxy.host.com',\n  proxy_port =\u003e 3128\n}\n```\n\nProxies that require usernames and passwords are similarly supported with the `proxy_username` and `proxy_password` parameters.\n\nPlugin name formats that are supported include:\n\n* `elasticsearch/plugin/version` (for official elasticsearch plugins downloaded from download.elastic.co)\n* `groupId/artifactId/version` (for community plugins downloaded from maven central or OSS Sonatype)\n* `username/repository` (for site plugins downloaded from github master)\n\n#### Upgrading plugins\n\nWhen you specify a certain plugin version, you can upgrade that plugin by specifying the new version.\n\n```puppet\nelasticsearch::plugin { 'elasticsearch/elasticsearch-cloud-aws/2.1.1': }\n```\n\nAnd to upgrade, you would simply change it to\n\n```puppet\nelasticsearch::plugin { 'elasticsearch/elasticsearch-cloud-aws/2.4.1': }\n```\n\nPlease note that this does not work when you specify 'latest' as a version number.\n\n#### ES 6.x and 7.x official plugins\nFor the Elasticsearch commercial plugins you can refer them to the simple name.\n\nSee [Plugin installation](https://www.elastic.co/guide/en/elasticsearch/plugins/current/installation.html) for more details.\n\n### Scripts\n\nInstalls [scripts](http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html) to be used by Elasticsearch.\nThese scripts are shared across all defined instances on the same host.\n\n```puppet\nelasticsearch::script { 'myscript':\n  ensure =\u003e 'present',\n  source =\u003e 'puppet:///path/to/my/script.groovy'\n}\n```\n\nScript directories can also be recursively managed for large collections of scripts:\n\n```puppet\nelasticsearch::script { 'myscripts_dir':\n  ensure  =\u003e 'directory,\n  source  =\u003e 'puppet:///path/to/myscripts_dir'\n  recurse =\u003e 'remote',\n}\n```\n\n### Templates\n\nBy default templates use the top-level `elasticsearch::api_*` settings to communicate with Elasticsearch.\nThe following is an example of how to override these settings:\n\n```puppet\nelasticsearch::template { 'templatename':\n  api_protocol            =\u003e 'https',\n  api_host                =\u003e $::ipaddress,\n  api_port                =\u003e 9201,\n  api_timeout             =\u003e 60,\n  api_basic_auth_username =\u003e 'admin',\n  api_basic_auth_password =\u003e 'adminpassword',\n  api_ca_file             =\u003e '/etc/ssl/certs',\n  api_ca_path             =\u003e '/etc/pki/certs',\n  validate_tls            =\u003e false,\n  source                  =\u003e 'puppet:///path/to/template.json',\n}\n```\n\nFrom version 7.8 elasticserch provides a new composable templates functionality, both legacy templates api and new composable templates api are supported using different data types.\n\n#### Data types \u0026 defines\n\nFor legacy templates `template` is used.\n\nFor composable templates `component_template` and `index_template` are used.\n\nBoth types can be used at the same time\n\n#### Add a new template using a file\n\nThis will install and/or replace the template in Elasticsearch:\n\n```puppet\nelasticsearch::template { 'templatename':\n  source =\u003e 'puppet:///path/to/template.json',\n}\n```\n\n#### Add a new template using content\n\nThis will install and/or replace the template in Elasticsearch:\n\n```puppet\nelasticsearch::template { 'templatename':\n  content =\u003e {\n    'template' =\u003e \"*\",\n    'settings' =\u003e {\n      'number_of_replicas' =\u003e 0\n    }\n  }\n}\n```\n\nPlain JSON strings are also supported.\n\n```puppet\nelasticsearch::template { 'templatename':\n  content =\u003e '{\"template\":\"*\",\"settings\":{\"number_of_replicas\":0}}'\n}\n```\n\n#### Delete a template\n\n```puppet\nelasticsearch::template { 'templatename':\n  ensure =\u003e 'absent'\n}\n```\n\n### Ingestion Pipelines\n\nPipelines behave similar to templates in that their contents can be controlled\nover the Elasticsearch REST API with a custom Puppet resource.\nAPI parameters follow the same rules as templates (those settings can either be\ncontrolled at the top-level in the `elasticsearch` class or set per-resource).\n\n#### Adding a new pipeline\n\nThis will install and/or replace an ingestion pipeline in Elasticsearch\n(ingestion settings are compared against the present configuration):\n\n```puppet\nelasticsearch::pipeline { 'addfoo':\n  content =\u003e {\n    'description' =\u003e 'Add the foo field',\n    'processors' =\u003e [{\n      'set' =\u003e {\n        'field' =\u003e 'foo',\n        'value' =\u003e 'bar'\n      }\n    }]\n  }\n}\n```\n\n#### Delete a pipeline\n\n```puppet\nelasticsearch::pipeline { 'addfoo':\n  ensure =\u003e 'absent'\n}\n```\n\n\n### Index Settings\n\nThis module includes basic support for ensuring an index is present or absent\nwith optional index settings.\nAPI access settings follow the pattern previously mentioned for templates.\n\n#### Creating an index\n\nAt the time of this writing, only index settings are supported.\nNote that some settings (such as `number_of_shards`) can only be set at index\ncreation time.\n\n```puppet\nelasticsearch::index { 'foo':\n  settings =\u003e {\n    'index' =\u003e {\n      'number_of_replicas' =\u003e 0\n    }\n  }\n}\n```\n\n#### Delete an index\n\n```puppet\nelasticsearch::index { 'foo':\n  ensure =\u003e 'absent'\n}\n```\n\n### Snapshot Repositories\n\nBy default snapshot_repositories use the top-level `elasticsearch::api_*` settings to communicate with Elasticsearch.\nThe following is an example of how to override these settings:\n\n```puppet\nelasticsearch::snapshot_repository { 'backups':\n  api_protocol            =\u003e 'https',\n  api_host                =\u003e $::ipaddress,\n  api_port                =\u003e 9201,\n  api_timeout             =\u003e 60,\n  api_basic_auth_username =\u003e 'admin',\n  api_basic_auth_password =\u003e 'adminpassword',\n  api_ca_file             =\u003e '/etc/ssl/certs',\n  api_ca_path             =\u003e '/etc/pki/certs',\n  validate_tls            =\u003e false,\n  location                =\u003e '/backups',\n}\n```\n\n#### Delete a snapshot repository\n\n```puppet\nelasticsearch::snapshot_repository { 'backups':\n  ensure   =\u003e 'absent',\n  location =\u003e '/backup'\n}\n```\n\n### SLM (Snapshot Lifecycle Management)\n\nBy default SLM use the top-level `elasticsearch::api_*` settings to communicate with Elasticsearch.\nThe following is an example of how to override these settings:\n\n```puppet\nelasticsearch::slm_policy { 'policiyname':\n  api_protocol            =\u003e 'https',\n  api_host                =\u003e $::ipaddress,\n  api_port                =\u003e 9201,\n  api_timeout             =\u003e 60,\n  api_basic_auth_username =\u003e 'admin',\n  api_basic_auth_password =\u003e 'adminpassword',\n  api_ca_file             =\u003e '/etc/ssl/certs',\n  api_ca_path             =\u003e '/etc/pki/certs',\n  validate_tls            =\u003e false,\n  source                  =\u003e 'puppet:///path/to/policy.json',\n}\n```\n\n#### Add a new SLM policy using a file\n\nThis will install and/or replace the SLM policy in Elasticsearch:\n\n```puppet\nelasticsearch::slm_policy { 'policyname':\n  source =\u003e 'puppet:///path/to/policy.json',\n}\n```\n\n#### Add a new SLM policy using content\nThis will install and/or replace ILM policy in Elasticsearch:\n\n```puppet\nelasticsearch::slm_policy { 'policyname':\n  content =\u003e {\n    name       =\u003e '\u003cbackup-{now/d}\u003e',\n    schedule   =\u003e '0 30 1 * * ?',\n    repository =\u003e 'backup',\n    config     =\u003e { },\n    retention  =\u003e {\n      expire_after =\u003e '60d',\n      min_count    =\u003e 2,\n      max_count    =\u003e 10\n    }\n  }\n}\n```\n\n### ILM (Index Lifecycle Management)\n\nBy default ILM use the top-level `elasticsearch::api_*` settings to communicate with Elasticsearch.\nThe following is an example of how to override these settings:\n\n```puppet\nelasticsearch::ilm_policy { 'policiyname':\n  api_protocol            =\u003e 'https',\n  api_host                =\u003e $::ipaddress,\n  api_port                =\u003e 9201,\n  api_timeout             =\u003e 60,\n  api_basic_auth_username =\u003e 'admin',\n  api_basic_auth_password =\u003e 'adminpassword',\n  api_ca_file             =\u003e '/etc/ssl/certs',\n  api_ca_path             =\u003e '/etc/pki/certs',\n  validate_tls            =\u003e false,\n  source                  =\u003e 'puppet:///path/to/policy.json',\n}\n```\n\n#### Add a new ILM policy using a file\n\nThis will install and/or replace the ILM policy in Elasticsearch:\n\n```puppet\nelasticsearch::ilm_policy { 'policyname':\n  source =\u003e 'puppet:///path/to/policy.json',\n}\n```\n\n#### Add a new ILM policy using content\nThis will install and/or replace ILM policy in Elasticsearch:\n\n```puppet\nelasticsearch::ilm_policy { 'policyname':\n  content =\u003e {\n    policy =\u003e {\n      phases =\u003e {\n        warm =\u003e {\n          min_age =\u003e \"7d\"\n          actions =\u003e {\n            forcemerge =\u003e {\n              max_num_segments =\u003e 1\n            }\n          }\n        }\n      }\n    }\n  }\n}\n```\n#### Delete an ILM policy\n\nThis will install and/or replace the ILM policy in Elasticsearch:\n\n```puppet\nelasticsearch::ilm_policy { 'policyname':\n  ensure =\u003e 'absent',\n}\n```\n\n### Connection Validator\n\nThis module offers a way to make sure an instance has been started and is up and running before\ndoing a next action. This is done via the use of the `es_instance_conn_validator` resource.\n```puppet\nes_instance_conn_validator { 'myinstance' :\n  server =\u003e 'es.example.com',\n  port   =\u003e '9200',\n}\n```\n\nA common use would be for example :\n\n```puppet\nclass { 'kibana4' :\n  require =\u003e Es_Instance_Conn_Validator['myinstance'],\n}\n```\n\n### Package installation\n\nThere are two different ways of installing Elasticsearch:\n\n#### Repository\n\n\n##### Choosing an Elasticsearch major version\n\nThis module uses the `elastic/elastic_stack` module to manage package repositories. Because there is a separate repository for each major version of the Elastic stack, selecting which version to configure is necessary to change the default repository value, like this:\n\n\n```puppet\nclass { 'elastic_stack::repo':\n  version =\u003e 6,\n}\n\nclass { 'elasticsearch':\n  version =\u003e '6.8.12',\n}\n```\n\nThis module defaults to the upstream package repositories, which as of Elasticsearch 6.3, includes X-Pack. In order to use the purely OSS (open source) package and repository, the appropriate `oss` flag must be set on the `elastic_stack::repo` and `elasticsearch` classes:\n\n```puppet\nclass { 'elastic_stack::repo':\n  oss =\u003e true,\n}\n\nclass { 'elasticsearch':\n  oss =\u003e true,\n}\n```\n\n##### Manual repository management\n\nYou may want to manage repositories manually. You can disable automatic repository management like this:\n\n```puppet\nclass { 'elasticsearch':\n  manage_repo =\u003e false,\n}\n```\n\n#### Remote package source\n\nWhen a repository is not available or preferred you can install the packages from a remote source:\n\n##### http/https/ftp\n\n```puppet\nclass { 'elasticsearch':\n  package_url =\u003e 'https://download.elasticsearch.org/elasticsearch/elasticsearch/elasticsearch-1.4.2.deb',\n  proxy_url   =\u003e 'http://proxy.example.com:8080/',\n}\n```\n\nSetting `proxy_url` to a location will enable download using the provided proxy\nserver.\nThis parameter is also used by `elasticsearch::plugin`.\nSetting the port in the `proxy_url` is mandatory.\n`proxy_url` defaults to `undef` (proxy disabled).\n\n##### puppet://\n```puppet\nclass { 'elasticsearch':\n  package_url =\u003e 'puppet:///path/to/elasticsearch-1.4.2.deb'\n}\n```\n\n##### Local file\n\n```puppet\nclass { 'elasticsearch':\n  package_url =\u003e 'file:/path/to/elasticsearch-1.4.2.deb'\n}\n```\n\n### JVM Configuration\n\nWhen configuring Elasticsearch's memory usage, you can modify it by setting `jvm_options`:\n\n```puppet\nclass { 'elasticsearch':\n  jvm_options =\u003e [\n    '-Xms4g',\n    '-Xmx4g'\n  ]\n}\n```\n\n### Service management\n\nCurrently only the basic SysV-style [init](https://en.wikipedia.org/wiki/Init) and [Systemd](http://en.wikipedia.org/wiki/Systemd) service providers are supported, but other systems could be implemented as necessary (pull requests welcome).\n\n#### Defaults File\n\nThe *defaults* file (`/etc/defaults/elasticsearch` or `/etc/sysconfig/elasticsearch`) for the Elasticsearch service can be populated as necessary.\nThis can either be a static file resource or a simple key value-style  [hash](http://docs.puppetlabs.com/puppet/latest/reference/lang_datatypes.html#hashes) object, the latter being particularly well-suited to pulling out of a data source such as Hiera.\n\n##### File source\n\n```puppet\nclass { 'elasticsearch':\n  init_defaults_file =\u003e 'puppet:///path/to/defaults'\n}\n```\n##### Hash representation\n\n```puppet\n$config_hash = {\n  'ES_HEAP_SIZE' =\u003e '30g',\n}\n\nclass { 'elasticsearch':\n  init_defaults =\u003e $config_hash\n}\n```\n\nNote: `init_defaults` hash can be passed to the main class and to the instance.\n\n## Advanced features\n\n### Security\n\nFile-based users, roles, and certificates can be managed by this module.\n\n**Note**: If you are planning to use these features, it is *highly recommended* you read the following documentation to understand the caveats and extent of the resources available to you.\n\n#### Roles\n\nRoles in the file realm can be managed using the `elasticsearch::role` type.\nFor example, to create a role called `myrole`, you could use the following resource:\n\n```puppet\nelasticsearch::role { 'myrole':\n  privileges =\u003e {\n    'cluster' =\u003e [ 'monitor' ],\n    'indices' =\u003e [{\n      'names'      =\u003e [ '*' ],\n      'privileges' =\u003e [ 'read' ],\n    }]\n  }\n}\n```\n\nThis role would grant users access to cluster monitoring and read access to all indices.\nSee the [Security](https://www.elastic.co/guide/en/elasticsearch/reference/current/elasticsearch-security.html) documentation for your version to determine what `privileges` to use and how to format them (the Puppet hash representation will simply be translated into yaml.)\n\n**Note**: The Puppet provider for `elasticsearch_user` has fine-grained control over the `roles.yml` file and thus will leave the default roles in-place.\nIf you would like to explicitly purge the default roles (leaving only roles managed by puppet), you can do so by including the following in your manifest:\n\n```puppet\nresources { 'elasticsearch_role':\n  purge =\u003e true,\n}\n```\n\n##### Mappings\n\nAssociating mappings with a role for file-based management is done by passing an array of strings to the `mappings` parameter of the `elasticsearch::role` type.\nFor example, to define a role with mappings:\n\n```puppet\nelasticsearch::role { 'logstash':\n  mappings   =\u003e [\n    'cn=group,ou=devteam',\n  ],\n  privileges =\u003e {\n    'cluster' =\u003e 'manage_index_templates',\n    'indices' =\u003e [{\n      'names'      =\u003e ['logstash-*'],\n      'privileges' =\u003e [\n        'write',\n        'delete',\n        'create_index',\n      ],\n    }],\n  },\n}\n```\n\nIf you'd like to keep the mappings file purged of entries not under Puppet's control, you should use the following `resources` declaration because mappings are a separate low-level type:\n\n```puppet\nresources { 'elasticsearch_role_mapping':\n  purge =\u003e true,\n}\n```\n\n#### Users\n\nUsers can be managed using the `elasticsearch::user` type.\nFor example, to create a user `mysuser` with membership in `myrole`:\n\n```puppet\nelasticsearch::user { 'myuser':\n  password =\u003e 'mypassword',\n  roles    =\u003e ['myrole'],\n}\n```\n\nThe `password` parameter will also accept password hashes generated from the `esusers`/`users` utility and ensure the password is kept in-sync with the Shield `users` file for all Elasticsearch instances.\n\n```puppet\nelasticsearch::user { 'myuser':\n  password =\u003e '$2a$10$IZMnq6DF4DtQ9c4sVovgDubCbdeH62XncmcyD1sZ4WClzFuAdqspy',\n  roles    =\u003e ['myrole'],\n}\n```\n\n**Note**: When using the `esusers`/`users` provider (the default for plaintext passwords), Puppet has no way to determine whether the given password is in-sync with the password hashed by Elasticsearch.\nIn order to work around this, the `elasticsearch::user` resource has been designed to accept refresh events in order to update password values.\nThis is not ideal, but allows you to instruct the resource to change the password when needed.\nFor example, to update the aforementioned user's password, you could include the following your manifest:\n\n```puppet\nnotify { 'update password': } ~\u003e\nelasticsearch::user { 'myuser':\n  password =\u003e 'mynewpassword',\n  roles    =\u003e ['myrole'],\n}\n```\n\n#### Certificates\n\nSSL/TLS can be enabled by providing the appropriate class params with paths to the certificate and private key files, and a password for the keystore.\n\n```puppet\nclass { 'elasticsearch' :\n  ssl                  =\u003e true,\n  ca_certificate       =\u003e '/path/to/ca.pem',\n  certificate          =\u003e '/path/to/cert.pem',\n  private_key          =\u003e '/path/to/key.pem',\n  keystore_password    =\u003e 'keystorepassword',\n}\n```\n\n**Note**: Setting up a proper CA and certificate infrastructure is outside the scope of this documentation, see the aforementioned security guide for more information regarding the generation of these certificate files.\n\nThe module will set up a keystore file for the node to use and set the relevant options in `elasticsearch.yml` to enable TLS/SSL using the certificates and key provided.\n\n#### System Keys\n\nSystem keys can be passed to the module, where they will be placed into individual instance configuration directories.\nThis can be set at the `elasticsearch` class and inherited across all instances:\n\n```puppet\nclass { 'elasticsearch':\n  system_key =\u003e 'puppet:///path/to/key',\n}\n```\n\n### Licensing\n\nIf you use the aforementioned security features, you may need to install a user license to leverage particular features outside of a trial license.\nThis module can handle installation of licenses without the need to write custom `exec` or `curl` code to install license data.\n\nYou may instruct the module to install a license through the `elasticsearch::license` parameter:\n\n```puppet\nclass { 'elasticsearch':\n  license =\u003e $license,\n}\n```\n\nThe `license` parameter will accept either a Puppet hash representation of the license file json or a plain json string that will be parsed into a native Puppet hash.\nAlthough dependencies are automatically created to ensure that the Elasticsearch service is listening and ready before API calls are made, you may need to set the appropriate `api_*` parameters to ensure that the module can interact with the Elasticsearch API over the appropriate port, protocol, and with sufficient user rights to install the license.\n\nThe native provider for licenses will _not_ print license signatures as part of Puppet's changelog to ensure that sensitive values are not included in console output or Puppet reports.\nAny fields present in the `license` parameter that differ from the license installed in a cluster will trigger a flush of the resource and new `POST` to the Elasticsearch API with the license content, though the sensitive `signature` field is not compared as it is not returned from the Elasticsearch licensing APIs.\n\n### Data directories\n\nThere are several different ways of setting data directories for Elasticsearch.\nIn every case the required configuration options are placed in the `elasticsearch.yml` file.\n\n#### Default\n\nBy default we use:\n\n    /var/lib/elasticsearch\n\nWhich mirrors the upstream defaults.\n\n#### Single global data directory\n\nIt is possible to override the default data directory by specifying the `datadir` param:\n\n```puppet\nclass { 'elasticsearch':\n  datadir =\u003e '/var/lib/elasticsearch-data'\n}\n```\n\n#### Multiple Global data directories\n\nIt's also possible to specify multiple data directories using the `datadir` param:\n\n```puppet\nclass { 'elasticsearch':\n  datadir =\u003e [ '/var/lib/es-data1', '/var/lib/es-data2']\n}\n```\n\nSee [the Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-node.html#max-local-storage-nodes) for additional information regarding this configuration.\n\n### Elasticsearch configuration\n\nThe `config` option can be used to provide additional configuration options to Elasticsearch.\n\n#### Configuration writeup\n\nThe `config` hash can be written in 2 different ways:\n\n##### Full hash writeup\n\nInstead of writing the full hash representation:\n\n```puppet\nclass { 'elasticsearch':\n  config                 =\u003e {\n   'cluster'             =\u003e {\n     'name'              =\u003e 'ClusterName',\n     'routing'           =\u003e {\n        'allocation'     =\u003e {\n          'awareness'    =\u003e {\n            'attributes' =\u003e 'rack'\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n##### Short hash writeup\n\n```puppet\nclass { 'elasticsearch':\n  config =\u003e {\n    'cluster' =\u003e {\n      'name' =\u003e 'ClusterName',\n      'routing.allocation.awareness.attributes' =\u003e 'rack'\n    }\n  }\n}\n```\n\n#### Keystore Settings\n\nRecent versions of Elasticsearch include the [elasticsearch-keystore](https://www.elastic.co/guide/en/elasticsearch/reference/current/secure-settings.html) utility to create and manage the `elasticsearch.keystore` file which can store sensitive values for certain settings.\nThe settings and values for this file can be controlled by this module.\nSettings follow the behavior of the `config` parameter for the top-level Elasticsearch class and `elasticsearch::instance` defined types.\nThat is, you may define keystore settings globally, and all values will be merged with instance-specific settings for final inclusion in the `elasticsearch.keystore` file.\nNote that each hash key is passed to the `elasticsearch-keystore` utility in a straightforward manner, so you should specify the hash passed to `secrets` in flattened form (that is, without full nested hash representation).\n\nFor example, to define cloud plugin credentials for all instances:\n\n```puppet\nclass { 'elasticsearch':\n  secrets =\u003e {\n    'cloud.aws.access_key' =\u003e 'AKIA....',\n    'cloud.aws.secret_key' =\u003e 'AKIA....',\n  }\n}\n```\n\n##### Purging Secrets\n\nBy default, if a secret setting exists on-disk that is not present in the `secrets` hash, this module will leave it intact.\nIf you prefer to keep only secrets in the keystore that are specified in the `secrets` hash, use the `purge_secrets` boolean parameter either on the `elasticsearch` class to set it globally or per-instance.\n\n##### Notifying Services\n\nAny changes to keystore secrets will notify running elasticsearch services by respecting the `restart_on_change` and `restart_config_change` parameters.\n\n## Reference\n\nClass parameters are available in [the auto-generated documentation\npages](https://elastic.github.io/puppet-elasticsearch/puppet_classes/elasticsearch.html).\nAutogenerated documentation for types, providers, and ruby helpers is also\navailable on the same documentation site.\n\n## Limitations\n\nThis module is built upon and tested against the versions of Puppet listed in\nthe metadata.json file (i.e. the listed compatible versions on the Puppet\nForge).\n\nThe module has been tested on:\n\n* Amazon Linux 1/2\n* Debian 8/9/10\n* CentOS 7/8\n* OracleLinux 7/8\n* Ubuntu 16.04, 18.04, 20.04\n* SLES 12\n\nTesting on other platforms has been light and cannot be guaranteed.\n\n## Development\n\nPlease see the [CONTRIBUTING.md](https://github.com/voxpupuli/puppet-elasticsearch/blob/master/.github/CONTRIBUTING.md) file for instructions regarding development environments and testing.\n\n## Support\n\nThe Puppet Elasticsearch module is community supported and not officially supported by Elastic Support.\n\n## Transfer Notice\n\nThis module was originally authored by [Elastic](https://www.elastic.co).\nThe maintainer preferred that Vox Pupuli take ownership of the module for future improvement and maintenance.\nExisting pull requests and issues were transferred over, please fork and continue to contribute here instead of Elastic.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxpupuli%2Fpuppet-elasticsearch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoxpupuli%2Fpuppet-elasticsearch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxpupuli%2Fpuppet-elasticsearch/lists"}