Menu
Amazon EC2 Systems Manager
User Guide

Method 2: Using IAM to Configure Roles for Automation

Automation requires an IAM instance profile role and a service role. The instance profile role gives Automation permission to perform actions on your instances, such as executing commands or starting and stopping services. The service role (also called an assume role) gives Automation permission to assume your IAM role and perform actions on your behalf. For example, the service role, allows Automation to create a new Amazon Machine Image (AMI) when executing the aws:createImage action in an Automation document. You can create an IAM instance profile role and a service role for Systems Manager Automation by using the IAM console, as described in this section.

After you create the instance profile role, you must assign it to any instance that you plan to configure using Automation. For information about how to assign the role to an existing instance, see Attaching an IAM Role to an Instance in the Amazon EC2 User Guide. For information about how to assign the role when you create a new instance, see Task 3: Create an Amazon EC2 Instance that Uses the Systems Manager Role.

Note

You can also use these roles and their Amazon Resource Names (ARNs) in Automation documents, such as the AWS-UpdateLinuxAmi document. Using these roles or their ARNs in Automation documents enables Automation to perform actions on your managed instances, launch new instances, and perform actions on your behalf. To view an example, see Automation CLI Walkthrough: Patch a Linux AMI.

To configure access to Automation, you must perform the following tasks. If you do not configure roles and permissions correctly, Automation returns errors when executing.

Task 1: Create an Instance Profile Role for Systems Manager Managed Instances

Managed instances require an IAM role that gives Systems Manager permission to perform actions on your instances. You can also specify this role in your Automation documents, such as the AWS-UpdateLinuxAmi document, so that Automation can perform actions on your managed instances or launch new instances.

Use the following procedure to create an instance profile role for Systems Manager that uses the AmazonEC2RoleforSSM managed policy. This policy enables the instance to communicate with the Systems Manager API for a limited set of management tasks.

To create an instance profile role for managed instances

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Roles, and then choose Create New Role.

  3. In Step 1: Set Role Name, enter a name that identifies this role as a Systems Manager role for managed instances.

  4. In Step 2: Select Role Type, choose Amazon EC2. The system skips Step 3: Establish Trust because this is a managed policy.

  5. In Step 4: Attach Policy, choose the AmazonEC2RoleforSSM managed policy.

  6. In Step 5: Review, make a note of the role name. You will specify this role name when you create new instances that you want to manage using Automation and in Automation documents.

  7. Choose Create Role. The system returns you to the Roles page.

You can assign the instance profile role to new instances when you create the instance, or you can attach it to an existing instance. For more information, see Working with IAM Roles in the Amazon EC2 User Guide.

Task 2: Create an IAM Role for Automation

Systems Manager Automation needs to have permission to perform the actions that you specify for the service on your behalf. It obtains these permissions by assuming your IAM role. Use the following procedures to:

  • Create a role so that Automation can perform tasks on your behalf while processing Automation documents.

  • Establish a trust relationship between the Automation role and Systems Manager

  • Assign permissions to the role so that you can reference IAM roles within an Automation document.

To create an IAM role and allow Automation to assume it

  1. Open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Roles, and then choose Create New Role.

  3. In Step 1: Select Role Type, choose Amazon EC2. The system skips Step 2: Establish Trust because this is a managed policy.

  4. In Step 3: Attach Policy, choose the AmazonSSMAutomationRole managed policy. They provide the same access permissions.

  5. In Step 4: Set role name and review, enter a name that identifies this role as an Automation role. Make a note of the Role Name and Role ARN. You will specify the role ARN when you attach the iam:PassRole policy to your IAM account in the next procedure. You will also specify the role name and the ARN in Automation json documents.

  6. Choose Create Role. The system returns you to the Roles page.

Note

The AmazonSSMAutomationRole policy assigns the Automation role permission to a subset of AWS Lambda functions within your account. These functions begin with "Automation". If you plan to use Automation with Lambda functions, the Lambda ARN must use the following format:

Copy
"arn:aws:lambda:*:*:function:Automation*"

If you have existing Lambda functions whose ARNs do not use this format, then you must also attach an additional Lambda policy to your automation role, such as the AWSLambdaRole policy. The additional policy or role must provide broader access to Lambda functions within the AWS account.

Task 3: Add a Trust Relationship for Automation

Use the following procedure to configure the role policy to trust Automation.

To add a trust relationship for Automation

  1. In the IAM console, locate the role you just created and double-click it.

  2. Choose the Trust Relationships tab, and then choose Edit Trust Relationship.

  3. Delete "ec2.amazonaws.com" from the existing policy (if it is listed), and then add "Service": "ssm.amazonaws.com", as shown in the following example:

    Copy
    { "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "ssm.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
  4. Choose Update Trust Policy.

  5. Copy or make a note of the Role ARN. You will specify this ARN in your automation document.

Task 4: Attach the iam:PassRole Policy to Your Automation Role

Use the following procedure to attach the iam:PassRole policy to your Automation role. This enables the Automation service to pass the roles you created earlier during execution.

To attach the iam:PassRole policy to your Automation role

  1. In the IAM console, copy the ARNs of the roles created in Tasks 1 and 3.

  2. Locate the Automation role you created in Task 3 and double-click it.

  3. Choose the Permissions tab.

  4. In the Inline Policies section, choose Create User Policy. If you don't see this button, choose the down arrow beside Inline Policies, and then choose click here.

  5. On the Set Permissions page, choose Policy Generator, and then choose Select.

  6. Verify that Effect is set to Allow.

  7. From AWS Services, choose AWS Identity and Access Management.

  8. From Actions, choose PassRole.

  9. In the Amazon Resource Name (ARN) field, paste the Automation role ARN that you created in Task 1.

  10. Choose Add Statement.

  11. From AWS Services, choose AWS Identity and Access Management.

  12. From Actions, choose PassRole.

  13. In the Amazon Resource Name (ARN) field, paste the Automation role ARN that you created in Task 3.

  14. Choose Add Statement, and then choose Next Step.

  15. On the Review Policy page, choose Apply Policy.

Task 5: Configure User Access to Automation

Use the following procedure to configure a user account to use Automation. The user account you choose will have permission to configure and execute Automation. If you need to create a new user account, see Creating an IAM User in Your AWS Account in the IAM User Guide.

Use the following procedure to add the iam:PassRole policy you created in Task 5 to the user account. This enables the user account to pass the role to Automation. In this procedure, you will also configure the account to use the AmazonSSMFullAccess policy so the account can communicate with the Systems Manager API.

To attach the iam:PassRole policy to a user account

  1. In the IAM navigation pane, choose Users, and then double-click the user account you want to configure.

  2. In the Managed Policies section, verify that either the AmazonSSMFullAccess policy is listed or there is a comparable policy that gives the account permissions for the SSM API.

  3. In the Inline Policies section, choose Create User Policy. If you don't see this button, choose the down arrow beside Inline Policies, and then choose click here.

  4. On the Set Permissions page, choose Policy Generator, and then choose Select.

  5. Verify that Effect is set to Allow.

  6. From AWS Services, choose AWS Identity and Access Management.

  7. From Actions, choose PassRole.

  8. In the Amazon Resource Name (ARN) field, paste the ARN for the Automation role you created in Task 3.

  9. Choose Add Statement, and then choose Next Step.

  10. On the Review Policy page, choose Apply Policy.

You can further delegate access to Automation by using a more restrictive IAM user policy. For more information, see Create a Restrictive IAM User Policy.