Merge pull request #100935 from openshift-cherrypick-robot/cherry-pick-100445-to-enterprise-4.20

[enterprise-4.20] OSDOCS-14809: Capacity Reservations in ROSA HCP

Author: jneczypor

modules/creating-a-machine-pool-cli-capres.adoc

@@ -0,0 +1,124 @@
+// Module included in the following assemblies:
+//
+// * rosa_cluster_admin/rosa_nodes/rosa-managing-worker-nodes.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="creating_machine_pools_cli_capres_{context}"]
+= Creating a machine pool with Capacity Reservations using the {rosa-cli}
+
+You can create a new machine pool with Capacity Reservations by using the {rosa-cli-first}. Both On-Demand Capacity Reservations and Capacity Blocks for ML are supported.
+
+[NOTE]
+====
+Currently, upgrading machine pools and enabling autoscaling is not suppored on machine pools with Capacity Reservations.
+====
+
+.Prerequisites
+
+* You installed and configured the {rosa-cli} version 1.2.57 or above.
+* You logged in to your Red{nbsp}Hat account using the {rosa-cli}.
+* You created a {product-title} cluster version 4.19 or above.
+* The cluster already has a machine pool that is not using a Capacity Reservation or taints. The machine pool must have at least 2 worker nodes.
+* You have a Capacity Reservation ID and capacity is reserved for the instance type required in the Availability Zone (AZ) of the machine pool that you are creating.
+
+.Procedure
+
+* Create the machine pool and define the instance type, worker node count, and Capacity Reservation ID by running the following command:
++
+--
+[source,terminal]
+----
+$ rosa create machinepool --cluster=<cluster-name> \
+                          --name=<machine_pool_id> \
+                          --replicas=<replica_count> \
+                          --capacity-reservation-id cr-<capacity_reservation_id> \
+                          --instance-type=<instance_type> \
+                          --subnet <subnet_id>
+----
+
+where:
+
+*<machine_pool_id>*:: Specifies the name of the machine pool.
+*<replica_count>*:: Specifies the number of provisioned compute nodes. If you deploy {product-title} using a single AZ, this defines the number of compute nodes provisioned to the machine pool for the AZ. If you deploy your cluster using multiple AZs, this defines the total number of compute nodes provisioned across all AZs. For multi-zone clusters, the compute node count must be a multiple of 3. The `--replicas` argument is required when autoscaling is not configured.
+*cr-<capacity_reservation_id>*:: Specifies the reservation ID. You get an ID in the `cr-<capacity_reservation_id>` format when you purchase a Capacity Reservation from AWS. The ID can be for both On-Demand Capacity Reservations or Capacity Blocks for ML, you do not need to specify the reservation type.
+*<instance_type>*:: *Optional*: Specifies the instance type for the compute nodes in your machine pool. The instance type defines the vCPU and memory allocation for each compute node in the pool. Replace `<instance_type>` with an instance type. The default is `m5.xlarge`. You cannot change the instance type for a machine pool after the pool is created.
+*<subnet_id>*:: *Optional*: Specifies the subnet ID. For Bring Your Own Virtual Private Cloud (BYO VPC) clusters, you can select a subnet to create a single-AZ machine pool. If you select a subnet that was not specified during the initial cluster creation, you must tag the subnet with the `kubernetes.io/cluster/<infra-id>` key and `shared` value. Customers can obtain the Infra ID by running the following command:
++
+[source,terminal]
+----
+$ rosa describe cluster --cluster <cluster_name>|grep "Infra ID:"
+----
++
+.Example output
+[source,terminal]
+----
+Infra ID:                   mycluster-xqvj7
+----
+--
+
+.Example
+
+The following example creates a machine pool called `mymachinepool` that uses the `c5.xlarge` instance type and has 1 compute node replica. The example also adds a Capacity Reservation ID. Example input and output:
+
+[source,terminal]
+----
+$ rosa create machinepool --cluster=mycluster --name=mymachinepool --replicas 1 --capacity-reservation-id <capacity_reservation_id> --subnet <subnet_id> --instance-type c5.xlarge
+----
+
+[source,terminal]
+----
+I: Checking available instance types for machine pool 'mymachinepool'
+I: Machine pool 'mymachinepool' created successfully on hosted cluster 'mycluster'
+----
+
+.Verification
+
+You can list all machine pools on your cluster or describe individual machine pools.
+
+* List the available machine pools on your cluster by running the following command:
++
+[source,terminal]
+----
+$ rosa list machinepools --cluster <cluster_name>
+----
+
+* Describe the information of a specific machine pool in your cluster by running the following command.
++
+[source,terminal]
+----
+$ rosa describe machinepool --cluster <cluster_name> --machinepool <machine_pool_name>
+----
++
+.Example output
+[source,terminal]
+----
+ID:                         <machine_pool_name>
+Cluster ID:                 <cluster-id>
+Autoscaling:                No
+Desired replicas:           1
+Current replicas:           1
+Instance type:              c5.xlarge
+Labels:
+Tags:                       red-hat-managed=true, api.openshift.com/environment=production, api.openshift.com/id=<cluster_name>, api.openshift.com/legal-entity-id=<legal_entity_id>, api.openshift.com/name=<cluster_name>, api.openshift.com/nodepool-hypershift=<cluster_name>-<machine_pool_name>, api.openshift.com/nodepool-ocm=<machine_pool_name>, red-hat-clustertype=rosa
+Taints:
+Availability zone:          us-east-1a
+Subnet:                     <subnet-id>
+Disk Size:                  300 GiB
+Version:                    4.19.10
+EC2 Metadata Http Tokens:   optional
+Autorepair:                 Yes
+Tuning configs:
+Kubelet configs:
+Additional security group IDs:
+Node drain grace period:
+Capacity Reservation:
+    - ID:                   <capacity-reservation-id>
+    - Type:                 OnDemand
+Management upgrade:
+    - Type:                 Replace
+    - Max surge:            1
+    - Max unavailable:      0
+Message:                    Minimum availability requires 1 replicas, current 1 available
+----
++
+The output should include the Capacity Reservation ID and type.

