AWS controltower medium security documentation change
Summary
Added new troubleshooting section for 'Landing Zone Update Failed with KMS Error', expanded remediation steps for failed stack sets, reorganized content about landing zone update failures including AWS Config resource conflicts and closed account handling
Security assessment
The KMS key policy error documentation addresses potential security misconfigurations that could prevent encryption controls from functioning properly. The AWS Config resource guidance prevents security monitoring gaps in audit/log accounts. While not fixing a specific vulnerability, these changes help maintain security posture by preventing misconfigurations.
Diff
diff --git a/controltower/latest/userguide/troubleshooting.md b/controltower/latest/userguide/troubleshooting.md index 3afedb316..c9967ef13 100644 --- a//controltower/latest/userguide/troubleshooting.md +++ b//controltower/latest/userguide/troubleshooting.md @@ -5 +5 @@ -Landing Zone Launch FailedLanding zone not up to date errorNew Account Provisioning FailedFailed to Enroll an Existing AccountUnable to Update an Account Factory AccountUnable to Update Landing ZoneFailure Error that Mentions AWS ConfigNo Launch Paths Found ErrorReceived an Insufficient Permissions ErrorDetective controls are not taking effect on accountsRate exceeded error returned by the AWS Organizations APIFailure to move an Account Factory account directly from one AWS Control Tower landing zone to another AWS Control Tower landing zoneAWS Support +Landing Zone Launch FailedLanding Zone Update Failed with KMS ErrorUnable to Update Landing ZoneLanding zone not up to date errorNew Account Provisioning FailedFailed to Enroll an Existing AccountUnable to Update an Account Factory AccountFailure Error that Mentions AWS ConfigNo Launch Paths Found ErrorReceived an Insufficient Permissions ErrorDetective controls are not taking effect on accountsRate exceeded error returned by the AWS Organizations APIFailure to move an Account Factory account directly from one AWS Control Tower landing zone to another AWS Control Tower landing zoneAWS Support @@ -10,0 +11,33 @@ If you encounter issues while using AWS Control Tower, you can use the following +###### Topics + + * Landing Zone Launch Failed + + * Landing Zone Update Failed with KMS Error + + * Unable to Update Landing Zone + + * Landing zone not up to date error + + * New Account Provisioning Failed + + * Failed to Enroll an Existing Account + + * Unable to Update an Account Factory Account + + * Failure Error that Mentions AWS Config + + * No Launch Paths Found Error + + * Received an Insufficient Permissions Error + + * Detective controls are not taking effect on accounts + + * Rate exceeded error returned by the AWS Organizations API + + * Failure to move an Account Factory account directly from one AWS Control Tower landing zone to another AWS Control Tower landing zone + + * AWS Support + + + + @@ -33,0 +67,15 @@ Be sure to enable all of your required AWS Security Token Service [ (STS) endpoi +**To remediate failed stack sets and retry the setup** + + 1. Navigate to the AWS CloudFormation console in the appropriate AWS Region. + + 2. Clean up the failed stack with the name **AWSControlTowerBP-BASELINE-CLOUDTRAIL-MASTER**. + + 3. Wait for the stack deletion to complete. + + 4. Return to the AWS Control Tower page. + + 5. Select **Set up landing zone** again. + + + + @@ -35,0 +84,76 @@ To view a list of AWS Regions that AWS Control Tower supports, see [How AWS Regi +## Landing Zone Update Failed with KMS Error + +The most common cause of landing zone update failure is a AWS KMS key policy that is not valid. + +Common reasons for a non-valid KMS key policy: + + * Typo in the policy. + + * Forgot to add the required policy statement. + + * Incorrect AWS partition. + + * Incorrect account number in the policy. + + * Forgot to remove the placeholders in the example policy. + + + + +###### Action to take + +Review your policy to check for these errors. + +For more information about AWS KMS key policies, see [Configure KMS keys](https://docs.aws.amazon.com/controltower/latest/userguide/configure-kms-keys.html) and [Backup prerequisites](https://docs.aws.amazon.com/controltower/latest/userguide/backup-prerequisites.html). + +## Unable to Update Landing Zone + +AWS Control Tower does not roll back to a previous landing zone version if an update fails. You may find your landing zone in an indeterminate state. If so, contact AWS support. + +Landing zone updates may fail for several reasons. + + * Prerequisites not met + + * AWS Config resources exist in certain accounts + + * Closed accounts exist + + + + +**Prerequisites not met** + +A landing zone update must meet the same prerequisites as a landing zone setup. Before you update, review the [pre-launch checks](https://docs.aws.amazon.com/controltower/latest/userguide/getting-started-prereqs.html). + +**AWS Config resources exist in Security OU accounts** + +Do not add AWS Config resources in your **Audit** and **Log archive** accounts. The landing zone update process cannot complete with these resources present. These restrictions are similar to those for enrolling an account or setting up a landing zone for the first time. For more information, see [Enroll accounts that have existing AWS Config resources](https://docs.aws.amazon.com/controltower/latest/userguide/existing-config-resources.html). + +**Closed accounts exist** + +When an account is in a **Closed** or **Suspended** state, you may encounter an issue when you try to update your landing zone. You must delete the provisioned product on every closed account before you perform an update to the landing zone. + +On the AWS Service Catalog provisioned product page, you may see an error message similar to this one: + +`AWSControlTowerExecution role can't be assumed on the account.` + +**Common cause:** You have suspended an account without deleting the provisioned product. + +**Action to take:** If you see this error, you have two options: + + 1. Contact AWS Support and reopen the account, delete the provisioned product, then close the account again. + + 2. Remove the resources from the StackSets that have been orphaned because of the account closure. (This option is available only if the StackSets have instances in **Current** state that you are not removing.) + + + + +###### To remove the resources from the StackSets, do this for each closed account: + + * Go into each of the AWS Control Tower StackSets and remove the StackInstances from every region, for the account that has been closed. + + * **IMPORTANT:** Choose the **Retain Stack** option so the StackSet removes only the stack instances. StackSet can't assume a role from the closed account, so it will fail if it tries to assume the `AWSControlTowerExecution` role, which leads to the error message you received. + + + + @@ -155,51 +278,0 @@ The `Tainted` state causes a follow-on issue: An account that is not updated may -## Unable to Update Landing Zone - -AWS Control Tower does not roll back to a previous landing zone version if an update fails. You may find your landing zone in an indeterminate state. If so, contact AWS support. - -Landing zone updates may fail for several reasons. - - * Prerequisites not met - - * AWS Config resources exist in certain accounts - - * Closed accounts exist - - - - -**Prerequisites not met** - -A landing zone update must meet the same prerequisites as a landing zone setup. Before you update, review the [pre-launch checks](https://docs.aws.amazon.com/controltower/latest/userguide/getting-started-prereqs.html). - -**AWS Config resources exist in Security OU accounts** - -Do not add AWS Config resources in your **Audit** and **Log archive** accounts. The landing zone update process cannot complete with these resources present. These restrictions are similar to those for enrolling an account or setting up a landing zone for the first time. For more information, see [Enroll accounts that have existing AWS Config resources](https://docs.aws.amazon.com/controltower/latest/userguide/existing-config-resources.html). - -**Closed accounts exist** - -When an account is in a **Closed** or **Suspended** state, you may encounter an issue when you try to update your landing zone. You must delete the provisioned product on every closed account before you perform an update to the landing zone. - -On the AWS Service Catalog provisioned product page, you may see an error message similar to this one: - -`AWSControlTowerExecution role can't be assumed on the account.` - -**Common cause:** You have suspended an account without deleting the provisioned product. - -**Action to take:** If you see this error, you have two options: - - 1. Contact AWS Support and reopen the account, delete the provisioned product, then close the account again. - - 2. Remove the resources from the StackSets that have been orphaned because of the account closure. (This option is available only if the StackSets have instances in **Current** state that you are not removing.) - - - - -###### To remove the resources from the StackSets, do this for each closed account: - - * Go into each of the AWS Control Tower StackSets and remove the StackInstances from every region, for the account that has been closed. - - * **IMPORTANT:** Choose the **Retain Stack** option so the StackSet removes only the stack instances. StackSet can't assume a role from the closed account, so it will fail if it tries to assume the `AWSControlTowerExecution` role, which leads to the error message you received. - - - -