Runbook has several confusing or completely contradictory statements and complimentary images

[botscholar-scott]

I cloned the repo and in my Lambda subdirectory there are only three zip files. Yet, step 3.0 of the "ASA IAM Key Rotation Runbook(v3).pdf" it shows a picture that has these zips and directories with their names. Is there a step missing where I should have extracted these zip files? It also has a sub-heading of "Project files included in the zip:" but this stuff was cloned from github.

Later in the Runbook it shows a screen capture of copying things into a lambdacoderepo1221155/asa/asa-iam-rotation/
but then in step 4.2 Step 3 it shows a picture of ****-demo-bucket-iam-key-rotation. What is the form of this CloudFormation S3 Bucket Name? Using your example should this something like s3://lambdacoderepo1221155?

For 4.2 Step 4 the Runbook says "For Permissions, select 'Service-managed permissions'..." but shows a screen shot that selects 'Self service permissions' with an IAM role name of AWSCloudFormationStackSetAdministrationRole and an IAM execution role name.

[botscholar-scott]

Here are several other errors/contradictions/missing information:

• 2.0 Architecture shows two different options. One to store the credentials in the AWS Secrets Manager of the member account and option 2 to store the credentials in the AWS Secrets Manager of the central account yet there is no discussion of how one would chose one option or the other when deploying the various yaml solutions. Do we need to modify something to get one option or the other?

• 4.2 Step 3 the S3BucketName must not include s3:// or end in a trailing /. Similar for the "CloudFormation S3 Bucket Prefix." We found this also cannot end in a trailing /.

• 4.2 Step 4 says, "For Permissions, select 'Service-managed permissions', and then 'Next'." However, the screen shot shows 'Self service permissions' selected. Additionally, it has an IAM role name of AWSCloudFormationStackSetAdministrationRole and AWSCloudFormationStackSetExecutionRole in the IAM execution role name yet neither of these fields were mentioned in this (or previous sections) or are visible to us when we follow these instructions. And this is not a StackSet so it appears they used the permissions screen shot from the next section here.

• 4.3 Deploy IAM Assumed Roles CloudFormation Template as a StackSet has an Important Note that says "The 'list_accounts' API operation can only be called from the organization's management account..." I think this image belongs under the "4.4 Deploy the List Account Role in the Central/Management Account." heading.

• 4.3 Step 4 has a similar "Select 'Service-managed permissions'" yet shows the same screen shot from 4.2 Step 4 with 'Self service permissions'. It also uses these AWSCloudFormationStackSetAdministrationRole and AWSCloudFormationStackSetExecutionRole but never mentions creating these IAM roles (as I stated above for 4.2 Step 4).

• There's an IMPORTANT NOTE following 4.3 Step 4 that says "If you selected more than 1 region per account you will get an error message similar to: ResourceLogicalId:ASAIAMAssumedRole, ResourceType:AWS::IAM::Role, ResourceStatusReason:asa-iam-key-
  rotation-lambda-assumed-role already exists.". This resulted in a failure to deploy for us due to the fact that the default failure tolerance is 0 and we chose to deploy to the 4 regions our sub-accounts are using. Should this be an actual recommendation/requirement that you should only choose 1 region to install the IAM Assumed Roles CloudFormation Template as a StackSet?

• Once we had things deployed we moved to section 5.0 Validating Deployment & Manual Tests. The ASA-Account-Inventory only listed our sub-accounts that are setup using us-west-2 (the region where we deployed this solution). It would be worth mentioning whether this a problem, an incomplete and limited test or that it's not a problem and that when run through the cron mechanism all the sub-accounts regardless of region will be found.

• Section 5.2 Manually Test: ASA-IAM-Access-Key-Rotation-Function Lambda Function. We discovered that when we tested rotating some dummy IAM that are in our main deployment account that we received errors. We only later discovered in 6.0 Troubleshooting the statement "If deployed via organizations, the root org account will not be included." The primary reason we are implementing this solution is to implement key rotation for all our IAM Access Keys per the FTR requirement. It would have been really helpful to know this when deploying the assume role solution and how to get the root org account to be included. We tried both organizations (the default) and by organization id and in either case have been unable to get beyond the error,
  "An error occurred (AccessDenied) when calling the AssumeRole operation: User: arn:aws:sts::<root_org_account_id>:assumed-role/asa-iam-key-rotation-lambda-execution-role/ASA-IAM-Access-Key-Rotation-Function is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::<root_org_account_id>:role/asa-iam-key-rotation-lambda-assumed-role"