Puppet Class: elasticsearch

Defined in:
manifests/init.pp

Summary

Manages the installation of Elasticsearch and related options.

Overview

Top-level Elasticsearch class which may manage installation of the Elasticsearch package, package repository, and other global options and parameters.

Examples:

install Elasticsearch

class { 'elasticsearch': }

removal and decommissioning

class { 'elasticsearch':
  ensure => 'absent',
}

install everything but disable service(s) afterwards

class { 'elasticsearch':
  status => 'disabled',
}

Parameters:

  • ensure (Enum['absent', 'present'])

    Controls if the managed resources shall be present or absent. If set to absent, the managed software packages will be uninstalled, and any traces of the packages will be purged as well as possible, possibly including existing configuration files. System modifications (if any) will be reverted as well as possible (e.g. removal of created users, services, changed log settings, and so on). This is a destructive parameter and should be used with care.

  • api_basic_auth_password (Optional[String])

    Defines the default REST basic auth password for API authentication.

  • api_basic_auth_username (Optional[String])

    Defines the default REST basic auth username for API authentication.

  • api_ca_file (Optional[String])

    Path to a CA file which will be used to validate server certs when communicating with the Elasticsearch API over HTTPS.

  • api_ca_path (Optional[String])

    Path to a directory with CA files which will be used to validate server certs when communicating with the Elasticsearch API over HTTPS.

  • api_host (String)

    Default host to use when accessing Elasticsearch APIs.

  • api_port (Integer[0, 65535])

    Default port to use when accessing Elasticsearch APIs.

  • api_protocol (Enum['http', 'https'])

    Default protocol to use when accessing Elasticsearch APIs.

  • api_timeout (Integer)

    Default timeout (in seconds) to use when accessing Elasticsearch APIs.

  • autoupgrade (Boolean)

    If set to true, any managed package will be upgraded on each Puppet run when the package provider is able to find a newer version than the present one. The exact behavior is provider dependent (see package, “upgradeable” in the Puppet documentation).

  • config (Hash)

    Elasticsearch configuration hash.

  • configdir (Stdlib::Absolutepath)

    Directory containing the elasticsearch configuration. Use this setting if your packages deviate from the norm (/etc/elasticsearch)

  • daily_rolling_date_pattern (String)

    File pattern for the file appender log when file_rolling_type is 'dailyRollingFile'.

  • datadir (Elasticsearch::Multipath)

    Allows you to set the data directory of Elasticsearch.

  • datadir_instance_directories (Boolean)

    Control whether individual directories for instances will be created within each instance's data directory.

  • default_logging_level (String)

    Default logging level for Elasticsearch.

  • defaults_location (Optional[Stdlib::Absolutepath])

    Absolute path to directory containing init defaults file.

  • download_tool (Optional[String])

    Command-line invocation with which to retrieve an optional package_url.

  • elasticsearch_group (String)

    The group Elasticsearch should run as. This also sets file group permissions.

  • elasticsearch_user (String)

    The user Elasticsearch should run as. This also sets file ownership.

  • file_rolling_type (Enum['dailyRollingFile', 'rollingFile', 'file'])

    Configuration for the file appender rotation. It can be 'dailyRollingFile', 'rollingFile' or 'file'. The first rotates by name, the second one by size or third don't rotate automatically.

  • homedir (Stdlib::Absolutepath)

    Directory where the elasticsearch installation's files are kept (plugins, etc.)

  • indices (Hash)

    Define indices via a hash. This is mainly used with Hiera's auto binding.

  • init_defaults (Hash)

    Defaults file content in hash representation.

  • init_defaults_file (Optional[String])

    Defaults file as puppet resource.

  • init_template (String)

    Service file as a template.

  • instances (Hash)

    Define instances via a hash. This is mainly used with Hiera's auto binding.

  • jvm_options (Array[String])

    Array of options to set in jvm_options.

  • license (Optional[Variant[String, Hash]])

    Optional Elasticsearch license in hash or string form.

  • logdir (Stdlib::Absolutepath)

    Directory that will be used for Elasticsearch logging.

  • logging_config (Hash)

    Representation of information to be included in the logging.yml file.

  • logging_file (Optional[String])

    Instead of a hash, you may supply a puppet:// file source for the logging.yml file.

  • logging_template (Optional[String])

    Use a custom logging template - just supply the relative path, i.e. $module/elasticsearch/logging.yml.erb

  • manage_repo (Boolean)

    Enable repo management by enabling official Elastic repositories.

  • oss (Boolean)

    Whether to use the purely open source Elasticsearch package distribution.

  • package_dir (Stdlib::Absolutepath)

    Directory where packages are downloaded to.

  • package_dl_timeout (Integer)

    For http, https, and ftp downloads, you may set how long the exec resource may take.

  • package_name (String)

    Name Of the package to install.

  • package_provider (Enum['package'])

    Method to install the packages, currently only package is supported.

  • package_url (Optional[String])

    URL of the package to download. This can be an http, https, or ftp resource for remote packages, or a puppet:// resource or file:/ for local packages

  • pid_dir (Optional[Stdlib::Absolutepath])

    Directory where the elasticsearch process should write out its PID.

  • pipelines (Hash)

    Define pipelines via a hash. This is mainly used with Hiera's auto binding.

  • plugindir (Stdlib::Absolutepath)

    Directory containing elasticsearch plugins. Use this setting if your packages deviate from the norm (/usr/share/elasticsearch/plugins)

  • plugins (Hash)

    Define plugins via a hash. This is mainly used with Hiera's auto binding.

  • proxy_url (Optional[Stdlib::HTTPUrl])

    For http and https downloads, you may set a proxy server to use. By default, no proxy is used. Format: proto://[user:pass@]server[:port]/

  • purge_configdir (Boolean)

    Purge the config directory of any unmanaged files.

  • purge_package_dir (Boolean)

    Purge package directory on removal

  • purge_secrets (Boolean)

    Whether or not keys present in the keystore will be removed if they are not present in the specified secrets hash.

  • repo_stage (Variant[Boolean, String])

    Use stdlib stage setup for managing the repo instead of relationship ordering.

  • restart_on_change (Boolean)

    Determines if the application should be automatically restarted whenever the configuration, package, or plugins change. Enabling this setting will cause Elasticsearch to restart whenever there is cause to re-read configuration files, load new plugins, or start the service using an updated/changed executable. This may be undesireable in highly available environments. If all other restart* parameters are left unset, the value of restart_on_change is used for all other restart*_change defaults.

  • restart_config_change (Boolean) (defaults to: $restart_on_change)

    Determines if the application should be automatically restarted whenever the configuration changes. This includes the Elasticsearch configuration file, any service files, and defaults files. Disabling automatic restarts on config changes may be desired in an environment where you need to ensure restarts occur in a controlled/rolling manner rather than during a Puppet run.

  • restart_package_change (Boolean) (defaults to: $restart_on_change)

    Determines if the application should be automatically restarted whenever the package (or package version) for Elasticsearch changes. Disabling automatic restarts on package changes may be desired in an environment where you need to ensure restarts occur in a controlled/rolling manner rather than during a Puppet run.

  • restart_plugin_change (Boolean) (defaults to: $restart_on_change)

    Determines if the application should be automatically restarted whenever plugins are installed or removed. Disabling automatic restarts on plugin changes may be desired in an environment where you need to ensure restarts occur in a controlled/rolling manner rather than during a Puppet run.

  • roles (Hash)

    Define roles via a hash. This is mainly used with Hiera's auto binding.

  • rolling_file_max_backup_index (Integer)

    Max number of logs to store whern file_rolling_type is 'rollingFile'

  • rolling_file_max_file_size (String)

    Max log file size when file_rolling_type is 'rollingFile'

  • scripts (Hash)

    Define scripts via a hash. This is mainly used with Hiera's auto binding.

  • secrets (Optional[Hash])

    Optional default configuration hash of key/value pairs to store in the Elasticsearch keystore file. If unset, the keystore is left unmanaged.

  • security_logging_content (Optional[String])

    File content for shield/x-pack logging configuration file (will be placed into logging.yml or log4j2.properties file as appropriate).

  • security_logging_source (Optional[String])

    File source for shield/x-pack logging configuration file (will be placed into logging.yml or log4j2.properties file as appropriate).

  • security_plugin (Optional[Enum['shield', 'x-pack']])

    Which security plugin will be used to manage users, roles, and certificates.

  • service_provider (Enum['init', 'openbsd', 'openrc', 'systemd'])

    The service resource type provider to use when managing elasticsearch instances.

  • snapshot_repositories (Hash)

    Define snapshot repositories via a hash. This is mainly used with Hiera's auto binding.

  • status (Elasticsearch::Status)

    To define the status of the service. If set to enabled, the service will be run and will be started at boot time. If set to disabled, the service is stopped and will not be started at boot time. If set to running, the service will be run but will not be started at boot time. You may use this to start a service on the first Puppet run instead of the system startup. If set to unmanaged, the service will not be started at boot time and Puppet does not care whether the service is running or not. For example, this may be useful if a cluster management software is used to decide when to start the service plus assuring it is running on the desired node.

  • system_key (Optional[String])

    Source for the Shield/x-pack system key. Valid values are any that are supported for the file resource source parameter.

  • systemd_service_path (Stdlib::Absolutepath)

    Path to the directory in which to install systemd service units.

  • templates (Hash)

    Define templates via a hash. This is mainly used with Hiera's auto binding.

  • users (Hash)

    Define templates via a hash. This is mainly used with Hiera's auto binding.

  • validate_tls (Boolean)

    Enable TLS/SSL validation on API calls.

  • version (Variant[String, Boolean])

    To set the specific version you want to install.

