Use CreateAssociation
with an Amazon SDK or CLI
The following code examples show how to use CreateAssociation
.
- CLI
-
- Amazon CLI
-
Example 1: To associate a document using instance IDs
This example associates a configuration document with an instance, using instance IDs.
aws ssm create-association \ --instance-id
"i-0cb2b964d3e14fd9f"
\ --name"AWS-UpdateSSMAgent"
Output:
{ "AssociationDescription": { "Status": { "Date": 1487875500.33, "Message": "Associated with AWS-UpdateSSMAgent", "Name": "Associated" }, "Name": "AWS-UpdateSSMAgent", "InstanceId": "i-0cb2b964d3e14fd9f", "Overview": { "Status": "Pending", "DetailedStatus": "Creating" }, "AssociationId": "b7c3266e-a544-44db-877e-b20d3a108189", "DocumentVersion": "$DEFAULT", "LastUpdateAssociationDate": 1487875500.33, "Date": 1487875500.33, "Targets": [ { "Values": [ "i-0cb2b964d3e14fd9f" ], "Key": "InstanceIds" } ] } }
For more information, see CreateAssociation
in the Amazon Systems Manager API Reference. Example 2: To associate a document using targets
This example associates a configuration document with an instance, using targets.
aws ssm create-association \ --name
"AWS-UpdateSSMAgent"
\ --targets"Key=instanceids,Values=i-0cb2b964d3e14fd9f"
Output:
{ "AssociationDescription": { "Status": { "Date": 1487875500.33, "Message": "Associated with AWS-UpdateSSMAgent", "Name": "Associated" }, "Name": "AWS-UpdateSSMAgent", "InstanceId": "i-0cb2b964d3e14fd9f", "Overview": { "Status": "Pending", "DetailedStatus": "Creating" }, "AssociationId": "b7c3266e-a544-44db-877e-b20d3a108189", "DocumentVersion": "$DEFAULT", "LastUpdateAssociationDate": 1487875500.33, "Date": 1487875500.33, "Targets": [ { "Values": [ "i-0cb2b964d3e14fd9f" ], "Key": "InstanceIds" } ] } }
For more information, see CreateAssociation
in the Amazon Systems Manager API Reference. Example 3: To create an association that runs only once
This example creates a new association that only runs once on the specified date and time. Associations created with a date in the past or present (by the time it is processed the date is in the past) run immediately.
aws ssm create-association \ --name
"AWS-UpdateSSMAgent"
\ --targets"Key=instanceids,Values=i-0cb2b964d3e14fd9f"
\ --schedule-expression"at(2020-05-14T15:55:00)"
\ --apply-only-at-cron-intervalOutput:
{ "AssociationDescription": { "Status": { "Date": 1487875500.33, "Message": "Associated with AWS-UpdateSSMAgent", "Name": "Associated" }, "Name": "AWS-UpdateSSMAgent", "InstanceId": "i-0cb2b964d3e14fd9f", "Overview": { "Status": "Pending", "DetailedStatus": "Creating" }, "AssociationId": "b7c3266e-a544-44db-877e-b20d3a108189", "DocumentVersion": "$DEFAULT", "LastUpdateAssociationDate": 1487875500.33, "Date": 1487875500.33, "Targets": [ { "Values": [ "i-0cb2b964d3e14fd9f" ], "Key": "InstanceIds" } ] } }
For more information, see CreateAssociation
in the Amazon Systems Manager API Reference or Reference: Cron and rate expressions for Systems Manager in the Amazon Systems Manager User Guide. -
For API details, see CreateAssociation
in Amazon CLI Command Reference.
-
- PowerShell
-
- Tools for PowerShell
-
Example 1: This example associates a configuration document with an instance, using instance IDs.
New-SSMAssociation -InstanceId "i-0cb2b964d3e14fd9f" -Name "AWS-UpdateSSMAgent"
Output:
Name : AWS-UpdateSSMAgent InstanceId : i-0000293ffd8c57862 Date : 2/23/2017 6:55:22 PM Status.Name : Associated Status.Date : 2/20/2015 8:31:11 AM Status.Message : Associated with AWS-UpdateSSMAgent Status.AdditionalInfo :
Example 2: This example associates a configuration document with an instance, using targets.
$target = @{Key="instanceids";Values=@("i-0cb2b964d3e14fd9f")} New-SSMAssociation -Name "AWS-UpdateSSMAgent" -Target $target
Output:
Name : AWS-UpdateSSMAgent InstanceId : Date : 3/1/2017 6:22:21 PM Status.Name : Status.Date : Status.Message : Status.AdditionalInfo :
Example 3: This example associates a configuration document with an instance, using targets and parameters.
$target = @{Key="instanceids";Values=@("i-0cb2b964d3e14fd9f")} $params = @{ "action"="configure" "mode"="ec2" "optionalConfigurationSource"="ssm" "optionalConfigurationLocation"="" "optionalRestart"="yes" } New-SSMAssociation -Name "Configure-CloudWatch" -AssociationName "CWConfiguration" -Target $target -Parameter $params
Output:
Name : Configure-CloudWatch InstanceId : Date : 5/17/2018 3:17:44 PM Status.Name : Status.Date : Status.Message : Status.AdditionalInfo :
Example 4: This example creates an association with all instances in the region, with
AWS-GatherSoftwareInventory
. It also provides custom files and registry locations in the parameters to collect$params = [Collections.Generic.Dictionary[String,Collections.Generic.List[String]]]::new() $params["windowsRegistry"] ='[{"Path":"HKEY_LOCAL_MACHINE\SOFTWARE\Amazon\MachineImage","Recursive":false,"ValueNames":["AMIName"]}]' $params["files"] = '[{"Path":"C:\Program Files","Pattern":["*.exe"],"Recursive":true}, {"Path":"C:\ProgramData","Pattern":["*.log"],"Recursive":true}]' New-SSMAssociation -AssociationName new-in-mum -Name AWS-GatherSoftwareInventory -Target @{Key="instanceids";Values="*"} -Parameter $params -region ap-south-1 -ScheduleExpression "rate(720 minutes)"
Output:
Name : AWS-GatherSoftwareInventory InstanceId : Date : 6/9/2019 8:57:56 AM Status.Name : Status.Date : Status.Message : Status.AdditionalInfo :
-
For API details, see CreateAssociation
in Amazon Tools for PowerShell Cmdlet Reference.
-
For a complete list of Amazon SDK developer guides and code examples, see Using Systems Manager with an Amazon SDK. This topic also includes information about getting started and details about previous SDK versions.