DOC-2297: Cross-account IAM delegation for BYOC on AWS (draft)

modules/get-started/pages/byoc-arch.adoc

@@ -30,6 +30,9 @@ In the Redpanda Cloud UI, you can identify which plane you're in by the side nav
 
 In a BYOC architecture, you deploy the data plane in your own VPC. All network connections into the data plane take place through either a public endpoint, or for private clusters, through Redpanda Cloud network connections such as VPC peering, AWS PrivateLink, Azure Private Link, or GCP Private Service Connect. Customer data never leaves the data plane.
 
+// DOC-2297: forward-reference so readers know the agent flow is not the AWS-new default.
+NOTE: On AWS, new clusters use <<provisioning-models-on-aws,cross-account IAM delegation>>. The agent-based setup described here applies to existing AWS clusters and to clusters on Azure and GCP.
+
 A BYOC cluster is initially set up from the control plane. This is a two-step process performed by `rpk cloud byoc apply`:
 
 . You bootstrap a virtual machine (VM) in your VPC. 
@@ -44,6 +47,33 @@ they have dedicated job queues in the control plane. Agents also manage VPC peer
 +
 image::shared:byoc_apply.png[cloud_byoc_apply]
 
-NOTE: To create a Redpanda cluster in your virtual private cloud (VPC), follow the instructions in the Redpanda Cloud UI. The UI contains the parameters necessary to successfully run `rpk cloud byoc apply` with your cloud provider. 
+NOTE: To create a Redpanda cluster in your virtual private cloud (VPC), follow the instructions in the Redpanda Cloud UI. The UI contains the parameters necessary to successfully run `rpk cloud byoc apply` with your cloud provider.
+
+== Provisioning models on AWS
+
+// DOC-2297: cross-account IAM delegation (ENG-1139), 26.2, AWS only, new clusters only.
+// TODO(team): confirm wording once the deploy workflow (ENG-1129) and external-ID
+// handling (CIAINFRA-3970) are finalized. Do not publish before GA (2026-07-14).
+
+New BYOC clusters on AWS use *cross-account IAM delegation*. Instead of bootstrapping an agent VM in your account, you create an IAM role that Redpanda's control plane assumes to provision and reconcile your cluster. Redpanda runs the deployment for you, so you do not run `rpk cloud byoc aws apply`. This is the recommended model for new AWS clusters, and it lets you review, audit, and revoke Redpanda's access at any time.
+
+[cols="1,2,2", options="header"]
+|===
+| | Cross-account IAM delegation | Agent-based provisioning
+
+| Applies to
+| New BYOC clusters on AWS
+| Existing clusters, and clusters on Azure and GCP
+
+| Who provisions
+| Redpanda's control plane assumes a role you create
+| An agent VM that runs in your account
+
+| How you start it
+| Create a cross-account IAM role, then deploy from the Cloud UI
+| Run `rpk cloud byoc apply`
+|===
+
+Cross-account IAM delegation applies only to new clusters on AWS. Migrating an existing cluster is not supported, and the agent-based model described above continues to apply to existing clusters and to clusters on Azure and GCP. To deploy a new AWS cluster with cross-account IAM delegation, see xref:get-started:cluster-types/byoc/aws/create-byoc-cluster-aws.adoc[Create a BYOC Cluster on AWS]. For the permissions the role grants, see xref:security:authorization/cloud-iam-policies.adoc[AWS IAM policies].
 
 include::get-started:partial$no-access.adoc[]

modules/get-started/pages/cluster-types/byoc/aws/create-byoc-cluster-aws.adoc

@@ -1,35 +1,65 @@
 = Create a BYOC Cluster on AWS
-:description: Use the Redpanda Cloud UI to create a BYOC cluster on AWS.
-:page-aliases: get-started:cluster-types/byoc/create-byoc-cluster-aws.adoc, cloud:create-byoc-cluster-aws.adoc, deploy:deployment-option/cloud/create-byoc-cluster-aws.adoc
+:description: Create a new BYOC cluster on AWS with cross-account IAM delegation, where Redpanda assumes an IAM role you create to provision and manage the cluster.
+:page-aliases: get-started:cluster-types/byoc/create-byoc-cluster-aws.adoc, cloud:create-byoc-cluster-aws.adoc, deploy:deployment-option/cloud/create-byoc-cluster-aws.adoc, get-started:cluster-types/byoc/aws/cross-account-iam-aws.adoc, deploy:deployment-option/cloud/cluster-types/byoc/aws/cross-account-iam-aws.adoc
 
-To create a Redpanda cluster in your virtual private cloud (VPC), follow the instructions in the Redpanda Cloud UI. The UI contains the parameters necessary to successfully run `rpk cloud byoc apply`. See also: xref:get-started:byoc-arch.adoc[BYOC architecture].
+// ============================================================================
+// DOC-2297 DRAFT — new AWS BYOC clusters use cross-account IAM delegation
+// (ENG-1139, targeted 26.2 / 2026-07-14). Blocked on team answers:
+//   TODO(team) 1: exact Cloud UI / deployment wizard steps (ENG-1129).
+//   TODO(team) 2: where customers get the role Terraform, and how it is delivered.
+//   TODO(team) 3: whether the external ID is shown before role creation, and the
+//                 exact step ordering (CIAINFRA-3970).
+//   TODO(team) 4: exact role name and trust policy content.
+//   TODO(team) 5: confirm whether agent-based creation (rpk cloud byoc aws apply)
+//                 is still offered for NEW AWS clusters, or fully replaced.
+// Do not publish until GA and the above are resolved.
+// ============================================================================
 
