It is time to say goodbye: This version of Elastic Cloud Enterprise has reached end-of-life (EOL) and is no longer supported.

The documentation for this version is no longer being maintained. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« Manage Elastic Stack versions Update a deployment template to a supported instance configuration »
Elastic Docs ›Elastic Cloud Enterprise Reference [2.12] ›Administering your installation

Upgrade your installation

edit

Upgrade your installation

edit

Periodically, you might need to upgrade your Elastic Cloud Enterprise installation as new versions with additional features become available. The upgrade process updates all hosts that are part of your Elastic Cloud Enterprise installation to the latest version of ECE, with little or no downtime for managed deployments.

Upgrading to 2.12.x or 2.13.0 is not recommended as it can cause issues and you may lose access to the admin console. You are strongly advised to upgrade to 2.13.1 and later.

We strongly recommend that you enable XFS quotas, otherwise disk usage won’t display correctly. To enable XFS quotas, you must modify the entry for the XFS volume in the /etc/fstab file to add pquota and prjquota. The default filesystem path used by Elastic Cloud Enterprise is /mnt/data.

Upgrading Elastic Cloud Enterprise works by replacing the containers that ECE itself requires to run on each host. Upgrading ECE does not touch any of the containers that run your Elasticsearch clusters and Kibana instances. Each container that needs to be upgraded is renamed and stopped, followed by the creation of a new container with an upgraded instance of the ECE software and its dependencies. When the upgrade process has completed successfully, it cleans up after itself and removes the old containers.

The upgrade process creates a frc-upgraders-monitor container on the host where you initiate the process that performs the following actions:

  • Back up the ZooKeeper transaction log to HOST_STORAGE_PATH/RUNNER_ID/services/zookeeper/data/backup, where HOST_STORAGE_PATH and RUNNER_ID are specific to your installation.
  • Configure Elastic Cloud Enterprise to perform the individual container upgrades by creating a frc-upgraders-upgrader container on each host that is part of the installation.
  • Monitor the upgrade process to ensure that all frc-upgraders-upgrader containers perform their part of the upgrade as expected and report their status.
  • After all hosts have been upgraded successfully, clean up temporary artifacts created during the upgrade process, and remove the old containers.

The entire process is designed to be failsafe. Containers get upgraded sequentially and the upgrade status of each container is tracked. The upgrade process also monitors that each new container is viable and continues to run as expected. If there is an issue with any part of the upgrade, the entire process is rolled back.

Before you begin

edit

We strongly recommend that you routinely update your ECE installation to the most current version so that any bugs and security issues are fixed promptly. If you need to upgrade but are currently experiencing any issues with your platform, note that as long as ZooKeeper is running and healthy you should be able to upgrade (you can use the get runners API to easily check the health of the runners on your ECE allocators). That is, you not need have healthy system clusters in order to perform an upgrade successfully.

To run the script to upgrade Elastic Cloud Enterprise, a user must be part of the docker group. You initiate the upgrade process by running the elastic-cloud-enterprise.sh script with the upgrade action on a single host. The host that you run the script on must be a host that holds the director role. You do not need to run the script on additional hosts.

Each host in your Elastic Cloud Enterprise installation must have at least 5 GB of disk space available to ensure that the upgrade process can complete successfully.

We strongly recommend that you do not attempt to perform certain actions during the upgrade process, such as:

  • Creating or changing Elasticsearch clusters and Kibana instances
  • Adding new hosts to your installation or removing existing hosts

As a precaution, we also recommend that you take current snapshots of your Elasticsearch clusters.

To avoid any downtime for Elastic Cloud Enterprise, your installation must include more than one proxy and you must use a load balancer as recommended. If you are using only a single proxy or if you are not using a load balancer, some downtime is expected when the containers on your proxies are upgraded. Each container upgrade typically takes five to ten seconds, times the number of containers on a typical host.

For offline or air-gapped installations, additional steps are required to upgrade Elastic Cloud Enterprise. After downloading the installation script for the new version, you also need to pull and load the required container images and push them to your own private Docker registry. To learn more about pulling and loading Docker images, see Install ECE offline.

If your ECE installation is still using the default, auto-generated certificates: We recommend that you perform one of the following steps to avoid trust errors related to the proxy server certificate after the upgrade. The proxy server certificate is used when connecting to Kibana and Elasticsearch clusters. During the upgrade, the ECE certificate authority generates a new certificate. As with any server certificate rotation, you must add an exception for the new proxy server certificate, unless the certificate authority is present in the trust store of your system or browser. You can perform either of these steps before or after the upgrade:

  • Recommended: Add your organization’s own certificate to Elastic Cloud Enterprise. The upgrade process ensures that the certificates you add do not change, which avoids the trust errors.
  • Add the default CA certificate to the trust store of your system or of your browser. Only the server certificate changes during upgrade, but the CA certificate remains the same. Adding the CA certificate to your trust store alone is sufficient to avoid the trust errors.

  • Apply valid license. It is required to have an Enterprise resource unit-compatible license applied before upgrading to ECE 2.7+. The most reliable way to check if your license is compatible is to use the Elastic Cloud Enterprise API and check the value of the license version field:

    curl -X GET -u admin:PASSWORD -k https://COORDINATOR_HOST:12443/api/v1/platform/license
{
  "license": {
    "version": 4,
    // other fields
  }
}

    If the version is not 4 or higher, you must request an updated license from Elastic Support. Once you receive your new license, make sure you are upgraded to at least Elastic Cloud Enterprise 2.5.0, and then upload the new license in the Settings page under the Platform menu.

