Attach an IAM role to an instance

You can create an IAM role and attach it to an instance during or after launch. You can also replace or detach IAM roles.

To attach an IAM role to an instance at launch using the Amazon EC2 console, expand Advanced details. For IAM instance profile, select the IAM role.

Note

If you created your IAM role using the IAM console, the instance profile was created for you and given the same name as the role. If you created your IAM role using the AWS CLI, API, or an AWS SDK, you might have given your instance profile a different name than the role.

You can attach an IAM role to an instance that is running or stopped. If the instance already has an IAM role attached, you must replace it with the new IAM role.

Console

To attach an IAM role to an instance

1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

2. In the navigation pane, choose Instances.

3. Select the instance.

4. Choose Actions, Security, Modify IAM role.

5. For IAM role, select the IAM instance profile.

6. Choose Update IAM role.

AWS CLI

To attach an IAM role to an instance

Use the associate-iam-instance-profile command to attach the IAM role to the instance. When you specify the instance profile, you can use either the Amazon Resource Name (ARN) of the instance profile, or you can use its name.

aws ec2 associate-iam-instance-profile \
    --instance-id i-1234567890abcdef0 \
    --iam-instance-profile Name="TestRole-1"

The following is example output.

{
    "IamInstanceProfileAssociation": {
        "InstanceId": "i-1234567890abcdef0", 
        "State": "associating", 
        "AssociationId": "iip-assoc-0dbd8529a48294120", 
        "IamInstanceProfile": {
            "Id": "AIPAJLNLDX3AMYZNWYYAY", 
            "Arn": "arn:aws:iam::123456789012:instance-profile/TestRole-1"
        }
    }
}

PowerShell

To attach an IAM role to an instance

• Get-EC2Instance

• Register-EC2IamInstanceProfile

To replace the IAM role on an instance that already has an attached IAM role, the instance must be in the running state. You can do this if you want to change the IAM role for an instance without detaching the existing one first. For example, you can do this to ensure that API actions performed by applications running on the instance are not interrupted.

Console

To replace an IAM role for an instance

1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

2. In the navigation pane, choose Instances.

3. Select the instance.

4. Choose Actions, Security, Modify IAM role.

5. For IAM role, select the IAM instance profile.

6. Choose Update IAM role.

AWS CLI

To replace an IAM role for an instance

1. If required, describe your IAM instance profile associations to get the association ID for the IAM instance profile to replace.

   aws ec2 describe-iam-instance-profile-associations

2. Use the replace-iam-instance-profile-association command to replace the IAM instance profile by specifying the association ID for the existing instance profile and the ARN or name of the instance profile that should replace it.

   aws ec2 replace-iam-instance-profile-association \
       --association-id iip-assoc-0044d817db6c0a4ba \
       --iam-instance-profile Name="TestRole-2"

   The following is example output.

   {
       "IamInstanceProfileAssociation": {
           "InstanceId": "i-087711ddaf98f9489", 
           "State": "associating", 
           "AssociationId": "iip-assoc-09654be48e33b91e0", 
           "IamInstanceProfile": {
               "Id": "AIPAJCJEDKX7QYHWYK7GS", 
               "Arn": "arn:aws:iam::123456789012:instance-profile/TestRole-2"
           }
       }
   }

PowerShell

To replace an IAM role for an instance

• Get-EC2IamInstanceProfileAssociation

• Set-EC2IamInstanceProfileAssociation

You can detach an IAM role from a running or stopped instance.

Console

To detach an IAM role from an instance

1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

2. In the navigation pane, choose Instances.

3. Select the instance.

4. Choose Actions, Security, Modify IAM role.

5. For IAM role, choose No IAM Role.

6. Choose Update IAM role.

7. When promoted for confirmation, enter Detach, and then choose Detach.

AWS CLI

To detach an IAM role from an instance

1. If required, use describe-iam-instance-profile-associations to describe your IAM instance profile associations and get the association ID for the IAM instance profile to detach.

   aws ec2 describe-iam-instance-profile-associations

   The following is example output.

   {
       "IamInstanceProfileAssociations": [
           {
               "InstanceId": "i-088ce778fbfeb4361", 
               "State": "associated", 
               "AssociationId": "iip-assoc-0044d817db6c0a4ba", 
               "IamInstanceProfile": {
                   "Id": "AIPAJEDNCAA64SSD265D6", 
                   "Arn": "arn:aws:iam::123456789012:instance-profile/TestRole-2"
               }
           }
       ]
   }

2. Use the disassociate-iam-instance-profile command to detach the IAM instance profile using its association ID.

   aws ec2 disassociate-iam-instance-profile --association-id iip-assoc-0044d817db6c0a4ba

   The following is example output.

   {
       "IamInstanceProfileAssociation": {
           "InstanceId": "i-087711ddaf98f9489", 
           "State": "disassociating", 
           "AssociationId": "iip-assoc-0044d817db6c0a4ba", 
           "IamInstanceProfile": {
               "Id": "AIPAJEDNCAA64SSD265D6", 
               "Arn": "arn:aws:iam::123456789012:instance-profile/TestRole-2"
           }
       }
   }

PowerShell

To detach an IAM role from an instance

• Get-EC2IamInstanceProfileAssociation

• Unregister-EC2IamInstanceProfile