Create an IAM service role (console)Create an IAM service role (command line)

Step 1: Create an IAM service role for a hybrid environment

Servers and virtual machines (VMs) in a hybrid environment require an Amazon Identity and Access Management (IAM) role to communicate with the Amazon Systems Manager service. The role grants Amazon Security Token Service (Amazon STS) AssumeRole trust to the Systems Manager service. You only need to create a service role for a hybrid environment once for each Amazon Web Services account. However, you might choose to create multiple service roles for different hybrid activations if machines in your hybrid environment require different permissions.

The following procedures describe how to create the required service role using the Systems Manager console or your preferred command line tool.

Create an IAM service role (console)

Use the following procedure to create a service role for hybrid activation. This procedure uses the AmazonSSMManagedInstanceCore policy for Systems Manager core functionality. Depending on your use case, you might need to add additional policies to your service role for your on-premises machines to be able to access other capabilities or Amazon Web Services. For example, without access to the required Amazon managed Amazon Simple Storage Service (Amazon S3) buckets, Patch Manager patching operations fail.

To create a service role (console)

Open the IAM console at https://console.amazonaws.cn/iam/.
In the navigation pane, choose Roles, and then choose Create role.
For Select trusted entity, make the following choices:
1. For Trusted entity type, choose Amazon Web Service.
2. For Use cases for other Amazon Web Services, choose Systems Manager.
3. Choose Systems Manager.
Choose Next.
On the Add permissions page, do the following:
- Use the Search field to locate the AmazonSSMManagedInstanceCore policy. Select the check box next to its name.
- The console retains your selection even if you search for other policies.
- If you created a custom S3 bucket policy in the procedure Task 1: (Optional) Create a custom policy for S3 bucket access, search for it and select the check box next to its name.
- If you plan to join instances to an Active Directory managed by Amazon Directory Service, search for AmazonSSMDirectoryServiceAccess and select the check box next to its name.
- If you plan to use EventBridge or CloudWatch Logs to manage or monitor your instance, search for CloudWatchAgentServerPolicy and select the check box next to its name.
Choose Next.
For Role name, enter a name for your new instance profile, such as SSMInstanceProfile.

Note
Make a note of the role name. You will choose this role when you create new instances that you want to manage by using Systems Manager.
(Optional) For Description, update the description for this instance profile.
(Optional) For Tags, add one or more tag-key value pairs to organize, track, or control access for this role.
Choose Create role. The system returns you to the Roles page.

Create an IAM service role (command line)

Use the following procedure to create a service role for hybrid activation. This procedure uses the AmazonSSMManagedInstanceCore policy Systems Manager core functionality. Depending on your use case, you might need to add additional policies to your service role for your on-premises machines to be able to access other capabilities or Amazon Web Services.

S3 bucket policy requirement

If either of the following cases are true, you must create a custom IAM permission policy for Amazon Simple Storage Service (Amazon S3) buckets before completing this procedure:

Case 1 – You're using a VPC endpoint to privately connect your VPC to supported Amazon Web Services and VPC endpoint services powered by Amazon PrivateLink.
Case 2 – You plan to use an Amazon S3 bucket that you create as part of your Systems Manager operations, such as for storing output for Run Command commands or Session Manager sessions to an Amazon S3 bucket. Before proceeding, follow the steps in Create a custom S3 bucket policy for an instance profile. The information about S3 bucket policies in that topic also applies to your service role.

Amazon CLI

To create an IAM service role for a hybrid environment (Amazon CLI)

Install and configure the Amazon Command Line Interface (Amazon CLI), if you haven't already.

For information, see Installing or updating the latest version of the Amazon CLI.

On your local machine, create a text file with a name such as SSMService-Trust.json with the following trust policy. Make sure to save the file with the .json file extension. Be sure to specify your Amazon Web Services account and the Amazon Web Services Region in the ARN where you created your hybrid activation.


{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Sid":"",
         "Effect":"Allow",
         "Principal":{
            "Service":"ssm.amazonaws.com.cn"
         },
         "Action":"sts:AssumeRole",
         "Condition":{
            "StringEquals":{
               "aws:SourceAccount":"123456789012"
            },
            "ArnEquals":{
               "aws:SourceArn":"arn:aws-cn:ssm:us-east-2:123456789012:*"
            }
         }
      }
   ]
}

Open the Amazon CLI, and in the directory where you created the JSON file, run the create-role command to create the service role. This example creates a role named SSMServiceRole. You can choose another name if you prefer.
Linux & macOSWindows
Linux & macOS
```
aws iam create-role \
    --role-name SSMServiceRole \
    --assume-role-policy-document file://SSMService-Trust.json 
```
Windows
```
aws iam create-role ^
    --role-name SSMServiceRole ^
    --assume-role-policy-document file://SSMService-Trust.json 
```
Run the attach-role-policy command as follows to allow the service role you just created to create a session token. The session token gives your managed node permission to run commands using Systems Manager.

Note
The policies you add for a service profile for managed nodes in a hybrid environment are the same policies used to create an instance profile for Amazon Elastic Compute Cloud (Amazon EC2) instances. For more information about the Amazon policies used in the following commands, see Create an IAM instance profile for Systems Manager.