Important: Check if you can upgrade directly

edit

If your upgrade path involves a version earlier than 2.1.0 to a version between 2.1.0 and 2.3.1, follow these steps to avoid a known upgrade bug:

  1. Download the upgrade script and set the required version in the script to CLOUD_ENTERPRISE_VERSION=2.1.0.
  2. Follow the steps in the next section to upgrade to version 2.1.0.
  3. Set the version in the upgrade script to the later target version, such as CLOUD_ENTERPRISE_VERSION=2.3.1.
  4. Follow the steps in the next section again, this time to upgrade to the later target version.

Upgrade your system deployments

edit

For Elastic Cloud Enterprise 2.12.1, you must upgrade your system deployments to version 6.8 before proceeding. To ensure the smoothest upgrade process, we recommend first upgrading ECE to at least version 2.5.0 if it is not already. Starting with ECE 2.7, all system clusters will be automatically upgraded to their latest supported Elasticsearch version as part of the ECE upgrade process. admin-console-elasticsearch, security-cluster and logging-and-metrics clusters will all be upgraded to 7.x. If you are installing ECE without internet access (commonly called an offline or air-gapped installation), you must ensure that the latest 6.x and 7.x Elastic stack versions are installed before running the upgrade process. For standard installations, the ECE upgrader will install these for you. If the automatic system deployment upgrade process fails, note that the Elastic Cloud Enterprise upgrade will not be rolled back, and you will need to upgrade them yourself. For admin-console-elasticsearch or logging-and-metrics, it is recommended to use the Elastic Cloud Enterprise user interface, while security-cluster has a dedicated API that should be used to create or update the deployment.

  1. If you haven’t done so already, add the latest version 5.6, 6.8, and 7.15 Stack packs to your installation.
  2. Log into the Cloud UI.

  3. On the Deployments page, select the admin-console-elasticsearch deployment.

    1. Upgrade Elasticsearch to the latest 5.6 version.
    2. Upgrade Elasticsearch to the latest 6.8 version. IMPORTANT: Do not upgrade this cluster to 7.x at this time.

  4. On the Deployments page, select the logging-and-metrics deployment.

    1. Export any customizations that you made to dashboards and visualizations. When you upgrade, any customizations are replaced with the new versions.
    2. Upgrade Elasticsearch to the latest 5.6 version.
    3. Upgrade Elasticsearch to the latest 6.8 version. IMPORTANT: Do not upgrade this cluster to 7.x at this time.
    4. Upgrade Kibana to match the new version of Elasticsearch.

  5. On the Deployments page, select the security-cluster deployment.

    1. Upgrade Elasticsearch to the latest 6.8 version.

If you upgrade ECE using the UI upgrader, this will automatically raise security-cluster to the latest 7.15 version. Just in case that upgrade isn’t successful, you can use a dedicated Update security deployment API to bring security-cluster to the most recent version.

ECE 2.10 introduces the upgrade of the logging-and-metrics system cluster to version 7.15. There is a possibility the some of the default ECE dashboards break after the upgrade - in particular, we’ve identified that some of the visualizations in the Metricbeat Docker Overview dashboard are likely to break. For that reason, we advise that you export Kibana saved objects through the Kibana UI before upgrading ECE to 2.10. If you notice that a Kibana dashboard is not working after the upgrade, you should reimport the saved object through the Kibana UI.

For clusters using version 5.5 or earlier, upgrading to version 5.6 is mandatory before a major upgrade. The UI will not show any 6.6.0 or higher versions until this is done. For clusters already on version 5.6 it is still recommended to upgrade to the latest 5.6 patch version first to ensure the smoothest possible transition.

Perform the upgrade

edit

To upgrade your Elastic Cloud Enterprise installation:

  1. Download and run the latest installation script with the upgrade action on a single host that holds the director role:

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

You can follow along whilst each container for Elastic Cloud Enterprise is upgraded on the hosts that are part of your installation.

Post upgrade: Review your deployment templates and instance configurations

edit

If you are upgrading to Elastic Cloud Enterprise version 2.5 or higher, it is possible that some instance configurations have been marked as deprecated. You can check the Deployment templates page for any deprecation warnings.

Here is what has changed in ECE version 2.5:

  1. The ingest instance configuration is deprecated and replaced by the new coordinating instance configuration.

  2. Instance configurations not matching one of these four combinations of instance types are deprecated:

    • master: a dedicated master node
    • ingest: a dedicated ingest node
    • master, data, ingest: the default set of roles
    • ml: a machine learning node

Additionally, validation has been introduced for deployments and deployment templates to prevent the topology of a deployment drifting from the one defined in the template that it is based on.

This means that a situation can occur where you are unable to apply changes to your deployment because it does not match the deployment template. However, this should be a relatively rare case.

If this situation happens, follow these steps to update your deployment template to a supported instance configuration.

« Manage Elastic Stack versions Update a deployment template to a supported instance configuration »