search

elastic / ansible-elastic-cloud-enterprise

Ansible playbooks for Elastic Cloud Enterprise (ECE)
https://www.elastic.co/products/ece
Other
60 stars 61 forks source link

readme

ansible-elastic-cloud-enterprise

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

Requirements

This role is tested against Ansible 2.8.7.

Contents of this role

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

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

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

- hosts: tertiary
  gather_facts: true
  roles:
    - ansible-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:

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

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 --tags bootstrap.

Role Variables

The following variables are avaible:

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:

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.

By default, all tags are applied, except vmimage, which means that it will install all prerequisites and Elastic Cloud Entreprise. In order to use this ansible playbook for building a VM image, the following tags should be selected: --tags base,vmimage (this won't install Elastic Cloud Enterprise)

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:
    - ansible-elastic-cloud-enterprise
  vars:
    ece_primary: true

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

- hosts: allocator
  roles:
    - ansible-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:

The corresponding site.yml could then look like:

- hosts: allocator
  roles:
    - ansible-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:
    - ansible-elastic-cloud-enterprise
  vars:
    ece_version: 2.2.0

with inventory.yml

all:
  children:
    upgradehost:
      hosts:
        host1:

It is important that you then specify --tags bootstrap 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 --tags bootstrap

Building a base Virtual Machine Image

Building a Virtual Machine Images depends on the tools and platform you are using. Once a base instance is running, you can use a playbook like the following:

- hosts: all
  become: true
  roles:
    - ansible-elastic-cloud-enterprise

And ansible should be run with --tags base,vmimage, this will install prerequisites for Elastic Cloud Entreprise, but not Elastic Cloud Entreprise. Finally, you will be able to save the instance as VM image (depending on your cloud provider)

Once the image is ready, you can use it as a base to install Elastic Cloud Entreprise, either from the boostraper script, or with ansible, using --tags bootstrap (this will install only Elastic Cloud Entreprise)

Extending and Contributing

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