modules/creating-a-machine-pool-cli.adoc

@@ -4,10 +4,16 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="creating_machine_pools_cli_{context}"]
-= Creating a machine pool using the ROSA CLI
+= Creating a machine pool using the {rosa-cli}
 
 You can create additional machine pools for your {product-title} cluster by using the {rosa-cli-first}.
 
+[NOTE]
+====
+To add a pre-purchased Capacity Reservation to a machine pool, see link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_on_aws/4/html-single/cluster_administration/index#creating_machine_pools_cli_rosa-managing-worker-nodes[Creating a machine pool with Capacity Reservations].
+====
+//Commenting out the not-yet-published link that breaks the build: https://docs.redhat.com/en/documentation/red_hat_openshift_service_on_aws/4/html-single/cluster_administration/index#creating_machine_pools_cli_capres_rosa-managing-worker-nodes Will have to add it here after the new Cap Res module is merged and published.
+
 .Prerequisites
 
 * You installed and configured the latest {rosa-cli} on your workstation.

modules/rosa-create-objects.adoc

@@ -853,6 +853,11 @@ $ rosa create machinepool --cluster=<cluster_name> | <cluster_id> --replicas=<nu
 |--additional-security-group-ids <sec_group_id>
 |The identifier of one or more additional security groups to use along with the default security groups for this machine pool. For more information on additional security groups, see the requirements for _Security groups_ under _Additional resources_.
 
+ifdef::openshift-rosa-hcp[]
+|--capacity-reservation-id
+|The ID of a pre-purchased AWS Capacity Reservation.
+endif::openshift-rosa-hcp[]
+
 a|--cluster <cluster_name>\|<cluster_id>
 |Required: The name or ID of the cluster to which the machine pool will be added.
 

modules/rosa-release-notes-Q4-2025.adoc

@@ -8,6 +8,8 @@
 * **New version of {product-title} available.** {product-title} version 4.20 is now available for new clusters.
 
 ifdef::openshift-rosa-hcp[]
+* ** On-Demand Capacity Reservations and Capacity Blocks for ML now supported.** You can now use pre-purchased Capacity Reservations when creating new machine pools on {product-title} clusters. For more information, see link:https://docs.redhat.com/documentation/red_hat_openshift_service_on_aws/4/html-single/cluster_administration/index#rosa-managing-worker-nodes[Managing compute nodes].
+
 * ** ImageDigestMirrorSets (IDMS) now supported.**
 {product-title} now supports ImageDigestMirrorSets (IDMS), enabling clusters to redirect image pulls to a private, mirrored registry. This critical enhancement means customers in air-gapped or restricted networks can host their own mirrors for third-party images while satisfying strict security and compliance requirements. For more information, see link:https://docs.redhat.com/en/documentation/red_hat_openshift_service_on_aws/4/html-single/images/index#images-registry-mirroring_image-configuration-hcp[Image registry mirroring for {product-title}].
 

