📖 Documentation Update to Creating a ROSA HCP cluster directions by tinaafitz · Pull Request #5920 · kubernetes-sigs/cluster-api-provider-aws

tinaafitz · 2026-03-31T17:07:29Z

/kind documentation

Simplify and reorganize the ROSA HCP "Creating a cluster" documentation
Add Prerequisites section with links to the Quick Start Guide and ROSA Setup guide
Separate Authentication and Permissions into distinct sections for clarity
Remove deprecated SSO offline token authentication and migration instructions
Minor wording fixes

k8s-ci-robot · 2026-03-31T17:07:33Z

Adding the "do-not-merge/release-note-label-needed" label because no release-note block was detected, please follow our release note process to remove it.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

k8s-ci-robot · 2026-03-31T17:07:41Z

Hi @tinaafitz. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Tip

We noticed you've done this a few times! Consider joining the org to skip this step and gain /lgtm and other bot rights. We recommend asking approvers on your previous PRs to sponsor you.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

…recent changes.

…ong with examples for each.

serngawy · 2026-04-01T19:45:45Z

+
+## Authentication
+The CAPA controller requires service account credentials to provision ROSA HCP clusters.  
+If you already have a service account, you can skip these steps.


Suggested change

If you already have a service account, you can skip these steps.

**Note:** If you already have a service account, you can skip these steps.

serngawy · 2026-04-01T19:53:20Z

+      rosaClusterName: rosa-hcp-1
+      domainPrefix: rosa-hcp
+      rosaRoleConfigRef:
+        name: role-config


Suggested change

name: role-config

name: role-config # reference to the ROSARoleConfig created above

serngawy · 2026-04-01T19:53:41Z

+      version: "4.19.0"
+      region: "us-west-2"
+      rosaNetworkRef:
+        name: "rosa-vpc"


Suggested change

name: "rosa-vpc"

name: "rosa-vpc" # reference to the ROSANetwork created above

… and deletion steps - Bold the service account skip note - Add full resource headers (apiVersion, kind, metadata, spec) to ROSARoleConfig and ROSANetwork status examples - Add inline comments to rosaRoleConfigRef and rosaNetworkRef for clarity - Add example for creating an additional ROSAMachinePool (workers-extra) - Add section for deleting a ROSA HCP cluster and cleaning up resources

serngawy · 2026-04-07T17:52:45Z

+1. Extract the OIDC provider from the management cluster and set your AWS account ID:
+
+    ```shell
+    export OIDC_PROVIDER=$(kubectl get authentication.config.openshift.io cluster -ojson | jq -r .spec.serviceAccountIssuer | sed 's/https:\/\///')


This is only for Openshift not kubernetes in general

serngawy · 2026-04-07T18:18:47Z

@@ -0,0 +1,86 @@
+# Specifying the IAM Role for ROSA HCP Management Components
+
+When using a management cluster (kind or minikube) with CAPI and CAPA installed, you can configure the CAPA controller to use IAM roles instead of storing AWS credentials. This uses OIDC federation to allow the CAPA controller service account to assume an IAM role.


lets mentioned that a rosa-hcp is the management cluster or any cluster created using aws credential

- Add IAM Role Configuration section linking to specify-management-iam-role doc - Reorder prerequisites: ROSA setup first, management cluster second - Fix Authentication section formatting and numbering - Add new specify-management-iam-role doc with step-by-step IAM role setup instructions

- Add ROSA and MachinePool feature gate requirements before clusterctl init - Add note about rosa-creds-secret namespace matching resource namespace - Add note about ROSARoleConfig prefix max length (4 characters) - Update OpenShift version from 4.19.0 to 4.20.11 with version check hint - Update Cluster and MachinePool API version from v1beta1 to v1beta2

…nces - Fix Markdown rendering issues: add blank lines to separate code blocks, notes, and section headings within list items - Remove YAML document separators (---) that were being interpreted as Markdown thematic breaks, breaking code block rendering - Move AWSClusterControllerIdentity to its own step before cluster creation - Remove separate identityRef/multi-tenancy step (identity now created upfront) - Remove IAM Role Configuration section - Add namespace: "capa-system" to ROSARoleConfig and ROSANetwork examples and their expected status output

serngawy · 2026-04-15T19:37:59Z

/ok-to-test

k8s-ci-robot · 2026-04-15T19:48:29Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign serngawy for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

docs/book/src/topics/rosa/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

tinaafitz · 2026-04-15T20:10:17Z

/retest

serngawy · 2026-04-17T13:30:47Z

+  --policy-arn arn:aws:iam::aws:policy/AmazonVPCFullAccess
+```
+
+## Annotate the Service Account


