Skip to content

Commit 5859f98

Browse files
EricPonvelleEricPonvelle
authored
Merge pull request #110935 from EricPonvelle/OSDOCS-18308_AutoNode-ROSA
OSDOCS-18308: Created Autonode documentation for ROSA
2 parents 2e70b96 + cbf0090 commit 5859f98

14 files changed

Lines changed: 501 additions & 6 deletions

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,5 @@ commercial_package
2020
!.vale/templates
2121
!.vale/config/vocabularies
2222

23+
# Agent workspace
24+
.agent_workspace/

‎_attributes/attributes-openshift-dedicated.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@
3535
:sts-short: STS
3636
:insights-operator: Insights Operator
3737
:red-hat-lightspeed: Red{nbsp}Hat Lightspeed
38+
:autonode: Red{nbsp}Hat build of Karpenter
3839
//logging
3940
:logging-title: logging for Red Hat OpenShift
4041
:logging-title-uc: Logging for Red Hat OpenShift

‎_topic_maps/_topic_map_rosa_hcp.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -458,6 +458,7 @@ Topics:
458458
File: rosa-cluster-autoscaling-hcp
459459
- Name: Managing compute nodes using machine pools
460460
Dir: rosa_nodes
461+
Distro: openshift-rosa-hcp
461462
Topics:
462463
- Name: About machine pools
463464
File: rosa-nodes-machinepools-about
@@ -470,6 +471,8 @@ Topics:
470471
File: rosa-nodes-about-autoscaling-nodes
471472
- Name: Configuring cluster memory to meet container memory and risk requirements
472473
File: nodes-cluster-resource-configure
474+
- Name: Managing compute nodes using Red Hat build of Karpenter
475+
File: rosa-nodes-managing-karpenter
473476
- Name: Configuring PID limits
474477
File: rosa-configuring-pid-limits
475478
- Name: Managing multi-architecture clusters

‎modules/rosa-hcp-upgrade-options.adoc‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,23 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * upgrading/rosa-hcp-upgrading.adoc
4+
15
:_mod-docs-content-type: CONCEPT
26
[id="rosa-upgrade-options_{context}"]
3-
= Update options for {product-title} clusters
7+
= Update options for {product-title} clusters configured with {autonode}
48

59
[role="_abstract"]
6-
You can control the impact of updates to your workload by controlling which parts of the cluster are updated, for example:
10+
You can control the impact of updates to your workload by controlling which parts of the cluster are updated.
711

8-
Update only the hosted control plane:: This initiates update of the hosted control plane. It does not impact your worker nodes.
12+
Update only the hosted control plane:: This initiates update of the hosted control plane. When the cluster is not configured with {autonode}, it does not impact your worker nodes. When the cluster is configured with {autonode}, worker nodes that are part of the default `EC2NodeClass` resource managed by Karpenter are updated along with the {hcp}.
913

1014
Update nodes in a machine pool:: {product-title} machine pool updates are designed to fully replace each node in a machine pool during the update process. This provides additional security and stability benefits over performing an in-place update. Updating the nodes in a machine pool initiates a rolling replacement of nodes in the specified machine pool, and temporarily impacts the worker nodes on that machine pool. You can also update multiple machine pools concurrently.
1115

16+
Update nodes in a Karpenter-managed `EC2NodeClass`:: When {autonode} is enabled, `OpenshiftEC2NodeClass` resource created in the cluster can be upgraded.
17+
1218
[IMPORTANT]
1319
====
14-
You cannot update the hosted control plane at the same time as any machine pool update. You will need to update the hosted control plane first, and then update machine pools.
20+
You cannot update the hosted control plane at the same time as any machine pool update. You must update the hosted control plane first, and then update machine pools.
1521
====
1622

1723
[IMPORTANT]

‎modules/rosa-hcp-upgrading-autonode-clusters.adoc‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * upgrading/rosa-hcp-upgrading.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="rosa-nodes-autonode-upgrading-autonode_{context}"]
7+
= Understanding upgrades for {product-title} clusters configured with {autonode}
8+
9+
[role="_abstract"]
10+
You can upgrade clusters that are configured with {autonode}.
11+
12+
[id="rosa-nodes-autonode-upgrading-autonode-openshiftec2nodeclass_{context}"]
13+
*Default `OpenshiftEC2NodeClass`*
14+
15+
When you enable {autonode}, a default `OpenshiftEC2NodeClass` resource is created with the same version as that of the hosted control plane. All node pools that reference the default `EC2NodeClass` are automatically upgraded as part of the hosted control plane upgrade.
16+
17+
[id="rosa-nodes-autonode-upgrading-autonode-secondary-openshiftec2nodeclass_{context}"]
18+
*Optional `OpenshiftEC2NodeClass`*
19+
20+
Upgrade behavior depends on whether or not the `OpenshiftEC2NodeClass` is pinned to a version by using the `spec.version` field.
21+
22+
Unpinned `OpenshiftEC2NodeClass`:: By default, `OpenshiftEC2NodeClass` resources have the same version of the hosted control plane. When the hosted control plane is upgraded, unpinned `OpenshiftEC2NodeClass` resources are automatically upgraded.
23+
24+
Pinned `OpenshiftEC2NodeClass`:: In the `OpenshiftEC2NodeClass` resource, you can specify a valid {ocp-short} version in `spec.version`. Specifying this version pins the cluster's node pools to a specific version. Any pinned `OpenshiftEC2NodeClass` resources are not upgraded as part of the hosted control plane upgrade. You can update the `spec.version` of pinned `OpenshiftEC2NodeClass` resources to a valid version. Updating this `spec.version` field initiates the upgrade of all of the node pools that reference its corresponding `OpenshiftEC2NodeClass` resource.

