3rdparty/modules/elasticsearch/README.md

   1 #Elasticsearch Puppet module
   2
   3 [![Build Status](https://travis-ci.org/elasticsearch/puppet-elasticsearch.png?branch=master)](https://travis-ci.org/elasticsearch/puppet-elasticsearch)
   4
   5 ####Table of Contents
   6
   7 1. [Overview](#overview)
   8 2. [Module description - What the module does and why it is useful](#module-description)
   9 3. [Setup - The basics of getting started with Elasticsearch](#setup)
  10   * [The module manages the following](#the-module-manages-the-following)
  11   * [Requirements](#requirements)
  12 4. [Usage - Configuration options and additional functionality](#usage)
  13 5. [Advanced features - Extra information on advanced usage](#advanced-features)
  14 6. [Limitations - OS compatibility, etc.](#limitations)
  15 7. [Development - Guide for contributing to the module](#development)
  16 8. [Support - When you need help with this module](#support)
  17
  18
  19
  20 ##Overview
  21
  22 This module manages Elasticsearch (http://www.elasticsearch.org/overview/elasticsearch/)
  23
  24 ##Module description
  25
  26 The elasticsearch module sets up Elasticsearch instances and can manage plugins and templates.
  27
  28 This module has been tested against ES 1.0 and up.
  29
  30 ##Setup
  31
  32 ###The module manages the following
  33
  34 * Elasticsearch repository files.
  35 * Elasticsearch package.
  36 * Elasticsearch configuration file.
  37 * Elasticsearch service.
  38 * Elasticsearch plugins.
  39 * Elasticsearch templates.
  40
  41 ###Requirements
  42
  43 * The [stdlib](https://forge.puppetlabs.com/puppetlabs/stdlib) Puppet library.
  44 * Augeas
  45
  46 #### Repository management
  47 When using the repository management you will need the following dependency modules:
  48
  49 * Debian/Ubuntu: [Puppetlabs/apt](http://forge.puppetlabs.com/puppetlabs/apt)
  50 * OpenSuSE: [Darin/zypprepo](https://forge.puppetlabs.com/darin/zypprepo)
  51
  52 ##Usage
  53
  54 ###Main class
  55
  56 ####Install a specific version
  57
  58 ```puppet
  59 class { 'elasticsearch':
  60   version => '1.4.2'
  61 }
  62 ```
  63
  64 Note: This will only work when using the repository.
  65
  66 ####Automatic upgrade of the software ( default set to false )
  67 ```
  68 class { 'elasticsearch':
  69   autoupgrade => true
  70 }
  71 ```
  72
  73 ####Removal/decommissioning
  74 ```puppet
  75 class { 'elasticsearch':
  76   ensure => 'absent'
  77 }
  78 ```
  79
  80 ####Install everything but disable service(s) afterwards
  81 ```puppet
  82 class { 'elasticsearch':
  83   status => 'disabled'
  84 }
  85 ```
  86
  87 ###Instances
  88
  89 This module works with the concept of instances. For service to start you need to specify at least one instance.
  90
  91 ####Quick setup
  92 ```puppet
  93 elasticsearch::instance { 'es-01': }
  94 ```
  95
  96 This will set up its own data directory and set the node name to `$hostname-$instance_name`
  97
  98 ####Advanced options
  99
 100 Instance specific options can be given:
 101
 102 ```puppet
 103 elasticsearch::instance { 'es-01':
 104   config => { },        # Configuration hash
 105   init_defaults => { }, # Init defaults hash
 106   datadir => [ ],       # Data directory
 107 }
 108 ```
 109
 110 See [Advanced features](#advanced-features) for more information
 111
 112 ###Plug-ins
 113
 114 Install [a variety of plugins](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/modules-plugins.html#known-plugins):
 115
 116 ####From official repository
 117 ```puppet
 118 elasticsearch::plugin{'lmenezes/elasticsearch-kopf':
 119   module_dir => 'kopf',
 120   instances  => 'instance_name'
 121 }
 122 ```
 123 ####From custom url
 124 ```puppet
 125 elasticsearch::plugin{ 'elasticsearch-jetty':
 126   module_dir => 'jetty',
 127   url        => 'https://oss-es-plugins.s3.amazonaws.com/elasticsearch-jetty/elasticsearch-jetty-1.2.1.zip',
 128   instances  => 'instance_name'
 129 }
 130 ```
 131
 132
 133 ####Using a proxy
 134 You can also use a proxy if required by setting the `proxy_host` and `proxy_port` options:
 135 ```puppet
 136 elasticsearch::plugin { 'lmenezes/elasticsearch-kopf',
 137   module_dir => 'kopf',
 138   instances  => 'instance_name',
 139   proxy_host => 'proxy.host.com',
 140   proxy_port => 3128
 141 }
 142 ```
 143
 144 #####Plugin name could be:
 145 * `elasticsearch/plugin/version` for official elasticsearch plugins (download from download.elasticsearch.org)
 146 * `groupId/artifactId/version`   for community plugins (download from maven central or oss sonatype)
 147 * `username/repository`          for site plugins (download from github master)
 148
 149 ###Templates
 150
 151 #### Add a new template using a file
 152
 153 This will install and/or replace the template in Elasticsearch:
 154
 155 ```puppet
 156 elasticsearch::template { 'templatename':
 157   file => 'puppet:///path/to/template.json'
 158 }
 159 ```
 160
 161 #### Add a new template using content
 162
 163 This will install and/or replace the template in Elasticsearch:
 164
 165 ```puppet
 166 elasticsearch::template { 'templatename':
 167   content => '{"template":"*","settings":{"number_of_replicas":0}}'
 168 }
 169 ```
 170
 171 #### Delete a template
 172
 173 ```puppet
 174 elasticsearch::template { 'templatename':
 175   ensure => 'absent'
 176 }
 177 ```
 178
 179 #### Host
 180
 181 By default it uses localhost:9200 as host. you can change this with the `host` and `port` variables
 182
 183 ```puppet
 184 elasticsearch::template { 'templatename':
 185   host => $::ipaddress,
 186   port => 9200
 187 }
 188 ```
 189
 190 ###Bindings / Clients
 191
 192 Install a variety of [clients/bindings](http://www.elasticsearch.org/guide/en/elasticsearch/client/community/current/clients.html):
 193
 194 ####Python
 195
 196 ```puppet
 197 elasticsearch::python { 'rawes': }
 198 ```
 199
 200 ####Ruby
 201 ```puppet
 202 elasticsearch::ruby { 'elasticsearch': }
 203 ```
 204
 205 ###Connection Validator
 206
 207 This module offers a way to make sure an instance has been started and is up and running before
 208 doing a next action. This is done via the use of the `es_instance_conn_validator` resource.
 209 ```puppet
 210 es_instance_conn_validator { 'myinstance' :
 211   server => 'es.example.com',
 212   port   => '9200',
 213 }
 214 ```
 215
 216 A common use would be for example :
 217
 218 ```puppet
 219 class { 'kibana4' :
 220   require => Es_Instance_Conn_Validator['myinstance'],
 221 }
 222 ```
 223
 224 ###Package installation
 225
 226 There are 2 different ways of installing the software
 227
 228 ####Repository
 229
 230 This option allows you to use an existing repository for package installation.
 231 The `repo_version` corresponds with the major version of Elasticsearch.
 232
 233 ```puppet
 234 class { 'elasticsearch':
 235   manage_repo  => true,
 236   repo_version => '1.4',
 237 }
 238 ```
 239
 240 ####Remote package source
 241
 242 When a repository is not available or preferred you can install the packages from a remote source:
 243
 244 #####http/https/ftp
 245 ```puppet
 246 class { 'elasticsearch':
 247   package_url => 'https://download.elasticsearch.org/elasticsearch/elasticsearch/elasticsearch-1.4.2.deb'
 248 }
 249 ```
 250
 251 #####puppet://
 252 ```puppet
 253 class { 'elasticsearch':
 254   package_url => 'puppet:///path/to/elasticsearch-1.4.2.deb'
 255 }
 256 ```
 257
 258 #####Local file
 259 ```puppet
 260 class { 'elasticsearch':
 261   package_url => 'file:/path/to/elasticsearch-1.4.2.deb'
 262 }
 263 ```
 264
 265 ###Java installation
 266
 267 Most sites will manage Java separately; however, this module can attempt to install Java as well.
 268 This is done by using the [puppetlabs-java](https://forge.puppetlabs.com/puppetlabs/java) module.
 269
 270 ```puppet
 271 class { 'elasticsearch':
 272   java_install => true
 273 }
 274 ```
 275
 276 Specify a particular Java package/version to be installed:
 277
 278 ```puppet
 279 class { 'elasticsearch':
 280   java_install => true,
 281   java_package => 'packagename'
 282 }
 283 ```
 284
 285 ###Service management
 286
 287 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).
 288
 289
 290 ####Defaults File
 291
 292 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.
 293
 294 #####file source
 295 ```puppet
 296 class { 'elasticsearch':
 297   init_defaults_file => 'puppet:///path/to/defaults'
 298 }
 299 ```
 300 #####hash representation
 301 ```puppet
 302 $config_hash = {
 303   'ES_USER' => 'elasticsearch',
 304   'ES_GROUP' => 'elasticsearch',
 305 }
 306
 307 class { 'elasticsearch':
 308   init_defaults => $config_hash
 309 }
 310 ```
 311
 312 Note: `init_defaults` hash can be passed to the main class and to the instance.
 313
 314 ##Advanced features
 315
 316
 317 ###Data directories
 318
 319 There are 4 different ways of setting data directories for Elasticsearch.
 320 In every case the required configuration options are placed in the `elasticsearch.yml` file.
 321
 322 ####Default
 323 By default we use:
 324
 325 `/usr/share/elasticsearch/data/$instance_name`
 326
 327 Which provides a data directory per instance.
 328
 329
 330 ####Single global data directory
 331
 332 ```puppet
 333 class { 'elasticsearch':
 334   datadir => '/var/lib/elasticsearch-data'
 335 }
 336 ```
 337 Creates the following for each instance:
 338
 339 `/var/lib/elasticsearch-data/$instance_name`
 340
 341 ####Multiple Global data directories
 342
 343 ```puppet
 344 class { 'elasticsearch':
 345   datadir => [ '/var/lib/es-data1', '/var/lib/es-data2']
 346 }
 347 ```
 348 Creates the following for each instance:
 349 `/var/lib/es-data1/$instance_name`
 350 and
 351 `/var/lib/es-data2/$instance_name`
 352
 353
 354 ####Single instance data directory
 355
 356 ```puppet
 357 class { 'elasticsearch': }
 358
 359 elasticsearch::instance { 'es-01':
 360   datadir => '/var/lib/es-data-es01'
 361 }
 362 ```
 363 Creates the following for this instance:
 364 `/var/lib/es-data-es01`
 365
 366 ####Multiple instance data directories
 367
 368 ```puppet
 369 class { 'elasticsearch': }
 370
 371 elasticsearch::instance { 'es-01':
 372   datadir => ['/var/lib/es-data1-es01', '/var/lib/es-data2-es01']
 373 }
 374 ```
 375 Creates the following for this instance:
 376 `/var/lib/es-data1-es01`
 377 and
 378 `/var/lib/es-data2-es01`
 379
 380
 381 ###Main and instance configurations
 382
 383 The `config` option in both the main class and the instances can be configured to work together.
 384
 385 The options in the `instance` config hash will merged with the ones from the main class and override any duplicates.
 386
 387 #### Simple merging
 388
 389 ```puppet
 390 class { 'elasticsearch':
 391   config => { 'cluster.name' => 'clustername' }
 392 }
 393
 394 elasticsearch::instance { 'es-01':
 395   config => { 'node.name' => 'nodename' }
 396 }
 397 elasticsearch::instance { 'es-02':
 398   config => { 'node.name' => 'nodename2' }
 399 }
 400
 401 ```
 402
 403 This example merges the `cluster.name` together with the `node.name` option.
 404
 405 #### Overriding
 406
 407 When duplicate options are provided, the option in the instance config overrides the ones from the main class.
 408
 409 ```puppet
 410 class { 'elasticsearch':
 411   config => { 'cluster.name' => 'clustername' }
 412 }
 413
 414 elasticsearch::instance { 'es-01':
 415   config => { 'node.name' => 'nodename', 'cluster.name' => 'otherclustername' }
 416 }
 417
 418 elasticsearch::instance { 'es-02':
 419   config => { 'node.name' => 'nodename2' }
 420 }
 421 ```
 422
 423 This will set the cluster name to `otherclustername` for the instance `es-01` but will keep it to `clustername` for instance `es-02`
 424
 425 ####Configuration writeup
 426
 427 The `config` hash can be written in 2 different ways:
 428
 429 ##### Full hash writeup
 430
 431 Instead of writing the full hash representation:
 432 ```puppet
 433 class { 'elasticsearch':
 434   config                 => {
 435    'cluster'             => {
 436      'name'              => 'ClusterName',
 437      'routing'           => {
 438         'allocation'     => {
 439           'awareness'    => {
 440             'attributes' => 'rack'
 441           }
 442         }
 443       }
 444     }
 445   }
 446 }
 447 ```
 448 ##### Short hash writeup
 449 ```puppet
 450 class { 'elasticsearch':
 451   config => {
 452     'cluster' => {
 453       'name' => 'ClusterName',
 454       'routing.allocation.awareness.attributes' => 'rack'
 455     }
 456   }
 457 }
 458 ```
 459
 460
 461 ##Limitations
 462
 463 This module has been built on and tested against Puppet 3.2 and higher.
 464
 465 The module has been tested on:
 466
 467 * Debian 6/7
 468 * CentOS 6
 469 * Ubuntu 12.04, 14.04
 470 * OpenSuSE 13.x
 471
 472 Other distro's that have been reported to work:
 473
 474 * RHEL 6
 475 * OracleLinux 6
 476 * Scientific 6
 477
 478 Testing on other platforms has been light and cannot be guaranteed.
 479
 480 ##Development
 481
 482
 483 ##Support
 484
 485 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.