📖 Document EKS cross-account role assumption with IRSA

[lmilbaum]

What type of PR is this?

/kind documentation

What this PR does / why we need it:

• Existing multitenancy documentation was outdated and difficult to discover.
• This adds an EKS guide for IRSA-based cross-account role assumption.
• It documents the IAM trust chain, CAPA identities, and AWSManagedControlPlane.identityRef.

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
Fixes #2105

Special notes for your reviewer:
In response to the review feedback asking for validation of the documented workflow, I added a local test that validates the parts of the documentation we can verify without access to AWS accounts.

The test validates that:

• The documented CAPA configuration is consistent with the current CAPA API types.
• The referenced fields and identity configuration are valid and represented in the CAPA manifests.
• The management-account and workload-account configuration described in the guide remains internally consistent with the implementation.
• Changes to CAPA APIs or manifests that make the documented configuration stale or invalid can be detected locally.

The test is intentionally self-contained and requires no AWS credentials or AWS accounts, so it can run locally and in CI without provisioning cloud resources.

There is an important limitation: this test validates the documentation contract against the CAPA codebase, not the actual AWS behavior. It does not prove that cross-account IAM role assumption or IRSA works end to end between two real AWS accounts.

Full validation of the cross-account IAM/IRSA flow still requires testing the documented procedure against real AWS infrastructure.

AI Usage:

Codex

Checklist:

• squashed commits
• includes documentation
• includes AI generated content
• includes emoji in title
• adds unit tests
• adds or updates e2e tests

Release note:

Added EKS documentation for cross-account role assumption using IRSA. There is no user action required. And the link to the new guild is - docs/book/src/topics/eks/cross-account-role-assumption.md

[kubernetes-prow]

[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 fabriziopandini 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:

• OWNERS

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

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: lmilbaum / name: Liora Milbaum (de21d4a)

[kubernetes-prow]

Welcome @lmilbaum!

It looks like this is your first PR to kubernetes-sigs/cluster-api-provider-aws 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/cluster-api-provider-aws has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[kubernetes-prow]

Hi @lmilbaum. 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.

Regular contributors should join the org to skip this step.

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.

[lmilbaum]

/label release-note-none

[kubernetes-prow]

@lmilbaum: The label(s) /label release-note-none cannot be applied. These labels are supported: api-review, tide/merge-method-merge, tide/merge-method-rebase, tide/merge-method-squash, team/katacoda, refactor, ci-short, ci-extended, ci-full. Is this label configured under labels -> additional_labels or labels -> restricted_labels in plugin.yaml?

Details

In response to this:

/label release-note-none

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.

[lmilbaum]

/label hold

[kubernetes-prow]

@lmilbaum: The label(s) /label hold cannot be applied. These labels are supported: api-review, tide/merge-method-merge, tide/merge-method-rebase, tide/merge-method-squash, team/katacoda, refactor, ci-short, ci-extended, ci-full. Is this label configured under labels -> additional_labels or labels -> restricted_labels in plugin.yaml?

Details

In response to this:

/label hold

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.

[richardcase]

/ok-to-test

[richardcase]

I think this looks good @lmilbaum .

I'm off on holiday tomorrow so i won't be able to test it until September. If we could get someone to follow the instructions and confirm they work that would be great.