AWS wellarchitected: AWS WA Agent: document IAM execution/access role creation options
Summary
Rewrites the AWS Well-Architected Agent getting-started guide to explain the two account-onboarding choices (current account vs. manually added accounts), how the console auto-creates the execution role and read-only access role, a role-description table, and clarifies that Termination protection applies regardless of onboarding method.
Security assessment
The change documents IAM role behavior for the WA Agent: an execution role that assumes an access role, and an access role that grants read-only access, reinforcing least-privilege expectations. It also clarifies that Termination protection must be disabled before deletion, reducing accidental profile removal. There is no reference to a specific vulnerability, CVE, or incident, so it is security-adjacent documentation rather than a fix.
Evidence
+If you chose **The current account** , this section shows **No action needed**. The console automatically creates the execution role and the access role in this account, so you don't need to create any roles manually. Both roles are read-only and can't modify your resources.
Diff
diff --git a/wellarchitected/latest/userguide/agent-getting-started.md b/wellarchitected/latest/userguide/agent-getting-started.md index d45e230..991ad5e 100644 --- a//wellarchitected/latest/userguide/agent-getting-started.md +++ b//wellarchitected/latest/userguide/agent-getting-started.md @@ -67 +67,8 @@ AWS WA Agent requires an active AWS Support plan at Business+ or higher in every -Create an agent profile from the AWS WA Agent console. During profile creation, you can create an execution role or select an existing one. +Create an agent profile from the AWS WA Agent console. During profile creation, you choose how to add the accounts that AWS WA Agent monitors. This choice determines how the required IAM roles are created: + + * If you choose **The current account** , AWS WA Agent monitors only the account you are signed in to, and the console automatically creates both the execution role and the access role in that account. You don't need to create any roles manually. + + * If you choose **Manually add accounts to monitor** , you enter the account IDs yourself. For more information about creating or selecting an execution role, see Step 3: Configure permissions and integrations. For more information about manually creating an access role in each workload account, see Step 6: Create access roles in your workload accounts. + + + @@ -85 +92,5 @@ Create an agent profile from the AWS WA Agent console. During profile creation, - 8. Under **Accounts to monitor** , enter account IDs separated by commas (up to 100 accounts). + 8. Under **How do you want to add accounts?** , select one of the following options: + + * **The current account** – AWS WA Agent monitors only the account you are signed in to and creates the required roles automatically. You don't need to create any roles manually. + + * **Manually add accounts to monitor** – Add the accounts yourself. Complete the following steps: @@ -87 +98,3 @@ Create an agent profile from the AWS WA Agent console. During profile creation, - 9. Then, under **Common access role name** , enter the access role name to use across all accounts in the profile. The recommended name is `AccessRoleForWellArchitectedAgent`. + 1. Under **Accounts to monitor** , enter account IDs separated by commas (up to 100 accounts). + + 2. Under **Common access role name** , enter the access role name to use across all accounts in the profile. The recommended name is `AccessRoleForWellArchitectedAgent`. @@ -109 +122,10 @@ During profile creation, configure the following in **Optimization pillars** : -After configuring pillars, under **Permissions and Integrations** , you can either select an existing execution role or create a new one. +What you configure under **Permissions and Integrations** depends on the option you selected for **How do you want to add accounts?** in Step 1: Create an agent profile. + +If you chose **The current account** , this section shows **No action needed**. The console automatically creates the execution role and the access role in this account, so you don't need to create any roles manually. Both roles are read-only and can't modify your resources. + +The following table describes each role. + +Role name | What it does +---|--- +`ExecutionRoleForWellArchitectedAgent` | Orchestrates resource discovery. Assumes the access role to read resources. +`AccessRoleForWellArchitectedAgent` | Grants read-only access to the resources in this account. @@ -111 +133 @@ After configuring pillars, under **Permissions and Integrations** , you can eith -The execution role is an IAM role in your profile account that AWS WA Agent assumes to orchestrate resource discovery. The execution role chains to the access roles in your workload accounts. When you choose **Create new role** , the console creates the IAM execution role for you automatically, applying the required trust policy and permissions policy. You do not need to navigate to the IAM console separately. +If you chose **Manually add accounts to monitor** , you select an existing execution role or create a new one. The execution role is an IAM role in your profile account that AWS WA Agent assumes to orchestrate resource discovery. The execution role chains to the access roles in your workload accounts. When you choose **Create new role** , the console creates the IAM execution role for you automatically, applying the required trust policy and permissions policy. You don't need to navigate to the IAM console separately. @@ -123 +144,0 @@ The execution role is an IAM role in your profile account that AWS WA Agent assu - 5. Determine whether to enable or disable Termination protection. It is recommended to enable this feature to avoid accidental profile deletion. @@ -126,0 +148 @@ The execution role is an IAM role in your profile account that AWS WA Agent assu +Choose whether to enable **Termination protection**. This setting applies regardless of how you added accounts. Enabling it is recommended to prevent accidental profile deletion from the console, API, or CLI. To delete a profile, you must first disable **Termination protection**. @@ -180,0 +203,4 @@ After you create your profile, create an IAM access role in each AWS account tha +###### Important + +This procedure applies only if you chose **Manually add accounts to monitor** in Step 1: Create an agent profile. If you chose **The current account** , the console already created both the execution role and the access role automatically during profile creation, and you can skip this step. +