From f3b2086aca5ba43e8eb5170b06643ae5e7cfac43 Mon Sep 17 00:00:00 2001 From: Erik Weber Date: Mon, 18 Feb 2019 11:58:41 -0500 Subject: [PATCH] Add new ssm examples Created 4 new command examples and added examples or updated output to 8 other existing commands. --- .../examples/ssm/create-association-batch.rst | 48 +++++------ awscli/examples/ssm/delete-association.rst | 10 ++- ...describe-association-execution-targets.rst | 28 +++++++ .../ssm/describe-association-executions.rst | 57 +++++++++++++ awscli/examples/ssm/describe-association.rst | 79 +++++++++++++++++- ...scribe-effective-instance-associations.rst | 9 ++- .../describe-instance-associations-status.rst | 26 ++++-- .../ssm/list-association-versions.rst | 38 +++++++++ awscli/examples/ssm/list-associations.rst | 80 ++++++++++--------- .../examples/ssm/start-associations-once.rst | 8 ++ .../ssm/update-association-status.rst | 32 ++++---- awscli/examples/ssm/update-association.rst | 36 +++++---- 12 files changed, 348 insertions(+), 103 deletions(-) create mode 100644 awscli/examples/ssm/describe-association-execution-targets.rst create mode 100644 awscli/examples/ssm/describe-association-executions.rst create mode 100644 awscli/examples/ssm/list-association-versions.rst create mode 100644 awscli/examples/ssm/start-associations-once.rst diff --git a/awscli/examples/ssm/create-association-batch.rst b/awscli/examples/ssm/create-association-batch.rst index 004994f4bbcc..792a377fc304 100644 --- a/awscli/examples/ssm/create-association-batch.rst +++ b/awscli/examples/ssm/create-association-batch.rst @@ -4,59 +4,61 @@ This example associates a configuration document with multiple instances. The ou Command:: - aws ssm create-association-batch --entries "Name=AWS-UpdateSSMAgent,InstanceId=i-0cb2b964d3e14fd9f" "Name=AWS-UpdateSSMAgent,InstanceId=i-0000293ffd8c57862" + aws ssm create-association-batch --entries "Name=AWS-UpdateSSMAgent,InstanceId=i-1234567890abcdef0" "Name=AWS-UpdateSSMAgent,InstanceId=i-9876543210abcdef0" Output:: { "Successful": [ { + "Name": "AWS-UpdateSSMAgent", + "InstanceId": "i-1234567890abcdef0", + "AssociationVersion": "1", + "Date": 1550504725.007, + "LastUpdateAssociationDate": 1550504725.007, "Status": { - "Date": 1487876122.564, - "Message": "Associated with AWS-UpdateSSMAgent", - "Name": "Associated" + "Date": 1550504725.007, + "Name": "Associated", + "Message": "Associated with AWS-UpdateSSMAgent" }, - "Name": "AWS-UpdateSSMAgent", - "InstanceId": "i-0000293ffd8c57862", "Overview": { "Status": "Pending", "DetailedStatus": "Creating" }, - "AssociationId": "d8617c07-2079-4c18-9847-1655fc2698b0", "DocumentVersion": "$DEFAULT", - "LastUpdateAssociationDate": 1487876122.564, - "Date": 1487876122.564, + "AssociationId": "8dfe3659-4309-493a-8755-0123456789ab", "Targets": [ { + "Key": "InstanceIds", "Values": [ - "i-0000293ffd8c57862" - ], - "Key": "InstanceIds" + "i-1234567890abcdef0" + ] } ] }, { + "Name": "AWS-UpdateSSMAgent", + "InstanceId": "i-9876543210abcdef0", + "AssociationVersion": "1", + "Date": 1550504725.057, + "LastUpdateAssociationDate": 1550504725.057, "Status": { - "Date": 1487876122.595, - "Message": "Associated with AWS-UpdateSSMAgent", - "Name": "Associated" + "Date": 1550504725.057, + "Name": "Associated", + "Message": "Associated with AWS-UpdateSSMAgent" }, - "Name": "AWS-UpdateSSMAgent", - "InstanceId": "i-0cb2b964d3e14fd9f", "Overview": { "Status": "Pending", "DetailedStatus": "Creating" }, - "AssociationId": "2ccfbc46-5fe4-4e5c-ba46-70b56cc93f53", "DocumentVersion": "$DEFAULT", - "LastUpdateAssociationDate": 1487876122.595, - "Date": 1487876122.595, + "AssociationId": "9c9f7f20-5154-4fed-a83e-0123456789ab", "Targets": [ { + "Key": "InstanceIds", "Values": [ - "i-0cb2b964d3e14fd9f" - ], - "Key": "InstanceIds" + "i-9876543210abcdef0" + ] } ] } diff --git a/awscli/examples/ssm/delete-association.rst b/awscli/examples/ssm/delete-association.rst index 8b3181d9dd9d..047966538871 100644 --- a/awscli/examples/ssm/delete-association.rst +++ b/awscli/examples/ssm/delete-association.rst @@ -4,4 +4,12 @@ This example deletes the association between an instance and a document. There i Command:: - aws ssm delete-association --instance-id "i-0cb2b964d3e14fd9f" --name "AWS-UpdateSSMAgent" + aws ssm delete-association --instance-id "i-1234567890abcdef0" --name "AWS-UpdateSSMAgent" + +**To delete an association using the association ID** + +This example deletes the association for the specified association ID. There is no output if the command succeeds. + +Command:: + + aws ssm delete-association --association-id "8dfe3659-4309-493a-8755-0123456789ab" diff --git a/awscli/examples/ssm/describe-association-execution-targets.rst b/awscli/examples/ssm/describe-association-execution-targets.rst new file mode 100644 index 000000000000..a8244081d895 --- /dev/null +++ b/awscli/examples/ssm/describe-association-execution-targets.rst @@ -0,0 +1,28 @@ +**To get details of an association execution** + +This example describes the specified association execution. + +Command:: + + aws ssm describe-association-execution-targets --association-id "8dfe3659-4309-493a-8755-0123456789ab" --execution-id "7abb6378-a4a5-4f10-8312-0123456789ab" + +Output:: + + { + "AssociationExecutionTargets": [ + { + "AssociationId": "8dfe3659-4309-493a-8755-0123456789ab", + "AssociationVersion": "1", + "ExecutionId": "7abb6378-a4a5-4f10-8312-0123456789ab", + "ResourceId": "i-1234567890abcdef0", + "ResourceType": "ManagedInstance", + "Status": "Success", + "DetailedStatus": "Success", + "LastExecutionDate": 1550505538.497, + "OutputSource": { + "OutputSourceId": "97fff367-fc5a-4299-aed8-0123456789ab", + "OutputSourceType": "RunCommand" + } + } + ] + } diff --git a/awscli/examples/ssm/describe-association-executions.rst b/awscli/examples/ssm/describe-association-executions.rst new file mode 100644 index 000000000000..7acb79396245 --- /dev/null +++ b/awscli/examples/ssm/describe-association-executions.rst @@ -0,0 +1,57 @@ +**To get details of all executions for an association** + +This example describes all executions of the specified association. + +Command:: + + aws ssm describe-association-executions --association-id "8dfe3659-4309-493a-8755-0123456789ab" + +Output:: + + { + "AssociationExecutions": [ + { + "AssociationId": "8dfe3659-4309-493a-8755-0123456789ab", + "AssociationVersion": "1", + "ExecutionId": "474925ef-1249-45a2-b93d-0123456789ab", + "Status": "Success", + "DetailedStatus": "Success", + "CreatedTime": 1550505827.119, + "ResourceCountByStatus": "{Success=1}" + }, + { + "AssociationId": "8dfe3659-4309-493a-8755-0123456789ab", + "AssociationVersion": "1", + "ExecutionId": "7abb6378-a4a5-4f10-8312-0123456789ab", + "Status": "Success", + "DetailedStatus": "Success", + "CreatedTime": 1550505536.843, + "ResourceCountByStatus": "{Success=1}" + }, + ... + ] + } + +**To get details of all executions for an association after a specific date and time** + +This example describes all executions of an association after the specified date and time. + +Command:: + + aws ssm describe-association-executions --association-id "8dfe3659-4309-493a-8755-0123456789ab" --filters "Key=CreatedTime,Value=2019-02-18T16:00:00Z,Type=GREATER_THAN" + +Output:: + + { + "AssociationExecutions": [ + { + "AssociationId": "8dfe3659-4309-493a-8755-0123456789ab", + "AssociationVersion": "1", + "ExecutionId": "474925ef-1249-45a2-b93d-0123456789ab", + "Status": "Success", + "DetailedStatus": "Success", + "CreatedTime": 1550505827.119, + "ResourceCountByStatus": "{Success=1}" + } + ] + } diff --git a/awscli/examples/ssm/describe-association.rst b/awscli/examples/ssm/describe-association.rst index 595a4071f46d..92234edc2b25 100644 --- a/awscli/examples/ssm/describe-association.rst +++ b/awscli/examples/ssm/describe-association.rst @@ -1,10 +1,81 @@ **To get details of an association** +This example describes the association for the specified association ID. + +Command:: + + aws ssm describe-association --association-id "8dfe3659-4309-493a-8755-0123456789ab" + +Output:: + + { + "AssociationDescription": { + "Name": "AWS-GatherSoftwareInventory", + "AssociationVersion": "1", + "Date": 1534864780.995, + "LastUpdateAssociationDate": 1543235759.81, + "Overview": { + "Status": "Success", + "AssociationStatusAggregatedCount": { + "Success": 2 + } + }, + "DocumentVersion": "$DEFAULT", + "Parameters": { + "applications": [ + "Enabled" + ], + "awsComponents": [ + "Enabled" + ], + "customInventory": [ + "Enabled" + ], + "files": [ + "" + ], + "instanceDetailedInformation": [ + "Enabled" + ], + "networkConfig": [ + "Enabled" + ], + "services": [ + "Enabled" + ], + "windowsRegistry": [ + "" + ], + "windowsRoles": [ + "Enabled" + ], + "windowsUpdates": [ + "Enabled" + ] + }, + "AssociationId": "8dfe3659-4309-493a-8755-0123456789ab", + "Targets": [ + { + "Key": "InstanceIds", + "Values": [ + "*" + ] + } + ], + "ScheduleExpression": "rate(24 hours)", + "LastExecutionDate": 1550501886.0, + "LastSuccessfulExecutionDate": 1550501886.0, + "AssociationName": "Inventory-Association" + } + } + +**To get details of an association for a specific instance and document** + This example describes the association between an instance and a document. Command:: - aws ssm describe-association --instance-id "i-0000293ffd8c57862" --name "AWS-UpdateSSMAgent" + aws ssm describe-association --instance-id "i-1234567890abcdef0" --name "AWS-UpdateSSMAgent" Output:: @@ -16,7 +87,7 @@ Output:: "Name": "Associated" }, "Name": "AWS-UpdateSSMAgent", - "InstanceId": "i-0000293ffd8c57862", + "InstanceId": "i-1234567890abcdef0", "Overview": { "Status": "Pending", "DetailedStatus": "Associated", @@ -24,14 +95,14 @@ Output:: "Pending": 1 } }, - "AssociationId": "d8617c07-2079-4c18-9847-1655fc2698b0", + "AssociationId": "d8617c07-2079-4c18-9847-1234567890ab", "DocumentVersion": "$DEFAULT", "LastUpdateAssociationDate": 1487876122.564, "Date": 1487876122.564, "Targets": [ { "Values": [ - "i-0000293ffd8c57862" + "i-1234567890abcdef0" ], "Key": "InstanceIds" } diff --git a/awscli/examples/ssm/describe-effective-instance-associations.rst b/awscli/examples/ssm/describe-effective-instance-associations.rst index 038e0bb76b4c..31f0a2801f58 100755 --- a/awscli/examples/ssm/describe-effective-instance-associations.rst +++ b/awscli/examples/ssm/describe-effective-instance-associations.rst @@ -4,16 +4,17 @@ This example describes the effective associations for an instance. Command:: - aws ssm describe-effective-instance-associations --instance-id "i-0000293ffd8c57862" + aws ssm describe-effective-instance-associations --instance-id "i-1234567890abcdef0" Output:: { "Associations": [ { - "InstanceId": "i-0000293ffd8c57862", + "AssociationId": "8dfe3659-4309-493a-8755-0123456789ab", + "InstanceId": "i-1234567890abcdef0", "Content": "{\n \"schemaVersion\": \"1.2\",\n \"description\": \"Update the Amazon SSM Agent to the latest version or specified version.\",\n \"parameters\": {\n \"version\": {\n \"default\": \"\",\n \"description\": \"(Optional) A specific version of the Amazon SSM Agent to install. If not specified, the agent will be updated to the latest version.\",\n \"type\": \"String\"\n },\n \"allowDowngrade\": {\n \"default\": \"false\",\n \"description\": \"(Optional) Allow the Amazon SSM Agent service to be downgraded to an earlier version. If set to false, the service can be upgraded to newer versions only (default). If set to true, specify the earlier version.\",\n \"type\": \"String\",\n \"allowedValues\": [\n \"true\",\n \"false\"\n ]\n }\n },\n \"runtimeConfig\": {\n \"aws:updateSsmAgent\": {\n \"properties\": [\n {\n \"agentName\": \"amazon-ssm-agent\",\n \"source\": \"https://s3.{Region}.amazonaws.com/amazon-ssm-{Region}/ssm-agent-manifest.json\",\n \"allowDowngrade\": \"{{ allowDowngrade }}\",\n \"targetVersion\": \"{{ version }}\"\n }\n ]\n }\n }\n}\n", - "AssociationId": "d8617c07-2079-4c18-9847-1655fc2698b0" + "AssociationVersion": "1" } ] - } +} diff --git a/awscli/examples/ssm/describe-instance-associations-status.rst b/awscli/examples/ssm/describe-instance-associations-status.rst index 37ea6ef68327..2fbc0cc1724d 100755 --- a/awscli/examples/ssm/describe-instance-associations-status.rst +++ b/awscli/examples/ssm/describe-instance-associations-status.rst @@ -4,19 +4,33 @@ This example shows details of the associations for an instance. Command:: - aws ssm describe-instance-associations-status --instance-id "i-0000293ffd8c57862" + aws ssm describe-instance-associations-status --instance-id "i-1234567890abcdef0" Output:: { "InstanceAssociationStatusInfos": [ { - "Status": "Pending", - "DetailedStatus": "Associated", + "AssociationId": "8dfe3659-4309-493a-8755-0123456789ab", + "Name": "AWS-GatherSoftwareInventory", + "DocumentVersion": "1", + "AssociationVersion": "1", + "InstanceId": "i-1234567890abcdef0", + "ExecutionDate": 1550501886.0, + "Status": "Success", + "ExecutionSummary": "1 out of 1 plugin processed, 1 success, 0 failed, 0 timedout, 0 skipped. ", + "AssociationName": "Inventory-Association" + }, + { + "AssociationId": "5c5a31f6-6dae-46f9-944c-0123456789ab", "Name": "AWS-UpdateSSMAgent", - "InstanceId": "i-0000293ffd8c57862", - "AssociationId": "d8617c07-2079-4c18-9847-1655fc2698b0", - "DocumentVersion": "1" + "DocumentVersion": "1", + "AssociationVersion": "1", + "InstanceId": "i-1234567890abcdef0", + "ExecutionDate": 1550505828.548, + "Status": "Success", + "DetailedStatus": "Success", + "AssociationName": "UpdateSSMAgent" } ] } diff --git a/awscli/examples/ssm/list-association-versions.rst b/awscli/examples/ssm/list-association-versions.rst new file mode 100644 index 000000000000..0bcc23c1af9a --- /dev/null +++ b/awscli/examples/ssm/list-association-versions.rst @@ -0,0 +1,38 @@ +**To list all versions of an association for a specific association ID** + +This example lists all versions of the specified associations. + +Command:: + + aws ssm list-association-versions --association-id "8dfe3659-4309-493a-8755-0123456789ab" + +Output:: + + { + "AssociationVersions": [ + { + "AssociationId": "8dfe3659-4309-493a-8755-0123456789ab", + "AssociationVersion": "1", + "CreatedDate": 1550505536.726, + "Name": "AWS-UpdateSSMAgent", + "Parameters": { + "allowDowngrade": [ + "false" + ], + "version": [ + "" + ] + }, + "Targets": [ + { + "Key": "InstanceIds", + "Values": [ + "i-1234567890abcdef0" + ] + } + ], + "ScheduleExpression": "cron(0 00 12 ? * SUN *)", + "AssociationName": "UpdateSSMAgent" + } + ] + } diff --git a/awscli/examples/ssm/list-associations.rst b/awscli/examples/ssm/list-associations.rst index dfb31b3154bb..2aa5d88d6390 100644 --- a/awscli/examples/ssm/list-associations.rst +++ b/awscli/examples/ssm/list-associations.rst @@ -4,14 +4,25 @@ This example lists all the associations for an instance. Command:: - aws ssm list-associations --association-filter-list "key=InstanceId,value=i-0000293ffd8c57862" + aws ssm list-associations --association-filter-list "key=InstanceId,value=i-1234567890abcdef0" Output:: { "Associations": [ { - "InstanceId": "i-0000293ffd8c57862", + "Name": "AWS-UpdateSSMAgent", + "InstanceId": "i-1234567890abcdef0", + "AssociationId": "8dfe3659-4309-493a-8755-0123456789ab", + "AssociationVersion": "1", + "Targets": [ + { + "Key": "InstanceIds", + "Values": [ + "i-016648b75dd622dab" + ] + } + ], "Overview": { "Status": "Pending", "DetailedStatus": "Associated", @@ -19,23 +30,15 @@ Output:: "Pending": 1 } }, - "AssociationId": "d8617c07-2079-4c18-9847-1655fc2698b0", - "Name": "AWS-UpdateSSMAgent", - "Targets": [ - { - "Values": [ - "i-0000293ffd8c57862" - ], - "Key": "InstanceIds" - } - ] + "ScheduleExpression": "cron(0 00 12 ? * SUN *)", + "AssociationName": "UpdateSSMAgent" } ] } **To list your associations for a specific document** -This example lists all associations for the a document. +This example lists all associations for the specified document. Command:: @@ -46,44 +49,49 @@ Output:: { "Associations": [ { - "InstanceId": "i-0000293ffd8c57862", - "Overview": { - "Status": "Pending", - "DetailedStatus": "Associated", - "AssociationStatusAggregatedCount": { - "Pending": 1 - } - }, - "AssociationId": "d8617c07-2079-4c18-9847-1655fc2698b0", "Name": "AWS-UpdateSSMAgent", + "InstanceId": "i-1234567890abcdef0", + "AssociationId": "8dfe3659-4309-493a-8755-0123456789ab", + "AssociationVersion": "1", "Targets": [ { + "Key": "InstanceIds", "Values": [ - "i-0000293ffd8c57862" - ], - "Key": "InstanceIds" + "i-1234567890abcdef0" + ] } - ] - }, - { - "Name": "AWS-UpdateSSMAgent", - "LastExecutionDate": 1487876123.0, - "InstanceId": "i-0cb2b964d3e14fd9f", + ], + "LastExecutionDate": 1550505828.548, "Overview": { "Status": "Success", + "DetailedStatus": "Success", "AssociationStatusAggregatedCount": { "Success": 1 } }, - "AssociationId": "2ccfbc46-5fe4-4e5c-ba46-70b56cc93f53", + "ScheduleExpression": "cron(0 00 12 ? * SUN *)", + "AssociationName": "UpdateSSMAgent" + }, + { + "Name": "AWS-UpdateSSMAgent", + "InstanceId": "i-9876543210abcdef0", + "AssociationId": "fbc07ef7-b985-4684-b82b-0123456789ab", + "AssociationVersion": "1", "Targets": [ { + "Key": "InstanceIds", "Values": [ - "i-0cb2b964d3e14fd9f" - ], - "Key": "InstanceIds" + "i-9876543210abcdef0" + ] + } + ], + "LastExecutionDate": 1550507531.0, + "Overview": { + "Status": "Success", + "AssociationStatusAggregatedCount": { + "Success": 1 } - ] + } } ] } diff --git a/awscli/examples/ssm/start-associations-once.rst b/awscli/examples/ssm/start-associations-once.rst new file mode 100644 index 000000000000..7b82d0dede43 --- /dev/null +++ b/awscli/examples/ssm/start-associations-once.rst @@ -0,0 +1,8 @@ +**To execute an association immediately and only one time** + +This example executes the specified association immediately and only once. There is no output if the command succeeds. + +Command:: + + aws ssm start-associations-once --association-id "8dfe3659-4309-493a-8755-0123456789ab" + diff --git a/awscli/examples/ssm/update-association-status.rst b/awscli/examples/ssm/update-association-status.rst index 225483a5aa47..470f4616dbbf 100644 --- a/awscli/examples/ssm/update-association-status.rst +++ b/awscli/examples/ssm/update-association-status.rst @@ -4,38 +4,40 @@ This example updates the association status of the association between an instan Command:: - aws ssm update-association-status --name "AWS-UpdateSSMAgent" --instance-id "i-0000293ffd8c57862" --association-status "Date=1424421071.939,Name=Pending,Message=temp_status_change,AdditionalInfo=Additional-Config-Needed" + aws ssm update-association-status --name "AWS-UpdateSSMAgent" --instance-id "i-1234567890abcdef0" --association-status "Date=1424421071.939,Name=Pending,Message=temp_status_change,AdditionalInfo=Additional-Config-Needed" Output:: { "AssociationDescription": { + "Name": "AWS-UpdateSSMAgent", + "InstanceId": "i-1234567890abcdef0", + "AssociationVersion": "1", + "Date": 1550507529.604, + "LastUpdateAssociationDate": 1550507806.974, "Status": { "Date": 1424421071.0, - "AdditionalInfo": "Additional-Config-Needed", + "Name": "Pending", "Message": "temp_status_change", - "Name": "Pending" + "AdditionalInfo": "Additional-Config-Needed" }, - "Name": "AWS-UpdateSSMAgent", - "InstanceId": "i-0000293ffd8c57862", "Overview": { - "Status": "Pending", - "DetailedStatus": "Associated", + "Status": "Success", "AssociationStatusAggregatedCount": { - "Pending": 1 + "Success": 1 } }, - "AssociationId": "d8617c07-2079-4c18-9847-1655fc2698b0", "DocumentVersion": "$DEFAULT", - "LastUpdateAssociationDate": 1487876122.564, - "Date": 1487876122.564, + "AssociationId": "8dfe3659-4309-493a-8755-0123456789ab", "Targets": [ { + "Key": "InstanceIds", "Values": [ - "i-0000293ffd8c57862" - ], - "Key": "InstanceIds" + "i-1234567890abcdef0" + ] } - ] + ], + "LastExecutionDate": 1550507808.0, + "LastSuccessfulExecutionDate": 1550507808.0 } } diff --git a/awscli/examples/ssm/update-association.rst b/awscli/examples/ssm/update-association.rst index 9cbd860c5480..3cfcf1d2b97e 100755 --- a/awscli/examples/ssm/update-association.rst +++ b/awscli/examples/ssm/update-association.rst @@ -4,32 +4,40 @@ This example updates an association with a new document version. Command:: - aws ssm update-association --association-id "4cc73e42-d5ae-4879-84f8-57e09c0efcd0" --document-version "\$LATEST" + aws ssm update-association --association-id "8dfe3659-4309-493a-8755-0123456789ab" --document-version "\$LATEST" Output:: { "AssociationDescription": { - "LastSuccessfulExecutionDate": 1487906247.0, "Name": "AWS-UpdateSSMAgent", - "LastExecutionDate": 1487906247.0, + "AssociationVersion": "2", + "Date": 1550508093.293, + "LastUpdateAssociationDate": 1550508106.596, "Overview": { - "Status": "Success", - "AssociationStatusAggregatedCount": { - "Success": 1 - } + "Status": "Pending", + "DetailedStatus": "Creating" }, - "AssociationId": "4cc73e42-d5ae-4879-84f8-57e09c0efcd0", "DocumentVersion": "$LATEST", - "LastUpdateAssociationDate": 1487906288.447, - "Date": 1487906246.999, + "AssociationId": "8dfe3659-4309-493a-8755-0123456789ab", "Targets": [ { + "Key": "tag:Name", "Values": [ - "i-0cb2b964d3e14fd9f" - ], - "Key": "instanceids" + "Linux" + ] } - ] + ], + "LastExecutionDate": 1550508094.879, + "LastSuccessfulExecutionDate": 1550508094.879 } } + +**To update the schedule expression of an association** + +This example updates the schedule expression for the specified association. + +Command:: + + aws ssm update-association --association-id "8dfe3659-4309-493a-8755-0123456789ab" --schedule-expression "cron(0 0 0/4 1/1 * ? *)" +