Install ECE (With Internet Access)

This section applies to you if you want to install Elastic Cloud Enterprise by directly downloading it from Elastic. A typical installation requires internet access.

You start setting up a new Elastic Cloud Enterprise installation by installing the software on your first host. This first host becomes the initial coordinator and provides access to the Cloud UI, where you can manage your installation. You then install Elastic Cloud Enterprise on additional hosts to add them as resources to an existing installation.

Not sure what your Elastic Cloud Enterprise installation should look like? Check our topology recommendations.

Before you begin

To run the installation script, a user must be part of the docker group. You should not install Elastic Cloud Enterprise as the root user.

Install on Your First Host

You start setting up a new Elastic Cloud Enterprise installation by installing the software on your first host. This first host becomes the initial coordinator and provides access to the Cloud UI, where you can manage your installation.

To install Elastic Cloud Enterprise on your first host:

  1. Download and run the installation script:

    bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install

    Installation can take a while to complete as it downloads the Elastic Cloud Enterprise image.

    Tip

    The installation script supports passing additional parameters, if you need them. To learn more, see elastic-cloud-enterprise.sh Installation Script.

  2. During installation, the secrets used by the system are generated, including:

    • The passwords for the root and readonly users
    • The root certificates to generate intermediate and client certificates to encrypt SSL communication among all of the services
    • Several roles tokens to enable additional hosts to join your Elastic Cloud Enterprise installation

      These secrets are placed into the /mnt/data/elastic/bootstrap-state/bootstrap-secrets.json secrets file, unless you passed in a different path with the --host-storage-path parameter.

      Important

      Keep the information in the bootstrap-secrets.json file secure by removing the file and placing it into secure storage, for example.

  3. Copy down the URL and user credentials for the administration console provided to you at the end of the installation process. You will use this information to log into the Cloud UI later on. For example:

    Administration Console Details:
    Cloud UI URL: http://192.168.40.102:12400
    Cloud UI URL: https://192.168.40.102:12443
    Root username: root
    Password: lCFNHcnDAfGUnOgN9MSCYo1q4i4NaNkufDoZVMzFL9x
    Read-only username: readonly
    Password: QtCOZTNe7KHUnGhHBMn4q5JMOqjOFNHT9YQ2yUmWzUX

    You can use either the root user or the readonly user to log in, but only the root user has the required privileges to make changes to any resources in the Cloud UI. If you are logging into the Cloud UI for the first time, use the root user.

  4. Copy down the roles tokens. These tokens enable hosts to join an existing Elastic Cloud Enterprise installation and grant permission to hosts to hold certain roles, such as the allocator role. These tokens help secure Elastic Cloud Enterprise by making sure that only authorized hosts become part of the installation.

    Roles tokens for adding hosts to this installation:
      Basic token (Don't forget to assign roles to new runners in the Cloud UI after installation): 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI4ZGQ3OGQ5NS0yODUwLTQ3MTctYjMzNS03YmQyMDY2NDMxNGUiLCJyb2xlcyI6W10sImlzcyI6ImN1cnJlbnQiLCJwZXJzaXN0ZW50Ijp0cnVlfQ.GXDYSwY9Y9HYnOxTP8Rdt68RNVlH9yaGe5jZfM-1dMo'
    Allocator token (Simply need more capacity to run Elasticseach clusters and Kibana? Use this token.): eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIzNWQ1N2EzYS1hY2NjLTQ3NTItODY5Yy0xZjI5NGY2N2E3YjQiLCJyb2xlcyI6WyJhbGxvY2F0b3IiXSwiaXNzIjoiY3VycmVudCIsInBlcnNpc3RlbnQiOnRydWV9.Hxa_wZva6s9cdpOAKbExA7_gXFvHhA5KPBclzPJbDrU
    Emergency token (Lost all of your coordinators? This token will save your installation.): eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIyZGVlYjlkZS01MDkzLTQxNGItYmI5NS0zNmJhZTQxMWI0YzgiLCJyb2xlcyI6WyJjb29yZGluYXRvciIsInByb3h5IiwiZGlyZWN0b3IiXSwiaXNzIjoiY3VycmVudCIsInBlcnNpc3RlbnQiOnRydWV9.5tIVQxEluSjtJ7qiwE8OWzy5O4l1GJ0urTFs_l1x5bU
    Important

    The emergency token can save your installation if all coordinators fail or are removed and you can no longer use the Cloud UI or the RESTful API. To learn more, see Using the Emergency Roles Token.

  5. If you plan to install Elastic Cloud Enterprise on additional hosts, also copy down the details for the --coordinator-host parameter, which provides the IP address of the first host you installed on, and the details for the --roles-token parameter. Installing Elastic Cloud Enterprise on additional hosts requires the roles token provided by the --roles-token parameter, otherwise the new host is rejected. You can use any of the tokens provided, or generate your own for specific roles first.

    To add hosts to this Elastic Cloud Enterprise installation, include the following parameters when you install the software on additional hosts: --coordinator-host 192.168.40.102 --roles-token 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI2ZDE2ZDY3YS01NGUzLTQ0MzMtYTlmZC05MTJjYzQwZmIxYmQiLCJyb2xlcyI6W10sImlzcyI6ImN1cnJlbnQiLCJwZXJzaXN0ZW50Ijp0cnVlfQ.MGEpEj0JmUGuucazf55sURNX-Q6QIMhKP0gdNJ2-vnk'
  6. Log into Cloud UI to provision your cluster or follow the steps in the next section to add more hosts first.

A note on output shown during the installation process

The script writes bootstrap status information to standard output. Unless you see stack traces, this status information is an expected part of the process.

There might be some errors shown during the installation that can be ignored safely, such as:

Error deleting container: Error response from daemon: Cannot destroy container bfe798eaf9d2525de16366ffb02d335252bbe532d5eb6a7776cdb73944fd9845: Driver aufs failed to remove root filesystem bfe798eaf9d2525de16366ffb02d335252bbe532d5eb6a7776cdb73944fd9845: rename /mnt/data/docker/aufs/mnt/bfe798eaf9d2525de16366ffb02d335252bbe532d5eb6a7776cdb73944fd9845 /mnt/data/docker/aufs/mnt/bfe798eaf9d2525de16366ffb02d335252bbe532d5eb6a7776cdb73944fd9845-removing: device or resource busy

Error response from daemon: Unable to remove filesystem for 3279e8fe8091820d4aa5b518c2488e2fe481b7dedff91515079ef0ce34edfc70: remove /mnt/data/docker/containers/3279e8fe8091820d4aa5b518c2488e2fe481b7dedff91515079ef0ce34edfc70/shm: device or resource busy

Install on Additional Hosts

You install Elastic Cloud Enterprise on additional hosts to add them as resources to an existing installation.

For example, if you need more processing capacity for Elasticsearch nodes in your cluster, you can add a host by installing Elastic Cloud Enterprise on it and then assign the allocator role in the Cloud UI. Or maybe you to want to create a cluster that is fault-tolerant and can be used for production? You’ll need to make sure there are enough resources available to support multiple availability zones.

To install Elastic Cloud Enterprise on additional hosts:

  1. Download and run the installation script on each additional host. Include the --coordinator-host HOST_IP and --roles-token 'TOKEN' parameters provided to you when you installed on the first host (example). Installing Elastic Cloud Enterprise on additional hosts requires the token, or the new host will be rejected.

    bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) install --coordinator-host HOST_IP --roles-token 'TOKEN'

    If you are creating a larger Elastic Cloud Enterprise installation:

    • To make your installation fault tolerant or highly available, include the --availability-zone ZONE_NAME parameter to specify the name of an availability zone for the additional host, which determines which failure domain the host should belong to. Hosts should go into three different availability zones for production systems. For example, including the parameter --availability-zone ece-region-1c when you install on additional hosts places the additional host into availability zone ece-region-1c.
    • To simplify the steps for assigning roles so that you do not have to change the roles in the Cloud UI later on, include the --roles parameter. For example, to bring up additional allocators to scale out your installation, specify the --roles "allocator" parameter. You do need to generate a roles token that has the right permissions for this to work; the token generated during the installation on the first host will not suffice.

      Tip

      The installation script supports passing additional parameters, if you need them. To learn more, see elastic-cloud-enterprise.sh Installation Script.

After installation completes, additional hosts come online as runners with some roles assigned to them already. If you did not specify additional roles with the --roles parameter, you can assign new roles to nodes to define the topology of clusters in the Cloud UI later.

For automation purposes, you can set up a DNS hostname for the coordinator host. Setting up a round robin CNAME should be enough to ensure that the value does not need to change in automation scripts. Any one coordinator can be used, including the initial coordinator (the first host you installed Elastic Cloud Enterprise on).