Upgrading a ROSA HCP cluster with Terraform

Learn how to upgrade Red Hat OpenShift Service on AWS (ROSA) Hosted Control Plane (HCP) clusters with the supported Terraform RHCS provider and the terraform-redhat/rosa-hcp module. Upgrade the control plane first, then additional machine pools, then the default installer worker pools. Do not change channel and version in the same apply.

This is a practical day-2 guide for z-stream and y-stream upgrades with the official RHCS Terraform stack. For cluster creation, see Deploying a ROSA HCP cluster with Terraform .

Why this matters

On ROSA Hosted Control Plane, the control plane and machine pools upgrade independently. The OpenShift version on a machine pool must never exceed the control plane version, and you cannot upgrade both to the same target in one Terraform apply. Teams that only bump openshift_version and run a full terraform apply often hit empty “available upgrades” lists on pools, or leave the installer-created workers-* pools behind while additional pools move forward.

This article follows the supported Terraform path:

• Provider: terraform-redhat/rhcs
• Module: terraform-redhat/rosa-hcp/rhcs (and its rosa-cluster-hcp / machine-pool submodules)
• Official guides: Upgrading HCP with Terraform , Default / worker machine pool , ROSA HCP upgrading

Three upgrade surfaces

Pools may lag the control plane by up to two minor (y-stream) versions.

Before you upgrade

Prerequisites

• A ROSA HCP cluster managed with Terraform (terraform-redhat/rosa-hcp or equivalent rhcs_cluster_rosa_hcp / rhcs_hcp_machine_pool resources)
• rosa CLI logged in
• terraform CLI with access to the same state used to create the cluster

Confirm a supported path

1. List available upgrades for the cluster and for each machine pool:

   If a machine pool shows no available upgrades ([]) while the CP target exists, the control plane has not finished moving to a version that unlocks that pool upgrade. Wait for the CP, then retry.

Z-stream vs y-stream

• Z-stream (for example 4.21.15 to 4.21.27): bump version only. upgrade_acknowledgements_for is usually not required.
• Y-stream (for example 4.21.z to 4.22.z): set channel (for example stable-4.22) and upgrade_acknowledgements_for = "4.22", but not in the same API request as the version bump (see below).

Acknowledge only after you validate

Setting upgrade_acknowledgements_for means you accept the administrative agreements for that minor upgrade. Before you set it:

• Review OpenShift / ROSA release notes and life cycle for the target y-stream
• Check API deprecations and removed APIs (operators, CRDs, GitOps manifests)
• Confirm workloads and operators support the target version

Part 1: Upgrade the control plane only

With the rosa-hcp root module (or an equivalent that wraps modules/rosa-cluster-hcp), target the cluster module so machine pools are not updated in the same apply.

Z-stream example

1. Set the target version:

2. Apply only the cluster module:

3. Wait until the control plane is ready:

Y-stream: channel and version cannot change together

The OCM API returns:

if you update both in one request. Use two control-plane applies.

1. Apply A: channel only (keep the current CP version):

2. Apply B: version (channel already stable-4.22):

Part 2: Upgrade additional machine pools

Additional pools are the ones you created with the machine-pool submodule (or rhcs_hcp_machine_pool resources) after cluster create, for example GPU, metal, or extra compute pools.

After the control plane is on the target version:

1. Set each pool’s openshift_version / version to the same target (or use a shared variable the module passes through).

2. For y-stream, set upgrade_acknowledgements_for on the pool if the provider requires it (same minor acknowledgement pattern as the cluster).

3. Apply pools only (or a full apply now that CP is done):

4. Verify:

You want pool VERSION to match the CP (or show a scheduled upgrade), and eventually “no available upgrades” once caught up.

Part 3: Default machine pools

What the official module does (and does not)

When you create a ROSA cluster with Terraform, a default worker machine pool is created by the installer so the cluster can become ready. After create, cluster attributes such as compute_machine_type / replicas on rhcs_cluster_rosa_hcp no longer drive day-2 pool changes.

Per the RHCS worker machine pool guide :

• You must import a machine pool resource that points at the default pool before you can change or delete it via Terraform.
• Classic docs often refer to a pool named worker.
• On ROSA HCP multi-AZ, you typically get one pool per AZ: workers-0, workers-1, workers-2, and so on, not a single worker name. Magic import for the name worker does not cover those HCP pools; use explicit terraform import for each.

Until you import them, bumping openshift_version on the cluster and on additional pools will not upgrade default workers-* pools. That is expected, not a Terraform bug.

Manual steps (supported RHCS pattern)

1. List pools and note subnet / replicas / instance type:

2. Declare rhcs_hcp_machine_pool resources that match live settings (names and subnet_id are immutable after create):

3. If the provider rejects updates to installer aws_node_pool fields (for example tags changing from null), add:

   so Terraform can still manage version without fighting create-time node-pool attributes.

4. Import into state (HCP import id is cluster_id,machine_pool_id):

5. Align config with terraform plan until you only see intended changes (usually version).

6. Upgrade default pools after the CP is on the target version:

7. Confirm:

Destroy / day-2 safety tips

• ROSA requires at least one machine pool; deleting the last pool is rejected by the API. Use ignore_deletion_error = true when the cluster and pools are destroyed in the same root module.
• To stop managing default pools in Terraform without deleting them in AWS/OCM: terraform state rm the resources, then remove them from configuration. Setting a “manage default pools” flag to false while resources remain in config will plan a destroy.

Recommended upgrade sequence

Common errors

References

• Upgrade ROSA HCP cluster or machine pool (RHCS Terraform)
• Default machine pool / import guide (RHCS Terraform)
• rhcs_hcp_machine_pool resource
• rhcs_cluster_rosa_hcp resource
• ROSA HCP upgrading (Red Hat docs)
• Module: terraform-redhat/rosa-hcp/rhcs