Terraform IAM Role Import Conflict Resolver

The Incident (What Does the Error Mean?)

Raw error output from a terraform apply:

Error: creating IAM Role (my-app-execution-role): EntityAlreadyExists:
  Role with name my-app-execution-role already exists.
│   with aws_iam_role.app_execution_role,
│   on iam.tf line 4, in resource "aws_iam_role" "app_execution_role":
│    4: resource "aws_iam_role" "app_execution_role" {

Immediate consequence: Terraform's AWS provider attempted a CreateRole API call. IAM rejected it with EntityAlreadyExists. Your entire terraform apply is now aborted — every resource depending on this role (ECS task definitions, Lambda functions, EC2 instance profiles) did not get created or updated. Your pipeline is dead.

This happens in three common scenarios:

1. The role was created manually in the AWS Console before IaC was adopted.
2. A previous Terraform run created the role but the state file was lost, corrupted, or the workspace was switched.
3. Another Terraform root module or stack owns this role, and you have a duplicate resource block.

The Attack Vector / Blast Radius

This is not just a nuisance error. The blast radius is significant:

• Pipeline deadlock: Every CI/CD run will fail at this step. No infrastructure changes can be applied until resolved.
• State drift accumulation: The longer the role exists outside of state, the more its live configuration (inline policies, tags, trust relationships) will drift from your HCL. Importing a heavily drifted role and running apply immediately can overwrite production trust policies, breaking service authentication silently.
• Duplicate ownership risk: If two Terraform stacks both define this role without remote state locking, a concurrent apply from either stack can delete and recreate the role, instantly invalidating all attached instance profiles and assumed-role sessions. Active workloads using sts:AssumeRole will receive AccessDenied with no warning.
• Audit trail gap: A role living outside of IaC state has no change history. You cannot answer "who modified this role's trust policy and when" from your Terraform logs.

Prevention in CI/CD

1. Enforce State Existence Before Apply with Checkov

Add Checkov to your pipeline to catch unmanaged IAM resources:

checkov -d . --check CKV_AWS_274 --compact

2. OPA Policy — Block Plans with IAM Role Creation if Role Name Already Exists

package terraform.iam

deny[msg] {
  resource := input.resource_changes[_]
  resource.type == "aws_iam_role"
  resource.change.actions[_] == "create"
  # Integrate with aws_iam_role data source pre-check in your pipeline
  msg := sprintf("IAM role '%v' is being created by Terraform. Verify it does not already exist in AWS before applying.", [resource.change.after.name])
}

3. Pre-Apply Shell Guard in CI/CD

Insert this before terraform apply in your pipeline script:

ROLE_NAME=$(terraform show -json | jq -r '.planned_values.root_module.resources[] | select(.type=="aws_iam_role") | .values.name')
if aws iam get-role --role-name "$ROLE_NAME" > /dev/null 2>&1; then
  echo "[WARN] IAM role $ROLE_NAME exists in AWS but may not be in state. Run terraform import before apply."
  exit 1
fi

4. Terragrunt + S3 Remote State Locking

If you are not already using remote state with DynamoDB locking, this class of error will recur. Shared IAM roles must live in a single authoritative state file, referenced by all consumer stacks via terraform_remote_state data source or SSM Parameter Store ARN lookup.

# In consumer stacks, never re-declare shared platform roles
data "terraform_remote_state" "platform_iam" {
  backend = "s3"
  config = {
    bucket = "my-org-terraform-state"
    key    = "platform/iam/terraform.tfstate"
    region = "us-east-1"
  }
}

resource "aws_ecs_task_definition" "app" {
  # ...
  execution_role_arn = data.terraform_remote_state.platform_iam.outputs.app_execution_role_arn
}