Menu
Amazon EC2 Systems Manager
User Guide

Systems Manager State Manager Walkthroughs

Use the following walkthroughs to manage the state of an EC2 instance in a test environment.

Launch a New Instance

Instances require an AWS Identity and Access Management (IAM) role that enables the instance to communicate with State Manager (SSM). The following procedure creates an instance with the required SSM-supported role.

To create an instance that uses an SSM-supported role

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. Select a supported region.

  3. Choose Launch Instance and select an Amazon Machine Image (AMI).

  4. Choose your instance type and then choose Next: Configure Instance Details.

  5. In Auto-assign Public IP, choose Enable.

  6. Beside IAM role choose Create new IAM role. The IAM console opens in a new tab.

    1. Choose Create New Role.

    2. In Step 1: Set Role Name, enter a name that identifies this role as a Systems Manager role.

    3. In Step 2: Select Role Type, choose Amazon EC2 Role for Simple Systems Manager. The system skips Step 3: Establish Trust because this is a managed policy.

    4. In Step 4: Attach Policy, choose AmazonEC2RoleforSSM.

    5. Choose Next Step, and then choose Create Role.

    6. Close the tab with the IAM console.

  7. In the Amazon EC2 console, choose the Refresh button beside Create New IAM role.

  8. From IAM role, choose the role you just created.

  9. Complete the wizard to launch the new instance. Make a note of the instance ID. You will need to specify this ID later in this tutorial.

Important

On Linux instance, you must install the SSM Agent on the instance you just created. For more information, see Installing SSM Agent on Linux.

To assign the role to one of your existing instances, see Attaching an IAM Role to an Instance in the Amazon EC2 User Guide.

Grant Your User Account Access to SSM

Your user account must be configured to communicate with the SSM API. Use the following procedure to attach a managed IAM policy to your user account that grants you full access to SSM API actions.

To create the IAM policy for your user account

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

  2. In the navigation pane, choose Policies. (If this is your first time using IAM, choose Get Started, and then choose Create Policy.)

  3. In the Filter field, type AmazonSSMFullAccess and press Enter.

  4. Select the check box next to AmazonSSMFullAccess and then choose Policy Actions, Attach.

  5. On the Attach Policy page, choose your user account and then choose Attach Policy.

Systems Manager State Manager Console Walkthrough

The following procedure walks you through the process of creating an association using the EC2 console.

To create an association using State Manager

  1. Open the Amazon EC2 console and choose Systems Manager Shared Resources in the navigation pane.

  2. Choose Documents and then choose Create Document.

  3. For Name, type a descriptive name that identifies this document as a test policy document.

  4. In the Document type list, choose Command.

  5. Delete the pre-populated brackets {} in the Content field and then copy and paste the following sample document in the Content field.

    The following is a sample of a basic policy document that defines the schema to use and a main step that uses the aws:runShellScript plugin to get network adapter information. A policy document can have multiple steps.

    Copy
    { "schemaVersion": "2.0", "description": "Sample version 2.0 document v2", "parameters": { }, "mainSteps": [ { "action": "aws:runShellScript", "name": "runShellScript", "inputs": { "runCommand": [ "ifconfig" ] } } ] }
  6. Choose Create document, and then choose OK after the system creates the policy document.

  7. In the EC2 console navigation pane, expand Systems Manager Services, and then choose State Manager.

  8. Choose Create Association.

  9. In the Document name list, choose the document you just created.

  10. In the Select Targets by section, choose Manually Selecting Instances, and then choose the instance you created at the beginning of this walkthrough.

  11. In the Schedule section, choose an option.

  12. Disregard the Specify Parameters section, as the test policy document does not take parameters.

  13. Choose Create Association.

Systems Manager State Manager CLI Walkthrough

The following procedure walks you through the process of creating an association using the AWS Command Line Interface (AWS CLI).

  1. Copy one of the following sample policy documents and paste it into a simple text editor like Notepad.

    Linux

    Copy
    { "schemaVersion": "2.0", "description": "Sample version 2.0 document v2", "parameters": { }, "mainSteps": [ { "action": "aws:runShellScript", "name": "runShellScript", "inputs": { "runCommand": [ "ifconfig" ] } } ] }

    Windows

    Copy
    { "schemaVersion": "2.0", "description": "Sample version 2.0 document v2", "parameters": { }, "mainSteps": [ { "action": "aws:runPowerShellScript", "name": "runShellScript", "inputs": { "runCommand": [ "ipconfig" ] } }, { "action": "aws:applications", "name": "installapp", "inputs": { "action": "Install", "source": "http://dev.mysql.com/get/Downloads/MySQLInstaller/mysql-installer-community-5.6.22.0.msi" } } ] }
  2. Save the document with a descriptive name and a .json file extension.

  3. Execute the following command to create the document and save it with your AWS user account using the AWS CLI.

    Copy
    aws ssm create-document --content file://c:\temp\your file --name "document name"
  4. Execute the following command to create an association with the instance you created at the start of this walkthrough. The Schedule parameter sets a schedule to run the association every 30 minutes.

    Copy
    aws ssm create-association --targets Key=instanceids,Values=Instance ID --document your document name --schedule "cron(0 0/30 * 1/1 * ? *)"
  5. Execute the following command to view the associations for the instance. Copy the association ID returned by the command. You'll specify this ID in the next step.

    Copy
    aws ssm list-instance-associations --instance-id=Instance ID