---
title: Customize instance configuration
description: This document explains how to modify the instance configurations used by specific components of your deployment without changing the overall hardware...
url: https://www.elastic.co/elastic/docs-builder/docs/3028/deploy-manage/deploy/elastic-cloud/change-hardware
products:
- Elastic Cloud Hosted
applies_to:
- Elastic Cloud Hosted: Generally available
---
# 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.
## Consideration
Elastic Stack deployments run on virtual hardware defined by instance configurations. For more details, refer to [Hardware profiles](/elastic/docs-builder/docs/3028/deploy-manage/deploy/elastic-cloud/ec-change-hardware-profile#ec-hardware-profile) and [Instance configurations](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/reference/cloud-hosted/hardware#ec-getting-started-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.
## Migrate to a different instance configuration for data tiers using the Elastic Cloud Console
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.
## Migrate to a different instance configuration using the API
Prerequisites:
- A valid Elastic Cloud [API key](https://www.elastic.co/elastic/docs-builder/docs/3028/deploy-manage/api-keys/elastic-cloud-api-keys) (`$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](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/reference/cloud-hosted/ec-regions-templates-instances), select the target instance configuration you want to migrate to.
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](https://cloud.elastic.co?page=docs&placement=docs-body) **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:
```json
{
"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:
```json
{
"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.
```sh
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
```
You can perform multiple instance configuration migrations in the same request.
Having an instance configuration mismatch between the deployment and the hardware profile will cause the Elastic Cloud console to announce that there is a **Newer version available** for the hardware profile. Any hardware profile migration performed through the Elastic Cloud console will cause the instance configurations to be reset to the values in the hardware profile.
## Deprecated instance configurations (ICs) and deployment templates (DTs)
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:
### Public documentation page
Visit the [Available regions, deployment templates and instance configurations](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/reference/cloud-hosted/ec-regions-templates-instances) page for detailed information.
### API access
Use the [Get deployment templates API](https://www.elastic.co/docs/api/doc/cloud/operation/operation-get-deployment-templates-v2) 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](https://www.elastic.co/docs/api/doc/cloud/operation/operation-migrate-deployment-template).
Deployments using Elastic Stack versions prior to 7.10 do not support changing the hardware profile through the Elastic Cloud console or API. To change the hardware profile, first upgrade to version 7.10 or later.
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.