‎modules/rosa-nodes-autonode-about.adoc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * rosa_cluster_admin/rosa-nodes-managing-karpenter.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="rosa-nodes-autonode-about_{context}"]
7+
= About {autonode}
8+
9+
[role="_abstract"]
10+
{autonode} builds on the open source Karpenter project and provides automatic node provisioning for {product-title} clusters. Karpenter watches for pods that the Kubernetes scheduler marks as unschedulable and evaluates their scheduling constraints, including resource requests, node selectors, affinities, tolerations, and topology spread constraints. Karpenter then provisions nodes that meet the specific requirements of those waiting pods.
11+
12+
Karpenter improves cluster efficiency by provisioning nodes that match workload requirements instead of requiring pre-configured node pools. When nodes are no longer needed, Karpenter removes them to reduce costs. For more information about Karpenter capabilities and architecture, see _Karpenter project documentation_ in the Additional resources.

‎modules/rosa-nodes-autonode-managing-create-nodepool.adoc‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * rosa_cluster_admin/rosa-nodes-managing-karpenter.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="rosa-nodes-autonode-managing-nodepool_{context}"]
7+
= Create a node pool
8+
9+
[role="_abstract"]
10+
Create a node pool to define the compute capacity that {autonode} can provision.
11+
12+
.Procedure
13+
14+
. Create a node pool manifest:
15+
+
16+
[source,terminal]
17+
----
18+
$ cat > nodepool.yaml <<'EOF'
19+
apiVersion: karpenter.sh/v1
20+
kind: NodePool
21+
metadata:
22+
name: default-np
23+
spec:
24+
template:
25+
metadata:
26+
labels:
27+
autonode: "true"
28+
spec:
29+
requirements:
30+
- key: node.kubernetes.io/instance-type
31+
operator: In
32+
values:
33+
- c5.xlarge
34+
- key: karpenter.sh/capacity-type
35+
operator: In
36+
values: ["on-demand"]
37+
nodeClassRef:
38+
group: karpenter.k8s.aws
39+
kind: EC2NodeClass
40+
name: default
41+
EOF
42+
----
43+
where:
44+
`nodeClassRef.kind`::
45+
Required field that must use the `EC2NodeClass` type.
46+
`spec.labels`::
47+
Optional field that you can use to place pods by using labels.
48+
+
49+
[NOTE]
50+
====
51+
For a list of all requirements available under `spec.requirements`, see the _Additional resources_.
52+
====
53+
54+
. Apply the node pool:
55+
+
56+
[source,terminal]
57+
----
58+
$ oc apply -f nodepool.yaml
59+
----
60+
61+
. Verify the node pool is ready:
62+
+
63+
[source,terminal]
64+
----
65+
$ oc get nodepool
66+
----
67+
+
68+
*Example output*
69+
+
70+
[source,terminal]
71+
----
72+
NAME NODECLASS NODES READY AGE
73+
default-np default 0 True 3s
74+
----