Before this step we assume the CAPA and CAPI are been installed. Better to show the steps using clusterctl and clusterawsadm to initialize CAPI/CAPA as below

# kubeconfig is pointing to the same cluster we retrieved the OIDC_PROVIDER from export EXP_ROSA=true export EXP_MACHINE_POOL=true # Not sure; if we set the env variable the capa deployment and serviceAccount will be annotated. export AWS_CONTROLLER_IAM_ROLE=$(aws iam get-role --role-name=capa-manager-role --query Role.Arn --output text) clusterctl init --infrastructure aws

andclt · 2026-04-17T14:05:52Z

+      oidcProviderType: Managed
+    apiVersion: infrastructure.cluster.x-k8s.io/v1beta2


I believe the --- separator is missing from here

andclt · 2026-04-17T14:08:45Z

-    export OPENSHIFT_VERSION="4.19.0"
+    export OPENSHIFT_VERSION="4.20.11"  # check available versions with: rosa list versions --hosted-cp
    export AWS_REGION="us-west-2"
    export AWS_AVAILABILITY_ZONE="us-west-2a"


we could probably provide the aws sts commands here:

export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text) export AWS_CREATOR_ARN=$(aws sts get-caller-identity --query Arn --output text)

andclt · 2026-04-17T14:11:01Z

