How to remove or decommission an IAM role

Topic: Accounts access

Safely remove or decommission an IAM role: detach all policies, delete inline policies, remove the role from instance profiles, then delete the role. Use this when a workload is retired or the role is consolidated; ensure no resources still assume or reference the role.

Intent: How-to

Quick answer

  • Detach all managed policies and delete all inline policies from the role so the role has no permissions; remove the role from any instance profile (EC2) or from Lambda/ECS configuration.
  • Ensure no running resources (instances, Lambda functions, ECS tasks) are using the role; update or terminate them first, then delete the role.
  • Delete the role with delete-role; if deletion fails, fix the dependency (instance profile, resource reference) and retry.

Prerequisites

Steps

  1. Identify dependencies

    Find resources that use the role: EC2 instance profiles (list-instance-profiles-for-role), Lambda functions (list-functions and check Role), ECS task definitions; list trust relationships that allow other roles to assume this role.

  2. Stop using the role on resources

    Detach the instance profile from EC2 instances or replace with another role; update Lambda execution role and ECS task role; remove the role from any cross-account or federated trust that assumes it.

  3. Detach policies and remove from instance profiles

    Detach all managed policies (detach-role-policy), delete all inline policies (delete-role-policy); remove the role from instance profiles (remove-role-from-instance-profile) and delete empty instance profiles if desired.

  4. Delete the role

    Run delete-role; if it fails (e.g. entity in use), resolve the reported dependency (policy still attached, instance profile still contains role, or resource still referencing) and retry.

Summary

You will remove or decommission an IAM role by identifying all resources that use it, stopping use of the role on those resources, detaching policies and removing the role from instance profiles, then deleting the role. Use this when retiring a workload or consolidating roles.

Prerequisites

  • IAM permissions to detach policies, delete inline policies, remove roles from instance profiles, and delete roles (iam:DetachRolePolicy, iam:DeleteRolePolicy, iam:RemoveRoleFromInstanceProfile, iam:DeleteRole).
  • Knowledge of which EC2 instances, Lambda functions, or ECS tasks use this role.

Steps

Step 1: Identify dependencies

Instance profiles (EC2):

aws iam list-instance-profiles-for-role --role-name ROLE_NAME

For each instance profile, find instances using it (EC2 describe-instances and check IamInstanceProfile).

Lambda: List functions and check the Role attribute:

aws lambda list-functions --query 'Functions[].[FunctionName,Role]' --output table

ECS: Check task definitions for taskRoleArn and executionRoleArn. Other: Check CloudFormation, Step Functions, or other services that may reference the role ARN.

Trust: Roles that can assume this role are in the trust policy; if you delete this role, those assume-role calls will fail. Update the caller to use a different role first.

Step 2: Stop using the role on resources

  • EC2: For each instance using the instance profile that contains this role, associate a different instance profile or remove the profile (replace-iam-instance-profile-association). Then remove the role from the instance profile: aws iam remove-role-from-instance-profile --instance-profile-name NAME --role-name ROLE_NAME
  • Lambda: Update each function’s execution role to a different role: aws lambda update-function-configuration --function-name NAME --role arn:aws:iam::ACCOUNT:role/OtherRole
  • ECS: Create a new task definition revision with a different task/execution role and stop tasks using the old definition; then delete the role when no tasks use it.

Step 3: Detach policies and remove from instance profiles

ROLE=ROLE_NAME
for policy in $(aws iam list-attached-role-policies --role-name "$ROLE" --query 'AttachedPolicies[].PolicyArn' --output text); do
  aws iam detach-role-policy --role-name "$ROLE" --policy-arn "$policy"
done
for policy in $(aws iam list-role-policies --role-name "$ROLE" --query 'PolicyNames[]' --output text); do
  aws iam delete-role-policy --role-name "$ROLE" --policy-name "$policy"
done
aws iam list-instance-profiles-for-role --role-name "$ROLE" --query 'InstanceProfiles[].InstanceProfileName' --output text | xargs -I {} aws iam remove-role-from-instance-profile --instance-profile-name {} --role-name "$ROLE"

Step 4: Delete the role

aws iam delete-role --role-name ROLE_NAME

If you get “Cannot delete entity, must remove policies from role first” or “must detach policies from role”, repeat Step 3. If you get “instance profile contains the role”, remove the role from the instance profile and retry. If a Lambda or other resource still references the role, update that resource first.

Verification

  • list-roles no longer shows the role (or the role is gone).
  • No EC2 instance, Lambda function, or ECS task is configured with the deleted role ARN.
  • CloudTrail shows DeleteRole for the role; any caller that previously assumed the role now uses an alternative or receives an error (expected).

Troubleshooting

DeleteRole: dependency still exists — The error message usually indicates the dependency (e.g. instance profile, managed policy still attached). List attached policies and instance profiles again; ensure inline policies are deleted (list-role-policies).

Lambda/ECS still references role — Update the Lambda function or ECS task definition to use another role, then delete the role. For ECS, ensure no running tasks use a definition that references this role.

Cross-account assume will break — Notify the other account; they should switch to another role before you delete this one. After deletion, their assume-role calls will fail until they update.

Next steps

Continue to