Configuring IAM Roles and Users for SSM Run Command
SSM Run Command requires an IAM role for EC2 instances that will process commands and a separate role for users executing commands. Both roles require permission policies that enable them to communicate with the SSM API. If you want to use an existing IAM role for EC2 instances, you must verify that ec2.amazonaws.com is listed in the trust policy for the role. For more information, see Verify the Trust Policy.
Important
You must assign the EC2 instance role when you create the instance. Or, you can create an AMI from an existing instance, create new instances from that AMI, and assign this role. You can choose to use SSM managed policies or you can create your own roles and specify permissions as shown in the examples provided.
Contents
Use Caution Delegating Access to Run Command
The commands or scripts specified in SSM documents run with administrative privilege on your instances because the Amazon SSM agent runs as root on Linux instances. If a user has permission to execute any of the pre-defined SSM documents (any document that begins with AWS-*), then that user also has administrator access to the instance. Delegate access to SSM and Run Command judiciously. This becomes extremely important if you create your own SSM documents.
Important
Amazon Web Services does not provide guidance about how to create secure SSM documents. You create SSM documents and delegate access to Run Command actions at your own risk. As a security best practice, we recommend that you assign access to AWS-* documents, especially the AWS-RunShellScript document, to trusted administrators only. You can create SSM documents for specific tasks and delegate access to non-administrators. For more information, see Delegating Access to SSM Run Command.
Use SSM Managed Policies
Run Command is an extension of Amazon EC2 Simple Systems Manager (SSM) for configuring EC2 instances. IAM managed policies for SSM can help you quickly configure access and permissions for Run Command users and instances. You can find these policies in the Policies page of the IAM console by searching for SSM, as shown in the following screen shot.
The managed policies perform the following functions:
AmazonEC2RoleforSSM (instance trust policy): This policy enables the instance to communicate with the Run Command API.
AmazonSSMFullAccess (user trust policy): This policy gives the user access to the Run Command API and SSM documents. Assign this policy to administrators and trusted power users.
AmazonSSMReadOnlyAccess (user trust policy): This policy gives the user access to read-only API actions, such as Get and List.
For information about how to configure these policies, see Managed Policies and Inline Policies.
Configure Your Own Roles and Polices
If you choose not to use SSM managed policies, then use the following procedures to create and configure an SSM EC2 instance role and an SSM user account.
Important
If you want to use an existing EC2 instance role and user account, you must attach the policies shown in this section to the role and the user account. You must also verify that ec2.amazonaws.com is listed in the trust policy for the EC2 instance role. For more information, see Verify the Trust Policy.
Create the IAM Policy for EC2 Instances
The following IAM policy enables EC2 instances to communicate with the Run Command API actions. You will create the role and attach this policy to that role later in this topic.
To create an IAM policy for EC2 instance
Open the Identity and Access Management (IAM) console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Policies. (If this is your first time using IAM, choose Get Started, and then choose Create Policy.)
Beside Create Your Own Policy, choose Select.
Type a policy name (for example, RunCommandInstance) and description, and then copy and paste the following policy into the Policy Document field:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:DescribeAssociation", "ssm:GetDocument", "ssm:ListAssociations", "ssm:UpdateAssociationStatus", "ssm:UpdateInstanceInformation" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2messages:AcknowledgeMessage", "ec2messages:DeleteMessage", "ec2messages:FailMessage", "ec2messages:GetEndpoint", "ec2messages:GetMessages", "ec2messages:SendReply" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "cloudwatch:PutMetricData" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2:DescribeInstanceStatus" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ds:CreateComputer", "ds:DescribeDirectories" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:PutLogEvents" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:AbortMultipartUpload", "s3:ListMultipartUploadParts", "s3:ListBucketMultipartUploads" ], "Resource": "*" } ] }Important
In the last section of this IAM policy, you can restrict access to the Amazon S3 bucket by specifying an Amazon Resource Name (ARN). For example, you can change the last "Resource": "*" item to "Resource": "arn:aws:s3:::
AnS3Bucket/*Choose Validate Policy. Verify that the policy is valid. If you receive an error, verify that you included the opening and closing brackets { }. After the policy is validated, choose Create Policy.
Create the IAM User Policy
This policy enables a user to call Run Command API actions on the instances. You will create a user account and attach this policy to that account later in this topic.
To create the IAM user policy
Repeat the previous procedure to create a policy for a user.
Copy and paste the following policy into the Policy Document field and create the policy:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:*", "ec2:DescribeInstanceStatus" ], "Resource": "*" } ] }
Create the EC2 Instance Role
The EC2 Instance role enables the instance to communicate with Run Command API actions. The role uses the EC2 instance policy you created earlier.
To create the EC2 instance role
In the navigation pane of the IAM console, choose Roles, and then choose Create New Role.
On the Set Role Name page, enter a name for the role that designates it as the instance role, for example, RunCommandInstance. Choose Next Step.
On the Select Role Type page, choose Select next to Amazon EC2.
On the Attach Policy page, select the RunCommandInstance policy you created earlier. Choose Next Step.
Review the role information and then choose Create Role.
Verify the Trust Policy
If you want to use an existing EC2 instance role, you must verify that ec2.amazonaws.com is listed in the trust policy for the role. If you created a new EC2 instance role, you must add ec2.amazonaws.com as a trusted entity.
To verify the trust policy
In the navigation pane of the IAM console, choose Roles, and then choose the server role you just created.
Choose Trust Relationships.
Under Trusted Entities verify that ec2.amazonaws.com is listed. If it's not listed, choose Edit Trust Relationship.
Copy and paste the following policy into the Policy Document field and create the policy:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } ] }
Create the User Account
The user account enables a user to call Run Command API actions on an instance. This account uses the IAM user policy you created earlier.
To create the user account
From the Users page on the IAM console, choose Create New Users.
Specify a user name (for example, RunCommandUser) and verify that the Generate an access key for each user option is selected.
Choose Create.
Choose Download Credentials. By default, the system prompts you to save the credentials as a .csv file.
Important
Make a note of the RunCommandUser access key and secret key from the .csv file you downloaded.
Choose Close.
In the IAM Dashboard, choose Users, and then locate the user you just created.
Choose the user name (do not select the option beside the name), and then choose Attach Policy.
Choose the user policy you created earlier, and then choose Attach Policy.
Create New EC2 Instances that Use the EC2 Instance Role
This procedure describes how to create a new EC2 instance that uses the role you created earlier. A role is assigned to an EC2 instance when you launch it. It can't be assigned to an instance that is already running. If you need to add a role to an instance that is already running, you can create an image of the instance, and then launch a new instance from the image with the desired role assigned.
To create an instance that use the EC2 instance role
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
Switch to a supported region.
Choose Launch Instance and select a Linux instance.
Choose your instance type and then choose Next: Configure Instance Details.
In the IAM role drop-down list choose the EC2 instance role you created earlier.
Complete the wizard.
If you create other instances that you want to configure with Run Command, you must specify the EC2 instance role for each instance.