‎modules/rosa-nodes-autonode-managing-enable-cli.adoc‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * rosa_cluster_admin/rosa-nodes-managing-karpenter.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="rosa-nodes-autonode-managing-enable-cli_{context}"]
7+
= Enable {autonode} using {rosa-cli}
8+
9+
[role="_abstract"]
10+
Enable {autonode} on your cluster by using {rosa-cli-first} after it finishes installing.
11+
12+
.Procedure
13+
14+
. Export your cluster name and ID to environment variables:
15+
+
16+
[source,terminal,subs="+quotes"]
17+
----
18+
$ export CLUSTER_NAME=<cluster_name>
19+
$ export CLUSTER_ID=$(rosa describe cluster -c "$CLUSTER_NAME" -o json | jq -r '.id')
20+
$ echo $CLUSTER_NAME $CLUSTER_ID
21+
----
22+
23+
. Wait for the cluster to become ready:
24+
+
25+
[source,terminal]
26+
----
27+
$ rosa describe cluster -c $CLUSTER_ID | grep -i State
28+
----
29+
+
30+
*Example output*
31+
+
32+
[source,terminal]
33+
----
34+
State: ready
35+
----
36+
37+
. Ensure that your {autonode} IAM role is correctly set:
38+
+
39+
[source,terminal]
40+
----
41+
$ ROLE_ARN=$(aws iam get-role --role-name rosa-karpenter-controller-role-${CLUSTER_NAME} --query 'Role.Arn' --output text)
42+
----
43+
44+
. Enable {autonode}:
45+
+
46+
[source,terminal]
47+
----
48+
$ rosa edit cluster -c $CLUSTER_ID \
49+
--autonode=enabled \
50+
--autonode-iam-role-arn=$ROLE_ARN
51+
----
52+
53+
. If you do not already have cluster admin access, create a cluster admin user:
54+
+
55+
[source,terminal]
56+
----
57+
$ rosa create admin -c $CLUSTER_ID
58+
----
59+
60+
. Log in to the cluster using the credentials from the previous command:
61+
+
62+
[source,terminal]
63+
----
64+
$ oc login <api_url> --username cluster-admin --password <password>
65+
----
66+
67+
. Verify that the {autonode} custom resource definitions (CRDs) are present:
68+
+
69+
[source,terminal]
70+
----
71+
$ oc get ec2nodeclass
72+
----
73+
+
74+
[NOTE]
75+
====
76+
The node pool manifest uses the `EC2NodeClass` resource.
77+
====
78+
+
79+
*Example output*
80+
+
81+
[source,terminal]
82+
----
83+
NAME READY AGE
84+
default True 5m
85+
----
86+
+
87+
[source,terminal]
88+
----
89+
$ oc get openshiftec2nodeclass
90+
----
91+
+
92+
[NOTE]
93+
====
94+
The `OpenShiftEC2NodeClass` resource is Red{nbsp}Hat's wrapper to communicate with the `EC2NodeClass` resource.
95+
====
96+
+
97+
*Example output*
98+
+
99+
[source,terminal]
100+
----
101+
NAME READY
102+
default True
103+
----

‎modules/rosa-nodes-autonode-managing-enable-ui.adoc‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * rosa_cluster_admin/rosa-nodes-managing-karpenter.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="rosa-nodes-autonode-managing-enable-ui_{context}"]
7+
= Enable {autonode} using {cluster-manager}
8+
9+
[role="_abstract"]
10+
Enable {autonode} on your cluster by using {cluster-manager} after it finishes installing.
11+
12+
.Prerequisites
13+
* You have created a {product-title} cluster, version 4.22.0 or later.
14+
* You have created an AWS Identity and Access Management (IAM) role to be configured for {autonode}.
15+
* You have your cluster's Open ID Connect (OIDC) Endpoint URL.
16+
+
17+
[NOTE]
18+
====
19+
Run `rosa describe cluster -c $CLUSTER_NAME | grep "OIDC Endpoint URL"` to see this URL. Do not include the `https://` prefix from the OIDC Endpoint URL. For example, use `example-oidc-endpoint.cloudfront.net/abcd1234examplehash5678` instead of `https://example-oidc-endpoint.cloudfront.net/abcd1234examplehash5678`.
20+
====
21+
* You have the proper credentials to access the AWS console.
22+
23+
24+
.Procedure
25+
26+
. Export your AWS ID:
27+
+
28+
[source,terminal]
29+
----
30+
$ export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
31+
----
32+
33+
. Log in to the link:https://console.aws.amazon.com/[AWS console].
34+
. In the AWS console, navigate to **IAM > Roles**.
35+
. On your {autonode} Amazon Resource Name (ARN), update the trust policy to include the following policy specifications:
36+
+
37+
[NOTE]
38+
====
39+
To access this ARN, run:
40+
41+
[source,terminal]
42+
----
43+
$ echo $ROLE_ARN
44+
----
45+
====
46+
+
47+
[source,json]
48+
----
49+
{
50+
"Version": "2012-10-17",
51+
"Statement": [
52+
{
53+
"Effect": "Allow",
54+
"Principal": {
55+
"Federated": "arn:aws:iam::<aws_account_id>:oidc-provider/<oidc-endpoint-url>"
56+
},
57+
"Action": "sts:AssumeRoleWithWebIdentity",
58+
"Condition": {
59+
"StringEquals": {
60+
"<oidc-endpoint-url>:sub": "system:serviceaccount:kube-system:karpenter"
61+
}
62+
}
63+
}
64+
]
65+
}
66+
----
67+
where:
68+
<aws_account_id>::
69+
Specifies your AWS Account ID.
70+
<oidc-endpoint-url>::
71+
Specifies the OIDC endpoint URL that you acquired.
72+
73+
. In {cluster-manager-url}, select your cluster from the cluster list.
74+
. On the cluster details screen, select the *Edit* button next to the status for {autonode}.
75+
. On the *Edit Autonode settings* dialog box, toggle *Enable Autonode*.
76+
. Add your {autonode} IAM role ARN to the field in this dialog box.
77+
. Select *Save* to save your configurations and close the *Edit Autonode settings* box.

0 commit comments

Comments
 (0)