ansible-elastic-cloud-enterprise

Ansible role for installing Elastic Cloud Enterprise and preparing hosts for it.

Contents of this role

A minimal example of a small playbook might look like this:

---
- hosts: primary
  gather_facts: true
  roles:
    - elastic-cloud-enterprise
  vars:
    ece_primary: true

- hosts: secondary
  gather_facts: true
  roles:
    - elastic-cloud-enterprise
  vars:
    ece_roles: [director, coordinator, proxy, allocator]

- hosts: tertiary
  gather_facts: true
  roles:
    - elastic-cloud-enterprise
  vars:
    ece_roles: [director, coordinator, proxy, allocator]

At least three hosts are needed for this example, a primary, a secondary, and tertiary host. The example above would execute the following high level steps on the defined hosts:

On all hosts:
- Remove an existing docker installation
- Install required general packages
- Install a current, supported docker version
- Create required users and set limits for them
- Create a xfs partition and configure it
- Configure docker

More information about the prerequisites can be found in the following page.

On the primary host:
- Make the primary installation of Elastic Cloud Enterprise
On the secondary host:
- Install Elastic Cloud Enterprise to join the existing installation with the given ece_roles
On the tertiary host:
- Install Elastic Cloud Enterprise to join the existing installation with the given ece_roles

There is a set of variables and tags available to further define the behaviour of this role, or exclude certain steps.

For example in many cases you might want to install Elastic Coud Enterprise without running any of the potentially destructive system prerequisites like removing existing docker installations and setting up a filesystem. This can be done by specifying --skip-tags destructive on your ansible run - or if you want to only install Elastic Coud Enterprise without any system tasks before --skip-tags system.

Role Variables

The following variables are avaible:

device_name: The name of the device on which the xfs partition should be created
- Required unless filestystem tasks are skipped via tags
- Default: xvdb
ece_primary: Whether this host should be the primary (first) host where Elastic Cloud Enterprise is installed
- Required on a single host
ece_roles: Elastic Cloud Enterprise roles that successive hosts should assume
- Default: [director, coordinator, proxy, allocator]
availability_zone: The availability zone this group of hosts belongs to
ece_version: The Elastic Cloud Enterprise version that should get installed
- Default: 2.2.0
ece_docker_registry: The docker registry from where to pull the Elastic Cloud Enterprise images. This is only relevant if you have a private mirror
- Default: docker.elastic.co
ece_docker_repository: The docker repository in the given registry. This is only relevant if you have a private mirror
- Default: cloud-enterprise
ece_installer_url: The location of the installation script. Can be a local file for offline installation.
- Default: https://download.elastic.co/cloud/elastic-cloud-enterprise.sh
docker_config: If specified as a path to a docker config, copies it to the target hosts
Supported Docker Versions
- docker_version: Supported version on CentOS 7, Ubuntu (14.04LTS, 16.04LTS) and SLES 12 is 18.09, Supported version on RHEL7 is 1.13
force_xfc: By default if the lxc xfc volume already exists, the setup_xfc step is skipped, if this is set to true, creation of the volume is forced
- Default: false
elastic_authorized_keys_file: Defines a local path to an authorized_keys file that should be copied to the elastic user. If not set, the keys from the default user that is used with ansible will be copied over.
memory: Defines the JVM heap size to be used for different services running in ece. See https://www.elastic.co/guide/en/cloud-enterprise/current/ece-heap.html for example values and defaults/main.yml for the default values.

If more hosts should join an Elastic Cloud Enterpise installation when a primary host was already installed previously there are two more variables that are required:

primary_hostname: The (reachable) hostname of the primary host
adminconsole_root_password: The adminconsole root password

Role Tags

The following tags are available to limit the execution, due to the nature of tags in ansible you should only use --skip-tags with these to skip certain parts instead of using --tags to limit the execution.

system Determines the execution of all tasks that setup the system (everything except the actual installation of Elastic Cloud Enterprise)
- setup_filesystem If system tasks are executed, this determines if the filesystem tasks should get executed - includes creating the partitions for xfs and mount points
- install_docker If system tasks are executed, this determines if existing docker packages should get removed and the current, supported version should get installed and configured
destructive This tag indicates whether a task is potentially destructive, like removing packages or doing filesystem partitioning
ece Determines if Elastic Cloud Enterprise should get installed

Examples and use cases

Medium sized first installation of Elastic Cloud Enterprise

This example installs Elastic Cloud Enterprise as detailed in "A medium installation with separate management services" in the official documentation and brings you up to step 5 - Modify the first host you installed Elastic Cloud Enterprise on

site.yml:

- hosts: primary
  roles:
    - elastic-cloud-enterprise
  vars:
    ece_primary: true

- hosts: director_coordinator
  roles:
    - elastic-cloud-enterprise
  vars:
    ece_roles: [director, coordinator, proxy]

- hosts: allocator
  roles:
    - elastic-cloud-enterprise
  vars:
    ece_roles: [allocator]

Assuming all hosts have the device name in common the inventory.yml could look like this:

all:
  vars:
    ansible_become: yes
    device_name: sdb
  children:
    primary:
      hosts:
        host1:
          availability_zone: zone-1
    director_coordinator:
      hosts:
        host2:
          availability_zone: zone-2
        host3:
          availability_zone: zone-3
    allocator:
      hosts:
        host4:
          availability_zone: zone-1
        host5:
          availability_zone: zone-2
        host6:
          availability_zone: zone-3

Adding hosts to an existing installation

Assuming you already have an existing installation of Elastic Cloud Enterprise and you want to add more allocators to it you need to specify two additional variables:

primary_hostname: The (reachable) hostname of the primary host
adminconsole_root_password: The adminconsole root password

The corresponding site.yml could then look like:

- hosts: allocator
  roles:
    - elastic-cloud-enterprise
  vars:
    ece_roles: [allocator]
    primary_hostname: host1
    adminconsole_root_password: secret_password

With the inventory.yml

all:
  vars:
    ansible_become: yes
    device_name: sdb
  children:
    allocator:
      hosts:
        host7:
          availability_zone: zone-1
        host8:
          availability_zone: zone-2
        host9:
          availability_zone: zone-3

Performing an upgrade

You only need to run the upgrade on a single host, it will then automatically propagate to all other hosts. An upgrade is usually performed on the first host you installed Elastic Cloud Enterprise on, but it can also be run from any host that holds the director role.

Assuming you have an installation of Elastic Cloud Enterprise 2.1.0 and want to upgrade to 2.2.0 site.yml could then look like:

- hosts: upgradehost
  roles:
    - elastic-cloud-enterprise
  vars:
    ece_version: 2.2.0

with inventory.yml

all:
  children:
    upgradehost:
      hosts:
        host1:

It is important that you then specify --skip-tags system when you run the playbook in order to only perform the Elastic Cloud Enterprise update and no other tasks, especially when the initial installation was not done with this role.

ansible-playbook -i inventory.yml site.yml --skip-tags system

Extending and Contributing

See CONTRIBUTING.md for more details on how to contribute and extend the Elastic Cloud Enterprise role.

vc0sta/ansible-elastic-cloud-enterprise