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
(PDF).
Editing and creating a new version
of an association
You can edit a State Manager association to specify a new name, schedule, severity
level, targets, or other values. For associations based on SSM Command-type
documents, you can also choose to write the output of the command to an Amazon Simple Storage Service
(Amazon S3) bucket. After you edit an association, State Manager creates a new version. You
can view different versions after editing, as described in the following procedures.
The following procedures describe how to edit and create a new version of an
association using the Systems Manager console, Amazon Command Line Interface (Amazon CLI), and Amazon Tools for PowerShell (Tools for PowerShell).
State Manager doesn't support running associations that use a new version of a
document if that document is shared from another account. State Manager always runs
the default
version of a document if shared from another account,
even though the Systems Manager console shows that a new version was processed. If you
want to run an association using a new version of a document shared form another
account, you must set the document version to default
.
Edit an association
(console)
The following procedure describes how to use the Systems Manager console to edit and
create a new version of an association.
For associations that use SSM Command documents, not Automation runbooks,
this procedure requires that you have write access to an existing Amazon S3
bucket. If you haven't used Amazon S3 before, be aware that you will incur
charges for using Amazon S3. For information about how to create a bucket, see
Create a
Bucket.
To edit a State Manager association
Open the Amazon Systems Manager console at https://console.amazonaws.cn/systems-manager/.
In the navigation pane, choose State Manager.
-
Choose an existing association, and then choose
Edit.
-
Reconfigure the association to meet your current requirements.
For information about association options with Command
and Policy
documents, see Creating associations. For
information about association options with Automation runbooks, see
Scheduling
automations with State Manager associations.
-
Choose Save Changes.
-
(Optional) To view association information, in the
Associations page, choose the name of the
association you edited, and then choose the
Versions tab. The system lists each version of
the association you created and edited.
-
(Optional) To view output for associations based on SSM
Command
documents, do the following:
Open the Amazon S3 console at
https://console.amazonaws.cn/s3/.
-
Choose the name of the Amazon S3 bucket you specified for storing
command output, and then choose the folder named with the ID of
the node that ran the association. (If you chose to store output
in a folder in the bucket, open it first.)
-
Drill down several levels, through the
awsrunPowerShell
folder, to the
stdout
file.
-
Choose Open or
Download to view the host name.
Edit an
association (command line)
The following procedure describes how to use the Amazon CLI (on Linux or Windows)
or Amazon Tools for PowerShell to edit and create a new version of an association.
To edit a State Manager association
Install and configure the Amazon CLI or the Amazon Tools for PowerShell, if you haven't already.
For information, see Installing or updating the latest version of the Amazon CLI and Installing the Amazon Tools for PowerShell.
-
Use the following format to create a command to edit and create a new
version of an existing State Manager association. Replace each
example resource placeholder
with your
own information.
When you call update-association
, the
system drops all optional parameters from the request and overwrites
the association with null values for those parameters. This is by
design. You must specify all optional parameters in the call, even
if you are not changing the parameters. This includes the
--name
parameter. Before calling this action, we
recommend that you call the
describe-association
operation and
make a note of all optional parameters required for your
update-association
call.
- Linux & macOS
-
aws ssm update-association \
--name document_name
\
--document-version version_of_document_applied
\
--instance-id instances_to_apply_association_on
\
--parameters (if any)
\
--targets target_options
\
--schedule-expression "cron_or_rate_expression
" \
--schedule-offset "number_between_1_and_6
" \
--output-location s3_bucket_to_store_output_details
\
--association-name association_name
\
--max-errors a_number_of_errors_or_a_percentage_of_target_set
\
--max-concurrency a_number_of_instances_or_a_percentage_of_target_set
\
--compliance-severity severity_level
\
--calendar-names change_calendar_names
\
--target-locations aws_region_or_account
- Windows
-
aws ssm update-association ^
--name document_name
^
--document-version version_of_document_applied
^
--instance-id instances_to_apply_association_on
^
--parameters (if any)
^
--targets target_options
^
--schedule-expression "cron_or_rate_expression
" ^
--schedule-offset "number_between_1_and_6
" ^
--output-location s3_bucket_to_store_output_details
^
--association-name association_name
^
--max-errors a_number_of_errors_or_a_percentage_of_target_set
^
--max-concurrency a_number_of_instances_or_a_percentage_of_target_set
^
--compliance-severity severity_level
^
--calendar-names change_calendar_names
^
--target-locations aws_region_or_account
- PowerShell
-
Update-SSMAssociation `
-Name document_name
`
-DocumentVersion version_of_document_applied
`
-InstanceId instances_to_apply_association_on
`
-Parameters (if any)
`
-Target target_options
`
-ScheduleExpression "cron_or_rate_expression
" `
-ScheduleOffset "number_between_1_and_6
" `
-OutputLocation s3_bucket_to_store_output_details
`
-AssociationName association_name
`
-MaxError a_number_of_errors_or_a_percentage_of_target_set
-MaxConcurrency a_number_of_instances_or_a_percentage_of_target_set
`
-ComplianceSeverity severity_level
`
-CalendarNames change_calendar_names
`
-TargetLocations aws_region_or_account
The following example updates an existing association to change the
name to TestHostnameAssociation2
. The new association
version runs every hour and writes the output of commands to the
specified Amazon S3 bucket.
- Linux & macOS
-
aws ssm update-association \
--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE \
--association-name TestHostnameAssociation2 \
--parameters commands="echo Association" \
--output-location S3Location='{OutputS3Region=us-east-1,OutputS3BucketName=amzn-s3-demo-bucket,OutputS3KeyPrefix=logs}' \
--schedule-expression "cron(0 */1 * * ? *)"
- Windows
-
aws ssm update-association ^
--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE ^
--association-name TestHostnameAssociation2 ^
--parameters commands="echo Association" ^
--output-location S3Location='{OutputS3Region=us-east-1,OutputS3BucketName=amzn-s3-demo-bucket,OutputS3KeyPrefix=logs}' ^
--schedule-expression "cron(0 */1 * * ? *)"
- PowerShell
-
Update-SSMAssociation `
-AssociationId b85ccafe-9f02-4812-9b81-01234EXAMPLE `
-AssociationName TestHostnameAssociation2 `
-Parameter @{"commands"="echo Association"} `
-S3Location_OutputS3BucketName amzn-s3-demo-bucket `
-S3Location_OutputS3KeyPrefix logs `
-S3Location_OutputS3Region us-east-1 `
-ScheduleExpression "cron(0 */1 * * ? *)"
The following example updates an existing association to change the
name to CalendarAssociation
. The new association runs when
the calendar is open and writes command output to the specified Amazon S3
bucket.
- Linux & macOS
-
aws ssm update-association \
--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE \
--association-name CalendarAssociation \
--parameters commands="echo Association" \
--output-location S3Location='{OutputS3Region=us-east-1,OutputS3BucketName=amzn-s3-demo-bucket,OutputS3KeyPrefix=logs}' \
--calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar2"
- Windows
-
aws ssm update-association ^
--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE ^
--association-name CalendarAssociation ^
--parameters commands="echo Association" ^
--output-location S3Location='{OutputS3Region=us-east-1,OutputS3BucketName=amzn-s3-demo-bucket,OutputS3KeyPrefix=logs}' ^
--calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar2"
- PowerShell
-
Update-SSMAssociation `
-AssociationId b85ccafe-9f02-4812-9b81-01234EXAMPLE `
-AssociationName CalendarAssociation `
-AssociationName OneTimeAssociation `
-Parameter @{"commands"="echo Association"} `
-S3Location_OutputS3BucketName amzn-s3-demo-bucket `
-CalendarNames "arn:aws:ssm:us-east-1:123456789012:document/testCalendar2"
The following example updates an existing association to change the
name to MultiCalendarAssociation
. The new association runs
when the calendars are open and writes command output to the specified
Amazon S3 bucket.
- Linux & macOS
-
aws ssm update-association \
--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE \
--association-name MultiCalendarAssociation \
--parameters commands="echo Association" \
--output-location S3Location='{OutputS3Region=us-east-1,OutputS3BucketName=amzn-s3-demo-bucket,OutputS3KeyPrefix=logs}' \
--calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" "arn:aws:ssm:us-east-2:123456789012:document/testCalendar2"
- Windows
-
aws ssm update-association ^
--association-id 8dfe3659-4309-493a-8755-01234EXAMPLE ^
--association-name MultiCalendarAssociation ^
--parameters commands="echo Association" ^
--output-location S3Location='{OutputS3Region=us-east-1,OutputS3BucketName=amzn-s3-demo-bucket,OutputS3KeyPrefix=logs}' ^
--calendar-names "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" "arn:aws:ssm:us-east-2:123456789012:document/testCalendar2"
- PowerShell
-
Update-SSMAssociation `
-AssociationId b85ccafe-9f02-4812-9b81-01234EXAMPLE `
-AssociationName MultiCalendarAssociation `
-Parameter @{"commands"="echo Association"} `
-S3Location_OutputS3BucketName amzn-s3-demo-bucket `
-CalendarNames "arn:aws:ssm:us-east-1:123456789012:document/testCalendar1" "arn:aws:ssm:us-east-2:123456789012:document/testCalendar2"
-
To view the new version of the association, run the following
command.
- Linux & macOS
-
aws ssm describe-association \
--association-id b85ccafe-9f02-4812-9b81-01234EXAMPLE
- Windows
-
aws ssm describe-association ^
--association-id b85ccafe-9f02-4812-9b81-01234EXAMPLE
- PowerShell
-
Get-SSMAssociation `
-AssociationId b85ccafe-9f02-4812-9b81-01234EXAMPLE | Select-Object *
The system returns information like the following.
- Linux & macOS
-
{
"AssociationDescription": {
"ScheduleExpression": "cron(0 */1 * * ? *)",
"OutputLocation": {
"S3Location": {
"OutputS3KeyPrefix": "logs",
"OutputS3BucketName": "amzn-s3-demo-bucket",
"OutputS3Region": "us-east-1"
}
},
"Name": "AWS-RunPowerShellScript",
"Parameters": {
"commands": [
"echo Association"
]
},
"LastExecutionDate": 1559316400.338,
"Overview": {
"Status": "Success",
"DetailedStatus": "Success",
"AssociationStatusAggregatedCount": {}
},
"AssociationId": "b85ccafe-9f02-4812-9b81-01234EXAMPLE",
"DocumentVersion": "$DEFAULT",
"LastSuccessfulExecutionDate": 1559316400.338,
"LastUpdateAssociationDate": 1559316389.753,
"Date": 1559314038.532,
"AssociationVersion": "2",
"AssociationName": "TestHostnameAssociation2",
"Targets": [
{
"Values": [
"Windows"
],
"Key": "tag:Environment"
}
]
}
}
- Windows
-
{
"AssociationDescription": {
"ScheduleExpression": "cron(0 */1 * * ? *)",
"OutputLocation": {
"S3Location": {
"OutputS3KeyPrefix": "logs",
"OutputS3BucketName": "amzn-s3-demo-bucket",
"OutputS3Region": "us-east-1"
}
},
"Name": "AWS-RunPowerShellScript",
"Parameters": {
"commands": [
"echo Association"
]
},
"LastExecutionDate": 1559316400.338,
"Overview": {
"Status": "Success",
"DetailedStatus": "Success",
"AssociationStatusAggregatedCount": {}
},
"AssociationId": "b85ccafe-9f02-4812-9b81-01234EXAMPLE",
"DocumentVersion": "$DEFAULT",
"LastSuccessfulExecutionDate": 1559316400.338,
"LastUpdateAssociationDate": 1559316389.753,
"Date": 1559314038.532,
"AssociationVersion": "2",
"AssociationName": "TestHostnameAssociation2",
"Targets": [
{
"Values": [
"Windows"
],
"Key": "tag:Environment"
}
]
}
}
- PowerShell
-
AssociationId : b85ccafe-9f02-4812-9b81-01234EXAMPLE
AssociationName : TestHostnameAssociation2
AssociationVersion : 2
AutomationTargetParameterName :
ComplianceSeverity :
Date : 5/31/2019 2:47:18 PM
DocumentVersion : $DEFAULT
InstanceId :
LastExecutionDate : 5/31/2019 3:26:40 PM
LastSuccessfulExecutionDate : 5/31/2019 3:26:40 PM
LastUpdateAssociationDate : 5/31/2019 3:26:29 PM
MaxConcurrency :
MaxErrors :
Name : AWS-RunPowerShellScript
OutputLocation : Amazon.SimpleSystemsManagement.Model.InstanceAssociationOutputLocation
Overview : Amazon.SimpleSystemsManagement.Model.AssociationOverview
Parameters : {[commands, Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
ScheduleExpression : cron(0 */1 * * ? *)
Status :
Targets : {tag:Environment}