Install SSM Agent for a hybrid environment (Windows)

Step 1: Complete general Systems Manager setup steps

If you haven't already done so, complete the following general setup steps for AWS Systems Manager in the Setting up AWS Systems Manager for EC2 instances (p. 17) section of this user guide. The other steps in that section are required only if you plan to manage Amazon Elastic Compute Cloud (Amazon EC2) instances.

• Sign up for AWS (p. 18)

• Create an Admin IAM user for AWS (p. 18)

• Create non-Admin IAM users and groups for Systems Manager (p. 19)

• (Optional) Create a Virtual Private Cloud endpoint (p. 29)

• (Optional) Create Systems Manager service roles (p. 33)

• (Optional) Set Up integrations with other AWS services (p. 35)

After ensuring that you have completed those steps, continue to Step 2: Create an IAM service role for a hybrid environment (p. 37).

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

Servers and virtual machines (VMs) in a hybrid environment require an AWS Identity and Access Management (IAM) role to communicate with the AWS Systems Manager service. The role grants AWS Security Token Service (AWS STS) AssumeRole trust to the Systems Manager service. You only need to create a service role for a hybrid environment once for each AWS account. However, you might choose to create multiple service roles for diﬀerent hybrid activations if machines in your hybrid environment require diﬀerent 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

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

machines to be able to access other capabilities or AWS services. For example, without access to the required AWS managed Amazon Simple Storage Service (Amazon S3) buckets, Patch Manager patching operations fail.

To create a service role (console)

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

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

3. Mark the following selections:

1.Select type of trusted entity area: AWS service

2.Choose the service that will use this role area: Systems Manager 4. Choose Next: Permissions.

5. In the list of policies, select the box next to AmazonSSMManagedInstanceCore, and then choose Next: Tags.

6. (Optional) Add one or more tag-key value pairs to organize, track, or control access for this role, and then choose Next: Review.

7. In Role name, enter a name that identiﬁes this role as a hybrid activation service role. For example:

my-hybrid-service-role.

8. (Optional) Change the default role description to reﬂect the purpose of this role. For example:

Provides permissions for on-premises machines.

9. 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 AWS 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 AWS services and VPC endpoint services powered by AWS 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 proﬁle (p. 26). The information about S3 bucket policies in that topic also applies to your service role.

AWS CLI

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

1. Install and conﬁgure the AWS Command Line Interface (AWS CLI), if you haven't already.

For information, see Install or upgrade AWS command line tools (p. 61).

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

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

{ "Version":"2012-10-17", "Statement":[

{

"Sid":"",

"Effect":"Allow", "Principal":{

"Service":"ssm.amazonaws.com"

"Action":"sts:AssumeRole", "Condition":{

"StringEquals":{

"aws:SourceAccount":"123456789012"

"ArnEquals":{

"aws:SourceArn":"arn:aws:ssm:us-east-2:123456789012:*"

} } } ]}

3. Open the AWS CLI, and in the directory where you created the JSON ﬁle, 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 & 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

4. 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.

Note

The policies you add for a service proﬁle for managed instances in a hybrid

environment are the same policies used to create an instance proﬁle for Amazon Elastic Compute Cloud (Amazon EC2) instances. For more information about the AWS policies used in the following commands, see Create an IAM instance proﬁle for Systems Manager (p. 22).

(Required) Run the following command to allow a managed instance to use AWS Systems Manager service core functionality.

Linux & macOS

aws iam attach-role-policy \ --role-name SSMServiceRole \

--policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

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

Windows

aws iam attach-role-policy ^ --role-name SSMServiceRole ^

--policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

If you created a custom S3 bucket policy for your service role, run the following command to allow AWS Systems Manager Agent (SSM Agent) to access the buckets you speciﬁed in the policy. Replace account-id and my-bucket-policy-name with your AWS account ID and your bucket name.

Linux & macOS

aws iam attach-role-policy \ --role-name SSMServiceRole \

--policy-arn arn:aws:iam::account-id:policy/my-bucket-policy-name

Windows

aws iam attach-role-policy ^ --role-name SSMServiceRole ^

--policy-arn arn:aws:iam::account-id:policy/my-bucket-policy-name

(Optional) Run the following command to allow SSM Agent to access AWS Directory Service on your behalf for requests to join the domain by the managed instance. Your instance proﬁle needs this policy only if you join your instances to a Microsoft AD directory.

Linux & macOS

aws iam attach-role-policy \ --role-name SSMServiceRole \

--policy-arn arn:aws:iam::aws:policy/AmazonSSMDirectoryServiceAccess

Windows

aws iam attach-role-policy ^ --role-name SSMServiceRole ^

--policy-arn arn:aws: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 proﬁle 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:iam::aws:policy/CloudWatchAgentServerPolicy

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

Tools for PowerShell

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

1. Install and conﬁgure the AWS Tools for PowerShell, if you haven't already.

For information, see Install or upgrade AWS command line tools (p. 61).

"aws:SourceArn":"arn:aws:ssm:us-east-2:123456789012:*"

} } } ] }