-NOTE: With standard BYOC clusters, Redpanda manages security policies and resources for your VPC, including subnetworks, service accounts, IAM roles, firewall rules, and storage buckets. For the highest level of security, you can manage these resources yourself with a xref:./vpc-byo-aws.adoc[BYOVPC cluster on AWS].
+New BYOC clusters on AWS use *cross-account IAM delegation*: you create an IAM role in your AWS account, and Redpanda's control plane assumes that role to provision and reconcile your cluster. Redpanda runs the deployment for you, so you do not run `rpk cloud byoc aws apply` or host a provisioning agent in your account. Because you own the role, you can review, audit, and revoke Redpanda's access at any time. See also xref:get-started:byoc-arch.adoc#provisioning-models-on-aws[Provisioning models on AWS].
 
-== Prerequisites
+[NOTE]
+====
+* With standard BYOC clusters, Redpanda manages security policies and resources for your VPC, including subnetworks, service accounts, IAM roles, firewall rules, and storage buckets. For the highest level of security, you can manage these resources yourself with a xref:./vpc-byo-aws.adoc[BYOVPC cluster on AWS].
+* Cross-account IAM delegation applies to *new AWS clusters* only. Migrating an existing cluster is not supported, and existing clusters continue to use the xref:get-started:byoc-arch.adoc#provisioning-models-on-aws[agent-based model]. TODO(team 5): confirm whether agent-based creation is still offered for new AWS clusters.
+====
 
-Before you deploy a BYOC cluster on AWS, check that the user creating the cluster has the following prerequisites: 
+== How it works
 
-* A minimum version of Redpanda `rpk` v24.1. See xref:manage:rpk/rpk-install.adoc[].
-* The user authenticating to AWS has `AWSAdministratorAccess` access to create the IAM policies specified in xref:security:authorization/cloud-iam-policies.adoc[AWS IAM policies].
+You grant Redpanda access before you create the cluster, in two parts:
 