rosa_cluster_admin/rosa_nodes/rosa-managing-worker-nodes.adoc

@@ -11,9 +11,37 @@ The majority of changes for compute nodes are configured on machine pools. A mac
 
 You can edit machine pool configuration options such as scaling, adding node labels, and adding taints.
 
+ifdef::openshift-rosa-hcp[]
+You can also create new machine pools with Capacity Reservations.
+
+.Overview of AWS Capacity Reservations
+
+If you have reserved compute capacity using link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/capacity-reservation-overview.html[AWS Capacity Reservations] for a specific instance type and Availability Zone (AZ), you can use it for your {product-title} worker nodes. Both On-Demand Capacity Reservations and Capacity Blocks for machine learning (ML) workloads are supported.
+
+Purchase and manage a Capacity Reservation directly with AWS. After reserving the capacity, add a Capacity Reservation ID to a new machine pool when you create it in your {product-title} cluster. You can also use a Capacity Reservation shared with you from another AWS account within your AWS Organization.
+
+Once you configure Capacity Reservations in {product-title}, you can use your AWS account to monitor reserved capacity usage across all workloads in the account.
+
+Using Capacity Reservations on machine pools in {product-title} clusters has the following prerequisites and limitations:
+
+* You have installed the {rosa-cli} version 1.2.57 or above.
+* Your {product-title} cluster is version 4.19 or later.
+* The cluster already has a machine pool that is not using a Capacity Reservation or taints. The machine pool must have at least 2 worker nodes.
+* You have purchased a Capacity Reservation for the instance type required in the AZ of the machine pool that you are creating.
+* You can only add a Capacity Reservation ID to a new machine pool.
+* You cannot use autoscaling on a machine pool with configured Capacity Reservations.
+* You cannot upgrade a machine pool with configured Capacity Reservations.
+
+To create a machine pool with a Capacity Reservation, see xref:../../rosa_cluster_admin/rosa_nodes/rosa-managing-worker-nodes.adoc#creating_machine_pools_cli_capres_rosa-managing-worker-nodes[Creating a machine pool with Capacity Reservations using the {rosa-cli}].
+endif::openshift-rosa-hcp[]
+
 include::modules/creating-a-machine-pool.adoc[leveloffset=+1]
 include::modules/creating-a-machine-pool-ocm.adoc[leveloffset=+2]
 include::modules/creating-a-machine-pool-cli.adoc[leveloffset=+2]
+//OSDOCS-14809: Adding a separate module about Capacity Reservations. This might be a temporary solution since this module largely reuses content from modules/creating-a-machine-pool-cli.adoc. We might consider restructuring content from these 2 modules to meet ContentX and DITA migration goals.
+ifdef::openshift-rosa-hcp[]
+include::modules/creating-a-machine-pool-cli-capres.adoc[leveloffset=+2]
+endif::openshift-rosa-hcp[]
 
 // TODO: This additional resource can be added back once all of the files are added to the ROSA HCP distro.
 ifndef::openshift-rosa-hcp[]
@@ -30,7 +58,7 @@ include::modules/configuring-machine-pool-disk-volume-cli.adoc[leveloffset=+2]
 ifndef::openshift-rosa-hcp[]
 [role="_additional-resources"]
 .Additional resources
-* For a detailed list of the arguments that are available for the `rosa create machinepool` subcommand, see xref:../../cli_reference/rosa_cli/rosa-manage-objects-cli.adoc#rosa-managing-objects-cli[Managing objects with the ROSA CLI].
+* For a detailed list of the arguments that are available for the `rosa create machinepool` subcommand, see xref:../../cli_reference/rosa_cli/rosa-manage-objects-cli.adoc#rosa-managing-objects-cli[Managing objects with the {rosa-cli}].
 endif::openshift-rosa-hcp[]
 
 include::modules/deleting-machine-pools.adoc[leveloffset=+1]