Introduction

You cannot rename an AWS IAM role in place. IAM lets you update settings such as the description and maximum session duration, but a role name itself is effectively immutable once created.

The practical solution is to create a new role with the desired name, copy the trust and permission configuration, update every consumer to use the new role, and then retire the old one. The work is usually straightforward, but the dependency cleanup is where most mistakes happen.

Why IAM Role Renaming Is a Migration

An IAM role is more than a display name. Other systems may refer to it by name, by ARN, or through attached resources such as instance profiles and service configuration. If AWS allowed the name to change silently, those references could break in difficult-to-debug ways.

That is why "rename the role" really means "replace the role safely."

Before making changes, collect:

• the trust policy
• attached managed policies
• inline policies
• the services or users that assume the role
• any hard-coded references to the role ARN or name

Create the Replacement Role

Start by creating a new role with the trust policy you want. The trust policy controls who can assume the role.

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Principal": {
7        "Service": "lambda.amazonaws.com"
8      },
9      "Action": "sts:AssumeRole"
10    }
11  ]
12}

Save that as trust-policy.json, then create the new role:

1aws iam create-role \
2  --role-name NewAppRole \
3  --assume-role-policy-document file://trust-policy.json \
4  --description "Replacement for OldAppRole"

Now attach the same managed policies that the old role used:

aws iam attach-role-policy \
  --role-name NewAppRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

If the old role had inline policies, recreate them on the new role:

1aws iam put-role-policy \
2  --role-name NewAppRole \
3  --policy-name InlineS3Access \
4  --policy-document file://inline-s3-access.json

These commands are runnable as written once you substitute your actual policy files and target role name.

Update the Systems That Use the Old Role

This is the step people underestimate. The new role can be perfectly configured and still do nothing until every consumer points at it.

Typical examples include:

• Lambda functions using the old execution role
• EC2 instance profiles
• ECS task definitions
• EKS service accounts using IAM roles for service accounts
• CI jobs or humans assuming the old role
• resource policies that mention the old role ARN

For example, updating a Lambda function to use the new execution role looks like this:

aws lambda update-function-configuration \
  --function-name my-function \
  --role arn:aws:iam::123456789012:role/NewAppRole

If the role is attached to an EC2 instance profile, you may need to create or update the instance profile association instead of changing only IAM. Always trace the role through the consuming service, not only through the IAM console.

Validate Before Deleting the Old Role

Once the new role is in place, test the real workload:

• can the service still assume the role
• do the expected API calls succeed
• do logs and metrics look normal
• are any iam:PassRole permissions still pointing at the old ARN

Only after the migration is verified should you detach the old role from live systems and delete it. Keeping both roles temporarily during the cutover is often safer than trying to switch everything in one risky step.

Common Pitfalls

The most common mistake is copying permission policies but forgetting the trust policy. A role that cannot be assumed is effectively broken even if its permissions look correct.

Another common problem is missing ARN references. Renaming by replacement changes the ARN, so any resource policy, automation script, or configuration file that names the old role must be updated explicitly.

Instance profiles are another source of confusion. An EC2 instance does not attach directly to a role in the same way Lambda does, so migrating EC2 usage often requires extra steps around the instance profile.

Be careful with service-linked roles too. Those are special IAM roles managed for AWS services and should be handled according to the service documentation rather than cloned casually.

Finally, do not delete the old role too early. Temporary overlap during validation is cheap; restoring a broken production permission path under pressure is not.

Summary

• IAM does not support renaming a role in place.
• The correct approach is to create a new role and migrate consumers to it.
• Copy both trust configuration and permission policies.
• Update every service, script, and policy that refers to the old name or ARN.
• Validate real assumptions and API calls before deleting the old role.
• Treat instance profiles and service-linked roles as special cases during the migration.