Author:



291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
# File 'manifests/init.pp', line 291

class elasticsearch (
  Enum['absent', 'present']                       $ensure,
  Optional[String]                                $api_basic_auth_password,
  Optional[String]                                $api_basic_auth_username,
  Optional[String]                                $api_ca_file,
  Optional[String]                                $api_ca_path,
  String                                          $api_host,
  Integer[0, 65535]                               $api_port,
  Enum['http', 'https']                           $api_protocol,
  Integer                                         $api_timeout,
  Boolean                                         $autoupgrade,
  Hash                                            $config,
  Stdlib::Absolutepath                            $configdir,
  String                                          $daily_rolling_date_pattern,
  Elasticsearch::Multipath                        $datadir,
  Boolean                                         $datadir_instance_directories,
  String                                          $default_logging_level,
  Optional[Stdlib::Absolutepath]                  $defaults_location,
  Optional[String]                                $download_tool,
  String                                          $elasticsearch_group,
  String                                          $elasticsearch_user,
  Enum['dailyRollingFile', 'rollingFile', 'file'] $file_rolling_type,
  Stdlib::Absolutepath                            $homedir,
  Hash                                            $indices,
  Hash                                            $init_defaults,
  Optional[String]                                $init_defaults_file,
  String                                          $init_template,
  Hash                                            $instances,
  Array[String]                                   $jvm_options,
  Optional[Variant[String, Hash]]                 $license,
  Stdlib::Absolutepath                            $logdir,
  Hash                                            $logging_config,
  Optional[String]                                $logging_file,
  Optional[String]                                $logging_template,
  Boolean                                         $manage_repo,
  Boolean                                         $oss,
  Stdlib::Absolutepath                            $package_dir,
  Integer                                         $package_dl_timeout,
  String                                          $package_name,
  Enum['package']                                 $package_provider,
  Optional[String]                                $package_url,
  Optional[Stdlib::Absolutepath]                  $pid_dir,
  Hash                                            $pipelines,
  Stdlib::Absolutepath                            $plugindir,
  Hash                                            $plugins,
  Optional[Stdlib::HTTPUrl]                       $proxy_url,
  Boolean                                         $purge_configdir,
  Boolean                                         $purge_package_dir,
  Boolean                                         $purge_secrets,
  Variant[Boolean, String]                        $repo_stage,
  Boolean                                         $restart_on_change,
  Hash                                            $roles,
  Integer                                         $rolling_file_max_backup_index,
  String                                          $rolling_file_max_file_size,
  Hash                                            $scripts,
  Optional[Hash]                                  $secrets,
  Optional[String]                                $security_logging_content,
  Optional[String]                                $security_logging_source,
  Optional[Enum['shield', 'x-pack']]              $security_plugin,
  Enum['init', 'openbsd', 'openrc', 'systemd']    $service_provider,
  Hash                                            $snapshot_repositories,
  Elasticsearch::Status                           $status,
  Optional[String]                                $system_key,
  Stdlib::Absolutepath                            $systemd_service_path,
  Hash                                            $templates,
  Hash                                            $users,
  Boolean                                         $validate_tls,
  Variant[String, Boolean]                        $version,
  Boolean $restart_config_change  = $restart_on_change,
  Boolean $restart_package_change = $restart_on_change,
  Boolean $restart_plugin_change  = $restart_on_change,
) {

  #### Validate parameters

  if ($package_url != undef and $version != false) {
    fail('Unable to set the version number when using package_url option.')
  }

  if ($version != false) {
    case $facts['os']['family'] {
      'RedHat', 'Linux', 'Suse': {
        if ($version =~ /.+-\d/) {
          $pkg_version = $version
        } else {
          $pkg_version = "${version}-1"
        }
      }
      default: {
        $pkg_version = $version
      }
    }
  }

  # This value serves as an unchanging default for platforms as a default for
  # init scripts to fallback on.
  $_datadir_default = $facts['kernel'] ? {
    'Linux'   => '/var/lib/elasticsearch',
    'OpenBSD' => '/var/elasticsearch/data',
    default   => undef,
  }

  # The OSS package distribution's package appends `-oss` to the end of the
  # canonical package name.
  $_package_name = $oss ? {
    true    => "${package_name}-oss",
    default => $package_name,
  }

  #### Manage actions

  contain elasticsearch::package
  contain elasticsearch::config

  create_resources('elasticsearch::index', $::elasticsearch::indices)
  create_resources('elasticsearch::instance', $::elasticsearch::instances)
  create_resources('elasticsearch::pipeline', $::elasticsearch::pipelines)
  create_resources('elasticsearch::plugin', $::elasticsearch::plugins)
  create_resources('elasticsearch::role', $::elasticsearch::roles)
  create_resources('elasticsearch::script', $::elasticsearch::scripts)
  create_resources('elasticsearch::snapshot_repository', $::elasticsearch::snapshot_repositories)
  create_resources('elasticsearch::template', $::elasticsearch::templates)
  create_resources('elasticsearch::user', $::elasticsearch::users)

  if ($manage_repo == true) {
    if ($repo_stage == false) {
      # Use normal relationship ordering
      contain elastic_stack::repo

      Class['elastic_stack::repo']
      -> Class['elasticsearch::package']

    } else {
      # Use staging for ordering
      if !(defined(Stage[$repo_stage])) {
        stage { $repo_stage:  before => Stage['main'] }
      }

      include elastic_stack::repo
      Class<|title == 'elastic_stack::repo'|>{
        stage => $repo_stage,
      }
    }
  }

  if ($license != undef) {
    contain elasticsearch::license
  }

  #### Manage relationships
  #
  # Note that many of these overly verbose declarations work around
  # https://tickets.puppetlabs.com/browse/PUP-1410
  # which means clean arrow order chaining won't work if someone, say,
  # doesn't declare any plugins.
  #
  # forgive me for what you're about to see

  if defined(Class['java']) { Class['java'] -> Class['elasticsearch::config'] }

  if $ensure == 'present' {

    # Installation and configuration
    Class['elasticsearch::package']
    -> Class['elasticsearch::config']

    # Top-level ordering bindings for resources.
    Class['elasticsearch::config']
    -> Elasticsearch::Plugin <| ensure == 'present' or ensure == 'installed' |>
    Elasticsearch::Plugin <| ensure == 'absent' |>
    -> Class['elasticsearch::config']
    Class['elasticsearch::config']
    -> Elasticsearch::Instance <| |>
    Class['elasticsearch::config']
    -> Elasticsearch::User <| |>
    Class['elasticsearch::config']
    -> Elasticsearch::Role <| |>
    Class['elasticsearch::config']
    -> Elasticsearch::Template <| |>
    Class['elasticsearch::config']
    -> Elasticsearch::Pipeline <| |>
    Class['elasticsearch::config']
    -> Elasticsearch::Index <| |>
    Class['elasticsearch::config']
    -> Elasticsearch::Snapshot_repository <| |>

  } else {

    # Absent; remove configuration before the package.
    Class['elasticsearch::config']
    -> Class['elasticsearch::package']

    # Top-level ordering bindings for resources.
    Elasticsearch::Plugin <| |>
    -> Class['elasticsearch::config']
    Elasticsearch::Instance <| |>
    -> Class['elasticsearch::config']
    Elasticsearch::User <| |>
    -> Class['elasticsearch::config']
    Elasticsearch::Role <| |>
    -> Class['elasticsearch::config']
    Elasticsearch::Template <| |>
    -> Class['elasticsearch::config']
    Elasticsearch::Pipeline <| |>
    -> Class['elasticsearch::config']
    Elasticsearch::Index <| |>
    -> Class['elasticsearch::config']
    Elasticsearch::Snapshot_repository <| |>
    -> Class['elasticsearch::config']

  }

  # Install plugins before managing instances or users/roles
  Elasticsearch::Plugin <| ensure == 'present' or ensure == 'installed' |>
  -> Elasticsearch::Instance <| |>
  Elasticsearch::Plugin <| ensure == 'present' or ensure == 'installed' |>
  -> Elasticsearch::User <| |>
  Elasticsearch::Plugin <| ensure == 'present' or ensure == 'installed' |>
  -> Elasticsearch::Role <| |>

  # Remove plugins after managing users/roles
  Elasticsearch::User <| |>
  -> Elasticsearch::Plugin <| ensure == 'absent' |>
  Elasticsearch::Role <| |>
  -> Elasticsearch::Plugin <| ensure == 'absent' |>

  # Ensure roles are defined before managing users that reference roles
  Elasticsearch::Role <| |>
  -> Elasticsearch::User <| ensure == 'present' |>
  # Ensure users are removed before referenced roles are managed
  Elasticsearch::User <| ensure == 'absent' |>
  -> Elasticsearch::Role <| |>

  # Ensure users and roles are managed before calling out to REST resources
  Elasticsearch::Role <| |>
  -> Elasticsearch::Template <| |>
  Elasticsearch::User <| |>
  -> Elasticsearch::Template <| |>
  Elasticsearch::Role <| |>
  -> Elasticsearch::Pipeline <| |>
  Elasticsearch::User <| |>
  -> Elasticsearch::Pipeline <| |>
  Elasticsearch::Role <| |>
  -> Elasticsearch::Index <| |>
  Elasticsearch::User <| |>
  -> Elasticsearch::Index <| |>
  Elasticsearch::Role <| |>
  -> Elasticsearch::Snapshot_repository <| |>
  Elasticsearch::User <| |>
  -> Elasticsearch::Snapshot_repository <| |>

  # Ensure that any command-line based user changes are performed before the
  # file is modified
  Elasticsearch_user <| |>
  -> Elasticsearch_user_file <| |>

  # Manage users/roles before instances (req'd to keep dir in sync)
  Elasticsearch::Role <| |>
  -> Elasticsearch::Instance <| |>
  Elasticsearch::User <| |>
  -> Elasticsearch::Instance <| |>

  # Ensure instances are started before managing REST resources
  Elasticsearch::Instance <| ensure == 'present' |>
  -> Elasticsearch::Template <| |>
  Elasticsearch::Instance <| ensure == 'present' |>
  -> Elasticsearch::Pipeline <| |>
  Elasticsearch::Instance <| ensure == 'present' |>
  -> Elasticsearch::Index <| |>
  Elasticsearch::Instance <| ensure == 'present' |>
  -> Elasticsearch::Snapshot_repository <| |>
  # Ensure instances are stopped after managing REST resources
  Elasticsearch::Template <| |>
  -> Elasticsearch::Instance <| ensure == 'absent' |>
  Elasticsearch::Pipeline <| |>
  -> Elasticsearch::Instance <| ensure == 'absent' |>
  Elasticsearch::Index <| |>
  -> Elasticsearch::Instance <| ensure == 'absent' |>
  Elasticsearch::Snapshot_repository <| |>
  -> Elasticsearch::Instance <| ensure == 'absent' |>
}