3. Open PowerShell in administrative mode, and in the directory where you created the JSON ﬁle, 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)

4. 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.

Note

The policies you add for a service proﬁle for managed instances in a hybrid

environment are the same policies used to create an instance proﬁle for EC2 instances.

For more information about the AWS policies used in the following commands, see Create an IAM instance proﬁle for Systems Manager (p. 22).

(Required) Run the following command to allow a managed instance to use AWS Systems Manager service core functionality.

-PolicyArn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

Step 3: Create a managed-instance activation for a hybrid environment

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 speciﬁed in the policy. Replace account-id and my-bucket-policy-name with your AWS account ID and your bucket name.

-PolicyArn arn:aws:iam::account-id:policy/my-bucket-policy-name

-PolicyArn arn:aws:iam::aws:policy/AmazonSSMDirectoryServiceAccess

-PolicyArn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy

Continue to Step 3: Create a managed-instance activation for a hybrid environment (p. 42).

Step 3: Create a managed-instance activation for a hybrid environment

To set up servers and virtual machines (VMs) in your hybrid environment as managed instances, you need to create a managed-instance activation. After you successfully complete the activation, you immediately receive an Activation Code and Activation ID. You specify this Code/ID combination when you install AWS Systems Manager SSM Agent on servers and VMs in your hybrid environment. The Code/ID provides secure access to the Systems Manager service from your managed instances.

Important

Systems Manager immediately returns the Activation Code and ID to the console or the command window, depending on how you created the activation. Copy this information and store it in a safe place. If you navigate away from the console or close the command window, you might lose this information. If you lose it, you must create a new activation.

About activation expirations

An activation expiration is a window of time when you can register on-premises machines with Systems Manager. An expired activation has no impact on your servers or virtual machines (VMs) that you previously registered with Systems Manager. If an activation expires then you can’t register more servers or VMs with Systems Manager by using that speciﬁc activation. You simply need to create a new one.

Every on-premises server and VM you previously registered remains registered as a Systems Manager managed instance until you explicitly deregister it. You can deregister a managed instance on the Fleet Manager page and Managed Instances tab of the Systems Manager console, by using the AWS CLI command deregister-managed-instance, or by using the API call DeregisterManagedInstance.

About activation tags

Step 3: Create a managed-instance activation for a hybrid environment

If you create an activation by using either the AWS Command Line Interface (AWS CLI) or AWS Tools for Windows PowerShell, you can specify tags. Tags are optional metadata that you assign to a resource.

Tags allow you to categorize a resource in diﬀerent ways, such as by purpose, owner, or environment.

Here is an AWS CLI sample command to run on a local Linux machine that includes optional tags.

aws ssm create-activation \

--default-instance-name MyWebServers \

--description "Activation for Finance department webservers" \ --iam-role service-role/AmazonEC2RunCommandRoleForManagedInstances \ --registration-limit 10 \

--region us-east-2 \

--tags "Key=Department,Value=Finance"

If you specify tags when you create an activation, then those tags are automatically assigned to your on-premises servers and VMs when you activate them.

You can't add tags to or delete tags from an existing activation. If you don't want to automatically assign tags to your on-premises servers and VMs using an activation, then you can add tags to them later. More speciﬁcally, you can tag your on-premises servers and VMs after they connect to Systems Manager for the ﬁrst time. After they connect, they're assigned a managed instance ID and listed in the Systems Manager console with an ID that is preﬁxed with "mi-". For information about how to add tags to your managed instances without using the activation process, see Tagging managed nodes (p. 1495).

Note

You can't assign tags to an activation if you create it by using the Systems Manager console. You must create it by using either the AWS CLI or Tools for Windows PowerShell.

If you no longer want to manage an on-premises server or virtual machine (VM) by using Systems Manager, you can deregister it. For information, see Deregistering managed nodes in a hybrid environment (p. 795).

Topics

• Create an activation (console) (p. 43)

• Create a managed instance activation (command line) (p. 44)

Create an activation (console)

To create a managed-instance activation

1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

2. In the navigation pane, choose Hybrid Activations.

-or-If the AWS Systems Manager home page opens ﬁrst, choose the menu icon ( ) to open the navigation pane, and then choose Hybrid Activations.

3. Choose Create activation.

4. (Optional) In the Activation description ﬁeld, enter a description for this activation. The description is optional, be we recommend that you enter a description if you plan to activate large numbers of servers and VMs.

5. In the Instance limit ﬁeld, specify the total number of on-premises servers or VMs that you want to register with AWS as part of this activation. The default value is 1 instance.

6. In the IAM role name section, choose a service role option that allows your servers and VMs to communicate with AWS Systems Manager in the cloud:

Step 3: Create a managed-instance activation for a hybrid environment

a. Choose Use the system created default command execution role to use a role and managed policy created by AWS.

b. Choose Select an existing custom IAM role that has the required permissions to use the optional custom role you created earlier. This role must have a trust relationship policy that speciﬁes "Service": "ssm.amazonaws.com". If your IAM role doesn't specify this principle in a trust relationship policy, you receive the following error:

