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