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). 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.
 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
 150 ###Scripts
 151
 152 Install [scripts](http://www.elastic.co/guide/en/elasticsearch/reference/1.x/modules-scripting.html) to be used by Elasticsearch.
 153 These scripts are shared accross all defined instances on the same host.
 154
 155 ```puppet
 156 elasticsearch::script { 'myscript':
 157   ensure => 'present',
 158   source => 'puppet:///path/to/my/script.groovy'
 159 }
 160 ```
 161
 162 ###Templates
 163
 164 #### Add a new template using a file
 165
 166 This will install and/or replace the template in Elasticsearch:
 167
 168 ```puppet
 169 elasticsearch::template { 'templatename':
 170   file => 'puppet:///path/to/template.json'
 171 }
 172 ```
 173
 174 #### Add a new template using content
 175
 176 This will install and/or replace the template in Elasticsearch:
 177
 178 ```puppet
 179 elasticsearch::template { 'templatename':
 180   content => '{"template":"*","settings":{"number_of_replicas":0}}'
 181 }
 182 ```
 183
 184 #### Delete a template
 185
 186 ```puppet
 187 elasticsearch::template { 'templatename':
 188   ensure => 'absent'
 189 }
 190 ```
 191
 192 #### Host
 193
 194 By default it uses localhost:9200 as host. you can change this with the `host` and `port` variables
 195
 196 ```puppet
 197 elasticsearch::template { 'templatename':
 198   host => $::ipaddress,
 199   port => 9200
 200 }
 201 ```
 202
 203 ###Bindings / Clients
 204
 205 Install a variety of [clients/bindings](http://www.elasticsearch.org/guide/en/elasticsearch/client/community/current/clients.html):
 206
 207 ####Python
 208
 209 ```puppet
 210 elasticsearch::python { 'rawes': }
 211 ```
 212
 213 ####Ruby
 214 ```puppet
 215 elasticsearch::ruby { 'elasticsearch': }
 216 ```
 217
 218 ###Connection Validator
 219
 220 This module offers a way to make sure an instance has been started and is up and running before
 221 doing a next action. This is done via the use of the `es_instance_conn_validator` resource.
 222 ```puppet
 223 es_instance_conn_validator { 'myinstance' :
 224   server => 'es.example.com',
 225   port   => '9200',
 226 }
 227 ```
 228
 229 A common use would be for example :
 230
 231 ```puppet
 232 class { 'kibana4' :
 233   require => Es_Instance_Conn_Validator['myinstance'],
 234 }
 235 ```
 236
 237 ###Package installation
 238
 239 There are 2 different ways of installing the software
 240
 241 ####Repository
 242
 243 This option allows you to use an existing repository for package installation.
 244 The `repo_version` corresponds with the major version of Elasticsearch.
 245
 246 ```puppet
 247 class { 'elasticsearch':
 248   manage_repo  => true,
 249   repo_version => '1.4',
 250 }
 251 ```
 252
 253 ####Remote package source
 254
 255 When a repository is not available or preferred you can install the packages from a remote source:
 256
 257 #####http/https/ftp
 258 ```puppet
 259 class { 'elasticsearch':
 260   package_url => 'https://download.elasticsearch.org/elasticsearch/elasticsearch/elasticsearch-1.4.2.deb'
 261 }
 262 ```
 263
 264 #####puppet://
 265 ```puppet
 266 class { 'elasticsearch':
 267   package_url => 'puppet:///path/to/elasticsearch-1.4.2.deb'
 268 }
 269 ```
 270
 271 #####Local file
 272 ```puppet
 273 class { 'elasticsearch':
 274   package_url => 'file:/path/to/elasticsearch-1.4.2.deb'
 275 }
 276 ```
 277
 278 ###Java installation
 279
 280 Most sites will manage Java separately; however, this module can attempt to install Java as well.
 281 This is done by using the [puppetlabs-java](https://forge.puppetlabs.com/puppetlabs/java) module.
 282
 283 ```puppet
 284 class { 'elasticsearch':
 285   java_install => true
 286 }
 287 ```
 288
 289 Specify a particular Java package/version to be installed:
 290
 291 ```puppet
 292 class { 'elasticsearch':
 293   java_install => true,
 294   java_package => 'packagename'
 295 }
 296 ```
 297
 298 ###Service management
 299
 300 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).
 301
 302
 303 ####Defaults File
 304
 305 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.
 306
 307 #####file source
 308 ```puppet
 309 class { 'elasticsearch':
 310   init_defaults_file => 'puppet:///path/to/defaults'
 311 }
 312 ```
 313 #####hash representation
 314 ```puppet
 315 $config_hash = {
 316   'ES_USER' => 'elasticsearch',
 317   'ES_GROUP' => 'elasticsearch',
 318 }
 319
 320 class { 'elasticsearch':
 321   init_defaults => $config_hash
 322 }
 323 ```
 324
 325 Note: `init_defaults` hash can be passed to the main class and to the instance.
 326
 327 ##Advanced features
 328
 329
 330 ###Data directories
 331
 332 There are 4 different ways of setting data directories for Elasticsearch.
 333 In every case the required configuration options are placed in the `elasticsearch.yml` file.
 334
 335 ####Default
 336 By default we use:
 337
 338 `/usr/share/elasticsearch/data/$instance_name`
 339
 340 Which provides a data directory per instance.
 341
 342
 343 ####Single global data directory
 344
 345 ```puppet
 346 class { 'elasticsearch':
 347   datadir => '/var/lib/elasticsearch-data'
 348 }
 349 ```
 350 Creates the following for each instance:
 351
 352 `/var/lib/elasticsearch-data/$instance_name`
 353
 354 ####Multiple Global data directories
 355
 356 ```puppet
 357 class { 'elasticsearch':
 358   datadir => [ '/var/lib/es-data1', '/var/lib/es-data2']
 359 }
 360 ```
 361 Creates the following for each instance:
 362 `/var/lib/es-data1/$instance_name`
 363 and
 364 `/var/lib/es-data2/$instance_name`
 365
 366
 367 ####Single instance data directory
 368
 369 ```puppet
 370 class { 'elasticsearch': }
 371
 372 elasticsearch::instance { 'es-01':
 373   datadir => '/var/lib/es-data-es01'
 374 }
 375 ```
 376 Creates the following for this instance:
 377 `/var/lib/es-data-es01`
 378
 379 ####Multiple instance data directories
 380
 381 ```puppet
 382 class { 'elasticsearch': }
 383
 384 elasticsearch::instance { 'es-01':
 385   datadir => ['/var/lib/es-data1-es01', '/var/lib/es-data2-es01']
 386 }
 387 ```
 388 Creates the following for this instance:
 389 `/var/lib/es-data1-es01`
 390 and
 391 `/var/lib/es-data2-es01`
 392
 393
 394 ###Main and instance configurations
 395
 396 The `config` option in both the main class and the instances can be configured to work together.
 397
 398 The options in the `instance` config hash will merged with the ones from the main class and override any duplicates.
 399
 400 #### Simple merging
 401
 402 ```puppet
 403 class { 'elasticsearch':
 404   config => { 'cluster.name' => 'clustername' }
 405 }
 406
 407 elasticsearch::instance { 'es-01':
 408   config => { 'node.name' => 'nodename' }
 409 }
 410 elasticsearch::instance { 'es-02':
 411   config => { 'node.name' => 'nodename2' }
 412 }
 413
 414 ```
 415
 416 This example merges the `cluster.name` together with the `node.name` option.
 417
 418 #### Overriding
 419
 420 When duplicate options are provided, the option in the instance config overrides the ones from the main class.
 421
 422 ```puppet
 423 class { 'elasticsearch':
 424   config => { 'cluster.name' => 'clustername' }
 425 }
 426
 427 elasticsearch::instance { 'es-01':
 428   config => { 'node.name' => 'nodename', 'cluster.name' => 'otherclustername' }
 429 }
 430
 431 elasticsearch::instance { 'es-02':
 432   config => { 'node.name' => 'nodename2' }
 433 }
 434 ```
 435
 436 This will set the cluster name to `otherclustername` for the instance `es-01` but will keep it to `clustername` for instance `es-02`
 437
 438 ####Configuration writeup
 439
 440 The `config` hash can be written in 2 different ways:
 441
 442 ##### Full hash writeup
 443
 444 Instead of writing the full hash representation:
 445 ```puppet
 446 class { 'elasticsearch':
 447   config                 => {
 448    'cluster'             => {
 449      'name'              => 'ClusterName',
 450      'routing'           => {
 451         'allocation'     => {
 452           'awareness'    => {
 453             'attributes' => 'rack'
 454           }
 455         }
 456       }
 457     }
 458   }
 459 }
 460 ```
 461 ##### Short hash writeup
 462 ```puppet
 463 class { 'elasticsearch':
 464   config => {
 465     'cluster' => {
 466       'name' => 'ClusterName',
 467       'routing.allocation.awareness.attributes' => 'rack'
 468     }
 469   }
 470 }
 471 ```
 472
 473
 474 ##Limitations
 475
 476 This module has been built on and tested against Puppet 3.2 and higher.
 477
 478 The module has been tested on:
 479
 480 * Debian 6/7
 481 * CentOS 6
 482 * Ubuntu 12.04, 14.04
 483 * OpenSuSE 13.x
 484
 485 Other distro's that have been reported to work:
 486
 487 * RHEL 6
 488 * OracleLinux 6
 489 * Scientific 6
 490
 491 Testing on other platforms has been light and cannot be guaranteed.
 492
 493 ##Development
 494
 495
 496 ##Support
 497
 498 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.