openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00
Code Issues Releases Activity
Files
38a4669cd6cbc8f670ad4e738f95564d2624fc28
openshift-docs/modules/creating-a-machine-pool-cli.adoc
mletalie 728f635ed5 LB restrictions
2025-01-27 15:21:15 +00:00

293 lines
16 KiB
Plaintext
Raw Blame History

// 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_{context}"]
= Creating a machine pool using the ROSA CLI
You can create additional machine pools for your {product-title} (ROSA) cluster by using the ROSA CLI (`rosa`).
.Prerequisites
* You installed and configured the latest {product-title} (ROSA) CLI, `rosa`, on your workstation.
* You logged in to your Red{nbsp}Hat account using the ROSA CLI (`rosa`).
* You created a ROSA cluster.
.Procedure
* To add a machine pool that does not use autoscaling, create the machine pool and define the instance type, compute (also known as worker) node count, and node labels:
+
--
[source,terminal]
----
$ rosa create machinepool --cluster=<cluster-name> \
--name=<machine_pool_id> \
--replicas=<replica_count> \
--instance-type=<instance_type> \
--labels=<key>=<value>,<key>=<value> \
--taints=<key>=<value>:<effect>,<key>=<value>:<effect> \
ifdef::openshift-rosa[]
--use-spot-instances \
--spot-max-price=<price> \
endif::openshift-rosa[]
--disk-size=<disk_size> \
--availability-zone=<availability_zone_name> \
--additional-security-group-ids <sec_group_id> \
--subnet <subnet_id>
----
where:
`--name=<machine_pool_id>`:: Specifies the name of the machine pool.
`--replicas=<replica_count>`:: Specifies the number of compute nodes to provision. If you deployed ROSA using a single availability zone, this defines the number of compute nodes to provision to the machine pool for the zone. If you deployed your cluster using multiple availability zones, this defines the number of compute nodes to provision in total across all zones and the count must be a multiple of 3. The `--replicas` argument is required when autoscaling is not configured.
`--instance-type=<instance_type>`:: Optional: Sets 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.
`--labels=<key>=<value>,<key>=<value>`:: Optional: Defines the labels for the machine pool. Replace `<key>=<value>,<key>=<value>` with a comma-delimited list of key-value pairs, for example `--labels=key1=value1,key2=value2`.
`--taints=<key>=<value>:<effect>,<key>=<value>:<effect>`:: Optional: Defines the taints for the machine pool. Replace `<key>=<value>:<effect>,<key>=<value>:<effect>` with a key, value, and effect for each taint, for example `--taints=key1=value1:NoSchedule,key2=value2:NoExecute`. Available effects include `NoSchedule`, `PreferNoSchedule`, and `NoExecute`.
ifdef::openshift-rosa[]
`--use-spot-instances`:: Optional: Configures your machine pool to deploy machines as non-guaranteed AWS Spot Instances. For information, see link:https://aws.amazon.com/ec2/spot/[Amazon EC2 Spot Instances] in the AWS documentation. If you select *Use Amazon EC2 Spot Instances* for a machine pool, you cannot disable the option after the machine pool is created.
`--spot-max-price=<price>`:: Optional: If you choose to use Spot Instances, you can specify this argument to define a maximum hourly price for a Spot Instance. If this argument is not specified, the on-demand price is used.
+
[IMPORTANT]
====
Your Amazon EC2 Spot Instances might be interrupted at any time. Use Amazon EC2 Spot Instances only for workloads that can tolerate interruptions.
====
endif::openshift-rosa[]
`--disk-size=<disk_size>`:: Optional: Specifies the worker node disk size. The value can be in GB, GiB, TB, or TiB. Replace `<disk_size>` with a numeric value and unit, for example `--disk-size=200GiB`.
`--availability-zone=<availability_zone_name>`::
ifdef::openshift-rosa-hcp[]
Optional: You can create a machine pool in an availability zone of your choice. Replace `<availability_zone_name>` with an availability zone name.
endif::openshift-rosa-hcp[]
ifdef::openshift-rosa[]
Optional: For Multi-AZ clusters, you can create a machine pool in a Single-AZ of your choice. Replace `<availability_zone_name>` with a Single-AZ name.
+
[NOTE]
====
Multi-AZ clusters retain a Multi-AZ control plane and can have worker machine pools across a Single-AZ or Multi-AZ. Machine pools distribute machines (nodes) evenly across availability zones.
====
+
[WARNING]
====
If you choose a worker machine pool with a Single-AZ, there is no fault tolerance for that machine pool, regardless of machine replica count.
For fault-tolerant worker machine pools, choosing a Multi-AZ machine pool distributes machines in multiples of 3 across availability zones.
* A Multi-AZ machine pool with three availability zones can have a machine count in multiples of 3 only, such as 3, 6, 9, and so on.
* A Single-AZ machine pool with one availability zone can have a machine count in multiples of 1, such as 1, 2, 3, 4, and so on.
====
endif::openshift-rosa[]
`--additional-security-group-ids <sec_group_id>`:: Optional: For machine pools in clusters that do not have Red{nbsp}Hat managed VPCs, you can select additional custom security groups to use in your machine pools. You must have already created the security groups and associated them with the VPC that you selected for this cluster. You cannot add or edit security groups after you create the machine pool.
ifdef::openshift-rosa[]
For more information, see the requirements for security groups in the "Additional resources" section.
endif::openshift-rosa[]
ifdef::openshift-rosa-hcp[]
+
[IMPORTANT]
====
You can use up to ten additional security groups for machine pools on {product-title} clusters.
====
endif::openshift-rosa-hcp[]
`--subnet <subnet_id>`:: Optional: For BYO VPC clusters, you can select a subnet to create a Single-AZ machine pool. If the subnet is out of your cluster creation subnets, there must be a tag with a key `kubernetes.io/cluster/<infra-id>` and value `shared`. Customers can obtain the Infra ID by using the following command:
+
[source,terminal]
----
$ rosa describe cluster -c <cluster name>|grep "Infra ID:"
----
+
.Example output
[source,terminal]
----
Infra ID: mycluster-xqvj7
----
+
[NOTE]
====
You cannot set both `--subnet` and `--availability-zone` at the same time, only 1 is allowed for a Single-AZ machine pool creation.
====
--
+
The following example creates a machine pool called `mymachinepool` that uses the `m5.xlarge` instance type and has 2 compute node replicas. The example also adds 2 workload-specific labels:
+
[source,terminal]
----
$ rosa create machinepool --cluster=mycluster --name=mymachinepool --replicas=2 --instance-type=m5.xlarge --labels=app=db,tier=backend
----
+
.Example output
[source,terminal]
----
I: Machine pool 'mymachinepool' created successfully on cluster 'mycluster'
I: To view all machine pools, run 'rosa list machinepools -c mycluster'
----
* To add a machine pool that uses autoscaling, create the machine pool and define the autoscaling configuration, instance type and node labels:
+
--
[source,terminal]
----
$ rosa create machinepool --cluster=<cluster-name> \
--name=<machine_pool_id> \
--enable-autoscaling \
--min-replicas=<minimum_replica_count> \
--max-replicas=<maximum_replica_count> \
--instance-type=<instance_type> \
--labels=<key>=<value>,<key>=<value> \
--taints=<key>=<value>:<effect>,<key>=<value>:<effect> \
ifdef::openshift-rosa-hcp[]
--availability-zone=<availability_zone_name>
endif::openshift-rosa-hcp[]
ifndef::openshift-rosa-hcp[]
--availability-zone=<availability_zone_name> \
--use-spot-instances \
--spot-max-price=<price>
endif::openshift-rosa-hcp[]
----
where:
`--name=<machine_pool_id>`:: Specifies the name of the machine pool. Replace `<machine_pool_id>` with the name of your machine pool.
`--enable-autoscaling`:: Enables autoscaling in the machine pool to meet the deployment needs.
`--min-replicas=<minimum_replica_count>` and `--max-replicas=<maximum_replica_count>`:: Defines the minimum and maximum compute node limits. The cluster autoscaler does not reduce or increase the machine pool node count beyond the limits that you specify.
ifndef::openshift-rosa-hcp[]
+
If you deployed ROSA using a single availability zone, the `--min-replicas` and `--max-replicas` arguments define the autoscaling limits in the machine pool for the zone. If you deployed your cluster using multiple availability zones, the arguments define the autoscaling limits in total across all zones and the counts must be multiples of 3.
endif::openshift-rosa-hcp[]
ifdef::openshift-rosa-hcp[]
+
The `--min-replicas` and `--max-replicas` arguments define the autoscaling limits in the machine pool for the availability zone.
endif::openshift-rosa-hcp[]
`--instance-type=<instance_type>`:: Optional: Sets 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.
`--labels=<key>=<value>,<key>=<value>`:: Optional: Defines the labels for the machine pool. Replace `<key>=<value>,<key>=<value>` with a comma-delimited list of key-value pairs, for example `--labels=key1=value1,key2=value2`.
`--taints=<key>=<value>:<effect>,<key>=<value>:<effect>`:: Optional: Defines the taints for the machine pool. Replace `<key>=<value>:<effect>,<key>=<value>:<effect>` with a key, value, and effect for each taint, for example `--taints=key1=value1:NoSchedule,key2=value2:NoExecute`. Available effects include `NoSchedule`, `PreferNoSchedule`, and `NoExecute`.
`--availability-zone=<availability_zone_name>`::
ifdef::openshift-rosa[]
Optional: For Multi-AZ clusters, you can create a machine pool in a Single-AZ of your choice. Replace `<availability_zone_name>` with a Single-AZ name.
endif::openshift-rosa[]
ifdef::openshift-rosa-hcp[]
Optional: You can create a machine pool in an availability zone of your choice. Replace `<availability_zone_name>` with an availability zone name.
endif::openshift-rosa-hcp[]
ifdef::openshift-rosa[]
`--use-spot-instances`:: Optional: Configures your machine pool to deploy machines as non-guaranteed AWS Spot Instances. For information, see link:https://aws.amazon.com/ec2/spot/[Amazon EC2 Spot Instances] in the AWS documentation. If you select *Use Amazon EC2 Spot Instances* for a machine pool, you cannot disable the option after the machine pool is created.
+
[IMPORTANT]
====
Your Amazon EC2 Spot Instances might be interrupted at any time. Use Amazon EC2 Spot Instances only for workloads that can tolerate interruptions.
====
`--spot-max-price=<price>`:: Optional: If you choose to use Spot Instances, you can specify this argument to define a maximum hourly price for a Spot Instance. If this argument is not specified, the on-demand price is used.
endif::openshift-rosa[]
--
+
The following example creates a machine pool called `mymachinepool` that uses the `m5.xlarge` instance type and has autoscaling enabled. The minimum compute node limit is 3 and the maximum is 6 overall. The example also adds 2 workload-specific labels:
+
[source,terminal]
----
$ rosa create machinepool --cluster=mycluster --name=mymachinepool --enable-autoscaling --min-replicas=3 --max-replicas=6 --instance-type=m5.xlarge --labels=app=db,tier=backend
----
+
.Example output
[source,terminal]
----
ifndef::openshift-rosa-hcp[]
I: Machine pool 'mymachinepool' created successfully on cluster 'mycluster'
endif::openshift-rosa-hcp[]
ifdef::openshift-rosa-hcp[]
I: Machine pool 'mymachinepool' created successfully on hosted cluster 'mycluster'
endif::openshift-rosa-hcp[]
I: To view all machine pools, run 'rosa list machinepools -c mycluster'
----
//ifdef::openshift-rosa-hcp[] Uncomment this out once HCP split occurs
* To add a Windows License Included enabled machine pool to a {hcp-title} cluster, see link:https://access.redhat.com/articles/7096903[AWS Windows License Included for ROSA with HCP].
+
Windows License Included enabled machine pools can only be created when the following criteria is met:
** The host cluster is a {hcp-title} cluster.
** The instance type is bare metal EC2.
+
[IMPORTANT]
====
AWS Windows License Included for {hcp-title} is a Technology Preview feature only. Technology Preview features are not supported with Red{nbsp}Hat production service level agreements (SLAs) and might not be functionally complete. Red{nbsp}Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
For more information about the support scope of Red{nbsp}Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope].
====
//endif::openshift-rosa-hcp[] Uncomment this out once HCP split occurs
.Verification
You can list all machine pools on your cluster or describe individual machine pools.
. List the available machine pools on your cluster:
+
[source,terminal]
----
$ rosa list machinepools --cluster=<cluster_name>
----
+
ifndef::openshift-rosa-hcp[]
.Example output
[source,terminal]
----
ID AUTOSCALING REPLICAS INSTANCE TYPE LABELS TAINTS AVAILABILITY ZONES SPOT INSTANCES
Default No 3 m5.xlarge us-east-1a, us-east-1b, us-east-1c N/A
mymachinepool Yes 3-6 m5.xlarge app=db, tier=backend us-east-1a, us-east-1b, us-east-1c No
----
endif::openshift-rosa-hcp[]
ifdef::openshift-rosa-hcp[]
.Example output
[source,terminal]
----
ID AUTOSCALING REPLICAS INSTANCE TYPE LABELS TAINTS AVAILABILITY ZONE SUBNET VERSION AUTOREPAIR
Default No 1/1 m5. xlarge us-east-2c subnet-00552ad67728a6ba3 4.14.34 Yes
mymachinepool Yes 3/3-6 m5.xlarge app=db, tier=backend us-east-2a subnet-0cb56f5f41880c413 4.14.34 Yes
----
endif::openshift-rosa-hcp[]
. Describe the information of a specific machine pool in your cluster:
+
[source,terminal]
----
$ rosa describe machinepool --cluster=<cluster_name> --machinepool=mymachinepool
----
+
ifndef::openshift-rosa-hcp[]
.Example output
[source,terminal]
----
ID: mymachinepool
Cluster ID: 27iimopsg1mge0m81l0sqivkne2qu6dr
Autoscaling: Yes
Replicas: 3-6
Instance type: m5.xlarge
Labels: app=db, tier=backend
Taints:
Availability zones: us-east-1a, us-east-1b, us-east-1c
Subnets:
Spot instances: No
Disk size: 300 GiB
Security Group IDs:
----
endif::openshift-rosa-hcp[]
ifdef::openshift-rosa-hcp[]
.Example output
[source,terminal]
----
ID: mymachinepool
Cluster ID: 2d6010rjvg17anri30v84vspf7c7kr6v
Autoscaling: Yes
Desired replicas: 3-6
Current replicas: 3
Instance type: m5.xlarge
Labels: app=db, tier=backend
Taints:
Availability zone: us-east-2a
Subnet: subnet-0cb56f5f41880c413
Version: 4.14.34
Autorepair: Yes
Tuning configs:
Additional security group IDs:
Node drain grace period:
Message:
----
endif::openshift-rosa-hcp[]
. Verify that the machine pool is included in the output and the configuration is as expected.
View Git Blame Copy Permalink