+    Save the following to a file named `rosa-role-network.yaml`:
+
+    ```yaml
+    apiVersion: infrastructure.cluster.x-k8s.io/v1beta2


It would be nice that this yaml file and the ones below have the cat <<EOF ... > command so that a user can just copy and paste them

andclt · 2026-04-17T14:13:15Z

+      controlPlaneRef:
+        apiGroup: controlplane.cluster.x-k8s.io
+        kind: ROSAControlPlane
+        name: "rosa-hcp-1-control-plane"


I believe the --- separator is missing from here

andclt · 2026-04-17T14:13:33Z

+    kind: ROSACluster
+    metadata:
+      name: "rosa-hcp-1"
+    spec: {}


I believe the --- separator is missing from here

andclt · 2026-04-17T16:16:46Z

+          infrastructureRef:
+            apiGroup: infrastructure.cluster.x-k8s.io
+            kind: ROSAMachinePool
+            name: "workers-extra"


missing --- separator here

linux-foundation-easycla · 2026-04-21T14:09:36Z

The committers listed above are authorized under a signed CLA.

✅ login: tinaafitz / name: Tina Fitzgerald (0441ae8, 338243d, 3f0c926, 43e7b99, 4dd3520, 5f68101, 9afb9f1, 9dee5e6, f21d69f, f93440a, f989baa)

serngawy

thanks @tinaafitz , looks good

serngawy · 2026-04-22T18:03:08Z

/lgtm

k8s-ci-robot · 2026-04-22T18:03:15Z

LGTM label has been added.

Details

Git tree hash: 314c01c9afd6bd6d11f5faa2212d84bd75bd675e

k8s-ci-robot added kind/documentation Categorizes issue or PR as related to documentation. do-not-merge/release-note-label-needed Indicates that a PR should not merge because it's missing one of the release note labels. labels Mar 31, 2026

k8s-ci-robot requested review from faiq and serngawy March 31, 2026 17:07

k8s-ci-robot added needs-priority cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Mar 31, 2026

tinaafitz force-pushed the create_cluster_doc_fix branch 4 times, most recently from 8f82392 to 818e792 Compare March 31, 2026 18:13

tinaafitz changed the title ~~Draft Documentation - Update Creating a ROSA HCP cluster directions~~ 📖 Draft - Documentation Update to Creating a ROSA HCP cluster directions Mar 31, 2026

serngawy suggested changes Mar 31, 2026

View reviewed changes

Comment thread docs/book/src/topics/rosa/creating-a-cluster.md Outdated

Comment thread docs/book/src/topics/rosa/creating-a-cluster.md

Comment thread docs/book/src/topics/rosa/creating-a-cluster.md

tinaafitz changed the title ~~📖 Draft - Documentation Update to Creating a ROSA HCP cluster directions~~ 📖 Documentation Update to Creating a ROSA HCP cluster directions Mar 31, 2026

tinaafitz added 2 commits April 1, 2026 14:57

Remove SSO Offline token references and update directions to reflect …

43e7b99

…recent changes.

Added explanations of the ROSARoleConfig and ROSNetwork resources, al…

9afb9f1

…ong with examples for each.

tinaafitz force-pushed the create_cluster_doc_fix branch from c6eaab7 to 9afb9f1 Compare April 1, 2026 18:58

serngawy reviewed Apr 1, 2026

View reviewed changes

serngawy suggested changes Apr 2, 2026

View reviewed changes

Comment thread docs/book/src/topics/rosa/creating-a-cluster.md Outdated

Comment thread docs/book/src/topics/rosa/creating-a-cluster.md

Fix deletion section: delete both Cluster and ROSAControlPlane resources

f93440a

serngawy suggested changes Apr 7, 2026

View reviewed changes

serngawy reviewed Apr 7, 2026

View reviewed changes

tinaafitz force-pushed the create_cluster_doc_fix branch 2 times, most recently from d911351 to cc9fec5 Compare April 8, 2026 21:51

tinaafitz force-pushed the create_cluster_doc_fix branch from cc9fec5 to f21d69f Compare April 9, 2026 13:36

tinaafitz added 2 commits April 15, 2026 11:51

Added prereq for management iam doc.

0441ae8

tinaafitz force-pushed the create_cluster_doc_fix branch from ee140cd to 0441ae8 Compare April 15, 2026 16:43

k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Apr 15, 2026

Moved file.

5f68101

serngawy reviewed Apr 17, 2026

View reviewed changes

andclt reviewed Apr 17, 2026

View reviewed changes

k8s-ci-robot added cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. and removed cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Apr 21, 2026

Address PR review feedback for ROSA HCP cluster creation docs

f989baa

tinaafitz force-pushed the create_cluster_doc_fix branch from 731e1ae to f989baa Compare April 21, 2026 14:24

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. and removed cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. labels Apr 21, 2026

Added Quick Start note.

9dee5e6

serngawy approved these changes Apr 22, 2026

View reviewed changes

k8s-ci-robot assigned serngawy Apr 22, 2026

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 22, 2026

	If you already have a service account, you can skip these steps.
	Note: If you already have a service account, you can skip these steps.

	name: role-config
	name: role-config # reference to the ROSARoleConfig created above

	name: "rosa-vpc"
	name: "rosa-vpc" # reference to the ROSANetwork created above

		@@ -0,0 +1,86 @@
		# Specifying the IAM Role for ROSA HCP Management Components

		When using a management cluster (kind or minikube) with CAPI and CAPA installed, you can configure the CAPA controller to use IAM roles instead of storing AWS credentials. This uses OIDC federation to allow the CAPA controller service account to assume an IAM role.

		oidcProviderType: Managed
		apiVersion: infrastructure.cluster.x-k8s.io/v1beta2

Conversation

tinaafitz commented Mar 31, 2026

Uh oh!

k8s-ci-robot commented Mar 31, 2026

Uh oh!

k8s-ci-robot commented Mar 31, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

serngawy commented Apr 15, 2026

Uh oh!

k8s-ci-robot commented Apr 15, 2026

Uh oh!

tinaafitz commented Apr 15, 2026

Uh oh!

serngawy Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

linux-foundation-easycla Bot commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

serngawy left a comment

Choose a reason for hiding this comment

Uh oh!

serngawy commented Apr 22, 2026

Uh oh!

k8s-ci-robot commented Apr 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

serngawy Apr 17, 2026 •

edited

Loading

linux-foundation-easycla Bot commented Apr 21, 2026 •

edited

Loading