-* The user has the AWS variables necessary to authenticate. Use either:
-+
---
-** `AWS_PROFILE` or
-** `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
+* A *permissions policy* that grants the access Redpanda needs to provision and manage your cluster. For the full list and an explanation of each permission, see xref:security:authorization/cloud-iam-policies.adoc[AWS IAM policies].
+* A *trust policy* that allows only Redpanda's control plane to assume the role, scoped by a unique external ID.
+
+Redpanda then assumes the role using AWS Security Token Service (STS), presenting the external ID, and provisions your cluster.
+
+// TODO(team 4): confirm role name, session duration, and trust policy details.
+
+== Prerequisites
 
-To verify access, you should be able to successfully run `aws sts get-caller-identity` for your region. For more information, see the https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sts/get-caller-identity.html[AWS CLI reference^].
---
+* An AWS account with permission to create IAM roles and policies (for example, `AWSAdministratorAccess`).
+* Terraform installed, or another way to apply the configuration Redpanda provides. TODO(team 2): confirm the supported tooling and where customers obtain the configuration.
 
-== Create a BYOC cluster
+== Grant IAM permissions
+
+Create the cross-account IAM role that Redpanda assumes to provision your cluster.
+
+// TODO(team 2, 3): replace with the confirmed workflow once the Terraform delivery
+// mechanism and external-ID ordering are known.
 
 . Log in to https://cloud.redpanda.com[Redpanda Cloud^].
-. On the Clusters page, click *Create cluster*, then click *Create* for BYOC. 
+. Start creating a BYOC cluster on AWS and note the external ID that Redpanda generates for your cross-account role. TODO(team 3): confirm exact UI location.
+. Apply the Redpanda-provided Terraform configuration in your AWS account to create the IAM role, its permissions policy, and its trust policy (scoped to the external ID from the previous step). TODO(team 2): add the configuration or a link to it.
+. Provide the resulting role ARN to Redpanda in the Cloud UI. TODO(team 1): confirm the field and screen.
+
+== Create the cluster
+
+// TODO(team 1): align these steps with the deployment wizard (ENG-1129).
+
+. On the Clusters page, click *Create cluster*, then click *Create* for BYOC.
 . Enter a cluster name, then select the resource group, provider (AWS), xref:reference:tiers/byoc-tiers.adoc[region, tier], availability, and Redpanda version.
 +
 [NOTE]
-==== 
+====
 * If you plan to create a private network in your own VPC, select the region where your VPC is located.
 * Three availability zones provide two backups in case one availability zone goes down.
 ====
@@ -49,12 +79,7 @@ NOTE: After the cluster is created, you can change the API Gateway access on the
 To route all cluster egress through your own AWS Transit Gateway and hub VPC instead of a per-VPC NAT Gateway, set the *Transit Gateway ID* field on this page. The field is only available on clusters with a private connection type, and is only visible if centralized egress is enabled for your organization. This option is in beta. See xref:networking:byoc/aws/nat-free-egress.adoc[].
 ====
 . Click *Next*.
-. On the Deploy page, follow the steps to log in to Redpanda Cloud and deploy the agent.
-+
-As part of agent deployment:
-+
-** Redpanda assigns the permission required to run the agent. For details about these permissions, see xref:security:authorization/cloud-iam-policies.adoc[AWS IAM policies].
-** Redpanda allocates one Elastic IP (EIP) address in AWS for each BYOC cluster. 
+. Complete the deployment. Redpanda assumes your cross-account role and provisions the cluster. No agent runs in your account, and you do not run `rpk cloud byoc aws apply`. Redpanda allocates one Elastic IP (EIP) address in AWS for each BYOC cluster.
 
 include::get-started:partial$no-access.adoc[]
 
@@ -64,4 +89,5 @@ include::get-started:partial$custom-tags-aws.adoc[]
 
 == Next steps
 
-xref:networking:byoc/aws/index.adoc[Configure private networking]
+* xref:security:authorization/cloud-iam-policies.adoc[Review the AWS IAM policies] that your cross-account role grants.
+* xref:networking:byoc/aws/index.adoc[Configure private networking]

modules/get-started/pages/cluster-types/byoc/index.adoc

@@ -11,6 +11,9 @@ Bring Your Own Cloud (BYOC) lets you run Redpanda in your own cloud environment
 
 Your data never leaves your environment, giving you extra security and control. See xref:get-started:byoc-arch.adoc[BYOC architecture] for details. Redpanda manages provisioning, monitoring, upgrades, and security policies, and it manages required resources in your VPC or VNet, including subnets (subnetworks in GCP), IAM roles, and object storage resources (for example, S3 buckets or Azure Storage accounts). You get hands-off operations with a 99.99% uptime guarantee while keeping full control of your data. 
 
+// DOC-2297: AWS-only, new clusters, targeted 26.2. Confirm/finalize at GA.
+On AWS, new BYOC clusters use xref:get-started:byoc-arch.adoc#provisioning-models-on-aws[cross-account IAM delegation]: you create an IAM role that Redpanda assumes to provision your cluster, instead of running `rpk cloud byoc apply`. See xref:get-started:cluster-types/byoc/aws/create-byoc-cluster-aws.adoc[Create a BYOC Cluster on AWS].
+
 If you want to manage the networking infrastructure yourself, create a Bring Your Own Virtual Private Cloud (BYOVPC) or Bring Your Own Virtual Network (BYOVNet) cluster. With BYOVPC/BYOVNet, the Redpanda agent does not create or change resources in your account. This is ideal for organizations with stringent compliance requirements or existing network configurations, when you need full control over the network lifecycle. Compared to standard BYOC, BYOVPC/BYOVNet provides more security, but the configuration is more complex. See the xref:get-started:cloud-overview.adoc#shared-responsibility-model[shared responsibility model] to understand what you manage versus what Redpanda manages.
 
 IMPORTANT: Don't deploy other workloads on the BYOC infrastructure that Redpanda manages.

modules/get-started/pages/whats-new-cloud.adoc

@@ -8,6 +8,12 @@ This page lists new features added to Redpanda Cloud.
 
 == July 2026
 
+// DOC-2297 DRAFT entry (ENG-1139), 26.2, AWS only, new clusters only. Targeted GA 2026-07-14.
+// TODO(team): confirm wording and links before publishing; do not publish before GA.
+=== Simpler, more transparent BYOC deployment on AWS
+
+When you create a new BYOC cluster on AWS, you no longer run a command-line tool to bootstrap it yourself. Instead, you grant Redpanda access through a standard AWS IAM role that you create (using cross-account IAM delegation), and Redpanda deploys and maintains the cluster for you. Because the role lives in your own AWS account, you can see exactly what Redpanda is allowed to do, and you can change or remove that access at any time. This applies to new clusters on AWS. See xref:get-started:cluster-types/byoc/aws/create-byoc-cluster-aws.adoc[Create a BYOC Cluster on AWS] and xref:security:authorization/cloud-iam-policies.adoc[AWS IAM policies].
+
 === SQL editor in Redpanda Cloud Console
 
 Redpanda Cloud Console now includes a built-in SQL editor. For SQL-enabled environments, you can write and run `SELECT` queries against your Redpanda topics directly in the Console without installing a separate PostgreSQL client. The editor supports syntax highlighting, autocomplete, query history, and CSV and JSON export. For Iceberg-enabled topics, an indicator shows when results span both live topic data and Iceberg-committed history. To enable Redpanda SQL, see xref:sql:get-started/deploy-sql-cluster.adoc[Enable Redpanda SQL]. To use the editor, see xref:sql:query-data/sql-editor.adoc[Use the SQL Editor].