An error occurred (ValidationException) when calling the CreateActivation operation: Not existing role:

arn:aws:iam::<accountid>:role/SSMRole

For more information about creating this role, see Step 2: Create an IAM service role for a hybrid environment (p. 37).

7. In the Activation expiry date ﬁeld, specify an expiration date for the activation. The expiry date must be in the future, and not more than 30 days into the future. The default value is 24 hours.

Note

If you want to register additional managed instances after the expiry date, you must create a new activation. The expiry date has no impact on registered and running instances.

8. (Optional) In the Default instance name ﬁeld, specify a name.

9. Choose Create activation. Systems Manager immediately returns the Activation Code and ID to the console.

Create a managed instance activation (command line)

The following procedure describes how to use the AWS Command Line Interface (AWS CLI) (on Linux or Windows) or AWS Tools for PowerShell to create a managed instance activation.

To create an activation

1. Install and conﬁgure the AWS CLI or the AWS Tools for PowerShell, if you haven't already.

For information, see Install or upgrade AWS command line tools (p. 61).

2. Run the following command to create an activation.

Note

• region represents the identiﬁer for an AWS Region supported by AWS Systems Manager, such as us-east-2 for the US East (Ohio) Region. For a list of supported region values, see the Region column in Systems Manager service endpoints in the Amazon Web Services General Reference.

• The role you specify for the iam-role parameter must have a trust relationship policy that speciﬁes "Service": "ssm.amazonaws.com". If your AWS Identity and Access Management (IAM) role doesn't specify this principle in a trust relationship policy, you receive the following error:

An error occurred (ValidationException) when calling the CreateActivation operation: Not existing role:

arn:aws:iam::<accountid>:role/SSMRole

For more information about creating this role, see Step 2: Create an IAM service role for a hybrid environment (p. 37).

• For --expiration-date, provide a date in timestamp format, such as

"2021-07-07T00:00:00", for when the activation code expires. You can specify a date

Step 3: Create a managed-instance activation for a hybrid environment

up to 30 days in advance. If you don't provide an expiration date, the activation code expires in 24 hours.

Linux & macOS

aws ssm create-activation \ --default-instance-name name \ --iam-role iam-service-role-name \

--registration-limit number-of-managed-instances \ --region region \

--expiration-date "timestamp" \\

--tags "Key=key-name-1,Value=key-value-1" "Key=key-name-2,Value=key-value-2"

Windows

aws ssm create-activation ^ --default-instance-name name ^ --iam-role iam-service-role-name ^

--registration-limit number-of-managed-instances ^ --region region ^

--expiration-date "timestamp" ^

--tags "Key=key-name-1,Value=key-value-1" "Key=key-name-2,Value=key-value-2"

PowerShell

New-SSMActivation -DefaultInstanceName name ` -IamRole iam-service-role-name `

-RegistrationLimit number-of-managed-instances ` –Region region `

-ExpirationDate "timestamp" `

-Tag @{"Key"="key-name-1";"Value"="key-value-1"},@{"Key"="key-name-2";"Value"="key-value-2"}

Here is an example.

Linux & macOS

aws ssm create-activation \

--default-instance-name MyWebServers \

--iam-role service-role/AmazonEC2RunCommandRoleForManagedInstances \ --registration-limit 10 \

--region us-east-2 \

--expiration-date "2021-07-07T00:00:00" \

--tags "Key=Environment,Value=Production" "Key=Department,Value=Finance"

Windows

aws ssm create-activation ^

--default-instance-name MyWebServers ^

--iam-role service-role/AmazonEC2RunCommandRoleForManagedInstances ^ --registration-limit 10 ^

--region us-east-2 ^

--expiration-date "2021-07-07T00:00:00" ^

--tags "Key=Environment,Value=Production" "Key=Department,Value=Finance"

Step 4: Install SSM Agent for a hybrid environment (Linux)

PowerShell

New-SSMActivation -DefaultInstanceName MyWebServers `

-IamRole service-role/AmazonEC2RunCommandRoleForManagedInstances ` -RegistrationLimit 10 `

–Region us-east-2 `

-ExpirationDate "2021-07-07T00:00:00" ` -Tag

@{"Key"="Environment";"Value"="Production"},@{"Key"="Department";"Value"="Finance"}

If the activation is created successfully, the system immediately returns an Activation Code and ID.

Continue to Step 5: Install SSM Agent for a hybrid environment (Windows) (p. 51).

Step 4: Install SSM Agent for a hybrid environment (Linux)

This topic describes how to install AWS Systems Manager SSM Agent on Linux machines in a hybrid environment. If you plan to use Windows Server machines in a hybrid environment, see the next step, Step 5: Install SSM Agent for a hybrid environment (Windows) (p. 51).

Important

This procedure is for servers and virtual machines (VMs) in an on-premises or hybrid

在文檔中 AWS Systems Manager (頁 47-64)