+++ /dev/null
-#Elasticsearch Puppet module
-
-[](https://travis-ci.org/elasticsearch/puppet-elasticsearch)
-
-####Table of Contents
-
-1. [Overview](#overview)
-2. [Module description - What the module does and why it is useful](#module-description)
-3. [Setup - The basics of getting started with Elasticsearch](#setup)
- * [The module manages the following](#the-module-manages-the-following)
- * [Requirements](#requirements)
-4. [Usage - Configuration options and additional functionality](#usage)
-5. [Advanced features - Extra information on advanced usage](#advanced-features)
-6. [Limitations - OS compatibility, etc.](#limitations)
-7. [Development - Guide for contributing to the module](#development)
-8. [Support - When you need help with this module](#support)
-
-
-
-##Overview
-
-This module manages Elasticsearch (http://www.elasticsearch.org/overview/elasticsearch/)
-
-##Module description
-
-The elasticsearch module sets up Elasticsearch instances and can manage plugins and templates.
-
-This module has been tested against ES 1.0 and up.
-
-##Setup
-
-###The module manages the following
-
-* Elasticsearch repository files.
-* Elasticsearch package.
-* Elasticsearch configuration file.
-* Elasticsearch service.
-* Elasticsearch plugins.
-* Elasticsearch templates.
-
-###Requirements
-
-* The [stdlib](https://forge.puppetlabs.com/puppetlabs/stdlib) Puppet library.
-* Augeas
-
-#### Repository management
-When using the repository management you will need the following dependency modules:
-
-* Debian/Ubuntu: [Puppetlabs/apt](http://forge.puppetlabs.com/puppetlabs/apt)
-* OpenSuSE: [Darin/zypprepo](https://forge.puppetlabs.com/darin/zypprepo)
-
-##Usage
-
-###Main class
-
-####Install a specific version
-
-```puppet
-class { 'elasticsearch':
- version => '1.4.2'
-}
-```
-
-Note: This will only work when using the repository.
-
-####Automatic upgrade of the software ( default set to false )
-```
-class { 'elasticsearch':
- autoupgrade => true
-}
-```
-
-####Removal/decommissioning
-```puppet
-class { 'elasticsearch':
- ensure => 'absent'
-}
-```
-
-####Install everything but disable service(s) afterwards
-```puppet
-class { 'elasticsearch':
- status => 'disabled'
-}
-```
-
-###Instances
-
-This module works with the concept of instances. For service to start you need to specify at least one instance.
-
-####Quick setup
-```puppet
-elasticsearch::instance { 'es-01': }
-```
-
-This will set up its own data directory and set the node name to `$hostname-$instance_name`
-
-####Advanced options
-
-Instance specific options can be given:
-
-```puppet
-elasticsearch::instance { 'es-01':
- config => { }, # Configuration hash
- init_defaults => { }, # Init defaults hash
- datadir => [ ], # Data directory
-}
-```
-
-See [Advanced features](#advanced-features) for more information
-
-###Plug-ins
-
-Install [a variety of plugins](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-plugins.html#known-plugins). Note 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.
-
-####From official repository
-```puppet
-elasticsearch::plugin{'lmenezes/elasticsearch-kopf':
- module_dir => 'kopf',
- instances => 'instance_name'
-}
-```
-####From custom url
-```puppet
-elasticsearch::plugin{ 'elasticsearch-jetty':
- module_dir => 'jetty',
- url => 'https://oss-es-plugins.s3.amazonaws.com/elasticsearch-jetty/elasticsearch-jetty-1.2.1.zip',
- instances => 'instance_name'
-}
-```
-
-
-####Using a proxy
-You can also use a proxy if required by setting the `proxy_host` and `proxy_port` options:
-```puppet
-elasticsearch::plugin { 'lmenezes/elasticsearch-kopf',
- module_dir => 'kopf',
- instances => 'instance_name',
- proxy_host => 'proxy.host.com',
- proxy_port => 3128
-}
-```
-
-#####Plugin name could be:
-* `elasticsearch/plugin/version` for official elasticsearch plugins (download from download.elasticsearch.org)
-* `groupId/artifactId/version` for community plugins (download from maven central or oss sonatype)
-* `username/repository` for site plugins (download from github master)
-
-
-###Scripts
-
-Install [scripts](http://www.elastic.co/guide/en/elasticsearch/reference/1.x/modules-scripting.html) to be used by Elasticsearch.
-These scripts are shared accross all defined instances on the same host.
-
-```puppet
-elasticsearch::script { 'myscript':
- ensure => 'present',
- source => 'puppet:///path/to/my/script.groovy'
-}
-```
-
-###Templates
-
-#### Add a new template using a file
-
-This will install and/or replace the template in Elasticsearch:
-
-```puppet
-elasticsearch::template { 'templatename':
- file => 'puppet:///path/to/template.json'
-}
-```
-
-#### Add a new template using content
-
-This will install and/or replace the template in Elasticsearch:
-
-```puppet
-elasticsearch::template { 'templatename':
- content => '{"template":"*","settings":{"number_of_replicas":0}}'
-}
-```
-
-#### Delete a template
-
-```puppet
-elasticsearch::template { 'templatename':
- ensure => 'absent'
-}
-```
-
-#### Host
-
-By default it uses localhost:9200 as host. you can change this with the `host` and `port` variables
-
-```puppet
-elasticsearch::template { 'templatename':
- host => $::ipaddress,
- port => 9200
-}
-```
-
-###Bindings / Clients
-
-Install a variety of [clients/bindings](http://www.elasticsearch.org/guide/en/elasticsearch/client/community/current/clients.html):
-
-####Python
-
-```puppet
-elasticsearch::python { 'rawes': }
-```
-
-####Ruby
-```puppet
-elasticsearch::ruby { 'elasticsearch': }
-```
-
-###Connection Validator
-
-This module offers a way to make sure an instance has been started and is up and running before
-doing a next action. This is done via the use of the `es_instance_conn_validator` resource.
-```puppet
-es_instance_conn_validator { 'myinstance' :
- server => 'es.example.com',
- port => '9200',
-}
-```
-
-A common use would be for example :
-
-```puppet
-class { 'kibana4' :
- require => Es_Instance_Conn_Validator['myinstance'],
-}
-```
-
-###Package installation
-
-There are 2 different ways of installing the software
-
-####Repository
-
-This option allows you to use an existing repository for package installation.
-The `repo_version` corresponds with the major version of Elasticsearch.
-
-```puppet
-class { 'elasticsearch':
- manage_repo => true,
- repo_version => '1.4',
-}
-```
-
-####Remote package source
-
-When a repository is not available or preferred you can install the packages from a remote source:
-
-#####http/https/ftp
-```puppet
-class { 'elasticsearch':
- package_url => 'https://download.elasticsearch.org/elasticsearch/elasticsearch/elasticsearch-1.4.2.deb'
-}
-```
-
-#####puppet://
-```puppet
-class { 'elasticsearch':
- package_url => 'puppet:///path/to/elasticsearch-1.4.2.deb'
-}
-```
-
-#####Local file
-```puppet
-class { 'elasticsearch':
- package_url => 'file:/path/to/elasticsearch-1.4.2.deb'
-}
-```
-
-###Java installation
-
-Most sites will manage Java separately; however, this module can attempt to install Java as well.
-This is done by using the [puppetlabs-java](https://forge.puppetlabs.com/puppetlabs/java) module.
-
-```puppet
-class { 'elasticsearch':
- java_install => true
-}
-```
-
-Specify a particular Java package/version to be installed:
-
-```puppet
-class { 'elasticsearch':
- java_install => true,
- java_package => 'packagename'
-}
-```
-
-###Service management
-
-Currently 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).
-
-
-####Defaults File
-
-The *defaults* file (`/etc/defaults/elasticsearch` or `/etc/sysconfig/elasticsearch`) for the Elasticsearch service can be populated as necessary. This 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.
-
-#####file source
-```puppet
-class { 'elasticsearch':
- init_defaults_file => 'puppet:///path/to/defaults'
-}
-```
-#####hash representation
-```puppet
-$config_hash = {
- 'ES_USER' => 'elasticsearch',
- 'ES_GROUP' => 'elasticsearch',
-}
-
-class { 'elasticsearch':
- init_defaults => $config_hash
-}
-```
-
-Note: `init_defaults` hash can be passed to the main class and to the instance.
-
-##Advanced features
-
-
-###Data directories
-
-There are 4 different ways of setting data directories for Elasticsearch.
-In every case the required configuration options are placed in the `elasticsearch.yml` file.
-
-####Default
-By default we use:
-
-`/usr/share/elasticsearch/data/$instance_name`
-
-Which provides a data directory per instance.
-
-
-####Single global data directory
-
-```puppet
-class { 'elasticsearch':
- datadir => '/var/lib/elasticsearch-data'
-}
-```
-Creates the following for each instance:
-
-`/var/lib/elasticsearch-data/$instance_name`
-
-####Multiple Global data directories
-
-```puppet
-class { 'elasticsearch':
- datadir => [ '/var/lib/es-data1', '/var/lib/es-data2']
-}
-```
-Creates the following for each instance:
-`/var/lib/es-data1/$instance_name`
-and
-`/var/lib/es-data2/$instance_name`
-
-
-####Single instance data directory
-
-```puppet
-class { 'elasticsearch': }
-
-elasticsearch::instance { 'es-01':
- datadir => '/var/lib/es-data-es01'
-}
-```
-Creates the following for this instance:
-`/var/lib/es-data-es01`
-
-####Multiple instance data directories
-
-```puppet
-class { 'elasticsearch': }
-
-elasticsearch::instance { 'es-01':
- datadir => ['/var/lib/es-data1-es01', '/var/lib/es-data2-es01']
-}
-```
-Creates the following for this instance:
-`/var/lib/es-data1-es01`
-and
-`/var/lib/es-data2-es01`
-
-
-###Main and instance configurations
-
-The `config` option in both the main class and the instances can be configured to work together.
-
-The options in the `instance` config hash will merged with the ones from the main class and override any duplicates.
-
-#### Simple merging
-
-```puppet
-class { 'elasticsearch':
- config => { 'cluster.name' => 'clustername' }
-}
-
-elasticsearch::instance { 'es-01':
- config => { 'node.name' => 'nodename' }
-}
-elasticsearch::instance { 'es-02':
- config => { 'node.name' => 'nodename2' }
-}
-
-```
-
-This example merges the `cluster.name` together with the `node.name` option.
-
-#### Overriding
-
-When duplicate options are provided, the option in the instance config overrides the ones from the main class.
-
-```puppet
-class { 'elasticsearch':
- config => { 'cluster.name' => 'clustername' }
-}
-
-elasticsearch::instance { 'es-01':
- config => { 'node.name' => 'nodename', 'cluster.name' => 'otherclustername' }
-}
-
-elasticsearch::instance { 'es-02':
- config => { 'node.name' => 'nodename2' }
-}
-```
-
-This will set the cluster name to `otherclustername` for the instance `es-01` but will keep it to `clustername` for instance `es-02`
-
-####Configuration writeup
-
-The `config` hash can be written in 2 different ways:
-
-##### Full hash writeup
-
-Instead of writing the full hash representation:
-```puppet
-class { 'elasticsearch':
- config => {
- 'cluster' => {
- 'name' => 'ClusterName',
- 'routing' => {
- 'allocation' => {
- 'awareness' => {
- 'attributes' => 'rack'
- }
- }
- }
- }
- }
-}
-```
-##### Short hash writeup
-```puppet
-class { 'elasticsearch':
- config => {
- 'cluster' => {
- 'name' => 'ClusterName',
- 'routing.allocation.awareness.attributes' => 'rack'
- }
- }
-}
-```
-
-
-##Limitations
-
-This module has been built on and tested against Puppet 3.2 and higher.
-
-The module has been tested on:
-
-* Debian 6/7
-* CentOS 6
-* Ubuntu 12.04, 14.04
-* OpenSuSE 13.x
-
-Other distro's that have been reported to work:
-
-* RHEL 6
-* OracleLinux 6
-* Scientific 6
-
-Testing on other platforms has been light and cannot be guaranteed.
-
-##Development
-
-
-##Support
-
-Need help? Join us in [#elasticsearch](https://webchat.freenode.net?channels=%23elasticsearch) on Freenode IRC or subscribe to the [elasticsearch@googlegroups.com](https://groups.google.com/forum/#!forum/elasticsearch) mailing list.
projects / mirror / dsa-puppet.git / blobdiff