Motivation

We are migrating IAM role handling from moto to LocalStack now - this includes attachement and detachement of policies.

Changes

1. Entity Structure

The RoleEntity dataclass wraps the API Role type with additional relations:

@dataclasses.dataclass
class RoleEntity:
    role: Role  # From localstack.aws.api.iam
    inline_policies: dict[str, str] = field(default_factory=dict)  # policy_name -> document
    attached_policy_arns: list[str] = field(default_factory=list)  # ARNs of attached managed policies
    linked_service: str | None = None  # For service-linked roles

Rationale:

• role: Role stores all core role attributes (Path, RoleName, RoleId, Arn, CreateDate, AssumeRolePolicyDocument, Description, MaxSessionDuration, PermissionsBoundary, Tags, RoleLastUsed)
• inline_policies is a dict mapping policy name to policy document JSON string, matching how inline policies work
• attached_policy_arns is a list (not set) to preserve attachment order; the ManagedPolicyEntity tracks its own AttachmentCount
• linked_service is needed for service-linked role identification

2. Storage Key

Roles are keyed by role name in IamStore.ROLES:

ROLES: dict[str, RoleEntity] = CrossRegionAttribute(default=dict)

Rationale:

• Role names are unique per account
• Provides O(1) lookup by name, which is the most common access pattern
• Uses CrossRegionAttribute since IAM is a global service

3. Locking Strategy

A separate _role_lock is used for role operations, independent of _policy_lock:

_role_lock: threading.Lock

Rationale:

• Allows concurrent policy and role operations
• Simpler than fine-grained locking per role
• Consistent with the policy migration approach

4. Trust Policy Validation

Trust policies (AssumeRolePolicyDocument) are validated separately from regular IAM policies, as in moto:

• Must be valid JSON
• Cannot contain Resource field (unlike regular policies)
• Actions must be valid STS actions: sts:AssumeRole, sts:AssumeRoleWithSAML, sts:AssumeRoleWithWebIdentity, sts:TagSession, sts:SetSourceIdentity, or *

5. Permissions Boundary Handling

Permissions boundaries are validated to:

• Have valid ARN format (must contain :policy/)
• Exist (for customer-managed policies; AWS-managed policies are trusted)

Stored in role["PermissionsBoundary"] as AttachedPermissionsBoundary:

{
    "PermissionsBoundaryType": "Policy",
    "PermissionsBoundaryArn": "<arn>"
}

6. Managed Policy Attachment

When attaching/detaching customer-managed policies:

• The policy ARN is added to/removed from attached_policy_arns
• The AttachmentCount on ManagedPolicyEntity.policy is incremented/decremented with a policy lock
• AWS-managed policies (prefix arn:{partition}:iam::aws:policy/) are tracked in attached_policy_arns but don't update any count since they're not in our store

7. Instance Profile Interaction

Instance profiles remain in moto for now. The delete_role operation checks moto's instance profiles to ensure the role is not attached before deletion:

for profile in backend.instance_profiles.values():
    for role in profile.roles:
        if role.name == role_name:
            raise DeleteConflictException(...)

Future work: When instance profiles are migrated, they should store role names and look up from IamStore.ROLES.

Migrated Operations

Core CRUD

• create_role - Creates role in native store with validation
• get_role - Returns role from native store
• delete_role - Deletes from native store with constraint checks
• list_roles - Lists from native store with path filtering and pagination
• update_role - Updates description and/or max_session_duration
• update_role_description - Updates description only
• update_assume_role_policy - Updates trust policy with validation

Tagging

• tag_role - Adds/updates tags with validation
• untag_role - Removes tags by key
• list_role_tags - Lists tags with pagination

Inline Policies

• put_role_policy - Adds/updates inline policy with validation
• get_role_policy - Returns inline policy document
• list_role_policies - Lists inline policy names
• delete_role_policy - Removes inline policy

Managed Policy Attachment

• attach_role_policy - Attaches managed policy, updates AttachmentCount
• detach_role_policy - Detaches managed policy, updates AttachmentCount
• list_attached_role_policies - Lists attached policies with path filtering

Permissions Boundary

• put_role_permissions_boundary - Sets permissions boundary
• delete_role_permissions_boundary - Removes permissions boundary

Service-Linked Roles

• create_service_linked_role - Creates in native store with linked_service set
• delete_service_linked_role - Deletes from native store (allows attached policies)
• get_service_linked_role_deletion_status - Returns SUCCESS (unchanged)

Known Limitations

1. RoleLastUsed: Not implemented - would require tracking role assumption across STS
2. Instance Profiles: Still in moto - creates potential state divergence if directly manipulated
3. AWS-Managed Policies: Existence not validated on attach (trusted to exist)
4. Service-Linked Role Deletion: Synchronous (AWS is async with task tracking)

Deviations from Moto Behavior

1. Trust Policy Validation: More strict validation of STS actions
2. Permissions Boundary Validation: Validates ARN format and existence
3. url encoding: Always URL-encoding policy documents (already at store time), to avoid unencoded policies anywhere

Tests

Tests are in tests/aws/services/iam/test_iam_roles.py and cover:

• Role lifecycle (create, get, delete, update)
• Error cases (NoSuchEntity, EntityAlreadyExists, DeleteConflict)
• Tagging operations
• Inline policy operations
• Managed policy attachment
• Permissions boundary
• Pagination

Related

Closes UNC-229