Skip to content

Clarify hardware profile and instance configuration related docs for ECH #2039

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
Open

Clarify hardware profile and instance configuration related docs for ECH #2039

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
2f9e518
Clarify hardware profile and instance configuration related docs
kunisen Jul 4, 2025
9d7cb96
Update ec-change-hardware-profile.md
kunisen Jul 4, 2025
2c5fafc
Update ec-change-hardware-profile.md
kunisen Jul 4, 2025
f5afb2b
Merge branch 'main' into kunisen-docpr-stl1586
kunisen Jul 4, 2025
b4ad1c5
Merge branch 'kunisen-docpr-stl1586' of https://github.com/elastic/do…
kunisen Jul 4, 2025
2749011
Update ec-change-hardware-profile.md
kunisen Jul 7, 2025
6f22fe1
Update deploy-manage/deploy/elastic-cloud/change-hardware.md
kunisen Jul 7, 2025
ba8353d
Update deploy-manage/deploy/elastic-cloud/change-hardware.md
kunisen Jul 7, 2025
17d4bd1
Merge branch 'main' into kunisen-docpr-stl1586
kunisen Jul 7, 2025
81b349c
Update change-hardware.md
kunisen Jul 8, 2025
6d6357e
Update change-hardware.md
kunisen Jul 8, 2025
66988bf
Update deploy-manage/deploy/elastic-cloud/change-hardware.md
kunisen Jul 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 29 additions & 3 deletions deploy-manage/deploy/elastic-cloud/change-hardware.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,11 @@ products:
- id: cloud-hosted
---

# Change hardware [ec-change-hardware-for-a-specific-resource]
# Customize instance configuration [ec-change-instance-configuration]
Copy link
Contributor

@eedugon eedugon Jul 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changing the anchor name (the part under [ and ]) could provoke existing links to this page (using the old anchor name) to not locate the section within the doc.

Changing the heading name is not a problem, of course.

I would only change the anchor names if I was sure it's an anchor that hasn't been used or referenced in the past.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@eedugon I checked the reference and didn't find any. Do we still need to keep the original anchor id?
(I should have mentioned that earlier 🙏 )

➜  docs-content git:(kunisen-docpr-stl1586) ag "ec-change-hardware-for-a-specific-resource"
deploy-manage/deploy/elastic-cloud/change-hardware.md
3:  - https://www.elastic.co/guide/en/cloud/current/ec-change-hardware-for-a-specific-resource.html

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd say you can change it, no problem. Worst thing can happen is that an existing link used in a KB article or kept locally by a user will continue working but without reaching the exact anchor, which is not a big deal either.

Also, considering this is also the first anchor of the page the impact will be even less visible.

So whatever you want.

If this was an important or popular anchor in the middle or at the bottom of a big page then I wouldn't touch it, just in case. But this case is probably irrelevant.

My comment was more to warn you about future anchor changes than this specific anchor (like: do not happily change anchors without acknowledging its implications).

Copy link
Contributor Author

@kunisen kunisen Jul 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd say you can change it, no problem. Worst thing can happen is that an existing link used in a KB article or kept locally by a user will continue working but without reaching the exact anchor, which is not a big deal either.

Thank you Edu!

