Delegating Access to Amazon EC2 Run Command

Amazon EC2 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. You can choose to use SSM managed policies or you can create your own roles and specify permissions as described in this section.

If you are configuring on-premises servers or VMs or VMs hosted by other cloud providers that you want to configure using Run Command you must also configure an IAM service role. For more information, see Create an IAM Service Role.

This section includes the following information.

After you configure roles and policies, we recommend that you further delegate access by creating commands that perform specific operations and assign access to specific users. For low-level actions that anyone in your group can perform, you can create low-level commands and make them public. For more information, see Creating SSM Documents.

Use SSM Managed Policies

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): Enables an instance to communicate with the Run Command API.
AmazonSSMFullAccess (user trust policy): Grants the user access to the Run Command API and SSM JSON documents. Assign this policy to administrators and trusted power users.
AmazonSSMReadOnlyAccess (user trust policy): Grants 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.

Topics

Create the IAM Policy for EC2 Instances

The following IAM policy enables EC2 instances to communicate with the Run Command API. You will create the role and attach this policy to that role later in this topic.

To create an IAM policy for EC2 instances

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

The IAM user policy determines which SSM documents a user can see in the Command document list. Users can see this list in either the Amazon EC2 console or by calling ListDocuments using the AWS CLI. The policy also limits the actions the user can perform with an SSM JSON document.

Note

You will create a user account and attach this policy to that account later on.

The IAM policy in the following procedure enables the user to perform any SSM action on the instance. Assign this policy only to trusted administrators. For all other users, create a restrictive IAM policy, as described in this section.

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 a Restrictive IAM User Policy

Create restrictive IAM user policies to further delegate access to Run Command. The following example IAM policy allows a user to list SSM JSON documents and view details about those documents, send a command using the document, and cancel or view details about the command after it has been sent. The user has permission to execute the document on three instances, as determined by the "arn:aws:ec2:us-east-1:*:instance/i-xxxxxxxxxxxxxxxxx" items in the second Resource section. If you want to give the user access to run the command on any instance for which the user currently has access (as determined by the AWS user account), you could specify "arn:aws:ec2:us-east-1:*:instance/*" in the Resource section and remove the other instance resources.

Note that the Resource section includes an S3 ARN entry:

arn:aws:s3:::bucket_name

You can also format this entry as follows:

arn:aws:s3:::bucket_name/*

-or-

arn:aws:s3:::bucket_name/key_prefix_name

{
     "Version": "2012-10-17",
     "Statement": [
           {
                "Action": [
                     "ssm:ListDocuments",
                     "ssm:DescribeDocument",
                     "ssm:GetDocument",
                     "ssm:DescribeInstanceInformation"
                ],
                "Effect": "Allow",
                "Resource": "*"
           },
           {
                "Action": "ssm:SendCommand",
                "Effect": "Allow",
                "Resource": [
                     "arn:aws:ec2:us-east-1:*:instance/i-1234567890abcdef0",
                     "arn:aws:ec2:us-east-1:*:instance/i-0598c7d356eba48d7",
                     "arn:aws:ec2:us-east-1:*:instance/i-345678abcdef12345",
                     "arn:aws:s3:::bucket_name",
                     "arn:aws:ssm:us-east-1:*:document/RestartLinuxService"
                ]
           },
           {
                "Action": [
                	 "ssm:CancelCommand",
                     "ssm:ListCommands",
                     "ssm:ListCommandInvocations"
                ],
                "Effect": "Allow",
                "Resource": "*"
           },
           {
                "Action": "ec2:DescribeInstanceStatus",
                "Effect": "Allow",
                "Resource": "*"
           }
     ]
}

For more information about creating IAM user policies, see Managed Policies and Inline Policies.

Create the EC2 Instance Role

The EC2 Instance role enables the instance to communicate with the Run Command API. 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 the Run Command API 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 EC2 Instances that Use the EC2 Instance Role

This procedure describes how to create an EC2 instance that uses the role you created. You must assign a role to an EC2 instance when you launch it. You can't assign a role to an instance that is already running. Instead, you would create an image of the instance, and then launch an instance from that image, with the role assigned.

To create an instance that use the EC2 instance role

Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
Select 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 using Run Command, you must specify the EC2 instance role for each instance.

Document Conventions

« Previous Next »