aws iam attach-role-policy: Attach Policies to Roles
aws iam attach-role-policy attaches an existing managed policy (AWS-managed or customer-managed) to an IAM role by ARN, granting the role those permissions.
After creating a role you grant it permissions, usually by attaching a customer-managed policy. attach-role-policy is the wiring step; it references the policy ARN, not its document.
What it does
aws iam attach-role-policy links the managed policy at --policy-arn to --role-name. It returns no output on success. The policy must already exist; this command does not create it. A role can hold up to 20 managed policies by default (an adjustable quota).
Common usage
aws iam attach-role-policy \
--role-name ci-deploy-role \
--policy-arn arn:aws:iam::123456789012:policy/ci-deploy-policy
# attach an AWS-managed policy
aws iam attach-role-policy \
--role-name ci-deploy-role \
--policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccessOptions
| Flag | What it does |
|---|---|
| --role-name <name> | Role to attach to (name, not ARN) |
| --policy-arn <arn> | ARN of the managed policy to attach |
In CI
IAM is eventually consistent: a role or policy created moments earlier may not be visible yet, surfacing as NoSuchEntity; retry with a short backoff. Use --role-name (a bare name), not the role ARN. Prefer customer-managed policies you version-control over wildcard AWS-managed ones so least privilege survives review.
Common errors in CI
"An error occurred (NoSuchEntity) when calling the AttachRolePolicy operation: Policy arn:... does not exist or is not attachable" means a wrong ARN or eventual-consistency lag after creation. "LimitExceeded: Cannot exceed quota for PoliciesPerRole: 20" means too many attached policies. "AccessDenied" means the caller lacks iam:AttachRolePolicy (or a permissions boundary blocks it).