Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.
Step 2: 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. Please
note that 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 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.
-
Mark the following selections:
-
Select type of trusted entity area:
Amazon service
-
Choose the service that will use this role
area: Systems Manager
-
Choose Next.
-
In the list of policies, select the box next to
AmazonSSMManagedInstanceCore, and then choose
Next.
-
In Role name, enter a name that identifies this role
as a hybrid activation service role. For example:
my-hybrid-service-role
.
-
(Optional) Add one or more tag-key value pairs to organize, track, or
control access for this role, and then choose Next:
Review.
-
(Optional) Change the default role description to reflect the purpose of
this role. For example: Provides permissions for on-premises
machines
.
-
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. Please
note that 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 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 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 Install or upgrade Amazon command line tools.
-
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 instance permission to run
commands using Systems Manager.
The policies you add for a service profile for managed
instances 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
instance 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 instance. Your instance profile needs this policy
only if you join your instances 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 instances. This command makes it possible to
read information on an instance 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, if you haven't already.
For information, see Install or upgrade Amazon command line tools.
-
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: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 instance permission to run commands
using Systems Manager.
The policies you add for a service profile for managed
instances 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
instance 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 instance. Your instance profile needs this policy
only if you join your instances 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 instances. This command makes it possible to
read information on an instance 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 3: Create a managed-instance
activation for a hybrid environment.