AWS AmazonECS medium security documentation change
Summary
Added troubleshooting guidance for Amazon ECS Managed Instances when instance role name doesn't match naming convention, with specific CloudFormation resolution steps and policy details.
Security assessment
This change addresses a specific security-related configuration issue where IAM role naming mismatches cause authorization errors in ECS Managed Instances. The documentation explains how the managed policy's iam:PassRole condition requires role names starting with 'ecsInstanceRole', and provides concrete resolution steps for CloudFormation users. This directly addresses a security misconfiguration that could prevent proper task execution.
Diff
diff --git a/AmazonECS/latest/developerguide/security_iam_troubleshoot.md b/AmazonECS/latest/developerguide/security_iam_troubleshoot.md index 32de67969..61df31bdb 100644 --- a//AmazonECS/latest/developerguide/security_iam_troubleshoot.md +++ b//AmazonECS/latest/developerguide/security_iam_troubleshoot.md @@ -55,0 +56,2 @@ If you need help, contact your AWS administrator. Your administrator is the pers +If you use Amazon ECS Managed Instances and receive this error, your instance role name might not match the naming convention required by the managed policy. For more information, see I am having issues with my Amazon ECS Managed Instances instance profile. + @@ -77 +79,14 @@ To learn more, consult the following: -If you use the `AmazonECSInfrastructureRolePolicyForManagedInstances` managed policy that Amazon ECS provides, then the instance profile must have `ecsInstanceRole` as prefix. The reason is that the managed policy is only authorized to pass roles with this prefix. +If you use the `AmazonECSInfrastructureRolePolicyForManagedInstances` managed policy, the instance role name must start with `ecsInstanceRole`. The policy scopes `iam:PassRole` to `arn:aws:iam::*:role/ecsInstanceRole*`, so a mismatched name causes an authorization error at task launch. + +This is common with CloudFormation when you omit `RoleName` from your `AWS::IAM::Role` resource, because CloudFormation auto-generates names like `MyStack-InstanceRole-ABC123` that do not match the policy condition. + +To resolve this issue, do one of the following: + + * Add `RoleName: ecsInstanceRole` to your `AWS::IAM::Role` resource so the name matches the managed policy. + + * Add an explicit `iam:PassRole` inline policy to your infrastructure role that targets the instance role ARN. + + + + +For CloudFormation templates and detailed steps, see [Create the instance profile using CloudFormation](./managed-instances-instance-profile.html#create-instance-profile-cfn).