(Required) Run the following command to allow a managed node to use Amazon Systems Manager service core functionality.
Linux & macOSWindows
Linux & macOS
```
aws iam attach-role-policy \
    --role-name SSMServiceRole \
    --policy-arn arn:aws-cn:iam::aws:policy/AmazonSSMManagedInstanceCore  
```
Windows
```
aws iam attach-role-policy ^
    --role-name SSMServiceRole ^
    --policy-arn arn:aws-cn:iam::aws:policy/AmazonSSMManagedInstanceCore 
```
If you created a custom S3 bucket policy for your service role, run the following command to allow Amazon Systems Manager Agent (SSM Agent) to access the buckets you specified in the policy. Replace account-id and my-bucket-policy-name with your Amazon Web Services account ID and your bucket name.
Linux & macOSWindows
Linux & macOS
```
aws iam attach-role-policy \
    --role-name SSMServiceRole \
    --policy-arn arn:aws-cn:iam::account-id:policy/my-bucket-policy-name
```
Windows
```
aws iam attach-role-policy ^
    --role-name SSMServiceRole ^
    --policy-arn arn:aws-cn:iam::account-id:policy/my-bucket-policy-name
```
(Optional) Run the following command to allow SSM Agent to access Amazon Directory Service on your behalf for requests to join the domain by the managed node. Your service role needs this policy only if you join your nodes to a Microsoft AD directory.
Linux & macOSWindows
Linux & macOS
```
aws iam attach-role-policy \
    --role-name SSMServiceRole \
    --policy-arn arn:aws-cn:iam::aws:policy/AmazonSSMDirectoryServiceAccess
```
Windows
```
aws iam attach-role-policy ^
    --role-name SSMServiceRole ^
    --policy-arn arn:aws-cn:iam::aws:policy/AmazonSSMDirectoryServiceAccess
```
(Optional) Run the following command to allow the CloudWatch agent to run on your managed nodes. This command makes it possible to read information on a node and write it to CloudWatch. Your service profile needs this policy only if you will use services such as Amazon EventBridge or Amazon CloudWatch Logs.
```
aws iam attach-role-policy \
    --role-name SSMServiceRole \
    --policy-arn arn:aws-cn:iam::aws:policy/CloudWatchAgentServerPolicy
```

Tools for PowerShell

To create an IAM service role for a hybrid environment (Amazon Tools for Windows PowerShell)

Install and configure the Amazon Tools for PowerShell (Tools for Windows PowerShell), if you haven't already.

For information, see Installing the Amazon Tools for PowerShell.


{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Sid":"",
         "Effect":"Allow",
         "Principal":{
            "Service":"ssm.amazonaws.com.cn"
         },
         "Action":"sts:AssumeRole",
         "Condition":{
            "StringEquals":{
               "aws:SourceAccount":"123456789012"
            },
            "ArnEquals":{
               "aws:SourceArn":"arn:aws-cn:ssm:region:123456789012:*"
            }
         }
      }
   ]
}

Open PowerShell in administrative mode, and in the directory where you created the JSON file, run New-IAMRole as follows to create a service role. This example creates a role named SSMServiceRole. You can choose another name if you prefer.
```
New-IAMRole `
    -RoleName SSMServiceRole `
    -AssumeRolePolicyDocument (Get-Content -raw SSMService-Trust.json)
```
Use Register-IAMRolePolicy as follows to allow the service role you created to create a session token. The session token gives your managed node permission to run commands using Systems Manager.

Note
The policies you add for a service profile for managed nodes in a hybrid environment are the same policies used to create an instance profile for EC2 instances. For more information about the Amazon policies used in the following commands, see Create an IAM instance profile for Systems Manager.

(Required) Run the following command to allow a managed node to use Amazon Systems Manager service core functionality.
```
Register-IAMRolePolicy `
    -RoleName SSMServiceRole `
    -PolicyArn arn:aws-cn:iam::aws:policy/AmazonSSMManagedInstanceCore
```
If you created a custom S3 bucket policy for your service role, run the following command to allow SSM Agent to access the buckets you specified in the policy. Replace account-id and my-bucket-policy-name with your Amazon Web Services account ID and your bucket name.
```
Register-IAMRolePolicy `
    -RoleName SSMServiceRole `
    -PolicyArn arn:aws-cn:iam::account-id:policy/my-bucket-policy-name
```
(Optional) Run the following command to allow SSM Agent to access Amazon Directory Service on your behalf for requests to join the domain by the managed node. Your instance profile needs this policy only if you join your nodes to a Microsoft AD directory.
```
Register-IAMRolePolicy `
    -RoleName SSMServiceRole `
    -PolicyArn arn:aws-cn:iam::aws:policy/AmazonSSMDirectoryServiceAccess
```
(Optional) Run the following command to allow the CloudWatch agent to run on your managed nodes. This command makes it possible to read information on a node and write it to CloudWatch. Your service profile needs this policy only if you will use services such as Amazon EventBridge or Amazon CloudWatch Logs.
```
Register-IAMRolePolicy `
    -RoleName SSMServiceRole `
    -PolicyArn arn:aws-cn:iam::aws:policy/CloudWatchAgentServerPolicy
```

Continue to Step 2: Create a managed-node activation for a hybrid environment.

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Setting up hybrid environments

Step 2: Create a managed-node activation for a hybrid environment