For this, IMHO it's not a problem.

  • The most important part is to keep information up-to-date and correct. In this PR, changing the anchor is to "correct the information" but not a "style or format change".
  • KB or internal reference should be on personal or team efforts and duty to keep them up-to-date to catch up with the correct information (but not we concern about the link reference and we don't make the proper correction)

Hope that makes sense.

My comment was more to warn you about future anchor changes than this specific anchor (like: do not happily change anchors without acknowledging its implications).

Sure, that makes perfect sense. I will also try to look at internal resources too next time. ^ ^


The virtual hardware on which {{stack}} deployments run is defined by instance configurations. To learn more about what an instance configuration is, refer to [Instance configurations](cloud://reference/cloud-hosted/hardware.md#ec-getting-started-configurations).
## Consideration [ec-consideration-on-changing-ic]

The virtual hardware on which {{stack}} deployments run is defined by instance configurations. Review [Hardware profile](./ec-change-hardware-profile.md#ec-hardware-profile) and [Instance configurations](cloud://reference/cloud-hosted/hardware.md#ec-getting-started-configurations) for more information about hardware profile and instance configuration respectively.

When a deployment is created, each {{es}} 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 not advisable to use instance configurations that are not specified on the hardware profile, except in specific situations in which we may need to migrate an {{es}} 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.

Expand Down Expand Up @@ -89,6 +91,30 @@ Having an instance configuration mismatch between the deployment and the hardwar

## Deprecated instance configurations (ICs) and deployment templates (DTs) [ec-deprecated-icdt]

A list of deprecated and valid ICs/DTs can be found on the [Available regions, deployment templates and instance configurations](cloud://reference/cloud-hosted/ec-regions-templates-instances.md) page, as well as through the API, using `hide_deprecated` to return valid ICs/DTs. 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`.
Hardware profile is also referenced as deployment templates in {{ecloud}}.

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](cloud://reference/cloud-hosted/ec-regions-templates-instances.md) 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).

::::{note}
Deployment with Elastic stack version prior to 7.10 does not support hardware profile change {{ecloud}} console and API. If you want to make change on hardware profile, upgrading to version 7.10 and onwards is required.
::::

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.
29 changes: 24 additions & 5 deletions deploy-manage/deploy/elastic-cloud/ec-change-hardware-profile.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,9 @@ products:
- id: cloud-hosted
---

# Change hardware profiles [ec-change-hardware-profile]
# Manage hardware profiles [ec-change-hardware-profile]

## Hardware profile [ec-hardware-profile]

Deployment hardware profiles deploy the {{stack}} on virtual hardware. Each hardware profile has a different blend of storage, RAM, and vCPU.

Expand All @@ -24,6 +26,11 @@ The {{ecloud}} console indicates when a new version of a hardware profile is ava

## Change the hardware profile using the {{ecloud}} console [ec_change_the_hardware_profile_using_the_elastic_cloud_console]

::::{note}
Deployment with Elastic stack version prior to 7.10 does not support hardware profile change {{ecloud}} console and API. If you want to make change on hardware profile, upgrading to version 7.10 and onwards is required.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just for my understanding: What's causing this behavior? Is this something that's fixable easily?

Copy link
Contributor Author

@kunisen kunisen Jul 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just for my understanding: What's causing this behavior? Is this something that's fixable easily?

@yuvielastic it's a product issue that we only support hardware profile migration based on node_roles, where previously in cloud deployment, they use node types and we only introduced node_roles from Elasticsearch 7.10.

You can review this KB (external link) for more details: https://support.elastic.co/knowledge/2040b616 (you can also view internal link and I can share it with you internally if you need more history context)

Also, @gigerdo and I had a sync recently and he suggested that we should use a more self-explanatory message - which is being handled in CP-11182 (internal ticket).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMHO it's not an easy fix - and we probably want to encourage customer more on upgrading to 7.10+ (preferably the current latest they can upgrade to) instead of fixing this and supporting customers to do HW migration on old versions. (It may cause other issues correspondingly as we didn't handle it very smoothly in earlier versions during node type to node roles migration, and it might be hard to cover all the test cases when we add an additional logic to hardware migration APIs - the most difficult part I can expect is the plan fails in the middle that having a mixed of node roles and types, then it may become technically hard to tackle.)

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Kuni for clarifying and agreed that we should encourage customers to upgrade to 7.10+ especially as that version is super old. Also, good to know that we will be updating the message to be more self-explanatory (separately in CP-11182).

::::


### Upgrade to the newest version of your current hardware profile [ec_upgrade_to_the_newest_version_of_your_current_hardware_profile]

Note that if there’s no indication that a newer version is available, that means that your deployment is already running on the latest version of that hardware profile.
Expand Down Expand Up @@ -72,6 +79,11 @@ If your deployment is configured for high availability, the hardware profile cha

## Change the hardware profile using the API [ec_change_the_hardware_profile_using_the_api]

::::{note}
Deployment with Elastic stack version prior to 7.10 does not support hardware profile change {{ecloud}} console and API. If you want to make change on hardware profile, upgrading to version 7.10 and onwards is required.
::::


Prerequisites:

* A valid {{ecloud}} [API key](../../api-keys/elastic-cloud-api-keys.md) (`$EC_API_KEY`)
Expand Down Expand Up @@ -176,21 +188,28 @@ Consider this configuration for ingestion use cases with 1-4 days of data availa

### CPU optimized (ARM) [ec-profiles-compute-optimized-arm]

This profile is similar to CPU optimized profile but is powered by AWS Graviton2 instances. You can find the exact storage, memory, and vCPU allotment on the [hardware details page](cloud://reference/cloud-hosted/hardware.md#ec-getting-started-configurations) for each cloud provider.
This profile is similar to CPU optimized profile but powered by ARM instances. Currently, we offer ARM instances on AWS. You can find the exact storage, memory, and vCPU allotment on the [hardware details page](cloud://reference/cloud-hosted/hardware.md#ec-getting-started-configurations) for each cloud provider.

**Ideal use case**

Consider this configuration for ingestion use cases with 1-4 days of data available for fast access and for search use cases with indexing and querying workloads. Provides the most CPU resources per unit of RAM.


### Vector search optimized (ARM) [ec-profiles-vector-search]
### Vector search optimized [ec-profiles-vector-search]

This profile is suited for Vector search, Generative AI and Semantic search optimized workloads. You can find the exact storage, memory, and vCPU allotment on the [hardware details page](cloud://reference/cloud-hosted/hardware.md#ec-getting-started-configurations) for each cloud provider.

**Ideal use case**

Optimized for applications that leverage Vector Search and/or Generative AI. Also the optimal choice for utilizing ELSER for semantic search applications. Broadly suitable for all semantic search, text embedding, image search, and other Vector Search use cases.

### Vector search optimized (ARM) [ec-profiles-vector-search-arm]

This profile is suited for Vector search, Generative AI and Semantic search optimized workloads powered by ARM instances. Currently, we offer ARM instances on AWS. You can find the exact storage, memory, and vCPU allotment on the [hardware details page](cloud://reference/cloud-hosted/hardware.md#ec-getting-started-configurations) for each cloud provider.

**Ideal use case**

Optimized for applications that leverage Vector Search and/or Generative AI. Also the optimal choice for utilizing ELSER for semantic search applications. Broadly suitable for all semantic search, text embedding, image search, and other Vector Search use cases.


### General purpose [ec-profiles-general-purpose]

Expand All @@ -203,7 +222,7 @@ Suitable for ingestion use cases with 5-7 days of data available for fast access

### General purpose (ARM) [ec-profiles-general-purpose-arm]

This profile is similar to the General purpose profile but is powered by AWS Graviton2 instances. You can find the exact storage, memory, and vCPU allotment on the [hardware details page](cloud://reference/cloud-hosted/hardware.md#ec-getting-started-configurations) for each cloud provider.
This profile is similar to General purpose profile but powered by ARM instances. Currently, we offer ARM instances on AWS. You can find the exact storage, memory, and vCPU allotment on the [hardware details page](cloud://reference/cloud-hosted/hardware.md#ec-getting-started-configurations) for each cloud provider.

**Ideal use case**

Expand Down
2 changes: 1 addition & 1 deletion deploy-manage/production-guidance/optimize-performance/indexing-speed.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ If indexing is I/O-bound, consider increasing the size of the filesystem cache (
Stripe your index across multiple SSDs by configuring a RAID 0 array. Remember that it will increase the risk of failure since the failure of any one SSD destroys the index. However this is typically the right tradeoff to make: optimize single shards for maximum performance, and then add replicas across different nodes so there’s redundancy for any node failures. You can also use [snapshot and restore](../../tools/snapshot-and-restore.md) to backup the index for further insurance.

::::{note}
In {{ech}} and {{ece}}, you can choose the underlying hardware by selecting different hardware profiles or deployment templates. Refer to [ECH > Change hardware](/deploy-manage/deploy/elastic-cloud/change-hardware.md) and [ECE deployment templates](/deploy-manage/deploy/cloud-enterprise/configure-deployment-templates.md) for more details.
In {{ech}} and {{ece}}, you can choose the underlying hardware by selecting different hardware profiles or deployment templates. Refer to [ECH > Manage hardware profiles](/deploy-manage/deploy/elastic-cloud/ec-change-hardware-profile.md) and [ECE > Manage deployment templates](/deploy-manage/deploy/cloud-enterprise/configure-deployment-templates.md) for more details.
::::

### Local vs. remote storage [_local_vs_remote_storage]
Expand Down
2 changes: 1 addition & 1 deletion deploy-manage/production-guidance/optimize-performance/search-speed.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ If your searches are I/O-bound, consider increasing the size of the filesystem c
If your searches are CPU-bound, consider using a larger number of faster CPUs.

::::{note}
In {{ech}} and {{ece}}, you can choose the underlying hardware by selecting different hardware profiles or deployment templates. Refer to [ECH > Change hardware](/deploy-manage/deploy/elastic-cloud/change-hardware.md) and [ECE deployment templates](/deploy-manage/deploy/cloud-enterprise/configure-deployment-templates.md) for more details.
In {{ech}} and {{ece}}, you can choose the underlying hardware by selecting different hardware profiles or deployment templates. Refer to [ECH > Manage hardware profiles](/deploy-manage/deploy/elastic-cloud/ec-change-hardware-profile.md) and [ECE > Manage deployment templates](/deploy-manage/deploy/cloud-enterprise/configure-deployment-templates.md) for more details.
::::

### Local vs. remote storage [_local_vs_remote_storage_2]
Expand Down
3 changes: 2 additions & 1 deletion deploy-manage/toc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,8 @@ toc:
- file: deploy/elastic-cloud/configure.md
children:
- file: deploy/elastic-cloud/ec-change-hardware-profile.md
children:
- file: deploy/elastic-cloud/change-hardware.md
- file: deploy/elastic-cloud/ec-customize-deployment-components.md
- file: deploy/elastic-cloud/edit-stack-settings.md
- file: deploy/elastic-cloud/add-plugins-extensions.md
Expand All @@ -57,7 +59,6 @@ toc:
- file: deploy/elastic-cloud/switch-from-apm-to-integrations-server-payload.md
- file: deploy/elastic-cloud/find-cloud-id.md
- file: deploy/elastic-cloud/ec-vcpu-boost-instance.md
- file: deploy/elastic-cloud/change-hardware.md
- file: deploy/elastic-cloud/manage-deployments-using-elastic-cloud-api.md
- file: deploy/elastic-cloud/keep-track-of-deployment-activity.md
- file: deploy/elastic-cloud/restrictions-known-problems.md
Expand Down
Loading