Customize instance configuration

This document explains how to modify the instance configurations used by specific components of your deployment without changing the overall hardware profile assigned to the deployment. This advanced configuration scenario is useful in situations where you need to migrate an Elasticsearch tier or stateless resource to a different hardware type.

Elastic Stack deployments run on virtual hardware defined by instance configurations. For more details, refer to Hardware profiles and Instance configurations documents.

When a deployment is created, each Elasticsearch tier and stateless resource (e.g., Kibana) gets an instance configuration assigned to it, based on the hardware profile used. The combination of instance configurations defined within each hardware profile is designed to provide the best possible outcome for each use case. Therefore, it is generally not advisable to use instance configurations that are not specified in the hardware profile, except in specific situations in which we may need to migrate an Elasticsearch tier or stateless resource to a different hardware type. An example of such a scenario is when a cloud provider stops supporting a hardware type in a specific region.

Note:

• Elastic Cloud console (UI): You can only update instance configurations for Elasticsearch data tiers (hot, warm, cold, and frozen). Stateless resources are shown in the plan preview but cannot be modified.
• API: You can update instance configurations for both Elasticsearch data tiers and stateless resources.

Using the Elastic Cloud console, you can change the instance configuration for Elasticsearch hot, warm, cold, or frozen data tiers without modifying other resources.

1. On the deployment overview page, find your current hardware profile and click Edit.

2. In the hardware profile flyout, select the instance configuration for each data tier you want to update. The configuration screen summarizes the changes for the tier-specific instance configurations as part of your deployment.

   Only instance types available in the deployment's regions are shown. Stateless resources (For example: master nodes, ML nodes, Kibana) cannot be modified, but the plan preview will still show their related updates.

3. After reviewing the changes, click Update.

4. A confirmation dialog will appear showing all changes that will happen. Review the plan and click Confirm to apply the update.

   If your instance configuration selection matches an existing hardware profile, that hardware profile is automatically selected. Otherwise, your hardware profile is labeled as custom in the console.

Prerequisites:

• A valid Elastic Cloud API key ($EC_API_KEY)

Follow these steps to migrate to a different instance configuration, replacing the default $EC_API_KEY value with your actual API key:

1. From the list of instance configurations available for each region, select the target instance configuration you want to migrate to.

   Note

   The target instance configuration must be compatible with the Elasticsearch tier or stateless resource you are updating. For example, if you are migrating the hot Elasticsearch tier, the target instance configuration must also be of the es.datahot family.

2. Get the deployment update payload from the Elastic Cloud Console Edit page, by selecting Equivalent API request, and store it in a file called migrate_instance_configuration.json.

   Example payload containing relevant data for migrating the hot Elasticsearch tier:

   {
     "resources": {
       "elasticsearch": [
         {
           "plan": {
             "cluster_topology": [
               {
                 "id": "hot_content",
                 "instance_configuration_id": "gcp.es.datahot.n2.68x10x45",
                 "instance_configuration_version": 1,
   		

3. Set the instance_configuration_id field of the Elasticsearch tier or stateless resource you want to migrate to the Instance ID of the instance configuration selected in step 1.

4. If the instance_configuration_version field is defined for that Elasticsearch tier or stateless resource, remove it from the payload.

   Following is the update that would be required to migrate the example above to the gcp.es.datahot.n2.68x10x95 instance configuration:

   {
     "resources": {
       "elasticsearch": [
         {
           "plan": {
             "cluster_topology": [
               {
                 "id": "hot_content",
                 "instance_configuration_id": "gcp.es.datahot.n2.68x10x95",
   		

5. Use the payload to update your deployment and perform the instance configuration migration.

   curl -XPUT https://api.elastic-cloud.com/api/v1/deployments/{deployment_id} \
   -H "Authorization: ApiKey $EC_API_KEY" \
   -H 'Content-Type: application/json' \
   -d @migrate_instance_configuration.json
   		

Hardware profile is also referenced as deployment templates in Elastic Cloud.

You can find a list of deprecated and valid instance configurations (ICs) and deployment templates (DTs) in two ways:

Visit the Available regions, deployment templates and instance configurations page for detailed information.

Use the Get deployment templates API with query parameters like hide_deprecated to retrieve valid ICs and DTs. This API request returns a list of DTs along with the respective ICs referenced within each DT.

For example,

• To return valid ICs/DTs the following request can be used: https://api.elastic-cloud.com/api/v1/deployments/templates?region=us-west-2&hide_deprecated=true.
• To list only the deprecated ones, this can be used: https://api.elastic-cloud.com/api/v1/deployments/templates?region=us-west-2&metadata=legacy:true.

If a deprecated IC/DT is already in use, it can continue to be used. However, creating or migrating to a deprecated IC/DT is no longer possible and will result in a plan failing. In order to migrate to a valid IC/DT, navigate to the Edit hardware profile option in the Cloud UI or use the Deployment API.

In addtion, you can refer to below information about how these terminologies are referenced.

• Deprecated is also referenced as legacy.
• Using the metadata=legacy:true query parameter will return only legacy/deprecated DTs.
• Using the hide_deprecated=true query parameter will return only valid DTs.
• Not using any of the query parameters above will return all DTs. In this case, check the presence of legacy: true in the metadata entries within the API response, to verify if an IC/DT is deprecated or not.