AWS Systems Manager
User Guide

Install Packages

You can use the AWS Management Console or the AWS CLI to deploy packages to your AWS Systems Manager managed instances by using AWS Systems Manager Distributor. You can currently deploy one version of one package per command. You can choose to deploy a specific version or choose to always deploy the latest version of a package for deployment.

Preference AWS Systems Manager Action More Information

Install a package immediately.

Run Command

Install a Package One Time (Console) or Install a Package One Time (CLI)

Install a package on a schedule, so that the installation always includes the default version.

State Manager

Schedule a Package Installation (Console) or Schedule a Package Installation (CLI)

Automatically install a package on new instances that have a specific tag or set of tags. For example, installing the Amazon CloudWatch agent on new instances.

State Manager

One way to do this is to apply tags to new instances, and then specify the tags as targets in your State Manager association. State Manager automatically installs the package in an association on instances that have matching tags. See Create an Association that Uses Targets and Rate Controls (CLI).

Install a Package One Time (Console)

You can use the AWS Systems Manager console to install a package one time. When you configure a one-time installation, Distributor uses AWS Systems Manager Run Command to perform the installation.

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

  2. In the navigation pane, choose Distributor.

  3. On the Distributor home page, choose the package that you want to install.

  4. To install the default package version, you can choose Install package from the package details page. To install another version, choose the Versions tab, choose the version you want to install, and then choose Install package.

  5. In Install package, choose Install one time.

    This command opens Systems Manager Run Command with the command document AWS-ConfigureAWSPackage and your Distributor package already selected.

  6. Keep Install as the value of Action. For Name, enter the name of the package that you want to install.

  7. For Version, enter the Version name value of the package. If you leave this field blank, Run Command installs the default version that you selected in Distributor.

  8. In Targets, choose target managed instances by specifying a tag key and values that are shared by the managed instances, or specify instances by any of seven attributes, including instance ID, platform, and SSM Agent version.

  9. You can use the advanced options to add comments about the installation, change Concurrency and Error threshold values in Rate control, specify output options, or configure Amazon Simple Notification Service (Amazon SNS) notifications. For more information, see Running Commands from the Console in this guide.

  10. When you are ready to install the package, choose Run, and then choose View results.

  11. In the commands list, choose the AWS-ConfigureAWSPackage command that you ran. If the command is still in progress, choose the refresh icon in the top-right corner of the console.

  12. When the Status column shows Success or Failed, choose the Output tab.

  13. Choose View output. The command output page shows the results of your command execution.

Schedule a Package Installation (Console)

You can use the AWS Systems Manager console to schedule the installation of a package. When you schedule package installation, Distributor uses AWS Systems Manager State Manager to perform the installation.

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

  2. In the navigation pane, choose Distributor.

  3. On the Distributor home page, choose the package that you want to install.

  4. To install the default package version, you can choose Install package from the package details page. To install another version, choose the Versions tab, choose the version you want to install, and then choose Install package. If you do not choose a version, Systems Manager installs the default version.

  5. In Install package, choose Install on a schedule.

    This command opens Systems Manager State Manager to a new association that is created for you.

  6. In Name, enter a name (for example, Deploy_test_agent_package). This is optional, but recommended. Spaces aren't allowed in the name.

  7. In the Command document list, the document name AWS-ConfigureAWSPackage is already selected. Verify that the Package value is set to the name of your package. Verify that in Parameters, for Operation, Install is already selected.

  8. In Targets, choose Selecting all managed instances in this account, Specifying tags, or Manually Selecting Instance. If you target resources by using tags, enter a tag key and a tag value in the fields provided.

  9. In Specify schedule, choose On Schedule to run the association on a regular schedule, or No Schedule to run the association once. For more information about these options, see Create an Association (Console) in this guide. Use the controls to create a cron or rate schedule for the association.

  10. For more information about advanced options, such as compliance severity, rate control, and output options, see Create an Association (Console) in this guide. When you are finished editing your association, choose Save Changes.

  11. On the association's home page, choose Apply association now.

    State Manager creates and immediately runs the association on the specified instances or targets. For more information about the results of running associations, see Create an Association (Console) in this guide.

Install a Package One Time (CLI)

You can run send-command in the AWS CLI to install a Distributor package one time.

  • Run the following command in the AWS CLI.

    aws ssm send-command --document-name "AWS-ConfigureAWSPackage" --instance-ids "instance_IDs" --parameters '{"action":["Install"],"name":["package_name (in same account) or package_ARN (shared from different account)"]}'

    The following is an example.

    aws ssm send-command --document-name "AWS-ConfigureAWSPackage" --instance-ids "i-00000000000000" --parameters '{"action":["Install"],"name":["ExamplePackage"]}'

For information about other options you can use with the send-command command, see send-command in the AWS Systems Manager section of the AWS CLI Command Reference.

Schedule a Package Installation (CLI)

You can run create-association in the AWS CLI to install a Distributor package on a schedule. The value of --name, the document name, is always AWS-ConfigureAWSPackage. The following command uses the key InstanceIds to specify target instances.

aws ssm create-association --name "AWS-ConfigureAWSPackage" --parameters '{"action":["Install"],"name":["package_name (in same account) or package_ARN (shared from different account)"]}' --targets [{\"Key\":\"InstanceIds\",\"Values\":[\"instance_ID1\",\"instance_ID2\"]}]

The following is an example.

aws ssm create-association --name "AWS-ConfigureAWSPackage" --parameters '{"action":["Install"],"name":["Test-ConfigureAWSPackage"]}' --targets [{\"Key\":\"InstanceIds\",\"Values\":[\"i-000100010000010\",\"i-020100010000011\"]}]

For information about other options you can use with the create-association command, see create-association in the AWS Systems Manager section of the AWS CLI Command Reference.