There are more AWS SDK examples available in the [AWS Doc SDK Examples](https://github.com/awsdocs/aws-doc-sdk-examples) GitHub repo.
# Code examples for Systems Manager using AWS SDKs
The following code examples show you how to use AWS Systems Manager with an AWS software development kit (SDK).
*Basics* are code examples that show you how to perform the essential operations within a service.
*Actions* are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios.
*Scenarios* are code examples that show you how to accomplish specific tasks by calling multiple functions within a service or combined with other AWS services.
**More resources**
+ **[ Systems Manager User Guide](https://docs.aws.amazon.com/systems-manager/latest/userguide/what-is-systems-manager.html)** – More information about Systems Manager.
+ **[Systems Manager API Reference](https://docs.aws.amazon.com/systems-manager/latest/APIReference/Welcome.html)** – Details about all available Systems Manager actions.
+ **[AWS Developer Center](https://aws.amazon.com/developer/code-examples/?awsf.sdk-code-examples-product=product%23systems-mgr)** – Code examples that you can filter by category or full-text search.
+ **[AWS SDK Examples](https://github.com/awsdocs/aws-doc-sdk-examples)** – GitHub repo with complete code in preferred languages. Includes instructions for setting up and running the code.
**Contents**
+ [Basics](ssm_code_examples_basics.md)
+ [Hello Systems Manager](ssm_example_ssm_Hello_section.md)
+ [Learn the basics](ssm_example_ssm_Scenario_section.md)
+ [Actions](ssm_code_examples_actions.md)
+ [`AddTagsToResource`](ssm_example_ssm_AddTagsToResource_section.md)
+ [`CancelCommand`](ssm_example_ssm_CancelCommand_section.md)
+ [`CreateActivation`](ssm_example_ssm_CreateActivation_section.md)
+ [`CreateAssociation`](ssm_example_ssm_CreateAssociation_section.md)
+ [`CreateAssociationBatch`](ssm_example_ssm_CreateAssociationBatch_section.md)
+ [`CreateDocument`](ssm_example_ssm_CreateDocument_section.md)
+ [`CreateMaintenanceWindow`](ssm_example_ssm_CreateMaintenanceWindow_section.md)
+ [`CreateOpsItem`](ssm_example_ssm_CreateOpsItem_section.md)
+ [`CreatePatchBaseline`](ssm_example_ssm_CreatePatchBaseline_section.md)
+ [`DeleteActivation`](ssm_example_ssm_DeleteActivation_section.md)
+ [`DeleteAssociation`](ssm_example_ssm_DeleteAssociation_section.md)
+ [`DeleteDocument`](ssm_example_ssm_DeleteDocument_section.md)
+ [`DeleteMaintenanceWindow`](ssm_example_ssm_DeleteMaintenanceWindow_section.md)
+ [`DeleteOpsItem`](ssm_example_ssm_DeleteOpsItem_section.md)
+ [`DeleteParameter`](ssm_example_ssm_DeleteParameter_section.md)
+ [`DeletePatchBaseline`](ssm_example_ssm_DeletePatchBaseline_section.md)
+ [`DeregisterManagedInstance`](ssm_example_ssm_DeregisterManagedInstance_section.md)
+ [`DeregisterPatchBaselineForPatchGroup`](ssm_example_ssm_DeregisterPatchBaselineForPatchGroup_section.md)
+ [`DeregisterTargetFromMaintenanceWindow`](ssm_example_ssm_DeregisterTargetFromMaintenanceWindow_section.md)
+ [`DeregisterTaskFromMaintenanceWindow`](ssm_example_ssm_DeregisterTaskFromMaintenanceWindow_section.md)
+ [`DescribeActivations`](ssm_example_ssm_DescribeActivations_section.md)
+ [`DescribeAssociation`](ssm_example_ssm_DescribeAssociation_section.md)
+ [`DescribeAssociationExecutionTargets`](ssm_example_ssm_DescribeAssociationExecutionTargets_section.md)
+ [`DescribeAssociationExecutions`](ssm_example_ssm_DescribeAssociationExecutions_section.md)
+ [`DescribeAutomationExecutions`](ssm_example_ssm_DescribeAutomationExecutions_section.md)
+ [`DescribeAutomationStepExecutions`](ssm_example_ssm_DescribeAutomationStepExecutions_section.md)
+ [`DescribeAvailablePatches`](ssm_example_ssm_DescribeAvailablePatches_section.md)
+ [`DescribeDocument`](ssm_example_ssm_DescribeDocument_section.md)
+ [`DescribeDocumentPermission`](ssm_example_ssm_DescribeDocumentPermission_section.md)
+ [`DescribeEffectiveInstanceAssociations`](ssm_example_ssm_DescribeEffectiveInstanceAssociations_section.md)
+ [`DescribeEffectivePatchesForPatchBaseline`](ssm_example_ssm_DescribeEffectivePatchesForPatchBaseline_section.md)
+ [`DescribeInstanceAssociationsStatus`](ssm_example_ssm_DescribeInstanceAssociationsStatus_section.md)
+ [`DescribeInstanceInformation`](ssm_example_ssm_DescribeInstanceInformation_section.md)
+ [`DescribeInstancePatchStates`](ssm_example_ssm_DescribeInstancePatchStates_section.md)
+ [`DescribeInstancePatchStatesForPatchGroup`](ssm_example_ssm_DescribeInstancePatchStatesForPatchGroup_section.md)
+ [`DescribeInstancePatches`](ssm_example_ssm_DescribeInstancePatches_section.md)
+ [`DescribeMaintenanceWindowExecutionTaskInvocations`](ssm_example_ssm_DescribeMaintenanceWindowExecutionTaskInvocations_section.md)
+ [`DescribeMaintenanceWindowExecutionTasks`](ssm_example_ssm_DescribeMaintenanceWindowExecutionTasks_section.md)
+ [`DescribeMaintenanceWindowExecutions`](ssm_example_ssm_DescribeMaintenanceWindowExecutions_section.md)
+ [`DescribeMaintenanceWindowTargets`](ssm_example_ssm_DescribeMaintenanceWindowTargets_section.md)
+ [`DescribeMaintenanceWindowTasks`](ssm_example_ssm_DescribeMaintenanceWindowTasks_section.md)
+ [`DescribeMaintenanceWindows`](ssm_example_ssm_DescribeMaintenanceWindows_section.md)
+ [`DescribeOpsItems`](ssm_example_ssm_DescribeOpsItems_section.md)
+ [`DescribeParameters`](ssm_example_ssm_DescribeParameters_section.md)
+ [`DescribePatchBaselines`](ssm_example_ssm_DescribePatchBaselines_section.md)
+ [`DescribePatchGroupState`](ssm_example_ssm_DescribePatchGroupState_section.md)
+ [`DescribePatchGroups`](ssm_example_ssm_DescribePatchGroups_section.md)
+ [`GetAutomationExecution`](ssm_example_ssm_GetAutomationExecution_section.md)
+ [`GetCommandInvocation`](ssm_example_ssm_GetCommandInvocation_section.md)
+ [`GetConnectionStatus`](ssm_example_ssm_GetConnectionStatus_section.md)
+ [`GetDefaultPatchBaseline`](ssm_example_ssm_GetDefaultPatchBaseline_section.md)
+ [`GetDeployablePatchSnapshotForInstance`](ssm_example_ssm_GetDeployablePatchSnapshotForInstance_section.md)
+ [`GetDocument`](ssm_example_ssm_GetDocument_section.md)
+ [`GetInventory`](ssm_example_ssm_GetInventory_section.md)
+ [`GetInventorySchema`](ssm_example_ssm_GetInventorySchema_section.md)
+ [`GetMaintenanceWindow`](ssm_example_ssm_GetMaintenanceWindow_section.md)
+ [`GetMaintenanceWindowExecution`](ssm_example_ssm_GetMaintenanceWindowExecution_section.md)
+ [`GetMaintenanceWindowExecutionTask`](ssm_example_ssm_GetMaintenanceWindowExecutionTask_section.md)
+ [`GetParameter`](ssm_example_ssm_GetParameter_section.md)
+ [`GetParameterHistory`](ssm_example_ssm_GetParameterHistory_section.md)
+ [`GetParameters`](ssm_example_ssm_GetParameters_section.md)
+ [`GetPatchBaseline`](ssm_example_ssm_GetPatchBaseline_section.md)
+ [`GetPatchBaselineForPatchGroup`](ssm_example_ssm_GetPatchBaselineForPatchGroup_section.md)
+ [`ListAssociationVersions`](ssm_example_ssm_ListAssociationVersions_section.md)
+ [`ListAssociations`](ssm_example_ssm_ListAssociations_section.md)
+ [`ListCommandInvocations`](ssm_example_ssm_ListCommandInvocations_section.md)
+ [`ListCommands`](ssm_example_ssm_ListCommands_section.md)
+ [`ListComplianceItems`](ssm_example_ssm_ListComplianceItems_section.md)
+ [`ListComplianceSummaries`](ssm_example_ssm_ListComplianceSummaries_section.md)
+ [`ListDocumentVersions`](ssm_example_ssm_ListDocumentVersions_section.md)
+ [`ListDocuments`](ssm_example_ssm_ListDocuments_section.md)
+ [`ListInventoryEntries`](ssm_example_ssm_ListInventoryEntries_section.md)
+ [`ListResourceComplianceSummaries`](ssm_example_ssm_ListResourceComplianceSummaries_section.md)
+ [`ListTagsForResource`](ssm_example_ssm_ListTagsForResource_section.md)
+ [`ModifyDocumentPermission`](ssm_example_ssm_ModifyDocumentPermission_section.md)
+ [`PutComplianceItems`](ssm_example_ssm_PutComplianceItems_section.md)
+ [`PutInventory`](ssm_example_ssm_PutInventory_section.md)
+ [`PutParameter`](ssm_example_ssm_PutParameter_section.md)
+ [`RegisterDefaultPatchBaseline`](ssm_example_ssm_RegisterDefaultPatchBaseline_section.md)
+ [`RegisterPatchBaselineForPatchGroup`](ssm_example_ssm_RegisterPatchBaselineForPatchGroup_section.md)
+ [`RegisterTargetWithMaintenanceWindow`](ssm_example_ssm_RegisterTargetWithMaintenanceWindow_section.md)
+ [`RegisterTaskWithMaintenanceWindow`](ssm_example_ssm_RegisterTaskWithMaintenanceWindow_section.md)
+ [`RemoveTagsFromResource`](ssm_example_ssm_RemoveTagsFromResource_section.md)
+ [`SendCommand`](ssm_example_ssm_SendCommand_section.md)
+ [`StartAutomationExecution`](ssm_example_ssm_StartAutomationExecution_section.md)
+ [`StartSession`](ssm_example_ssm_StartSession_section.md)
+ [`StopAutomationExecution`](ssm_example_ssm_StopAutomationExecution_section.md)
+ [`UpdateAssociation`](ssm_example_ssm_UpdateAssociation_section.md)
+ [`UpdateAssociationStatus`](ssm_example_ssm_UpdateAssociationStatus_section.md)
+ [`UpdateDocument`](ssm_example_ssm_UpdateDocument_section.md)
+ [`UpdateDocumentDefaultVersion`](ssm_example_ssm_UpdateDocumentDefaultVersion_section.md)
+ [`UpdateMaintenanceWindow`](ssm_example_ssm_UpdateMaintenanceWindow_section.md)
+ [`UpdateManagedInstanceRole`](ssm_example_ssm_UpdateManagedInstanceRole_section.md)
+ [`UpdateOpsItem`](ssm_example_ssm_UpdateOpsItem_section.md)
+ [`UpdatePatchBaseline`](ssm_example_ssm_UpdatePatchBaseline_section.md)
+ [Scenarios](ssm_code_examples_scenarios.md)
+ [Creating an Amazon ECS service for the EC2 launch type](ssm_example_ecs_GettingStarted_018_section.md)
+ [Getting started with Amazon EC2](ssm_example_ec2_GettingStarted_013_section.md)
+ [Setting up Systems Manager](ssm_example_iam_GettingStarted_046_section.md)
# Basic examples for Systems Manager using AWS SDKs
The following code examples show how to use the basics of AWS Systems Manager with AWS SDKs.
**Contents**
+ [Hello Systems Manager](ssm_example_ssm_Hello_section.md)
+ [Learn the basics](ssm_example_ssm_Scenario_section.md)
+ [Actions](ssm_code_examples_actions.md)
+ [`AddTagsToResource`](ssm_example_ssm_AddTagsToResource_section.md)
+ [`CancelCommand`](ssm_example_ssm_CancelCommand_section.md)
+ [`CreateActivation`](ssm_example_ssm_CreateActivation_section.md)
+ [`CreateAssociation`](ssm_example_ssm_CreateAssociation_section.md)
+ [`CreateAssociationBatch`](ssm_example_ssm_CreateAssociationBatch_section.md)
+ [`CreateDocument`](ssm_example_ssm_CreateDocument_section.md)
+ [`CreateMaintenanceWindow`](ssm_example_ssm_CreateMaintenanceWindow_section.md)
+ [`CreateOpsItem`](ssm_example_ssm_CreateOpsItem_section.md)
+ [`CreatePatchBaseline`](ssm_example_ssm_CreatePatchBaseline_section.md)
+ [`DeleteActivation`](ssm_example_ssm_DeleteActivation_section.md)
+ [`DeleteAssociation`](ssm_example_ssm_DeleteAssociation_section.md)
+ [`DeleteDocument`](ssm_example_ssm_DeleteDocument_section.md)
+ [`DeleteMaintenanceWindow`](ssm_example_ssm_DeleteMaintenanceWindow_section.md)
+ [`DeleteOpsItem`](ssm_example_ssm_DeleteOpsItem_section.md)
+ [`DeleteParameter`](ssm_example_ssm_DeleteParameter_section.md)
+ [`DeletePatchBaseline`](ssm_example_ssm_DeletePatchBaseline_section.md)
+ [`DeregisterManagedInstance`](ssm_example_ssm_DeregisterManagedInstance_section.md)
+ [`DeregisterPatchBaselineForPatchGroup`](ssm_example_ssm_DeregisterPatchBaselineForPatchGroup_section.md)
+ [`DeregisterTargetFromMaintenanceWindow`](ssm_example_ssm_DeregisterTargetFromMaintenanceWindow_section.md)
+ [`DeregisterTaskFromMaintenanceWindow`](ssm_example_ssm_DeregisterTaskFromMaintenanceWindow_section.md)
+ [`DescribeActivations`](ssm_example_ssm_DescribeActivations_section.md)
+ [`DescribeAssociation`](ssm_example_ssm_DescribeAssociation_section.md)
+ [`DescribeAssociationExecutionTargets`](ssm_example_ssm_DescribeAssociationExecutionTargets_section.md)
+ [`DescribeAssociationExecutions`](ssm_example_ssm_DescribeAssociationExecutions_section.md)
+ [`DescribeAutomationExecutions`](ssm_example_ssm_DescribeAutomationExecutions_section.md)
+ [`DescribeAutomationStepExecutions`](ssm_example_ssm_DescribeAutomationStepExecutions_section.md)
+ [`DescribeAvailablePatches`](ssm_example_ssm_DescribeAvailablePatches_section.md)
+ [`DescribeDocument`](ssm_example_ssm_DescribeDocument_section.md)
+ [`DescribeDocumentPermission`](ssm_example_ssm_DescribeDocumentPermission_section.md)
+ [`DescribeEffectiveInstanceAssociations`](ssm_example_ssm_DescribeEffectiveInstanceAssociations_section.md)
+ [`DescribeEffectivePatchesForPatchBaseline`](ssm_example_ssm_DescribeEffectivePatchesForPatchBaseline_section.md)
+ [`DescribeInstanceAssociationsStatus`](ssm_example_ssm_DescribeInstanceAssociationsStatus_section.md)
+ [`DescribeInstanceInformation`](ssm_example_ssm_DescribeInstanceInformation_section.md)
+ [`DescribeInstancePatchStates`](ssm_example_ssm_DescribeInstancePatchStates_section.md)
+ [`DescribeInstancePatchStatesForPatchGroup`](ssm_example_ssm_DescribeInstancePatchStatesForPatchGroup_section.md)
+ [`DescribeInstancePatches`](ssm_example_ssm_DescribeInstancePatches_section.md)
+ [`DescribeMaintenanceWindowExecutionTaskInvocations`](ssm_example_ssm_DescribeMaintenanceWindowExecutionTaskInvocations_section.md)
+ [`DescribeMaintenanceWindowExecutionTasks`](ssm_example_ssm_DescribeMaintenanceWindowExecutionTasks_section.md)
+ [`DescribeMaintenanceWindowExecutions`](ssm_example_ssm_DescribeMaintenanceWindowExecutions_section.md)
+ [`DescribeMaintenanceWindowTargets`](ssm_example_ssm_DescribeMaintenanceWindowTargets_section.md)
+ [`DescribeMaintenanceWindowTasks`](ssm_example_ssm_DescribeMaintenanceWindowTasks_section.md)
+ [`DescribeMaintenanceWindows`](ssm_example_ssm_DescribeMaintenanceWindows_section.md)
+ [`DescribeOpsItems`](ssm_example_ssm_DescribeOpsItems_section.md)
+ [`DescribeParameters`](ssm_example_ssm_DescribeParameters_section.md)
+ [`DescribePatchBaselines`](ssm_example_ssm_DescribePatchBaselines_section.md)
+ [`DescribePatchGroupState`](ssm_example_ssm_DescribePatchGroupState_section.md)
+ [`DescribePatchGroups`](ssm_example_ssm_DescribePatchGroups_section.md)
+ [`GetAutomationExecution`](ssm_example_ssm_GetAutomationExecution_section.md)
+ [`GetCommandInvocation`](ssm_example_ssm_GetCommandInvocation_section.md)
+ [`GetConnectionStatus`](ssm_example_ssm_GetConnectionStatus_section.md)
+ [`GetDefaultPatchBaseline`](ssm_example_ssm_GetDefaultPatchBaseline_section.md)
+ [`GetDeployablePatchSnapshotForInstance`](ssm_example_ssm_GetDeployablePatchSnapshotForInstance_section.md)
+ [`GetDocument`](ssm_example_ssm_GetDocument_section.md)
+ [`GetInventory`](ssm_example_ssm_GetInventory_section.md)
+ [`GetInventorySchema`](ssm_example_ssm_GetInventorySchema_section.md)
+ [`GetMaintenanceWindow`](ssm_example_ssm_GetMaintenanceWindow_section.md)
+ [`GetMaintenanceWindowExecution`](ssm_example_ssm_GetMaintenanceWindowExecution_section.md)
+ [`GetMaintenanceWindowExecutionTask`](ssm_example_ssm_GetMaintenanceWindowExecutionTask_section.md)
+ [`GetParameter`](ssm_example_ssm_GetParameter_section.md)
+ [`GetParameterHistory`](ssm_example_ssm_GetParameterHistory_section.md)
+ [`GetParameters`](ssm_example_ssm_GetParameters_section.md)
+ [`GetPatchBaseline`](ssm_example_ssm_GetPatchBaseline_section.md)
+ [`GetPatchBaselineForPatchGroup`](ssm_example_ssm_GetPatchBaselineForPatchGroup_section.md)
+ [`ListAssociationVersions`](ssm_example_ssm_ListAssociationVersions_section.md)
+ [`ListAssociations`](ssm_example_ssm_ListAssociations_section.md)
+ [`ListCommandInvocations`](ssm_example_ssm_ListCommandInvocations_section.md)
+ [`ListCommands`](ssm_example_ssm_ListCommands_section.md)
+ [`ListComplianceItems`](ssm_example_ssm_ListComplianceItems_section.md)
+ [`ListComplianceSummaries`](ssm_example_ssm_ListComplianceSummaries_section.md)
+ [`ListDocumentVersions`](ssm_example_ssm_ListDocumentVersions_section.md)
+ [`ListDocuments`](ssm_example_ssm_ListDocuments_section.md)
+ [`ListInventoryEntries`](ssm_example_ssm_ListInventoryEntries_section.md)
+ [`ListResourceComplianceSummaries`](ssm_example_ssm_ListResourceComplianceSummaries_section.md)
+ [`ListTagsForResource`](ssm_example_ssm_ListTagsForResource_section.md)
+ [`ModifyDocumentPermission`](ssm_example_ssm_ModifyDocumentPermission_section.md)
+ [`PutComplianceItems`](ssm_example_ssm_PutComplianceItems_section.md)
+ [`PutInventory`](ssm_example_ssm_PutInventory_section.md)
+ [`PutParameter`](ssm_example_ssm_PutParameter_section.md)
+ [`RegisterDefaultPatchBaseline`](ssm_example_ssm_RegisterDefaultPatchBaseline_section.md)
+ [`RegisterPatchBaselineForPatchGroup`](ssm_example_ssm_RegisterPatchBaselineForPatchGroup_section.md)
+ [`RegisterTargetWithMaintenanceWindow`](ssm_example_ssm_RegisterTargetWithMaintenanceWindow_section.md)
+ [`RegisterTaskWithMaintenanceWindow`](ssm_example_ssm_RegisterTaskWithMaintenanceWindow_section.md)
+ [`RemoveTagsFromResource`](ssm_example_ssm_RemoveTagsFromResource_section.md)
+ [`SendCommand`](ssm_example_ssm_SendCommand_section.md)
+ [`StartAutomationExecution`](ssm_example_ssm_StartAutomationExecution_section.md)
+ [`StartSession`](ssm_example_ssm_StartSession_section.md)
+ [`StopAutomationExecution`](ssm_example_ssm_StopAutomationExecution_section.md)
+ [`UpdateAssociation`](ssm_example_ssm_UpdateAssociation_section.md)
+ [`UpdateAssociationStatus`](ssm_example_ssm_UpdateAssociationStatus_section.md)
+ [`UpdateDocument`](ssm_example_ssm_UpdateDocument_section.md)
+ [`UpdateDocumentDefaultVersion`](ssm_example_ssm_UpdateDocumentDefaultVersion_section.md)
+ [`UpdateMaintenanceWindow`](ssm_example_ssm_UpdateMaintenanceWindow_section.md)
+ [`UpdateManagedInstanceRole`](ssm_example_ssm_UpdateManagedInstanceRole_section.md)
+ [`UpdateOpsItem`](ssm_example_ssm_UpdateOpsItem_section.md)
+ [`UpdatePatchBaseline`](ssm_example_ssm_UpdatePatchBaseline_section.md)
# Hello Systems Manager
The following code examples show how to get started using Systems Manager.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/ssm#code-examples).
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ssm.SsmClient;
import software.amazon.awssdk.services.ssm.model.DocumentFilter;
import software.amazon.awssdk.services.ssm.model.ListDocumentsRequest;
import software.amazon.awssdk.services.ssm.model.ListDocumentsResponse;
public class HelloSSM {
public static void main(String[] args) {
final String usage = """
Usage:
Where:
awsAccount - Your AWS Account number.
""";
if (args.length != 1) {
System.out.println(usage);
System.exit(1);
}
String awsAccount = args[0] ;
Region region = Region.US_EAST_1;
SsmClient ssmClient = SsmClient.builder()
.region(region)
.build();
listDocuments(ssmClient, awsAccount);
}
/*
This code automatically fetches the next set of results using the `nextToken` and
stops once the desired maxResults (20 in this case) have been reached.
*/
public static void listDocuments(SsmClient ssmClient, String awsAccount) {
String nextToken = null;
int totalDocumentsReturned = 0;
int maxResults = 20;
do {
ListDocumentsRequest request = ListDocumentsRequest.builder()
.documentFilterList(
DocumentFilter.builder()
.key("Owner")
.value(awsAccount)
.build()
)
.maxResults(maxResults)
.nextToken(nextToken)
.build();
ListDocumentsResponse response = ssmClient.listDocuments(request);
response.documentIdentifiers().forEach(identifier -> System.out.println("Document Name: " + identifier.name()));
nextToken = response.nextToken();
totalDocumentsReturned += response.documentIdentifiers().size();
} while (nextToken != null && totalDocumentsReturned < maxResults);
}
}
```
+ For API details, see [ListDocuments](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/ListDocuments) in *AWS SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ssm#code-examples).
```
import { paginateListDocuments, SSMClient } from "@aws-sdk/client-ssm";
// Call ListDocuments and display the result.
export const main = async () => {
const client = new SSMClient();
const listDocumentsPaginated = [];
console.log(
"Hello, AWS Systems Manager! Let's list some of your documents:\n",
);
try {
// The paginate function is a wrapper around the base command.
const paginator = paginateListDocuments({ client }, { MaxResults: 5 });
for await (const page of paginator) {
listDocumentsPaginated.push(...page.DocumentIdentifiers);
}
} catch (caught) {
console.error(`There was a problem saying hello: ${caught.message}`);
throw caught;
}
for (const { Name, DocumentFormat, CreatedDate } of listDocumentsPaginated) {
console.log(`${Name} - ${DocumentFormat} - ${CreatedDate}`);
}
};
// Call function if run directly.
import { fileURLToPath } from "node:url";
if (process.argv[1] === fileURLToPath(import.meta.url)) {
main();
}
```
+ For API details, see [ListDocuments](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/ListDocumentsCommand) in *AWS SDK for JavaScript API Reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
```
import boto3
from botocore.exceptions import ClientError
def hello_systems_manager(ssm_client):
"""
Use the AWS SDK for Python (Boto3) to create an AWS Systems Manager
client and list the first 5 documents in your account.
This example uses the default settings specified in your shared credentials
and config files.
:param ssm_client: A Boto3 AWS Systems Manager Client object. This object wraps
the low-level AWS Systems Manager service API.
"""
print("Hello, AWS Systems Manager! Let's list some of your documents:\n")
paginator = ssm_client.get_paginator("list_documents")
page_iterator = paginator.paginate(PaginationConfig={"MaxItems": 5})
for page in page_iterator:
for document in page["DocumentIdentifiers"]:
print(f" {document['Name']}")
if __name__ == "__main__":
try:
hello_systems_manager(boto3.client("ssm"))
except ClientError as err:
print("Hello systems manager had an error.")
print(err.response["Error"]["Code"])
print(err.response["Error"]["Message"])
```
+ For API details, see [ListDocuments](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/ListDocuments) in *AWS SDK for Python (Boto3) API Reference*.
------
# Learn the basics of Systems Manager with an AWS SDK
The following code examples show how to:
+ Create a maintenance window.
+ Modify the maintenance window schedule.
+ Create a document.
+ Send a command to a specified EC2 instance.
+ Create an OpsItem.
+ Update and resolve the OpsItem.
+ Delete the maintenance window, OpsItem, and document.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/ssm#code-examples).
```
import software.amazon.awssdk.services.ssm.model.DocumentAlreadyExistsException;
import software.amazon.awssdk.services.ssm.model.SsmException;
import java.util.Map;
import java.util.Scanner;
public class SSMScenario {
public static final String DASHES = new String(new char[80]).replace("\0", "-");
private static final String ROLES_STACK = "SsmStack3`1";
public static void main(String[] args) {
String usage = """
Usage:
<source> <category> <severity>
Where:
title - The title of the parameter (default is Disk Space Alert).
source - The source of the parameter (default is EC2).
category - The category of the parameter. Valid values are 'Availability', 'Cost', 'Performance', 'Recovery', 'Security' (default is Performance).
severity - The severity of the parameter. Severity should be a number from 1 to 4 (default is 2).
""";
Scanner scanner = new Scanner(System.in);
SSMActions actions = new SSMActions();
String documentName;
String windowName;
System.out.println("Use AWS CloudFormation to create the EC2 instance that is required for this scenario.");
CloudFormationHelper.deployCloudFormationStack(ROLES_STACK);
Map<String, String> stackOutputs = CloudFormationHelper.getStackOutputsAsync(ROLES_STACK).join();
String instanceId = stackOutputs.get("InstanceId");
System.out.println("The Instance ID: " + instanceId +" was created.");
String title = "Disk Space Alert" ;
String source = "EC2" ;
String category = "Availability" ;
String severity = "2" ;
System.out.println(DASHES);
System.out.println("""
Welcome to the AWS Systems Manager SDK Basics scenario.
This Java program demonstrates how to interact with AWS Systems Manager using the AWS SDK for Java (v2).
AWS Systems Manager is the operations hub for your AWS applications and resources and a secure end-to-end management solution.
The program's primary functionalities include creating a maintenance window, creating a document, sending a command to a document,
listing documents, listing commands, creating an OpsItem, modifying an OpsItem, and deleting AWS SSM resources.
Upon completion of the program, all AWS resources are cleaned up.
Let's get started...
""");
waitForInputToContinue(scanner);
System.out.println(DASHES);
System.out.println("1. Create an SSM maintenance window.");
System.out.println("Please enter the maintenance window name (default is ssm-maintenance-window):");
String win = scanner.nextLine();
windowName = win.isEmpty() ? "ssm-maintenance-window" : win;
String winId = null;
try {
winId = actions.createMaintenanceWindow(windowName);
waitForInputToContinue(scanner);
System.out.println("The maintenance window ID is: " + winId);
} catch (DocumentAlreadyExistsException e) {
System.err.println("The SSM maintenance window already exists. Retrieving existing window ID...");
String existingWinId = actions.createMaintenanceWindow(windowName);
System.out.println("Existing window ID: " + existingWinId);
} catch (SsmException e) {
System.err.println("SSM error: " + e.getMessage());
return;
} catch (RuntimeException e) {
System.err.println("Unexpected error: " + e.getMessage());
return;
}
waitForInputToContinue(scanner);
System.out.println(DASHES);
System.out.println("2. Modify the maintenance window by changing the schedule");
waitForInputToContinue(scanner);
try {
actions.updateSSMMaintenanceWindow(winId, windowName);
waitForInputToContinue(scanner);
System.out.println("The SSM maintenance window was successfully updated");
} catch (SsmException e) {
System.err.println("SSM error: " + e.getMessage());
return;
} catch (RuntimeException e) {
System.err.println("Unexpected error: " + e.getMessage());
return;
}
waitForInputToContinue(scanner);
System.out.println(DASHES);
System.out.println("3. Create an SSM document that defines the actions that Systems Manager performs on your managed nodes.");
System.out.println("Please enter the document name (default is ssmdocument):");
String doc = scanner.nextLine();
documentName = doc.isEmpty() ? "ssmdocument" : doc;
try {
actions.createSSMDoc(documentName);
waitForInputToContinue(scanner);
System.out.println("The SSM document was successfully created");
} catch (DocumentAlreadyExistsException e) {
System.err.println("The SSM document already exists. Moving on");
} catch (SsmException e) {
System.err.println("SSM error: " + e.getMessage());
return;
} catch (RuntimeException e) {
System.err.println("Unexpected error: " + e.getMessage());
}
waitForInputToContinue(scanner);
System.out.println(DASHES);
System.out.println("4. Now we are going to run a command on an EC2 instance");
waitForInputToContinue(scanner);
String commandId="";
try {
commandId = actions.sendSSMCommand(documentName, instanceId);
waitForInputToContinue(scanner);
System.out.println("The command was successfully sent. Command ID: " + commandId);
} catch (SsmException e) {
System.err.println("SSM error: " + e.getMessage());
} catch (InterruptedException e) {
System.err.println("Thread was interrupted: " + e.getMessage());
} catch (RuntimeException e) {
System.err.println("Unexpected error: " + e.getMessage());
}
waitForInputToContinue(scanner);
System.out.println(DASHES);
System.out.println("5. Lets get the time when the specific command was sent to the specific managed node");
waitForInputToContinue(scanner);
try {
actions.displayCommands(commandId);
System.out.println("The command invocations were successfully displayed.");
} catch (SsmException e) {
System.err.println("SSM error: " + e.getMessage());
return;
} catch (RuntimeException e) {
System.err.println("Unexpected error: " + e.getMessage());
return;
}
waitForInputToContinue(scanner);
System.out.println(DASHES);
System.out.println(DASHES);
System.out.println("""
6. Now we will create an SSM OpsItem.
A SSM OpsItem is a feature provided by Amazon's Systems Manager (SSM) service.
It is a type of operational data item that allows you to manage and track various operational issues,
events, or tasks within your AWS environment.
You can create OpsItems to track and manage operational issues as they arise.
For example, you could create an OpsItem whenever your application detects a critical error
or an anomaly in your infrastructure.
""");
waitForInputToContinue(scanner);
String opsItemId;
try {
opsItemId = actions.createSSMOpsItem(title, source, category, severity);
System.out.println(opsItemId + " was created");
} catch (SsmException e) {
System.err.println("SSM error: " + e.getMessage());
return;
} catch (RuntimeException e) {
System.err.println("Unexpected error: " + e.getMessage());
return;
}
waitForInputToContinue(scanner);
System.out.println(DASHES);
System.out.println(DASHES);
System.out.println("7. Now we will update the SSM OpsItem "+opsItemId);
waitForInputToContinue(scanner);
String description = "An update to "+opsItemId ;
try {
actions.updateOpsItem(opsItemId, title, description);
} catch (SsmException e) {
System.err.println("SSM error: " + e.getMessage());
return;
} catch (RuntimeException e) {
System.err.println("Unexpected error: " + e.getMessage());
return;
}
System.out.println(DASHES);
System.out.println("8. Now we will get the status of the SSM OpsItem "+opsItemId);
waitForInputToContinue(scanner);
try {
actions.describeOpsItems(opsItemId);
} catch (SsmException e) {
System.err.println("SSM error: " + e.getMessage());
return;
} catch (RuntimeException e) {
System.err.println("Unexpected error: " + e.getMessage());
return;
}
System.out.println(DASHES);
System.out.println("9. Now we will resolve the SSM OpsItem "+opsItemId);
waitForInputToContinue(scanner);
try {
actions.resolveOpsItem(opsItemId);
} catch (SsmException e) {
System.err.println("SSM error: " + e.getMessage());
return;
} catch (RuntimeException e) {
System.err.println("Unexpected error: " + e.getMessage());
return;
}
System.out.println(DASHES);
System.out.println("10. Would you like to delete the AWS Systems Manager resources? (y/n)");
String delAns = scanner.nextLine().trim();
if (delAns.equalsIgnoreCase("y")) {
System.out.println("You selected to delete the resources.");
waitForInputToContinue(scanner);
try {
actions.deleteMaintenanceWindow(winId);
actions.deleteDoc(documentName);
} catch (SsmException e) {
System.err.println("SSM error: " + e.getMessage());
return;
} catch (RuntimeException e) {
System.err.println("Unexpected error: " + e.getMessage());
return;
}
} else {
System.out.println("The AWS Systems Manager resources will not be deleted");
}
System.out.println(DASHES);
CloudFormationHelper.destroyCloudFormationStack(ROLES_STACK);
System.out.println("This concludes the AWS Systems Manager SDK Basics scenario.");
System.out.println(DASHES);
}
private static void waitForInputToContinue(Scanner scanner) {
while (true) {
System.out.println("");
System.out.println("Enter 'c' followed by <ENTER> to continue:");
String input = scanner.nextLine();
if (input.trim().equalsIgnoreCase("c")) {
System.out.println("Continuing with the program...");
System.out.println("");
break;
} else {
// Handle invalid input.
System.out.println("Invalid input. Please try again.");
}
}
}
}
```
A wrapper class for Systems Manager SDK methods.
```
public class SSMActions {
private static SsmAsyncClient ssmAsyncClient;
private static SsmAsyncClient getAsyncClient() {
if (ssmAsyncClient == null) {
SdkAsyncHttpClient httpClient = NettyNioAsyncHttpClient.builder()
.maxConcurrency(100)
.connectionTimeout(Duration.ofSeconds(60))
.readTimeout(Duration.ofSeconds(60))
.writeTimeout(Duration.ofSeconds(60))
.build();
ClientOverrideConfiguration overrideConfig = ClientOverrideConfiguration.builder()
.apiCallTimeout(Duration.ofMinutes(2))
.apiCallAttemptTimeout(Duration.ofSeconds(90))
.retryPolicy(RetryPolicy.builder()
.numRetries(3)
.build())
.build();
ssmAsyncClient = SsmAsyncClient.builder()
.region(Region.US_WEST_2)
.httpClient(httpClient)
.overrideConfiguration(overrideConfig)
.build();
}
return ssmAsyncClient;
}
/**
* Deletes an AWS SSM document asynchronously.
*
* @param documentName The name of the document to delete.
* <p>
* This method initiates an asynchronous request to delete an SSM document.
* If an exception occurs, it handles the error appropriately.
*/
public void deleteDoc(String documentName) {
DeleteDocumentRequest documentRequest = DeleteDocumentRequest.builder()
.name(documentName)
.build();
CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
getAsyncClient().deleteDocument(documentRequest)
.thenAccept(response -> {
System.out.println("The SSM document was successfully deleted.");
})
.exceptionally(ex -> {
throw new CompletionException(ex);
}).join();
}).exceptionally(ex -> {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw new RuntimeException("SSM error: " + cause.getMessage(), cause);
} else {
throw new RuntimeException("Unexpected error: " + cause.getMessage(), cause);
}
});
try {
future.join();
} catch (CompletionException ex) {
throw ex.getCause() instanceof RuntimeException ? (RuntimeException) ex.getCause() : ex;
}
}
/**
* Deletes an AWS SSM Maintenance Window asynchronously.
*
* @param winId The ID of the Maintenance Window to delete.
* <p>
* This method initiates an asynchronous request to delete an SSM Maintenance Window.
* If an exception occurs, it handles the error appropriately.
*/
public void deleteMaintenanceWindow(String winId) {
DeleteMaintenanceWindowRequest windowRequest = DeleteMaintenanceWindowRequest.builder()
.windowId(winId)
.build();
CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
getAsyncClient().deleteMaintenanceWindow(windowRequest)
.thenAccept(response -> {
System.out.println("The maintenance window was successfully deleted.");
})
.exceptionally(ex -> {
throw new CompletionException(ex);
}).join();
}).exceptionally(ex -> {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw new RuntimeException("SSM error: " + cause.getMessage(), cause);
} else {
throw new RuntimeException("Unexpected error: " + cause.getMessage(), cause);
}
});
try {
future.join();
} catch (CompletionException ex) {
throw ex.getCause() instanceof RuntimeException ? (RuntimeException) ex.getCause() : ex;
}
}
/**
* Resolves an AWS SSM OpsItem asynchronously.
*
* @param opsID The ID of the OpsItem to resolve.
* <p>
* This method initiates an asynchronous request to resolve an SSM OpsItem.
* If an exception occurs, it handles the error appropriately.
*/
public void resolveOpsItem(String opsID) {
UpdateOpsItemRequest opsItemRequest = UpdateOpsItemRequest.builder()
.opsItemId(opsID)
.status(OpsItemStatus.RESOLVED)
.build();
CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
getAsyncClient().updateOpsItem(opsItemRequest)
.thenAccept(response -> {
System.out.println("OpsItem resolved successfully.");
})
.exceptionally(ex -> {
throw new CompletionException(ex);
}).join();
}).exceptionally(ex -> {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw new RuntimeException("SSM error: " + cause.getMessage(), cause);
} else {
throw new RuntimeException("Unexpected error: " + cause.getMessage(), cause);
}
});
try {
future.join();
} catch (CompletionException ex) {
throw ex.getCause() instanceof RuntimeException ? (RuntimeException) ex.getCause() : ex;
}
}
/**
* Describes AWS SSM OpsItems asynchronously.
*
* @param key The key to filter OpsItems by (e.g., OPS_ITEM_ID).
*
* This method initiates an asynchronous request to describe SSM OpsItems.
* If the request is successful, it prints the title and status of each OpsItem.
* If an exception occurs, it handles the error appropriately.
*/
public void describeOpsItems(String key) {
OpsItemFilter filter = OpsItemFilter.builder()
.key(OpsItemFilterKey.OPS_ITEM_ID)
.values(key)
.operator(OpsItemFilterOperator.EQUAL)
.build();
DescribeOpsItemsRequest itemsRequest = DescribeOpsItemsRequest.builder()
.maxResults(10)
.opsItemFilters(filter)
.build();
CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
getAsyncClient().describeOpsItems(itemsRequest)
.thenAccept(itemsResponse -> {
List<OpsItemSummary> items = itemsResponse.opsItemSummaries();
for (OpsItemSummary item : items) {
System.out.println("The item title is " + item.title() + " and the status is " + item.status().toString());
}
})
.exceptionally(ex -> {
throw new CompletionException(ex);
}).join();
}).exceptionally(ex -> {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw new RuntimeException("SSM error: " + cause.getMessage(), cause);
} else {
throw new RuntimeException("Unexpected error: " + cause.getMessage(), cause);
}
});
try {
future.join();
} catch (CompletionException ex) {
throw ex.getCause() instanceof RuntimeException ? (RuntimeException) ex.getCause() : ex;
}
}
/**
* Updates the AWS SSM OpsItem asynchronously.
*
* @param opsItemId The ID of the OpsItem to update.
* @param title The new title of the OpsItem.
* @param description The new description of the OpsItem.
* <p>
* This method initiates an asynchronous request to update an SSM OpsItem.
* If the request is successful, it completes without returning a value.
* If an exception occurs, it handles the error appropriately.
*/
public void updateOpsItem(String opsItemId, String title, String description) {
Map<String, OpsItemDataValue> operationalData = new HashMap<>();
operationalData.put("key1", OpsItemDataValue.builder().value("value1").build());
operationalData.put("key2", OpsItemDataValue.builder().value("value2").build());
CompletableFuture<Void> future = getOpsItem(opsItemId).thenCompose(opsItem -> {
UpdateOpsItemRequest request = UpdateOpsItemRequest.builder()
.opsItemId(opsItemId)
.title(title)
.operationalData(operationalData)
.status(opsItem.statusAsString())
.description(description)
.build();
return getAsyncClient().updateOpsItem(request).thenAccept(response -> {
System.out.println(opsItemId + " updated successfully.");
}).exceptionally(ex -> {
throw new CompletionException(ex);
});
}).exceptionally(ex -> {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw new RuntimeException("SSM error: " + cause.getMessage(), cause);
} else {
throw new RuntimeException("Unexpected error: " + cause.getMessage(), cause);
}
});
try {
future.join();
} catch (CompletionException ex) {
throw ex.getCause() instanceof RuntimeException ? (RuntimeException) ex.getCause() : ex;
}
}
private static CompletableFuture<OpsItem> getOpsItem(String opsItemId) {
GetOpsItemRequest request = GetOpsItemRequest.builder().opsItemId(opsItemId).build();
return getAsyncClient().getOpsItem(request).thenApply(GetOpsItemResponse::opsItem);
}
/**
* Creates an SSM OpsItem asynchronously.
*
* @param title The title of the OpsItem.
* @param source The source of the OpsItem.
* @param category The category of the OpsItem.
* @param severity The severity of the OpsItem.
* @return The ID of the created OpsItem.
* <p>
* This method initiates an asynchronous request to create an SSM OpsItem.
* If the request is successful, it returns the OpsItem ID.
* If an exception occurs, it handles the error appropriately.
*/
public String createSSMOpsItem(String title, String source, String category, String severity) {
CreateOpsItemRequest opsItemRequest = CreateOpsItemRequest.builder()
.description("Created by the SSM Java API")
.title(title)
.source(source)
.category(category)
.severity(severity)
.build();
CompletableFuture<CreateOpsItemResponse> future = getAsyncClient().createOpsItem(opsItemRequest);
try {
CreateOpsItemResponse response = future.join();
return response.opsItemId();
} catch (CompletionException e) {
Throwable cause = e.getCause();
if (cause instanceof SsmException) {
throw (SsmException) cause;
} else {
throw new RuntimeException(cause);
}
}
}
/**
* Displays the date and time when the specific command was invoked.
*
* @param commandId The ID of the command to describe.
* <p>
* This method initiates an asynchronous request to list command invocations and prints the date and time of each command invocation.
* If an exception occurs, it handles the error appropriately.
*/
public void displayCommands(String commandId) {
ListCommandInvocationsRequest commandInvocationsRequest = ListCommandInvocationsRequest.builder()
.commandId(commandId)
.build();
CompletableFuture<ListCommandInvocationsResponse> future = getAsyncClient().listCommandInvocations(commandInvocationsRequest);
future.thenAccept(response -> {
List<CommandInvocation> commandList = response.commandInvocations();
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss").withZone(ZoneId.systemDefault());
for (CommandInvocation invocation : commandList) {
System.out.println("The time of the command invocation is " + formatter.format(invocation.requestedDateTime()));
}
}).exceptionally(ex -> {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw (SsmException) cause;
} else {
throw new RuntimeException(cause);
}
}).join();
}
/**
* Sends a SSM command to a managed node asynchronously.
*
* @param documentName The name of the document to use.
* @param instanceId The ID of the instance to send the command to.
* @return The command ID.
* <p>
* This method initiates asynchronous requests to send a SSM command to a managed node.
* It waits until the document is active, sends the command, and checks the command execution status.
*/
public String sendSSMCommand(String documentName, String instanceId) throws InterruptedException, SsmException {
// Before we use Document to send a command - make sure it is active.
CompletableFuture<Void> documentActiveFuture = CompletableFuture.runAsync(() -> {
boolean isDocumentActive = false;
DescribeDocumentRequest request = DescribeDocumentRequest.builder()
.name(documentName)
.build();
while (!isDocumentActive) {
CompletableFuture<DescribeDocumentResponse> response = getAsyncClient().describeDocument(request);
String documentStatus = response.join().document().statusAsString();
if (documentStatus.equals("Active")) {
System.out.println("The SSM document is active and ready to use.");
isDocumentActive = true;
} else {
System.out.println("The SSM document is not active. Status: " + documentStatus);
try {
Thread.sleep(5000);
} catch (InterruptedException e) {
throw new RuntimeException(e);
}
}
}
});
documentActiveFuture.join();
// Create the SendCommandRequest.
SendCommandRequest commandRequest = SendCommandRequest.builder()
.documentName(documentName)
.instanceIds(instanceId)
.build();
// Send the command.
CompletableFuture<SendCommandResponse> commandFuture = getAsyncClient().sendCommand(commandRequest);
final String[] commandId = {null};
commandFuture.whenComplete((commandResponse, ex) -> {
if (commandResponse != null) {
commandId[0] = commandResponse.command().commandId();
System.out.println("Command ID: " + commandId[0]);
// Wait for the command execution to complete.
GetCommandInvocationRequest invocationRequest = GetCommandInvocationRequest.builder()
.commandId(commandId[0])
.instanceId(instanceId)
.build();
try {
System.out.println("Wait 5 secs");
TimeUnit.SECONDS.sleep(5);
// Retrieve the command execution details.
CompletableFuture<GetCommandInvocationResponse> invocationFuture = getAsyncClient().getCommandInvocation(invocationRequest);
invocationFuture.whenComplete((commandInvocationResponse, invocationEx) -> {
if (commandInvocationResponse != null) {
// Check the status of the command execution.
CommandInvocationStatus status = commandInvocationResponse.status();
if (status == CommandInvocationStatus.SUCCESS) {
System.out.println("Command execution successful");
} else {
System.out.println("Command execution failed. Status: " + status);
}
} else {
Throwable invocationCause = (invocationEx instanceof CompletionException) ? invocationEx.getCause() : invocationEx;
throw new CompletionException(invocationCause);
}
}).join();
} catch (InterruptedException e) {
throw new RuntimeException(e);
}
} else {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw (SsmException) cause;
} else {
throw new RuntimeException(cause);
}
}
}).join();
return commandId[0];
}
/**
* Creates an AWS SSM document asynchronously.
*
* @param docName The name of the document to create.
* <p>
* This method initiates an asynchronous request to create an SSM document.
* If the request is successful, it prints the document status.
* If an exception occurs, it handles the error appropriately.
*/
public void createSSMDoc(String docName) throws SsmException {
String jsonData = """
{
"schemaVersion": "2.2",
"description": "Run a simple shell command",
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runEchoCommand",
"inputs": {
"runCommand": [
"echo 'Hello, world!'"
]
}
}
]
}
""";
CreateDocumentRequest request = CreateDocumentRequest.builder()
.content(jsonData)
.name(docName)
.documentType(DocumentType.COMMAND)
.build();
CompletableFuture<CreateDocumentResponse> future = getAsyncClient().createDocument(request);
future.thenAccept(response -> {
System.out.println("The status of the SSM document is " + response.documentDescription().status());
}).exceptionally(ex -> {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof DocumentAlreadyExistsException) {
throw new CompletionException(cause);
} else if (cause instanceof SsmException) {
throw new CompletionException(cause);
} else {
throw new RuntimeException(cause);
}
}).join();
}
/**
* Updates an SSM maintenance window asynchronously.
*
* @param id The ID of the maintenance window to update.
* @param name The new name for the maintenance window.
* <p>
* This method initiates an asynchronous request to update an SSM maintenance window.
* If the request is successful, it prints a success message.
* If an exception occurs, it handles the error appropriately.
*/
public void updateSSMMaintenanceWindow(String id, String name) throws SsmException {
UpdateMaintenanceWindowRequest updateRequest = UpdateMaintenanceWindowRequest.builder()
.windowId(id)
.allowUnassociatedTargets(true)
.duration(24)
.enabled(true)
.name(name)
.schedule("cron(0 0 ? * MON *)")
.build();
CompletableFuture<UpdateMaintenanceWindowResponse> future = getAsyncClient().updateMaintenanceWindow(updateRequest);
future.whenComplete((response, ex) -> {
if (response != null) {
System.out.println("The SSM maintenance window was successfully updated");
} else {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw new CompletionException(cause);
} else {
throw new RuntimeException(cause);
}
}
}).join();
}
/**
* Creates an SSM maintenance window asynchronously.
*
* @param winName The name of the maintenance window.
* @return The ID of the created or existing maintenance window.
* <p>
* This method initiates an asynchronous request to create an SSM maintenance window.
* If the request is successful, it prints the maintenance window ID.
* If an exception occurs, it handles the error appropriately.
*/
public String createMaintenanceWindow(String winName) throws SsmException, DocumentAlreadyExistsException {
CreateMaintenanceWindowRequest request = CreateMaintenanceWindowRequest.builder()
.name(winName)
.description("This is my maintenance window")
.allowUnassociatedTargets(true)
.duration(2)
.cutoff(1)
.schedule("cron(0 10 ? * MON-FRI *)")
.build();
CompletableFuture<CreateMaintenanceWindowResponse> future = getAsyncClient().createMaintenanceWindow(request);
final String[] windowId = {null};
future.whenComplete((response, ex) -> {
if (response != null) {
String maintenanceWindowId = response.windowId();
System.out.println("The maintenance window id is " + maintenanceWindowId);
windowId[0] = maintenanceWindowId;
} else {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof DocumentAlreadyExistsException) {
throw new CompletionException(cause);
} else if (cause instanceof SsmException) {
throw new CompletionException(cause);
} else {
throw new RuntimeException(cause);
}
}
}).join();
if (windowId[0] == null) {
MaintenanceWindowFilter filter = MaintenanceWindowFilter.builder()
.key("name")
.values(winName)
.build();
DescribeMaintenanceWindowsRequest winRequest = DescribeMaintenanceWindowsRequest.builder()
.filters(filter)
.build();
CompletableFuture<DescribeMaintenanceWindowsResponse> describeFuture = getAsyncClient().describeMaintenanceWindows(winRequest);
describeFuture.whenComplete((describeResponse, describeEx) -> {
if (describeResponse != null) {
List<MaintenanceWindowIdentity> windows = describeResponse.windowIdentities();
if (!windows.isEmpty()) {
windowId[0] = windows.get(0).windowId();
System.out.println("Window ID: " + windowId[0]);
} else {
System.out.println("Window not found.");
windowId[0] = "";
}
} else {
Throwable describeCause = (describeEx instanceof CompletionException) ? describeEx.getCause() : describeEx;
throw new RuntimeException("Error describing maintenance windows: " + describeCause.getMessage(), describeCause);
}
}).join();
}
return windowId[0];
}
}
```
+ For API details, see the following topics in *AWS SDK for Java 2.x API Reference*.
+ [CreateDocument](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/CreateDocument)
+ [CreateMaintenanceWindow](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/CreateMaintenanceWindow)
+ [CreateOpsItem](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/CreateOpsItem)
+ [DeleteMaintenanceWindow](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/DeleteMaintenanceWindow)
+ [ListCommandInvocations](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/ListCommandInvocations)
+ [SendCommand](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/SendCommand)
+ [UpdateOpsItem](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/UpdateOpsItem)
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ssm#code-examples).
```
import {
Scenario,
ScenarioAction,
ScenarioInput,
ScenarioOutput,
} from "@aws-doc-sdk-examples/lib/scenario/index.js";
import { fileURLToPath } from "node:url";
import {
CreateDocumentCommand,
CreateMaintenanceWindowCommand,
CreateOpsItemCommand,
DeleteDocumentCommand,
DeleteMaintenanceWindowCommand,
DeleteOpsItemCommand,
DescribeOpsItemsCommand,
DocumentAlreadyExists,
OpsItemStatus,
waitUntilCommandExecuted,
CancelCommandCommand,
paginateListCommandInvocations,
SendCommandCommand,
UpdateMaintenanceWindowCommand,
UpdateOpsItemCommand,
SSMClient,
} from "@aws-sdk/client-ssm";
import { parseArgs } from "node:util";
/**
* @typedef {{
* ssmClient: import('@aws-sdk/client-ssm').SSMClient,
* documentName?: string
* maintenanceWindow?: string
* winId?: int
* ec2InstanceId?: string
* requestedDateTime?: Date
* opsItemId?: string
* askToDeleteResources?: boolean
* }} State
*/
const defaultMaintenanceWindow = "ssm-maintenance-window";
const defaultDocumentName = "ssmdocument";
// The timeout duration is highly dependent on the specific setup and environment necessary. This example handles only the most common error cases, and uses a much shorter duration than most productions systems would use.
const COMMAND_TIMEOUT_DURATION_SECONDS = 30; // 30 seconds
const pressEnter = new ScenarioInput("continue", "Press Enter to continue", {
type: "confirm",
});
const greet = new ScenarioOutput(
"greet",
`Welcome to the AWS Systems Manager SDK Getting Started scenario.
This program demonstrates how to interact with Systems Manager using the AWS SDK for JavaScript V3.
Systems Manager is the operations hub for your AWS applications and resources and a secure end-to-end management solution.
The program's primary functions include creating a maintenance window, creating a document, sending a command to a document,
listing documents, listing commands, creating an OpsItem, modifying an OpsItem, and deleting Systems Manager resources.
Upon completion of the program, all AWS resources are cleaned up.
Let's get started...`,
{ header: true },
);
const createMaintenanceWindow = new ScenarioOutput(
"createMaintenanceWindow",
"Step 1: Create a Systems Manager maintenance window.",
);
const getMaintenanceWindow = new ScenarioInput(
"maintenanceWindow",
"Please enter the maintenance window name:",
{ type: "input", default: defaultMaintenanceWindow },
);
export const sdkCreateMaintenanceWindow = new ScenarioAction(
"sdkCreateMaintenanceWindow",
async (/** @type {State} */ state) => {
try {
const response = await state.ssmClient.send(
new CreateMaintenanceWindowCommand({
Name: state.maintenanceWindow,
Schedule: "cron(0 10 ? * MON-FRI *)", //The schedule of the maintenance window in the form of a cron or rate expression.
Duration: 2, //The duration of the maintenance window in hours.
Cutoff: 1, //The number of hours before the end of the maintenance window that Amazon Web Services Systems Manager stops scheduling new tasks for execution.
AllowUnassociatedTargets: true, //Allow the maintenance window to run on managed nodes, even if you haven't registered those nodes as targets.
}),
);
state.winId = response.WindowId;
} catch (caught) {
console.error(caught.message);
console.log(
`An error occurred while creating the maintenance window. Please fix the error and try again. Error message: ${caught.message}`,
);
throw caught;
}
},
);
const modifyMaintenanceWindow = new ScenarioOutput(
"modifyMaintenanceWindow",
"Modify the maintenance window by changing the schedule.",
);
const sdkModifyMaintenanceWindow = new ScenarioAction(
"sdkModifyMaintenanceWindow",
async (/** @type {State} */ state) => {
try {
await state.ssmClient.send(
new UpdateMaintenanceWindowCommand({
WindowId: state.winId,
Schedule: "cron(0 0 ? * MON *)",
}),
);
} catch (caught) {
console.error(caught.message);
console.log(
`An error occurred while modifying the maintenance window. Please fix the error and try again. Error message: ${caught.message}`,
);
throw caught;
}
},
);
const createSystemsManagerActions = new ScenarioOutput(
"createSystemsManagerActions",
"Create a document that defines the actions that Systems Manager performs on your EC2 instance.",
);
const getDocumentName = new ScenarioInput(
"documentName",
"Please enter the document: ",
{ type: "input", default: defaultDocumentName },
);
const sdkCreateSSMDoc = new ScenarioAction(
"sdkCreateSSMDoc",
async (/** @type {State} */ state) => {
const contentData = `{
"schemaVersion": "2.2",
"description": "Run a simple shell command",
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runEchoCommand",
"inputs": {
"runCommand": [
"echo 'Hello, world!'"
]
}
}
]
}`;
try {
await state.ssmClient.send(
new CreateDocumentCommand({
Content: contentData,
Name: state.documentName,
DocumentType: "Command",
}),
);
} catch (caught) {
console.log(`Exception type: (${typeof caught})`);
if (caught instanceof DocumentAlreadyExists) {
console.log("Document already exists. Continuing...\n");
} else {
console.error(caught.message);
console.log(
`An error occurred while creating the document. Please fix the error and try again. Error message: ${caught.message}`,
);
throw caught;
}
}
},
);
const ec2HelloWorld = new ScenarioOutput(
"ec2HelloWorld",
`Now you have the option of running a command on an EC2 instance that echoes 'Hello, world!'. In order to run this command, you must provide the instance ID of a Linux EC2 instance. If you do not already have a running Linux EC2 instance in your account, you can create one using the AWS console. For information about creating an EC2 instance, see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-instance-wizard.html.`,
);
const enterIdOrSkipEC2HelloWorld = new ScenarioInput(
"enterIdOrSkipEC2HelloWorld",
"Enter your EC2 InstanceId or press enter to skip this step: ",
{ type: "input", default: "" },
);
const sdkEC2HelloWorld = new ScenarioAction(
"sdkEC2HelloWorld",
async (/** @type {State} */ state) => {
try {
const response = await state.ssmClient.send(
new SendCommandCommand({
DocumentName: state.documentName,
InstanceIds: [state.ec2InstanceId],
TimeoutSeconds: COMMAND_TIMEOUT_DURATION_SECONDS,
}),
);
state.CommandId = response.Command.CommandId;
} catch (caught) {
console.error(caught.message);
console.log(
`An error occurred while sending the command. Please fix the error and try again. Error message: ${caught.message}`,
);
throw caught;
}
},
{
skipWhen: (/** @type {State} */ state) =>
state.enterIdOrSkipEC2HelloWorld === "",
},
);
const sdkGetCommandTime = new ScenarioAction(
"sdkGetCommandTime",
async (/** @type {State} */ state) => {
const listInvocationsPaginated = [];
console.log(
"Let's get the time when the specific command was sent to the specific managed node.",
);
console.log(
`First, we'll wait for the command to finish executing. This may take up to ${COMMAND_TIMEOUT_DURATION_SECONDS} seconds.`,
);
const commandExecutedResult = waitUntilCommandExecuted(
{ client: state.ssmClient },
{
CommandId: state.CommandId,
InstanceId: state.ec2InstanceId,
},
);
// This is necessary because the TimeoutSeconds of SendCommandCommand is only for the delivery, not execution.
try {
await new Promise((_, reject) =>
setTimeout(
reject,
COMMAND_TIMEOUT_DURATION_SECONDS * 1000,
new Error("Command Timed Out"),
),
);
} catch (caught) {
if (caught.message === "Command Timed Out") {
commandExecutedResult.state = "TIMED_OUT";
} else {
throw caught;
}
}
if (commandExecutedResult.state !== "SUCCESS") {
console.log(
`The command with id: ${state.CommandId} did not execute in the allotted time. Canceling command.`,
);
state.ssmClient.send(
new CancelCommandCommand({
CommandId: state.CommandId,
}),
);
state.enterIdOrSkipEC2HelloWorld === "";
return;
}
for await (const page of paginateListCommandInvocations(
{ client: state.ssmClient },
{ CommandId: state.CommandId },
)) {
listInvocationsPaginated.push(...page.CommandInvocations);
}
/**
* @type {import('@aws-sdk/client-ssm').CommandInvocation}
*/
const commandInvocation = listInvocationsPaginated.shift(); // Because the call was made with CommandId, there's only one result, so shift it off.
state.requestedDateTime = commandInvocation.RequestedDateTime;
console.log(
`The command invocation happened at: ${state.requestedDateTime}.`,
);
},
{
skipWhen: (/** @type {State} */ state) =>
state.enterIdOrSkipEC2HelloWorld === "",
},
);
const createSSMOpsItem = new ScenarioOutput(
"createSSMOpsItem",
`Now we will create a Systems Manager OpsItem. An OpsItem is a feature provided by the Systems Manager service. It is a type of operational data item that allows you to manage and track various operational issues, events, or tasks within your AWS environment.
You can create OpsItems to track and manage operational issues as they arise. For example, you could create an OpsItem whenever your application detects a critical error or an anomaly in your infrastructure.`,
);
const sdkCreateSSMOpsItem = new ScenarioAction(
"sdkCreateSSMOpsItem",
async (/** @type {State} */ state) => {
try {
const response = await state.ssmClient.send(
new CreateOpsItemCommand({
Description: "Created by the System Manager Javascript API",
Title: "Disk Space Alert",
Source: "EC2",
Category: "Performance",
Severity: "2",
}),
);
state.opsItemId = response.OpsItemId;
} catch (caught) {
console.error(caught.message);
console.log(
`An error occurred while creating the ops item. Please fix the error and try again. Error message: ${caught.message}`,
);
throw caught;
}
},
);
const updateOpsItem = new ScenarioOutput(
"updateOpsItem",
(/** @type {State} */ state) =>
`Now we will update the OpsItem: ${state.opsItemId}`,
);
const sdkUpdateOpsItem = new ScenarioAction(
"sdkUpdateOpsItem",
async (/** @type {State} */ state) => {
try {
const _response = await state.ssmClient.send(
new UpdateOpsItemCommand({
OpsItemId: state.opsItemId,
Description: `An update to ${state.opsItemId}`,
}),
);
} catch (caught) {
console.error(caught.message);
console.log(
`An error occurred while updating the ops item. Please fix the error and try again. Error message: ${caught.message}`,
);
throw caught;
}
},
);
const getOpsItemStatus = new ScenarioOutput(
"getOpsItemStatus",
(/** @type {State} */ state) =>
`Now we will get the status of the OpsItem: ${state.opsItemId}`,
);
const sdkOpsItemStatus = new ScenarioAction(
"sdkGetOpsItemStatus",
async (/** @type {State} */ state) => {
try {
const response = await state.ssmClient.send(
new DescribeOpsItemsCommand({
OpsItemId: state.opsItemId,
}),
);
state.opsItemStatus = response.OpsItemStatus;
} catch (caught) {
console.error(caught.message);
console.log(
`An error occurred while describing the ops item. Please fix the error and try again. Error message: ${caught.message}`,
);
throw caught;
}
},
);
const resolveOpsItem = new ScenarioOutput(
"resolveOpsItem",
(/** @type {State} */ state) =>
`Now we will resolve the OpsItem: ${state.opsItemId}`,
);
const sdkResolveOpsItem = new ScenarioAction(
"sdkResolveOpsItem",
async (/** @type {State} */ state) => {
try {
const _response = await state.ssmClient.send(
new UpdateOpsItemCommand({
OpsItemId: state.opsItemId,
Status: OpsItemStatus.RESOLVED,
}),
);
} catch (caught) {
console.error(caught.message);
console.log(
`An error occurred while updating the ops item. Please fix the error and try again. Error message: ${caught.message}`,
);
throw caught;
}
},
);
const askToDeleteResources = new ScenarioInput(
"askToDeleteResources",
"Would you like to delete the Systems Manager resources created during this example run?",
{ type: "confirm" },
);
const confirmDeleteChoice = new ScenarioOutput(
"confirmDeleteChoice",
(/** @type {State} */ state) => {
if (state.askToDeleteResources) {
return "You chose to delete the resources.";
}
return "The Systems Manager resources will not be deleted. Please delete them manually to avoid charges.";
},
);
export const sdkDeleteResources = new ScenarioAction(
"sdkDeleteResources",
async (/** @type {State} */ state) => {
try {
await state.ssmClient.send(
new DeleteOpsItemCommand({
OpsItemId: state.opsItemId,
}),
);
console.log(`The ops item: ${state.opsItemId} was successfully deleted.`);
} catch (caught) {
console.log(
`There was a problem deleting the ops item: ${state.opsItemId}. Please delete it manually. Error: ${caught.message}`,
);
}
try {
await state.ssmClient.send(
new DeleteMaintenanceWindowCommand({
Name: state.maintenanceWindow,
WindowId: state.winId,
}),
);
console.log(
`The maintenance window: ${state.maintenanceWindow} was successfully deleted.`,
);
} catch (caught) {
console.log(
`There was a problem deleting the maintenance window: ${state.opsItemId}. Please delete it manually. Error: ${caught.message}`,
);
}
try {
await state.ssmClient.send(
new DeleteDocumentCommand({
Name: state.documentName,
}),
);
console.log(
`The document: ${state.documentName} was successfully deleted.`,
);
} catch (caught) {
console.log(
`There was a problem deleting the document: ${state.documentName}. Please delete it manually. Error: ${caught.message}`,
);
}
},
{ skipWhen: (/** @type {{}} */ state) => !state.askToDeleteResources },
);
const goodbye = new ScenarioOutput(
"goodbye",
"This concludes the Systems Manager Basics scenario for the AWS Javascript SDK v3. Thank you!",
);
const myScenario = new Scenario(
"SSM Basics",
[
greet,
pressEnter,
createMaintenanceWindow,
getMaintenanceWindow,
sdkCreateMaintenanceWindow,
modifyMaintenanceWindow,
pressEnter,
sdkModifyMaintenanceWindow,
createSystemsManagerActions,
getDocumentName,
sdkCreateSSMDoc,
ec2HelloWorld,
enterIdOrSkipEC2HelloWorld,
sdkEC2HelloWorld,
sdkGetCommandTime,
pressEnter,
createSSMOpsItem,
pressEnter,
sdkCreateSSMOpsItem,
updateOpsItem,
pressEnter,
sdkUpdateOpsItem,
getOpsItemStatus,
pressEnter,
sdkOpsItemStatus,
resolveOpsItem,
pressEnter,
sdkResolveOpsItem,
askToDeleteResources,
confirmDeleteChoice,
sdkDeleteResources,
goodbye,
],
{ ssmClient: new SSMClient({}) },
);
/** @type {{ stepHandlerOptions: StepHandlerOptions }} */
export const main = async (stepHandlerOptions) => {
await myScenario.run(stepHandlerOptions);
};
// Invoke main function if this file was run directly.
if (process.argv[1] === fileURLToPath(import.meta.url)) {
const { values } = parseArgs({
options: {
yes: {
type: "boolean",
short: "y",
},
},
});
main({ confirmAll: values.yes });
}
```
+ For API details, see the following topics in *AWS SDK for JavaScript API Reference*.
+ [CreateDocument](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/CreateDocumentCommand)
+ [CreateMaintenanceWindow](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/CreateMaintenanceWindowCommand)
+ [CreateOpsItem](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/CreateOpsItemCommand)
+ [DeleteMaintenanceWindow](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/DeleteMaintenanceWindowCommand)
+ [ListCommandInvocations](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/ListCommandInvocationsCommand)
+ [SendCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/SendCommandCommand)
+ [UpdateOpsItem](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/UpdateOpsItemCommand)
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
Run an interactive scenario at a command prompt.
```
class SystemsManagerScenario:
"""Runs an interactive scenario that shows how to get started using Amazon Systems Manager."""
def __init__(self, document_wrapper, maintenance_window_wrapper, ops_item_wrapper):
"""
:param document_wrapper: An object that wraps Systems Manager document functions.
:param maintenance_window_wrapper: An object that wraps Systems Manager maintenance window functions.
:param ops_item_wrapper: An object that wraps Systems Manager OpsItem functions.
"""
self.document_wrapper = document_wrapper
self.maintenance_window_wrapper = maintenance_window_wrapper
self.ops_item_wrapper = ops_item_wrapper
def run(self):
"""Demonstrates how to use the AWS SDK for Python (Boto3) to get started with Systems Manager."""
try:
print("-" * 88)
print(
"""
Welcome to the AWS Systems Manager SDK Getting Started scenario.
This program demonstrates how to interact with Systems Manager using the AWS SDK for Python (Boto3).
Systems Manager is the operations hub for your AWS applications and resources and a secure end-to-end management
solution. The program's primary functions include creating a maintenance window, creating a document, sending a
command to a document, listing documents, listing commands, creating an OpsItem, modifying an OpsItem, and deleting
Systems Manager resources. Upon completion of the program, all AWS resources are cleaned up.
Let's get started..."""
)
q.ask("Please hit Enter")
print("-" * 88)
print("Create a Systems Manager maintenance window.")
maintenance_window_name = q.ask(
"Please enter the maintenance window name (default is ssm-maintenance-window):",
)
if not maintenance_window_name:
maintenance_window_name = "ssm-maintenance-window"
self.maintenance_window_wrapper.create(
name=maintenance_window_name,
schedule="cron(0 10 ? * MON-FRI *)",
duration=2,
cutoff=1,
allow_unassociated_targets=True,
)
print("-" * 88)
print("Modify the maintenance window by changing the schedule")
q.ask("Please hit Enter")
self.maintenance_window_wrapper.update(
name=maintenance_window_name,
schedule="cron(0 0 ? * MON *)",
duration=24,
cutoff=1,
allow_unassociated_targets=True,
enabled=True,
)
print("-" * 88)
print(
"Create a document that defines the actions that Systems Manager performs on your EC2 instance."
)
document_name = q.ask(
"Please enter the document name (default is ssmdocument):"
)
if not document_name:
document_name = "ssmdocument"
self.document_wrapper.create(
name=document_name,
content="""
{
"schemaVersion": "2.2",
"description": "Run a simple shell command",
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runEchoCommand",
"inputs": {
"runCommand": [
"echo 'Hello, world!'"
]
}
}
]
}
""",
)
self.document_wrapper.wait_until_active()
print(
"""
Now you have the option of running a command on an EC2 instance that echoes 'Hello, world!'.
In order to run this command, you must provide the instance ID of a Linux EC2 instance. If you do
not already have a running Linux EC2 instance in your account, you can create one using the AWS console.
For information about creating an EC2 instance, see
https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-instance-wizard.html.
"""
)
if q.ask(
"Would you like to run a command on an EC2 instance? (y/n)",
q.is_yesno,
):
instance_id = q.ask(
"Please enter the instance ID of the EC2 instance:", q.non_empty
)
command_id = self.document_wrapper.send_command(
instance_ids=[instance_id]
)
self.document_wrapper.wait_command_executed(
command_id=command_id, instance_id=instance_id
)
print("-" * 88)
print(
"Lets get the time when the specific command was sent to the specific managed node"
)
q.ask("Please hit Enter")
self.document_wrapper.list_command_invocations(instance_id=instance_id)
print("-" * 88)
print("-" * 88)
print(
"""
Now we will create a Systems Manager OpsItem.
An OpsItem is a feature provided by the Systems Manager service.
It is a type of operational data item that allows you to manage and track various operational issues,
events, or tasks within your AWS environment.
You can create OpsItems to track and manage operational issues as they arise.
For example, you could create an OpsItem whenever your application detects a critical error
or an anomaly in your infrastructure.
"""
)
q.ask("Please hit Enter")
self.ops_item_wrapper.create(
title="Disk Space Alert",
description="Created by the Systems Manager Python (Boto3) API",
source="EC2",
category="Performance",
severity="2",
)
print("-" * 88)
print("-" * 88)
print(f"Now we will update the OpsItem {self.ops_item_wrapper.id}")
q.ask("Please hit Enter")
self.ops_item_wrapper.update(
title="Disk Space Alert",
description=f"An update to {self.ops_item_wrapper.id}",
)
print(
f"Now we will get the status of the OpsItem {self.ops_item_wrapper.id}"
)
q.ask("Please hit Enter")
# It may take a second for the ops item to be available
counter = 0
while not self.ops_item_wrapper.describe() and counter < 5:
counter += 1
time.sleep(1)
print(f"Now we will resolve the OpsItem {self.ops_item_wrapper.id}")
q.ask("Please hit Enter")
self.ops_item_wrapper.update(status="Resolved")
print("-" * 88)
print("-" * 88)
if q.ask(
"Would you like to delete the Systems Manager resources? (y/n)",
q.is_yesno,
):
print("You selected to delete the resources.")
self.cleanup()
else:
print("The Systems Manager resources will not be deleted")
print("-" * 88)
print("This concludes the Systems Manager SDK Getting Started scenario.")
print("-" * 88)
except Exception:
self.cleanup()
raise
def cleanup(self):
self.maintenance_window_wrapper.delete()
self.ops_item_wrapper.delete()
self.document_wrapper.delete()
if __name__ == "__main__":
try:
scenario = SystemsManagerScenario(
DocumentWrapper.from_client(),
MaintenanceWindowWrapper.from_client(),
OpsItemWrapper.from_client(),
)
scenario.run()
except Exception:
logging.exception("Something went wrong with the demo.")
```
Define a class that wraps document and command actions.
```
class DocumentWrapper:
"""Encapsulates AWS Systems Manager Document actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def create(self, content, name):
"""
Creates a document.
:param content: The content of the document.
:param name: The name of the document.
"""
try:
self.ssm_client.create_document(
Name=name, Content=content, DocumentType="Command"
)
self.name = name
except self.ssm_client.exceptions.DocumentAlreadyExists:
print(f"Document {name} already exists.")
self.name = name
except ClientError as err:
logger.error(
"Couldn't create %s. Here's why: %s: %s",
name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def delete(self):
"""
Deletes an AWS Systems Manager document.
"""
if self.name is None:
return
try:
self.ssm_client.delete_document(Name=self.name)
print(f"Deleted document {self.name}.")
self.name = None
except ClientError as err:
logger.error(
"Couldn't delete %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def send_command(self, instance_ids):
"""
Sends a command to one or more instances.
:param instance_ids: The IDs of the instances to send the command to.
:return: The ID of the command.
"""
try:
response = self.ssm_client.send_command(
InstanceIds=instance_ids, DocumentName=self.name, TimeoutSeconds=3600
)
return response["Command"]["CommandId"]
except ClientError as err:
logger.error(
"Couldn't send command to %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def describe(self):
"""
Describes the document.
:return: Document status.
"""
try:
response = self.ssm_client.describe_document(Name=self.name)
return response["Document"]["Status"]
except ClientError as err:
logger.error(
"Couldn't get %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def wait_until_active(self, max_attempts=20, delay=5):
"""
Waits until the document is active.
:param max_attempts: The maximum number of attempts for checking the status.
:param delay: The delay in seconds between each check.
"""
attempt = 0
status = ""
while attempt <= max_attempts:
status = self.describe()
if status == "Active":
break
attempt += 1
time.sleep(delay)
if status != "Active":
logger.error("Document is not active.")
else:
logger.info("Document is active.")
def wait_command_executed(self, command_id, instance_id):
"""
Waits until the command is executed on the instance.
:param command_id: The ID of the command.
:param instance_id: The ID of the instance.
"""
waiter = self.ssm_client.get_waiter("command_executed")
waiter.wait(CommandId=command_id, InstanceId=instance_id)
def list_command_invocations(self, instance_id):
"""
Lists the commands for an instance.
:param instance_id: The ID of the instance.
:return: The list of commands.
"""
try:
paginator = self.ssm_client.get_paginator("list_command_invocations")
command_invocations = []
for page in paginator.paginate(InstanceId=instance_id):
command_invocations.extend(page["CommandInvocations"])
num_of_commands = len(command_invocations)
print(
f"{num_of_commands} command invocation(s) found for instance {instance_id}."
)
if num_of_commands > 10:
print("Displaying the first 10 commands:")
num_of_commands = 10
date_format = "%A, %d %B %Y %I:%M%p"
for command in command_invocations[:num_of_commands]:
print(
f" The time of command invocation is {command['RequestedDateTime'].strftime(date_format)}"
)
except ClientError as err:
logger.error(
"Couldn't list commands for %s. Here's why: %s: %s",
instance_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
Define a class that wraps ops item actions.
```
class OpsItemWrapper:
"""Encapsulates AWS Systems Manager OpsItem actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.id = None
@classmethod
def from_client(cls):
"""
:return: A OpsItemWrapper instance.
"""
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def create(self, title, source, category, severity, description):
"""
Create an OpsItem
:param title: The OpsItem title.
:param source: The OpsItem source.
:param category: The OpsItem category.
:param severity: The OpsItem severity.
:param description: The OpsItem description.
"""
try:
response = self.ssm_client.create_ops_item(
Title=title,
Source=source,
Category=category,
Severity=severity,
Description=description,
)
self.id = response["OpsItemId"]
except self.ssm_client.exceptions.OpsItemLimitExceededException as err:
logger.error(
"Couldn't create ops item because you have exceeded your open OpsItem limit. "
"Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
except ClientError as err:
logger.error(
"Couldn't create ops item %s. Here's why: %s: %s",
title,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def delete(self):
"""
Delete the OpsItem.
"""
if self.id is None:
return
try:
self.ssm_client.delete_ops_item(OpsItemId=self.id)
print(f"Deleted ops item with id {self.id}")
self.id = None
except ClientError as err:
logger.error(
"Couldn't delete ops item %s. Here's why: %s: %s",
self.id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def describe(self):
"""
Describe an OpsItem.
"""
try:
paginator = self.ssm_client.get_paginator("describe_ops_items")
ops_items = []
for page in paginator.paginate(
OpsItemFilters=[
{"Key": "OpsItemId", "Values": [self.id], "Operator": "Equal"}
]
):
ops_items.extend(page["OpsItemSummaries"])
for item in ops_items:
print(
f"The item title is {item['Title']} and the status is {item['Status']}"
)
return len(ops_items) > 0
except ClientError as err:
logger.error(
"Couldn't describe ops item %s. Here's why: %s: %s",
self.id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def update(self, title=None, description=None, status=None):
"""
Update an OpsItem.
:param title: The new OpsItem title.
:param description: The new OpsItem description.
:param status: The new OpsItem status.
:return:
"""
args = dict(OpsItemId=self.id)
if title is not None:
args["Title"] = title
if description is not None:
args["Description"] = description
if status is not None:
args["Status"] = status
try:
self.ssm_client.update_ops_item(**args)
except ClientError as err:
logger.error(
"Couldn't update ops item %s. Here's why: %s: %s",
self.id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
Define a class that wraps maintenance window actions.
```
class MaintenanceWindowWrapper:
"""Encapsulates AWS Systems Manager maintenance window actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.window_id = None
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def create(self, name, schedule, duration, cutoff, allow_unassociated_targets):
"""
Create an AWS Systems Manager maintenance window.
:param name: The name of the maintenance window.
:param schedule: The schedule of the maintenance window.
:param duration: The duration of the maintenance window.
:param cutoff: The cutoff time of the maintenance window.
:param allow_unassociated_targets: Allow the maintenance window to run on managed nodes, even
if you haven't registered those nodes as targets.
"""
try:
response = self.ssm_client.create_maintenance_window(
Name=name,
Schedule=schedule,
Duration=duration,
Cutoff=cutoff,
AllowUnassociatedTargets=allow_unassociated_targets,
)
self.window_id = response["WindowId"]
self.name = name
logger.info("Created maintenance window %s.", self.window_id)
except ParamValidationError as error:
logger.error(
"Parameter validation error when trying to create maintenance window %s. Here's why: %s",
self.window_id,
error,
)
raise
except ClientError as err:
logger.error(
"Couldn't create maintenance window %s. Here's why: %s: %s",
name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def delete(self):
"""
Delete the associated AWS Systems Manager maintenance window.
"""
if self.window_id is None:
return
try:
self.ssm_client.delete_maintenance_window(WindowId=self.window_id)
logger.info("Deleted maintenance window %s.", self.window_id)
print(f"Deleted maintenance window {self.name}")
self.window_id = None
except ClientError as err:
logger.error(
"Couldn't delete maintenance window %s. Here's why: %s: %s",
self.window_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
def update(
self, name, enabled, schedule, duration, cutoff, allow_unassociated_targets
):
"""
Update an AWS Systems Manager maintenance window.
:param name: The name of the maintenance window.
:param enabled: Whether the maintenance window is enabled to run on managed nodes.
:param schedule: The schedule of the maintenance window.
:param duration: The duration of the maintenance window.
:param cutoff: The cutoff time of the maintenance window.
:param allow_unassociated_targets: Allow the maintenance window to run on managed nodes, even
if you haven't registered those nodes as targets.
"""
try:
self.ssm_client.update_maintenance_window(
WindowId=self.window_id,
Name=name,
Enabled=enabled,
Schedule=schedule,
Duration=duration,
Cutoff=cutoff,
AllowUnassociatedTargets=allow_unassociated_targets,
)
self.name = name
logger.info("Updated maintenance window %s.", self.window_id)
except ParamValidationError as error:
logger.error(
"Parameter validation error when trying to update maintenance window %s. Here's why: %s",
self.window_id,
error,
)
raise
except ClientError as err:
logger.error(
"Couldn't update maintenance window %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see the following topics in *AWS SDK for Python (Boto3) API Reference*.
+ [CreateDocument](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateDocument)
+ [CreateMaintenanceWindow](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateMaintenanceWindow)
+ [CreateOpsItem](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateOpsItem)
+ [DeleteMaintenanceWindow](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DeleteMaintenanceWindow)
+ [ListCommandInvocations](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/ListCommandInvocations)
+ [SendCommand](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/SendCommand)
+ [UpdateOpsItem](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/UpdateOpsItem)
------
# Actions for Systems Manager using AWS SDKs
<a name="ssm_code_examples_actions"></a>
The following code examples demonstrate how to perform individual Systems Manager actions with AWS SDKs. Each example includes a link to GitHub, where you can find instructions for setting up and running the code.
These excerpts call the Systems Manager API and are code excerpts from larger programs that must be run in context. You can see actions in context in [Scenarios for Systems Manager using AWS SDKs](ssm_code_examples_scenarios.md).
The following examples include only the most commonly used actions. For a complete list, see the [AWS Systems Manager API Reference](https://docs.aws.amazon.com/systems-manager/latest/APIReference/Welcome.html).
**Topics**
+ [`AddTagsToResource`](ssm_example_ssm_AddTagsToResource_section.md)
+ [`CancelCommand`](ssm_example_ssm_CancelCommand_section.md)
+ [`CreateActivation`](ssm_example_ssm_CreateActivation_section.md)
+ [`CreateAssociation`](ssm_example_ssm_CreateAssociation_section.md)
+ [`CreateAssociationBatch`](ssm_example_ssm_CreateAssociationBatch_section.md)
+ [`CreateDocument`](ssm_example_ssm_CreateDocument_section.md)
+ [`CreateMaintenanceWindow`](ssm_example_ssm_CreateMaintenanceWindow_section.md)
+ [`CreateOpsItem`](ssm_example_ssm_CreateOpsItem_section.md)
+ [`CreatePatchBaseline`](ssm_example_ssm_CreatePatchBaseline_section.md)
+ [`DeleteActivation`](ssm_example_ssm_DeleteActivation_section.md)
+ [`DeleteAssociation`](ssm_example_ssm_DeleteAssociation_section.md)
+ [`DeleteDocument`](ssm_example_ssm_DeleteDocument_section.md)
+ [`DeleteMaintenanceWindow`](ssm_example_ssm_DeleteMaintenanceWindow_section.md)
+ [`DeleteOpsItem`](ssm_example_ssm_DeleteOpsItem_section.md)
+ [`DeleteParameter`](ssm_example_ssm_DeleteParameter_section.md)
+ [`DeletePatchBaseline`](ssm_example_ssm_DeletePatchBaseline_section.md)
+ [`DeregisterManagedInstance`](ssm_example_ssm_DeregisterManagedInstance_section.md)
+ [`DeregisterPatchBaselineForPatchGroup`](ssm_example_ssm_DeregisterPatchBaselineForPatchGroup_section.md)
+ [`DeregisterTargetFromMaintenanceWindow`](ssm_example_ssm_DeregisterTargetFromMaintenanceWindow_section.md)
+ [`DeregisterTaskFromMaintenanceWindow`](ssm_example_ssm_DeregisterTaskFromMaintenanceWindow_section.md)
+ [`DescribeActivations`](ssm_example_ssm_DescribeActivations_section.md)
+ [`DescribeAssociation`](ssm_example_ssm_DescribeAssociation_section.md)
+ [`DescribeAssociationExecutionTargets`](ssm_example_ssm_DescribeAssociationExecutionTargets_section.md)
+ [`DescribeAssociationExecutions`](ssm_example_ssm_DescribeAssociationExecutions_section.md)
+ [`DescribeAutomationExecutions`](ssm_example_ssm_DescribeAutomationExecutions_section.md)
+ [`DescribeAutomationStepExecutions`](ssm_example_ssm_DescribeAutomationStepExecutions_section.md)
+ [`DescribeAvailablePatches`](ssm_example_ssm_DescribeAvailablePatches_section.md)
+ [`DescribeDocument`](ssm_example_ssm_DescribeDocument_section.md)
+ [`DescribeDocumentPermission`](ssm_example_ssm_DescribeDocumentPermission_section.md)
+ [`DescribeEffectiveInstanceAssociations`](ssm_example_ssm_DescribeEffectiveInstanceAssociations_section.md)
+ [`DescribeEffectivePatchesForPatchBaseline`](ssm_example_ssm_DescribeEffectivePatchesForPatchBaseline_section.md)
+ [`DescribeInstanceAssociationsStatus`](ssm_example_ssm_DescribeInstanceAssociationsStatus_section.md)
+ [`DescribeInstanceInformation`](ssm_example_ssm_DescribeInstanceInformation_section.md)
+ [`DescribeInstancePatchStates`](ssm_example_ssm_DescribeInstancePatchStates_section.md)
+ [`DescribeInstancePatchStatesForPatchGroup`](ssm_example_ssm_DescribeInstancePatchStatesForPatchGroup_section.md)
+ [`DescribeInstancePatches`](ssm_example_ssm_DescribeInstancePatches_section.md)
+ [`DescribeMaintenanceWindowExecutionTaskInvocations`](ssm_example_ssm_DescribeMaintenanceWindowExecutionTaskInvocations_section.md)
+ [`DescribeMaintenanceWindowExecutionTasks`](ssm_example_ssm_DescribeMaintenanceWindowExecutionTasks_section.md)
+ [`DescribeMaintenanceWindowExecutions`](ssm_example_ssm_DescribeMaintenanceWindowExecutions_section.md)
+ [`DescribeMaintenanceWindowTargets`](ssm_example_ssm_DescribeMaintenanceWindowTargets_section.md)
+ [`DescribeMaintenanceWindowTasks`](ssm_example_ssm_DescribeMaintenanceWindowTasks_section.md)
+ [`DescribeMaintenanceWindows`](ssm_example_ssm_DescribeMaintenanceWindows_section.md)
+ [`DescribeOpsItems`](ssm_example_ssm_DescribeOpsItems_section.md)
+ [`DescribeParameters`](ssm_example_ssm_DescribeParameters_section.md)
+ [`DescribePatchBaselines`](ssm_example_ssm_DescribePatchBaselines_section.md)
+ [`DescribePatchGroupState`](ssm_example_ssm_DescribePatchGroupState_section.md)
+ [`DescribePatchGroups`](ssm_example_ssm_DescribePatchGroups_section.md)
+ [`GetAutomationExecution`](ssm_example_ssm_GetAutomationExecution_section.md)
+ [`GetCommandInvocation`](ssm_example_ssm_GetCommandInvocation_section.md)
+ [`GetConnectionStatus`](ssm_example_ssm_GetConnectionStatus_section.md)
+ [`GetDefaultPatchBaseline`](ssm_example_ssm_GetDefaultPatchBaseline_section.md)
+ [`GetDeployablePatchSnapshotForInstance`](ssm_example_ssm_GetDeployablePatchSnapshotForInstance_section.md)
+ [`GetDocument`](ssm_example_ssm_GetDocument_section.md)
+ [`GetInventory`](ssm_example_ssm_GetInventory_section.md)
+ [`GetInventorySchema`](ssm_example_ssm_GetInventorySchema_section.md)
+ [`GetMaintenanceWindow`](ssm_example_ssm_GetMaintenanceWindow_section.md)
+ [`GetMaintenanceWindowExecution`](ssm_example_ssm_GetMaintenanceWindowExecution_section.md)
+ [`GetMaintenanceWindowExecutionTask`](ssm_example_ssm_GetMaintenanceWindowExecutionTask_section.md)
+ [`GetParameter`](ssm_example_ssm_GetParameter_section.md)
+ [`GetParameterHistory`](ssm_example_ssm_GetParameterHistory_section.md)
+ [`GetParameters`](ssm_example_ssm_GetParameters_section.md)
+ [`GetPatchBaseline`](ssm_example_ssm_GetPatchBaseline_section.md)
+ [`GetPatchBaselineForPatchGroup`](ssm_example_ssm_GetPatchBaselineForPatchGroup_section.md)
+ [`ListAssociationVersions`](ssm_example_ssm_ListAssociationVersions_section.md)
+ [`ListAssociations`](ssm_example_ssm_ListAssociations_section.md)
+ [`ListCommandInvocations`](ssm_example_ssm_ListCommandInvocations_section.md)
+ [`ListCommands`](ssm_example_ssm_ListCommands_section.md)
+ [`ListComplianceItems`](ssm_example_ssm_ListComplianceItems_section.md)
+ [`ListComplianceSummaries`](ssm_example_ssm_ListComplianceSummaries_section.md)
+ [`ListDocumentVersions`](ssm_example_ssm_ListDocumentVersions_section.md)
+ [`ListDocuments`](ssm_example_ssm_ListDocuments_section.md)
+ [`ListInventoryEntries`](ssm_example_ssm_ListInventoryEntries_section.md)
+ [`ListResourceComplianceSummaries`](ssm_example_ssm_ListResourceComplianceSummaries_section.md)
+ [`ListTagsForResource`](ssm_example_ssm_ListTagsForResource_section.md)
+ [`ModifyDocumentPermission`](ssm_example_ssm_ModifyDocumentPermission_section.md)
+ [`PutComplianceItems`](ssm_example_ssm_PutComplianceItems_section.md)
+ [`PutInventory`](ssm_example_ssm_PutInventory_section.md)
+ [`PutParameter`](ssm_example_ssm_PutParameter_section.md)
+ [`RegisterDefaultPatchBaseline`](ssm_example_ssm_RegisterDefaultPatchBaseline_section.md)
+ [`RegisterPatchBaselineForPatchGroup`](ssm_example_ssm_RegisterPatchBaselineForPatchGroup_section.md)
+ [`RegisterTargetWithMaintenanceWindow`](ssm_example_ssm_RegisterTargetWithMaintenanceWindow_section.md)
+ [`RegisterTaskWithMaintenanceWindow`](ssm_example_ssm_RegisterTaskWithMaintenanceWindow_section.md)
+ [`RemoveTagsFromResource`](ssm_example_ssm_RemoveTagsFromResource_section.md)
+ [`SendCommand`](ssm_example_ssm_SendCommand_section.md)
+ [`StartAutomationExecution`](ssm_example_ssm_StartAutomationExecution_section.md)
+ [`StartSession`](ssm_example_ssm_StartSession_section.md)
+ [`StopAutomationExecution`](ssm_example_ssm_StopAutomationExecution_section.md)
+ [`UpdateAssociation`](ssm_example_ssm_UpdateAssociation_section.md)
+ [`UpdateAssociationStatus`](ssm_example_ssm_UpdateAssociationStatus_section.md)
+ [`UpdateDocument`](ssm_example_ssm_UpdateDocument_section.md)
+ [`UpdateDocumentDefaultVersion`](ssm_example_ssm_UpdateDocumentDefaultVersion_section.md)
+ [`UpdateMaintenanceWindow`](ssm_example_ssm_UpdateMaintenanceWindow_section.md)
+ [`UpdateManagedInstanceRole`](ssm_example_ssm_UpdateManagedInstanceRole_section.md)
+ [`UpdateOpsItem`](ssm_example_ssm_UpdateOpsItem_section.md)
+ [`UpdatePatchBaseline`](ssm_example_ssm_UpdatePatchBaseline_section.md)
# Use `AddTagsToResource` with a CLI
<a name="ssm_example_ssm_AddTagsToResource_section"></a>
The following code examples show how to use `AddTagsToResource`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To add tags to a maintenance window**
The following `add-tags-to-resource` example adds a tag to the specified maintenance window.
```
aws ssm add-tags-to-resource \
--resource-type "MaintenanceWindow" \
--resource-id "mw-03eb9db428EXAMPLE" \
--tags "Key=Stack,Value=Production"
```
This command produces no output.
**Example 2: To add tags to a parameter**
The following `add-tags-to-resource` example adds two tags to to the specified parameter.
```
aws ssm add-tags-to-resource \
--resource-type "Parameter" \
--resource-id "My-Parameter" \
--tags '[{"Key":"Region","Value":"East"},{"Key":"Environment", "Value":"Production"}]'
```
This command produces no output.
**Example 3: To add tags to an SSM document**
The following `add-tags-to-resource` example adds a tag to to the specified document.
```
aws ssm add-tags-to-resource \
--resource-type "Document" \
--resource-id "My-Document" \
--tags "Key=Quarter,Value=Q322"
```
This command produces no output.
For more information, see [Tagging Systems Manager resources](https://docs.aws.amazon.com/systems-manager/latest/userguide/tagging-resources.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [AddTagsToResource](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/add-tags-to-resource.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example updates a maintenance window with new tags. There is no output if the command succeeds. The syntax used by this example requires PowerShell version 3 or later.**
```
$option1 = @{Key="Stack";Value=@("Production")}
Add-SSMResourceTag -ResourceId "mw-03eb9db42890fb82d" -ResourceType "MaintenanceWindow" -Tag $option1
```
**Example 2: With PowerShell version 2, you must use New-Object to create each tag. There is no output if the command succeeds.**
```
$tag1 = New-Object Amazon.SimpleSystemsManagement.Model.Tag
$tag1.Key = "Stack"
$tag1.Value = "Production"
Add-SSMResourceTag -ResourceId "mw-03eb9db42890fb82d" -ResourceType "MaintenanceWindow" -Tag $tag1
```
+ For API details, see [AddTagsToResource](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example updates a maintenance window with new tags. There is no output if the command succeeds. The syntax used by this example requires PowerShell version 3 or later.**
```
$option1 = @{Key="Stack";Value=@("Production")}
Add-SSMResourceTag -ResourceId "mw-03eb9db42890fb82d" -ResourceType "MaintenanceWindow" -Tag $option1
```
**Example 2: With PowerShell version 2, you must use New-Object to create each tag. There is no output if the command succeeds.**
```
$tag1 = New-Object Amazon.SimpleSystemsManagement.Model.Tag
$tag1.Key = "Stack"
$tag1.Value = "Production"
Add-SSMResourceTag -ResourceId "mw-03eb9db42890fb82d" -ResourceType "MaintenanceWindow" -Tag $tag1
```
+ For API details, see [AddTagsToResource](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `CancelCommand` with a CLI
<a name="ssm_example_ssm_CancelCommand_section"></a>
The following code examples show how to use `CancelCommand`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To cancel a command for all instances**
The following `cancel-command` example attempts to cancel the specified command that is already running for all instances.
```
aws ssm cancel-command \
--command-id "662add3d-5831-4a10-b64a-f2ff3EXAMPLE"
```
This command produces no output.
**Example 2: To cancel a command for specific instances**
The following `cancel-command` example attempts to cancel a command for the specified instance only.
```
aws ssm cancel-command \
--command-id "662add3d-5831-4a10-b64a-f2ff3EXAMPLE"
--instance-ids "i-02573cafcfEXAMPLE"
```
This command produces no output.
For more information, see [Tagging Systems Manager Parameters](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-su-tag.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [CancelCommand](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/cancel-command.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example attempts to cancel a command. There is no output if the operation succeeds.**
```
Stop-SSMCommand -CommandId "9ded293e-e792-4440-8e3e-7b8ec5feaa38"
```
+ For API details, see [CancelCommand](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example attempts to cancel a command. There is no output if the operation succeeds.**
```
Stop-SSMCommand -CommandId "9ded293e-e792-4440-8e3e-7b8ec5feaa38"
```
+ For API details, see [CancelCommand](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `CreateActivation` with a CLI
<a name="ssm_example_ssm_CreateActivation_section"></a>
The following code examples show how to use `CreateActivation`.
------
#### [ CLI ]
**AWS CLI**
**To create a managed instance activation**
The following `create-activation` example creates a managed instance activation.
```
aws ssm create-activation \
--default-instance-name "HybridWebServers" \
--iam-role "HybridWebServersRole" \
--registration-limit 5
```
Output:
```
{
"ActivationId": "5743558d-563b-4457-8682-d16c3EXAMPLE",
"ActivationCode": "dRmgnYaFv567vEXAMPLE"
}
```
For more information, see [Step 4: Create a Managed-Instance Activation for a Hybrid Environment](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-managed-instance-activation.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [CreateActivation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/create-activation.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example creates a managed instance.**
```
New-SSMActivation -DefaultInstanceName "MyWebServers" -IamRole "SSMAutomationRole" -RegistrationLimit 10
```
**Output:**
```
ActivationCode ActivationId
-------------- ------------
KWChhOxBTiwDcKE9BlKC 08e51e79-1e36-446c-8e63-9458569c1363
```
+ For API details, see [CreateActivation](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example creates a managed instance.**
```
New-SSMActivation -DefaultInstanceName "MyWebServers" -IamRole "SSMAutomationRole" -RegistrationLimit 10
```
**Output:**
```
ActivationCode ActivationId
-------------- ------------
KWChhOxBTiwDcKE9BlKC 08e51e79-1e36-446c-8e63-9458569c1363
```
+ For API details, see [CreateActivation](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `CreateAssociation` with a CLI
<a name="ssm_example_ssm_CreateAssociation_section"></a>
The following code examples show how to use `CreateAssociation`.
------
#### [ CLI ]
**AWS 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](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateAssociation.html) in the *AWS 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](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateAssociation.html) in the *AWS 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-interval
```
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](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateAssociation.html) in the *AWS Systems Manager API Reference* or [Reference: Cron and rate expressions for Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/reference-cron-and-rate-expressions.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [CreateAssociation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/create-association.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**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](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**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](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `CreateAssociationBatch` with a CLI
<a name="ssm_example_ssm_CreateAssociationBatch_section"></a>
The following code examples show how to use `CreateAssociationBatch`.
------
#### [ CLI ]
**AWS CLI**
**To create multiple associations**
This example associates a configuration document with multiple instances. The output returns a list of successful and failed operations, if applicable.
Command:
```
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": 1550504725.007,
"Name": "Associated",
"Message": "Associated with AWS-UpdateSSMAgent"
},
"Overview": {
"Status": "Pending",
"DetailedStatus": "Creating"
},
"DocumentVersion": "$DEFAULT",
"AssociationId": "8dfe3659-4309-493a-8755-0123456789ab",
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-1234567890abcdef0"
]
}
]
},
{
"Name": "AWS-UpdateSSMAgent",
"InstanceId": "i-9876543210abcdef0",
"AssociationVersion": "1",
"Date": 1550504725.057,
"LastUpdateAssociationDate": 1550504725.057,
"Status": {
"Date": 1550504725.057,
"Name": "Associated",
"Message": "Associated with AWS-UpdateSSMAgent"
},
"Overview": {
"Status": "Pending",
"DetailedStatus": "Creating"
},
"DocumentVersion": "$DEFAULT",
"AssociationId": "9c9f7f20-5154-4fed-a83e-0123456789ab",
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-9876543210abcdef0"
]
}
]
}
],
"Failed": []
}
```
+ For API details, see [CreateAssociationBatch](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/create-association-batch.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example associates a configuration document with multiple instances. The output returns a list of successful and failed operations, if applicable.**
```
$option1 = @{InstanceId="i-0cb2b964d3e14fd9f";Name=@("AWS-UpdateSSMAgent")}
$option2 = @{InstanceId="i-0000293ffd8c57862";Name=@("AWS-UpdateSSMAgent")}
New-SSMAssociationFromBatch -Entry $option1,$option2
```
**Output:**
```
Failed Successful
------ ----------
{} {Amazon.SimpleSystemsManagement.Model.FailedCreateAssociation, Amazon.SimpleSystemsManagement.Model.FailedCreateAsso...
```
**Example 2: This example will show the full details of a successful operation.**
```
$option1 = @{InstanceId="i-0cb2b964d3e14fd9f";Name=@("AWS-UpdateSSMAgent")}
$option2 = @{InstanceId="i-0000293ffd8c57862";Name=@("AWS-UpdateSSMAgent")}
(New-SSMAssociationFromBatch -Entry $option1,$option2).Successful
```
+ For API details, see [CreateAssociationBatch](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example associates a configuration document with multiple instances. The output returns a list of successful and failed operations, if applicable.**
```
$option1 = @{InstanceId="i-0cb2b964d3e14fd9f";Name=@("AWS-UpdateSSMAgent")}
$option2 = @{InstanceId="i-0000293ffd8c57862";Name=@("AWS-UpdateSSMAgent")}
New-SSMAssociationFromBatch -Entry $option1,$option2
```
**Output:**
```
Failed Successful
------ ----------
{} {Amazon.SimpleSystemsManagement.Model.FailedCreateAssociation, Amazon.SimpleSystemsManagement.Model.FailedCreateAsso...
```
**Example 2: This example will show the full details of a successful operation.**
```
$option1 = @{InstanceId="i-0cb2b964d3e14fd9f";Name=@("AWS-UpdateSSMAgent")}
$option2 = @{InstanceId="i-0000293ffd8c57862";Name=@("AWS-UpdateSSMAgent")}
(New-SSMAssociationFromBatch -Entry $option1,$option2).Successful
```
+ For API details, see [CreateAssociationBatch](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `CreateDocument` with an AWS SDK or CLI
<a name="ssm_example_ssm_CreateDocument_section"></a>
The following code examples show how to use `CreateDocument`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](ssm_example_ssm_Scenario_section.md)
------
#### [ CLI ]
**AWS CLI**
**To create a document**
The following `create-document` example creates a Systems Manager document.
```
aws ssm create-document \
--content file://exampleDocument.yml \
--name "Example" \
--document-type "Automation" \
--document-format YAML
```
Output:
```
{
"DocumentDescription": {
"Hash": "fc2410281f40779e694a8b95975d0f9f316da8a153daa94e3d9921102EXAMPLE",
"HashType": "Sha256",
"Name": "Example",
"Owner": "29884EXAMPLE",
"CreatedDate": 1583256349.452,
"Status": "Creating",
"DocumentVersion": "1",
"Description": "Document Example",
"Parameters": [
{
"Name": "AutomationAssumeRole",
"Type": "String",
"Description": "(Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to execute this document.",
"DefaultValue": ""
},
{
"Name": "InstanceId",
"Type": "String",
"Description": "(Required) The ID of the Amazon EC2 instance.",
"DefaultValue": ""
}
],
"PlatformTypes": [
"Windows",
"Linux"
],
"DocumentType": "Automation",
"SchemaVersion": "0.3",
"LatestVersion": "1",
"DefaultVersion": "1",
"DocumentFormat": "YAML",
"Tags": []
}
}
```
For more information, see [Creating Systems Manager Documents](https://docs.aws.amazon.com/systems-manager/latest/userguide/create-ssm-doc.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [CreateDocument](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/create-document.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/ssm#code-examples).
```
/**
* Creates an AWS SSM document asynchronously.
*
* @param docName The name of the document to create.
* <p>
* This method initiates an asynchronous request to create an SSM document.
* If the request is successful, it prints the document status.
* If an exception occurs, it handles the error appropriately.
*/
public void createSSMDoc(String docName) throws SsmException {
String jsonData = """
{
"schemaVersion": "2.2",
"description": "Run a simple shell command",
"mainSteps": [
{
"action": "aws:runShellScript",
"name": "runEchoCommand",
"inputs": {
"runCommand": [
"echo 'Hello, world!'"
]
}
}
]
}
""";
CreateDocumentRequest request = CreateDocumentRequest.builder()
.content(jsonData)
.name(docName)
.documentType(DocumentType.COMMAND)
.build();
CompletableFuture<CreateDocumentResponse> future = getAsyncClient().createDocument(request);
future.thenAccept(response -> {
System.out.println("The status of the SSM document is " + response.documentDescription().status());
}).exceptionally(ex -> {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof DocumentAlreadyExistsException) {
throw new CompletionException(cause);
} else if (cause instanceof SsmException) {
throw new CompletionException(cause);
} else {
throw new RuntimeException(cause);
}
}).join();
}
```
+ For API details, see [CreateDocument](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/CreateDocument) in *AWS SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ssm#code-examples).
```
import { CreateDocumentCommand, SSMClient } from "@aws-sdk/client-ssm";
import { parseArgs } from "node:util";
/**
* Create an SSM document.
* @param {{ content: string, name: string, documentType?: DocumentType }}
*/
export const main = async ({ content, name, documentType }) => {
const client = new SSMClient({});
try {
const { documentDescription } = await client.send(
new CreateDocumentCommand({
Content: content, // The content for the new SSM document. The content must not exceed 64KB.
Name: name,
DocumentType: documentType, // Document format type can be JSON, YAML, or TEXT. The default format is JSON.
}),
);
console.log("Document created successfully.");
return { DocumentDescription: documentDescription };
} catch (caught) {
if (caught instanceof Error && caught.name === "DocumentAlreadyExists") {
console.warn(`${caught.message}. Did you provide a new document name?`);
} else {
throw caught;
}
}
};
```
+ For API details, see [CreateDocument](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/CreateDocumentCommand) in *AWS SDK for JavaScript API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example creates a document in your account. The document must be in JSON format. For more information about writing a configuration document, see Configuration Document in the SSM API Reference.**
```
New-SSMDocument -Content (Get-Content -Raw "c:\temp\RunShellScript.json") -Name "RunShellScript" -DocumentType "Command"
```
**Output:**
```
CreatedDate : 3/1/2017 1:21:33 AM
DefaultVersion : 1
Description : Run an updated script
DocumentType : Command
DocumentVersion : 1
Hash : 1d5ce820e999ff051eb4841ed887593daf77120fd76cae0d18a53cc42e4e22c1
HashType : Sha256
LatestVersion : 1
Name : RunShellScript
Owner : 809632081692
Parameters : {commands}
PlatformTypes : {Linux}
SchemaVersion : 2.0
Sha1 :
Status : Creating
```
+ For API details, see [CreateDocument](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example creates a document in your account. The document must be in JSON format. For more information about writing a configuration document, see Configuration Document in the SSM API Reference.**
```
New-SSMDocument -Content (Get-Content -Raw "c:\temp\RunShellScript.json") -Name "RunShellScript" -DocumentType "Command"
```
**Output:**
```
CreatedDate : 3/1/2017 1:21:33 AM
DefaultVersion : 1
Description : Run an updated script
DocumentType : Command
DocumentVersion : 1
Hash : 1d5ce820e999ff051eb4841ed887593daf77120fd76cae0d18a53cc42e4e22c1
HashType : Sha256
LatestVersion : 1
Name : RunShellScript
Owner : 809632081692
Parameters : {commands}
PlatformTypes : {Linux}
SchemaVersion : 2.0
Sha1 :
Status : Creating
```
+ For API details, see [CreateDocument](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
```
class DocumentWrapper:
"""Encapsulates AWS Systems Manager Document actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def create(self, content, name):
"""
Creates a document.
:param content: The content of the document.
:param name: The name of the document.
"""
try:
self.ssm_client.create_document(
Name=name, Content=content, DocumentType="Command"
)
self.name = name
except self.ssm_client.exceptions.DocumentAlreadyExists:
print(f"Document {name} already exists.")
self.name = name
except ClientError as err:
logger.error(
"Couldn't create %s. Here's why: %s: %s",
name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [CreateDocument](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateDocument) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/ssm#code-examples).
```
TRY.
lo_ssm->createdocument(
iv_name = iv_name
iv_content = iv_content
iv_documenttype = 'Command' ).
MESSAGE 'Document created.' TYPE 'I'.
CATCH /aws1/cx_ssmdocalreadyexists.
MESSAGE 'Document already exists.' TYPE 'I'.
CATCH /aws1/cx_ssminvaliddoccontent.
MESSAGE 'Invalid document content.' TYPE 'I'.
ENDTRY.
```
+ For API details, see [CreateDocument](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------
# Use `CreateMaintenanceWindow` with an AWS SDK or CLI
<a name="ssm_example_ssm_CreateMaintenanceWindow_section"></a>
The following code examples show how to use `CreateMaintenanceWindow`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](ssm_example_ssm_Scenario_section.md)
------
#### [ CLI ]
**AWS CLI**
**Example 1: To create a maintenance window**
The following `create-maintenance-window` example creates a new maintenance window that every five minutes for up to two hours (as needed), prevents new tasks from starting within one hour of the end of the maintenance window execution, allows unassociated targets (instances that you haven't registered with the maintenance window), and indicates through the use of custom tags that its creator intends to use it in a tutorial.
```
aws ssm create-maintenance-window \
--name "My-Tutorial-Maintenance-Window" \
--schedule "rate(5 minutes)" \
--duration 2 --cutoff 1 \
--allow-unassociated-targets \
--tags "Key=Purpose,Value=Tutorial"
```
Output:
```
{
"WindowId": "mw-0c50858d01EXAMPLE"
}
```
**Example 2: To create a maintenance window that runs only once**
The following `create-maintenance-window` example creates a new maintenance window that only runs one time on the specified date and time.
```
aws ssm create-maintenance-window \
--name My-One-Time-Maintenance-Window \
--schedule "at(2020-05-14T15:55:00)" \
--duration 5 \
--cutoff 2 \
--allow-unassociated-targets \
--tags "Key=Environment,Value=Production"
```
Output:
```
{
"WindowId": "mw-01234567890abcdef"
}
```
For more information, see [Maintenance Windows](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-maintenance.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [CreateMaintenanceWindow](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/create-maintenance-window.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/ssm#code-examples).
```
/**
* Creates an SSM maintenance window asynchronously.
*
* @param winName The name of the maintenance window.
* @return The ID of the created or existing maintenance window.
* <p>
* This method initiates an asynchronous request to create an SSM maintenance window.
* If the request is successful, it prints the maintenance window ID.
* If an exception occurs, it handles the error appropriately.
*/
public String createMaintenanceWindow(String winName) throws SsmException, DocumentAlreadyExistsException {
CreateMaintenanceWindowRequest request = CreateMaintenanceWindowRequest.builder()
.name(winName)
.description("This is my maintenance window")
.allowUnassociatedTargets(true)
.duration(2)
.cutoff(1)
.schedule("cron(0 10 ? * MON-FRI *)")
.build();
CompletableFuture<CreateMaintenanceWindowResponse> future = getAsyncClient().createMaintenanceWindow(request);
final String[] windowId = {null};
future.whenComplete((response, ex) -> {
if (response != null) {
String maintenanceWindowId = response.windowId();
System.out.println("The maintenance window id is " + maintenanceWindowId);
windowId[0] = maintenanceWindowId;
} else {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof DocumentAlreadyExistsException) {
throw new CompletionException(cause);
} else if (cause instanceof SsmException) {
throw new CompletionException(cause);
} else {
throw new RuntimeException(cause);
}
}
}).join();
if (windowId[0] == null) {
MaintenanceWindowFilter filter = MaintenanceWindowFilter.builder()
.key("name")
.values(winName)
.build();
DescribeMaintenanceWindowsRequest winRequest = DescribeMaintenanceWindowsRequest.builder()
.filters(filter)
.build();
CompletableFuture<DescribeMaintenanceWindowsResponse> describeFuture = getAsyncClient().describeMaintenanceWindows(winRequest);
describeFuture.whenComplete((describeResponse, describeEx) -> {
if (describeResponse != null) {
List<MaintenanceWindowIdentity> windows = describeResponse.windowIdentities();
if (!windows.isEmpty()) {
windowId[0] = windows.get(0).windowId();
System.out.println("Window ID: " + windowId[0]);
} else {
System.out.println("Window not found.");
windowId[0] = "";
}
} else {
Throwable describeCause = (describeEx instanceof CompletionException) ? describeEx.getCause() : describeEx;
throw new RuntimeException("Error describing maintenance windows: " + describeCause.getMessage(), describeCause);
}
}).join();
}
return windowId[0];
}
```
+ For API details, see [CreateMaintenanceWindow](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/CreateMaintenanceWindow) in *AWS SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ssm#code-examples).
```
import { CreateMaintenanceWindowCommand, SSMClient } from "@aws-sdk/client-ssm";
import { parseArgs } from "node:util";
/**
* Create an SSM maintenance window.
* @param {{ name: string, allowUnassociatedTargets: boolean, duration: number, cutoff: number, schedule: string, description?: string }}
*/
export const main = async ({
name,
allowUnassociatedTargets, // Allow the maintenance window to run on managed nodes, even if you haven't registered those nodes as targets.
duration, // The duration of the maintenance window in hours.
cutoff, // The number of hours before the end of the maintenance window that Amazon Web Services Systems Manager stops scheduling new tasks for execution.
schedule, // The schedule of the maintenance window in the form of a cron or rate expression.
description = undefined,
}) => {
const client = new SSMClient({});
try {
const { windowId } = await client.send(
new CreateMaintenanceWindowCommand({
Name: name,
Description: description,
AllowUnassociatedTargets: allowUnassociatedTargets, // Allow the maintenance window to run on managed nodes, even if you haven't registered those nodes as targets.
Duration: duration, // The duration of the maintenance window in hours.
Cutoff: cutoff, // The number of hours before the end of the maintenance window that Amazon Web Services Systems Manager stops scheduling new tasks for execution.
Schedule: schedule, // The schedule of the maintenance window in the form of a cron or rate expression.
}),
);
console.log(`Maintenance window created with Id: ${windowId}`);
return { WindowId: windowId };
} catch (caught) {
if (caught instanceof Error && caught.name === "MissingParameter") {
console.warn(`${caught.message}. Did you provide these values?`);
} else {
throw caught;
}
}
};
```
+ For API details, see [CreateMaintenanceWindow](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/CreateMaintenanceWindowCommand) in *AWS SDK for JavaScript API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example creates a new maintenance window with the specified name that runs at 4 PM on every Tuesday for 4 hours, with a 1 hour cutoff, and that allows unassociated targets.**
```
New-SSMMaintenanceWindow -Name "MyMaintenanceWindow" -Duration 4 -Cutoff 1 -AllowUnassociatedTarget $true -Schedule "cron(0 16 ? * TUE *)"
```
**Output:**
```
mw-03eb53e1ea7383998
```
+ For API details, see [CreateMaintenanceWindow](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example creates a new maintenance window with the specified name that runs at 4 PM on every Tuesday for 4 hours, with a 1 hour cutoff, and that allows unassociated targets.**
```
New-SSMMaintenanceWindow -Name "MyMaintenanceWindow" -Duration 4 -Cutoff 1 -AllowUnassociatedTarget $true -Schedule "cron(0 16 ? * TUE *)"
```
**Output:**
```
mw-03eb53e1ea7383998
```
+ For API details, see [CreateMaintenanceWindow](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
```
class MaintenanceWindowWrapper:
"""Encapsulates AWS Systems Manager maintenance window actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.window_id = None
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def create(self, name, schedule, duration, cutoff, allow_unassociated_targets):
"""
Create an AWS Systems Manager maintenance window.
:param name: The name of the maintenance window.
:param schedule: The schedule of the maintenance window.
:param duration: The duration of the maintenance window.
:param cutoff: The cutoff time of the maintenance window.
:param allow_unassociated_targets: Allow the maintenance window to run on managed nodes, even
if you haven't registered those nodes as targets.
"""
try:
response = self.ssm_client.create_maintenance_window(
Name=name,
Schedule=schedule,
Duration=duration,
Cutoff=cutoff,
AllowUnassociatedTargets=allow_unassociated_targets,
)
self.window_id = response["WindowId"]
self.name = name
logger.info("Created maintenance window %s.", self.window_id)
except ParamValidationError as error:
logger.error(
"Parameter validation error when trying to create maintenance window %s. Here's why: %s",
self.window_id,
error,
)
raise
except ClientError as err:
logger.error(
"Couldn't create maintenance window %s. Here's why: %s: %s",
name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [CreateMaintenanceWindow](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateMaintenanceWindow) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/ssm#code-examples).
```
TRY.
oo_result = lo_ssm->createmaintenancewindow(
iv_name = iv_name
iv_schedule = iv_schedule
iv_duration = iv_duration
iv_cutoff = iv_cutoff
iv_allowunassociatedtargets = iv_allow_unassociated_targets ).
MESSAGE 'Maintenance window created.' TYPE 'I'.
CATCH /aws1/cx_ssmresrclimitexcdex.
MESSAGE 'Resource limit exceeded.' TYPE 'I'.
ENDTRY.
```
+ For API details, see [CreateMaintenanceWindow](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------
# Use `CreateOpsItem` with an AWS SDK or CLI
<a name="ssm_example_ssm_CreateOpsItem_section"></a>
The following code examples show how to use `CreateOpsItem`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](ssm_example_ssm_Scenario_section.md)
------
#### [ CLI ]
**AWS CLI**
**To create an OpsItems**
The following `create-ops-item` example uses the /aws/resources key in OperationalData to create an OpsItem with an Amazon DynamoDB related resource.
```
aws ssm create-ops-item \
--title "EC2 instance disk full" \
--description "Log clean up may have failed which caused the disk to be full" \
--priority 2 \
--source ec2 \
--operational-data '{"/aws/resources":{"Value":"[{\"arn\": \"arn:aws:dynamodb:us-west-2:12345678:table/OpsItems\"}]","Type":"SearchableString"}}' \
--notifications Arn="arn:aws:sns:us-west-2:12345678:TestUser"
```
Output:
```
{
"OpsItemId": "oi-1a2b3c4d5e6f"
}
```
For more information, see [Creating OpsItems](https://docs.aws.amazon.com/systems-manager/latest/userguide/OpsCenter-creating-OpsItems.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [CreateOpsItem](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/create-ops-item.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/ssm#code-examples).
```
/**
* Creates an SSM OpsItem asynchronously.
*
* @param title The title of the OpsItem.
* @param source The source of the OpsItem.
* @param category The category of the OpsItem.
* @param severity The severity of the OpsItem.
* @return The ID of the created OpsItem.
* <p>
* This method initiates an asynchronous request to create an SSM OpsItem.
* If the request is successful, it returns the OpsItem ID.
* If an exception occurs, it handles the error appropriately.
*/
public String createSSMOpsItem(String title, String source, String category, String severity) {
CreateOpsItemRequest opsItemRequest = CreateOpsItemRequest.builder()
.description("Created by the SSM Java API")
.title(title)
.source(source)
.category(category)
.severity(severity)
.build();
CompletableFuture<CreateOpsItemResponse> future = getAsyncClient().createOpsItem(opsItemRequest);
try {
CreateOpsItemResponse response = future.join();
return response.opsItemId();
} catch (CompletionException e) {
Throwable cause = e.getCause();
if (cause instanceof SsmException) {
throw (SsmException) cause;
} else {
throw new RuntimeException(cause);
}
}
}
```
+ For API details, see [CreateOpsItem](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/CreateOpsItem) in *AWS SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ssm#code-examples).
```
import { CreateOpsItemCommand, SSMClient } from "@aws-sdk/client-ssm";
import { parseArgs } from "node:util";
/**
* Create an SSM OpsItem.
* @param {{ title: string, source: string, category?: string, severity?: string }}
*/
export const main = async ({
title,
source,
category = undefined,
severity = undefined,
}) => {
const client = new SSMClient({});
try {
const { opsItemArn, opsItemId } = await client.send(
new CreateOpsItemCommand({
Title: title,
Source: source, // The origin of the OpsItem, such as Amazon EC2 or Systems Manager.
Category: category,
Severity: severity,
}),
);
console.log(`Ops item created with id: ${opsItemId}`);
return { OpsItemArn: opsItemArn, OpsItemId: opsItemId };
} catch (caught) {
if (caught instanceof Error && caught.name === "MissingParameter") {
console.warn(`${caught.message}. Did you provide these values?`);
} else {
throw caught;
}
}
};
```
+ For API details, see [CreateOpsItem](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/CreateOpsItemCommand) in *AWS SDK for JavaScript API Reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
```
class OpsItemWrapper:
"""Encapsulates AWS Systems Manager OpsItem actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.id = None
@classmethod
def from_client(cls):
"""
:return: A OpsItemWrapper instance.
"""
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def create(self, title, source, category, severity, description):
"""
Create an OpsItem
:param title: The OpsItem title.
:param source: The OpsItem source.
:param category: The OpsItem category.
:param severity: The OpsItem severity.
:param description: The OpsItem description.
"""
try:
response = self.ssm_client.create_ops_item(
Title=title,
Source=source,
Category=category,
Severity=severity,
Description=description,
)
self.id = response["OpsItemId"]
except self.ssm_client.exceptions.OpsItemLimitExceededException as err:
logger.error(
"Couldn't create ops item because you have exceeded your open OpsItem limit. "
"Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
except ClientError as err:
logger.error(
"Couldn't create ops item %s. Here's why: %s: %s",
title,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [CreateOpsItem](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/CreateOpsItem) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/ssm#code-examples).
```
TRY.
oo_result = lo_ssm->createopsitem(
iv_title = iv_title
iv_source = iv_source
iv_category = iv_category
iv_severity = iv_severity
iv_description = iv_description ).
MESSAGE 'OpsItem created.' TYPE 'I'.
CATCH /aws1/cx_ssmopsitemlimitexcdex.
MESSAGE 'You have exceeded your open OpsItem limit.' TYPE 'I'.
CATCH /aws1/cx_ssmopsitemalrdyexex.
MESSAGE 'OpsItem already exists.' TYPE 'I'.
ENDTRY.
```
+ For API details, see [CreateOpsItem](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------
# Use `CreatePatchBaseline` with a CLI
<a name="ssm_example_ssm_CreatePatchBaseline_section"></a>
The following code examples show how to use `CreatePatchBaseline`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To create a patch baseline with auto-approval**
The following `create-patch-baseline` example creates a patch baseline for Windows Server that approves patches for a production environment seven days after they are released by Microsoft.
```
aws ssm create-patch-baseline \
--name "Windows-Production-Baseline-AutoApproval" \
--operating-system "WINDOWS" \
--approval-rules "PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=MSRC_SEVERITY,Values=[Critical,Important,Moderate]},{Key=CLASSIFICATION,Values=[SecurityUpdates,Updates,UpdateRollups,CriticalUpdates]}]},ApproveAfterDays=7}]" \
--description "Baseline containing all updates approved for Windows Server production systems"
```
Output:
```
{
"BaselineId": "pb-045f10b4f3EXAMPLE"
}
```
**Example 2: To create a patch baseline with an approval cutoff date**
The following `create-patch-baseline` example creates a patch baseline for Windows Server that approves all patches for a production environment that are released on or before July 7, 2020.
```
aws ssm create-patch-baseline \
--name "Windows-Production-Baseline-AutoApproval" \
--operating-system "WINDOWS" \
--approval-rules "PatchRules=[{PatchFilterGroup={PatchFilters=[{Key=MSRC_SEVERITY,Values=[Critical,Important,Moderate]},{Key=CLASSIFICATION,Values=[SecurityUpdates,Updates,UpdateRollups,CriticalUpdates]}]},ApproveUntilDate=2020-07-07}]" \
--description "Baseline containing all updates approved for Windows Server production systems"
```
Output:
```
{
"BaselineId": "pb-045f10b4f3EXAMPLE"
}
```
**Example 3: To create a patch baseline with approval rules stored in a JSON file**
The following `create-patch-baseline` example creates a patch baseline for Amazon Linux 2017.09 that approves patches for a production environment seven days after they are released, specifies approval rules for the patch baseline, and specifies a custom repository for patches.
```
aws ssm create-patch-baseline \
--cli-input-json file://my-amazon-linux-approval-rules-and-repo.json
```
Contents of `my-amazon-linux-approval-rules-and-repo.json`:
```
{
"Name": "Amazon-Linux-2017.09-Production-Baseline",
"Description": "My approval rules patch baseline for Amazon Linux 2017.09 instances",
"OperatingSystem": "AMAZON_LINUX",
"Tags": [
{
"Key": "Environment",
"Value": "Production"
}
],
"ApprovalRules": {
"PatchRules": [
{
"ApproveAfterDays": 7,
"EnableNonSecurity": true,
"PatchFilterGroup": {
"PatchFilters": [
{
"Key": "SEVERITY",
"Values": [
"Important",
"Critical"
]
},
{
"Key": "CLASSIFICATION",
"Values": [
"Security",
"Bugfix"
]
},
{
"Key": "PRODUCT",
"Values": [
"AmazonLinux2017.09"
]
}
]
}
}
]
},
"Sources": [
{
"Name": "My-AL2017.09",
"Products": [
"AmazonLinux2017.09"
],
"Configuration": "[amzn-main] \nname=amzn-main-Base\nmirrorlist=http://repo./$awsregion./$awsdomain//$releasever/main/mirror.list //nmirrorlist_expire=300//nmetadata_expire=300 \npriority=10 \nfailovermethod=priority \nfastestmirror_enabled=0 \ngpgcheck=1 \ngpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-amazon-ga \nenabled=1 \nretries=3 \ntimeout=5\nreport_instanceid=yes"
}
]
}
```
**Example 4: To create a patch baseline that specifies approved and rejected patches**
The following `create-patch-baseline` example explicitly specifies patches to approve and reject as exception to the default approval rules.
```
aws ssm create-patch-baseline \
--name "Amazon-Linux-2017.09-Alpha-Baseline" \
--description "My custom approve/reject patch baseline for Amazon Linux 2017.09 instances" \
--operating-system "AMAZON_LINUX" \
--approved-patches "CVE-2018-1234567,example-pkg-EE-2018*.amzn1.noarch" \
--approved-patches-compliance-level "HIGH" \
--approved-patches-enable-non-security \
--tags "Key=Environment,Value=Alpha"
```
For more information, see [Create a Custom Patch Baseline](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-baseline-console.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [CreatePatchBaseline](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/create-patch-baseline.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example creates a patch baseline that approves patches, seven days after they are released by Microsoft, for managed instances running Windows Server 2019 in a production environment.**
```
$rule = New-Object Amazon.SimpleSystemsManagement.Model.PatchRule
$rule.ApproveAfterDays = 7
$ruleFilters = New-Object Amazon.SimpleSystemsManagement.Model.PatchFilterGroup
$patchFilter = New-Object Amazon.SimpleSystemsManagement.Model.PatchFilter
$patchFilter.Key="PRODUCT"
$patchFilter.Values="WindowsServer2019"
$severityFilter = New-Object Amazon.SimpleSystemsManagement.Model.PatchFilter
$severityFilter.Key="MSRC_SEVERITY"
$severityFilter.Values.Add("Critical")
$severityFilter.Values.Add("Important")
$severityFilter.Values.Add("Moderate")
$classificationFilter = New-Object Amazon.SimpleSystemsManagement.Model.PatchFilter
$classificationFilter.Key = "CLASSIFICATION"
$classificationFilter.Values.Add( "SecurityUpdates" )
$classificationFilter.Values.Add( "Updates" )
$classificationFilter.Values.Add( "UpdateRollups" )
$classificationFilter.Values.Add( "CriticalUpdates" )
$ruleFilters.PatchFilters.Add($severityFilter)
$ruleFilters.PatchFilters.Add($classificationFilter)
$ruleFilters.PatchFilters.Add($patchFilter)
$rule.PatchFilterGroup = $ruleFilters
New-SSMPatchBaseline -Name "Production-Baseline-Windows2019" -Description "Baseline containing all updates approved for production systems" -ApprovalRules_PatchRule $rule
```
**Output:**
```
pb-0z4z6221c4296b23z
```
+ For API details, see [CreatePatchBaseline](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example creates a patch baseline that approves patches, seven days after they are released by Microsoft, for managed instances running Windows Server 2019 in a production environment.**
```
$rule = New-Object Amazon.SimpleSystemsManagement.Model.PatchRule
$rule.ApproveAfterDays = 7
$ruleFilters = New-Object Amazon.SimpleSystemsManagement.Model.PatchFilterGroup
$patchFilter = New-Object Amazon.SimpleSystemsManagement.Model.PatchFilter
$patchFilter.Key="PRODUCT"
$patchFilter.Values="WindowsServer2019"
$severityFilter = New-Object Amazon.SimpleSystemsManagement.Model.PatchFilter
$severityFilter.Key="MSRC_SEVERITY"
$severityFilter.Values.Add("Critical")
$severityFilter.Values.Add("Important")
$severityFilter.Values.Add("Moderate")
$classificationFilter = New-Object Amazon.SimpleSystemsManagement.Model.PatchFilter
$classificationFilter.Key = "CLASSIFICATION"
$classificationFilter.Values.Add( "SecurityUpdates" )
$classificationFilter.Values.Add( "Updates" )
$classificationFilter.Values.Add( "UpdateRollups" )
$classificationFilter.Values.Add( "CriticalUpdates" )
$ruleFilters.PatchFilters.Add($severityFilter)
$ruleFilters.PatchFilters.Add($classificationFilter)
$ruleFilters.PatchFilters.Add($patchFilter)
$rule.PatchFilterGroup = $ruleFilters
New-SSMPatchBaseline -Name "Production-Baseline-Windows2019" -Description "Baseline containing all updates approved for production systems" -ApprovalRules_PatchRule $rule
```
**Output:**
```
pb-0z4z6221c4296b23z
```
+ For API details, see [CreatePatchBaseline](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DeleteActivation` with a CLI
<a name="ssm_example_ssm_DeleteActivation_section"></a>
The following code examples show how to use `DeleteActivation`.
------
#### [ CLI ]
**AWS CLI**
**To delete a managed instance activation**
The following `delete-activation` example deletes a managed instance activation.
```
aws ssm delete-activation \
--activation-id "aa673477-d926-42c1-8757-1358cEXAMPLE"
```
This command produces no output.
For more information, see [Setting Up AWS Systems Manager for Hybrid Environments](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-managedinstances.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DeleteActivation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/delete-activation.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example deletes an activation. There is no output if the command succeeds.**
```
Remove-SSMActivation -ActivationId "08e51e79-1e36-446c-8e63-9458569c1363"
```
+ For API details, see [DeleteActivation](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example deletes an activation. There is no output if the command succeeds.**
```
Remove-SSMActivation -ActivationId "08e51e79-1e36-446c-8e63-9458569c1363"
```
+ For API details, see [DeleteActivation](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DeleteAssociation` with a CLI
<a name="ssm_example_ssm_DeleteAssociation_section"></a>
The following code examples show how to use `DeleteAssociation`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To delete an association using the association ID**
The following `delete-association` example deletes the association for the specified association ID. There is no output if the command succeeds.
```
aws ssm delete-association \
--association-id "8dfe3659-4309-493a-8755-0123456789ab"
```
This command produces no output.
For more information, see [Editing and creating a new version of an association](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-state-assoc-edit.html) in the *AWS Systems Manager User Guide*.
**Example 2: To delete an association**
The following `delete-association` example deletes the association between an instance and a document. There is no output if the command succeeds.
```
aws ssm delete-association \
--instance-id "i-1234567890abcdef0" \
--name "AWS-UpdateSSMAgent"
```
This command produces no output.
For more information, see [Working with associations in Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-associations.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DeleteAssociation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/delete-association.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example deletes the association between an instance and a document. There is no output if the command succeeds.**
```
Remove-SSMAssociation -InstanceId "i-0cb2b964d3e14fd9f" -Name "AWS-UpdateSSMAgent"
```
+ For API details, see [DeleteAssociation](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example deletes the association between an instance and a document. There is no output if the command succeeds.**
```
Remove-SSMAssociation -InstanceId "i-0cb2b964d3e14fd9f" -Name "AWS-UpdateSSMAgent"
```
+ For API details, see [DeleteAssociation](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DeleteDocument` with an AWS SDK or CLI
<a name="ssm_example_ssm_DeleteDocument_section"></a>
The following code examples show how to use `DeleteDocument`.
------
#### [ CLI ]
**AWS CLI**
**To delete a document**
The following `delete-document` example deletes a Systems Manager document.
```
aws ssm delete-document \
--name "Example"
```
This command produces no output.
For more information, see [Creating Systems Manager Documents](https://docs.aws.amazon.com/systems-manager/latest/userguide/create-ssm-doc.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DeleteDocument](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/delete-document.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/ssm#code-examples).
```
/**
* Deletes an AWS SSM document asynchronously.
*
* @param documentName The name of the document to delete.
* <p>
* This method initiates an asynchronous request to delete an SSM document.
* If an exception occurs, it handles the error appropriately.
*/
public void deleteDoc(String documentName) {
DeleteDocumentRequest documentRequest = DeleteDocumentRequest.builder()
.name(documentName)
.build();
CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
getAsyncClient().deleteDocument(documentRequest)
.thenAccept(response -> {
System.out.println("The SSM document was successfully deleted.");
})
.exceptionally(ex -> {
throw new CompletionException(ex);
}).join();
}).exceptionally(ex -> {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw new RuntimeException("SSM error: " + cause.getMessage(), cause);
} else {
throw new RuntimeException("Unexpected error: " + cause.getMessage(), cause);
}
});
try {
future.join();
} catch (CompletionException ex) {
throw ex.getCause() instanceof RuntimeException ? (RuntimeException) ex.getCause() : ex;
}
}
```
+ For API details, see [DeleteDocument](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/DeleteDocument) in *AWS SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ssm#code-examples).
```
import { DeleteDocumentCommand, SSMClient } from "@aws-sdk/client-ssm";
import { parseArgs } from "node:util";
/**
* Delete an SSM document.
* @param {{ documentName: string }}
*/
export const main = async ({ documentName }) => {
const client = new SSMClient({});
try {
await client.send(new DeleteDocumentCommand({ Name: documentName }));
console.log(`Document '${documentName}' deleted.`);
return { Deleted: true };
} catch (caught) {
if (caught instanceof Error && caught.name === "MissingParameter") {
console.warn(`${caught.message}. Did you provide this value?`);
} else {
throw caught;
}
}
};
```
+ For API details, see [DeleteDocument](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/DeleteDocumentCommand) in *AWS SDK for JavaScript API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example deletes a document. There is no output if the command succeeds.**
```
Remove-SSMDocument -Name "RunShellScript"
```
+ For API details, see [DeleteDocument](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example deletes a document. There is no output if the command succeeds.**
```
Remove-SSMDocument -Name "RunShellScript"
```
+ For API details, see [DeleteDocument](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
```
class DocumentWrapper:
"""Encapsulates AWS Systems Manager Document actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def delete(self):
"""
Deletes an AWS Systems Manager document.
"""
if self.name is None:
return
try:
self.ssm_client.delete_document(Name=self.name)
print(f"Deleted document {self.name}.")
self.name = None
except ClientError as err:
logger.error(
"Couldn't delete %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [DeleteDocument](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DeleteDocument) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/ssm#code-examples).
```
TRY.
lo_ssm->deletedocument( iv_name = iv_name ).
MESSAGE 'Document deleted.' TYPE 'I'.
CATCH /aws1/cx_ssminvaliddocument.
MESSAGE 'Invalid document.' TYPE 'I'.
CATCH /aws1/cx_ssmassocdinstances.
MESSAGE 'Document has associated instances.' TYPE 'I'.
ENDTRY.
```
+ For API details, see [DeleteDocument](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------
# Use `DeleteMaintenanceWindow` with an AWS SDK or CLI
<a name="ssm_example_ssm_DeleteMaintenanceWindow_section"></a>
The following code examples show how to use `DeleteMaintenanceWindow`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](ssm_example_ssm_Scenario_section.md)
------
#### [ CLI ]
**AWS CLI**
**To delete a maintenance window**
This `delete-maintenance-window` example removes the specified maintenance window.
```
aws ssm delete-maintenance-window \
--window-id "mw-1a2b3c4d5e6f7g8h9"
```
Output:
```
{
"WindowId":"mw-1a2b3c4d5e6f7g8h9"
}
```
For more information, see [Delete a Maintenance Window (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/mw-cli-tutorial-delete-mw.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DeleteMaintenanceWindow](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/delete-maintenance-window.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/ssm#code-examples).
```
/**
* Deletes an AWS SSM Maintenance Window asynchronously.
*
* @param winId The ID of the Maintenance Window to delete.
* <p>
* This method initiates an asynchronous request to delete an SSM Maintenance Window.
* If an exception occurs, it handles the error appropriately.
*/
public void deleteMaintenanceWindow(String winId) {
DeleteMaintenanceWindowRequest windowRequest = DeleteMaintenanceWindowRequest.builder()
.windowId(winId)
.build();
CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
getAsyncClient().deleteMaintenanceWindow(windowRequest)
.thenAccept(response -> {
System.out.println("The maintenance window was successfully deleted.");
})
.exceptionally(ex -> {
throw new CompletionException(ex);
}).join();
}).exceptionally(ex -> {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw new RuntimeException("SSM error: " + cause.getMessage(), cause);
} else {
throw new RuntimeException("Unexpected error: " + cause.getMessage(), cause);
}
});
try {
future.join();
} catch (CompletionException ex) {
throw ex.getCause() instanceof RuntimeException ? (RuntimeException) ex.getCause() : ex;
}
}
```
+ For API details, see [DeleteMaintenanceWindow](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/DeleteMaintenanceWindow) in *AWS SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ssm#code-examples).
```
import { DeleteMaintenanceWindowCommand, SSMClient } from "@aws-sdk/client-ssm";
import { parseArgs } from "node:util";
/**
* Delete an SSM maintenance window.
* @param {{ windowId: string }}
*/
export const main = async ({ windowId }) => {
const client = new SSMClient({});
try {
await client.send(
new DeleteMaintenanceWindowCommand({ WindowId: windowId }),
);
console.log(`Maintenance window '${windowId}' deleted.`);
return { Deleted: true };
} catch (caught) {
if (caught instanceof Error && caught.name === "MissingParameter") {
console.warn(`${caught.message}. Did you provide this value?`);
} else {
throw caught;
}
}
};
```
+ For API details, see [DeleteMaintenanceWindow](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/DeleteMaintenanceWindowCommand) in *AWS SDK for JavaScript API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example removes a maintenance window.**
```
Remove-SSMMaintenanceWindow -WindowId "mw-06d59c1a07c022145"
```
**Output:**
```
mw-06d59c1a07c022145
```
+ For API details, see [DeleteMaintenanceWindow](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example removes a maintenance window.**
```
Remove-SSMMaintenanceWindow -WindowId "mw-06d59c1a07c022145"
```
**Output:**
```
mw-06d59c1a07c022145
```
+ For API details, see [DeleteMaintenanceWindow](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
```
class MaintenanceWindowWrapper:
"""Encapsulates AWS Systems Manager maintenance window actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.window_id = None
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def delete(self):
"""
Delete the associated AWS Systems Manager maintenance window.
"""
if self.window_id is None:
return
try:
self.ssm_client.delete_maintenance_window(WindowId=self.window_id)
logger.info("Deleted maintenance window %s.", self.window_id)
print(f"Deleted maintenance window {self.name}")
self.window_id = None
except ClientError as err:
logger.error(
"Couldn't delete maintenance window %s. Here's why: %s: %s",
self.window_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [DeleteMaintenanceWindow](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DeleteMaintenanceWindow) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/ssm#code-examples).
```
TRY.
lo_ssm->deletemaintenancewindow( iv_windowid = iv_window_id ).
MESSAGE 'Maintenance window deleted.' TYPE 'I'.
CATCH /aws1/cx_ssminternalservererr.
MESSAGE 'Internal server error occurred.' TYPE 'I'.
ENDTRY.
```
+ For API details, see [DeleteMaintenanceWindow](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------
# Use `DeleteOpsItem` with an AWS SDK
<a name="ssm_example_ssm_DeleteOpsItem_section"></a>
The following code examples show how to use `DeleteOpsItem`.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
```
class OpsItemWrapper:
"""Encapsulates AWS Systems Manager OpsItem actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.id = None
@classmethod
def from_client(cls):
"""
:return: A OpsItemWrapper instance.
"""
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def delete(self):
"""
Delete the OpsItem.
"""
if self.id is None:
return
try:
self.ssm_client.delete_ops_item(OpsItemId=self.id)
print(f"Deleted ops item with id {self.id}")
self.id = None
except ClientError as err:
logger.error(
"Couldn't delete ops item %s. Here's why: %s: %s",
self.id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [DeleteOpsItem](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DeleteOpsItem) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/ssm#code-examples).
```
TRY.
lo_ssm->deleteopsitem( iv_opsitemid = iv_ops_item_id ).
MESSAGE 'OpsItem deleted.' TYPE 'I'.
CATCH /aws1/cx_ssmopsiteminvparamex.
MESSAGE 'Invalid OpsItem parameter.' TYPE 'I'.
ENDTRY.
```
+ For API details, see [DeleteOpsItem](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------
# Use `DeleteParameter` with a CLI
<a name="ssm_example_ssm_DeleteParameter_section"></a>
The following code examples show how to use `DeleteParameter`.
------
#### [ CLI ]
**AWS CLI**
**To delete a parameter**
The following `delete-parameter` example deletes the specified single parameter.
```
aws ssm delete-parameter \
--name "MyParameter"
```
This command produces no output.
For more information, see [Working with Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-working-with.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DeleteParameter](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/delete-parameter.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example deletes a parameter. There is no output if the command succeeds.**
```
Remove-SSMParameter -Name "helloWorld"
```
+ For API details, see [DeleteParameter](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example deletes a parameter. There is no output if the command succeeds.**
```
Remove-SSMParameter -Name "helloWorld"
```
+ For API details, see [DeleteParameter](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DeletePatchBaseline` with a CLI
<a name="ssm_example_ssm_DeletePatchBaseline_section"></a>
The following code examples show how to use `DeletePatchBaseline`.
------
#### [ CLI ]
**AWS CLI**
**To delete a patch baseline**
The following `delete-patch-baseline` example deletes the specified patch baseline.
```
aws ssm delete-patch-baseline \
--baseline-id "pb-045f10b4f382baeda"
```
Output:
```
{
"BaselineId": "pb-045f10b4f382baeda"
}
```
For more information, see [Update or Delete a Patch Baseline (Console)](https://docs.aws.amazon.com/systems-manager/latest/userguide/patch-baseline-update-or-delete.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DeletePatchBaseline](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/delete-patch-baseline.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example deletes a patch baseline.**
```
Remove-SSMPatchBaseline -BaselineId "pb-045f10b4f382baeda"
```
**Output:**
```
pb-045f10b4f382baeda
```
+ For API details, see [DeletePatchBaseline](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example deletes a patch baseline.**
```
Remove-SSMPatchBaseline -BaselineId "pb-045f10b4f382baeda"
```
**Output:**
```
pb-045f10b4f382baeda
```
+ For API details, see [DeletePatchBaseline](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DeregisterManagedInstance` with a CLI
<a name="ssm_example_ssm_DeregisterManagedInstance_section"></a>
The following code examples show how to use `DeregisterManagedInstance`.
------
#### [ CLI ]
**AWS CLI**
**To deregister a managed instance**
The following `deregister-managed-instance` example deregisters the specified managed instance.
```
aws ssm deregister-managed-instance \
--instance-id 'mi-08ab247cdfEXAMPLE'
```
This command produces no output.
For more information, see [Deregistering managed nodes in a hybrid and multicloud environment](https://docs.aws.amazon.com/systems-manager/latest/userguide/fleet-manager-deregister-hybrid-nodes.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DeregisterManagedInstance](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/deregister-managed-instance.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example deregisters a managed instance. There is no output if the command succeeds.**
```
Unregister-SSMManagedInstance -InstanceId "mi-08ab247cdf1046573"
```
+ For API details, see [DeregisterManagedInstance](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example deregisters a managed instance. There is no output if the command succeeds.**
```
Unregister-SSMManagedInstance -InstanceId "mi-08ab247cdf1046573"
```
+ For API details, see [DeregisterManagedInstance](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DeregisterPatchBaselineForPatchGroup` with a CLI
<a name="ssm_example_ssm_DeregisterPatchBaselineForPatchGroup_section"></a>
The following code examples show how to use `DeregisterPatchBaselineForPatchGroup`.
------
#### [ CLI ]
**AWS CLI**
**To deregister a patch group from a patch baseline**
The following `deregister-patch-baseline-for-patch-group` example deregisters the specified patch group from the specified patch baseline.
```
aws ssm deregister-patch-baseline-for-patch-group \
--patch-group "Production" \
--baseline-id "pb-0ca44a362fEXAMPLE"
```
Output:
```
{
"PatchGroup":"Production",
"BaselineId":"pb-0ca44a362fEXAMPLE"
}
```
For more information, see [Add a Patch Group to a Patch Baseline](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-group-patchbaseline.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DeregisterPatchBaselineForPatchGroup](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/deregister-patch-baseline-for-patch-group.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example deregisters a patch group from a patch baseline.**
```
Unregister-SSMPatchBaselineForPatchGroup -BaselineId "pb-045f10b4f382baeda" -PatchGroup "Production"
```
**Output:**
```
BaselineId PatchGroup
---------- ----------
pb-045f10b4f382baeda Production
```
+ For API details, see [DeregisterPatchBaselineForPatchGroup](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example deregisters a patch group from a patch baseline.**
```
Unregister-SSMPatchBaselineForPatchGroup -BaselineId "pb-045f10b4f382baeda" -PatchGroup "Production"
```
**Output:**
```
BaselineId PatchGroup
---------- ----------
pb-045f10b4f382baeda Production
```
+ For API details, see [DeregisterPatchBaselineForPatchGroup](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DeregisterTargetFromMaintenanceWindow` with a CLI
<a name="ssm_example_ssm_DeregisterTargetFromMaintenanceWindow_section"></a>
The following code examples show how to use `DeregisterTargetFromMaintenanceWindow`.
------
#### [ CLI ]
**AWS CLI**
**To remove a target from a maintenance window**
The following `deregister-target-from-maintenance-window` example removes the specified target from the specified maintenance window.
```
aws ssm deregister-target-from-maintenance-window \
--window-id "mw-ab12cd34ef56gh78" \
--window-target-id "1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2"
```
Output:
```
{
"WindowId":"mw-ab12cd34ef56gh78",
"WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2"
}
```
For more information, see [Update a Maintenance Window (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/maintenance-windows-cli-tutorials-update.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DeregisterTargetFromMaintenanceWindow](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/deregister-target-from-maintenance-window.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example removes a target from a maintenance window.**
```
Unregister-SSMTargetFromMaintenanceWindow -WindowTargetId "6ab5c208-9fc4-4697-84b7-b02a6cc25f7d" -WindowId "mw-06cf17cbefcb4bf4f"
```
**Output:**
```
WindowId WindowTargetId
-------- --------------
mw-06cf17cbefcb4bf4f 6ab5c208-9fc4-4697-84b7-b02a6cc25f7d
```
+ For API details, see [DeregisterTargetFromMaintenanceWindow](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example removes a target from a maintenance window.**
```
Unregister-SSMTargetFromMaintenanceWindow -WindowTargetId "6ab5c208-9fc4-4697-84b7-b02a6cc25f7d" -WindowId "mw-06cf17cbefcb4bf4f"
```
**Output:**
```
WindowId WindowTargetId
-------- --------------
mw-06cf17cbefcb4bf4f 6ab5c208-9fc4-4697-84b7-b02a6cc25f7d
```
+ For API details, see [DeregisterTargetFromMaintenanceWindow](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DeregisterTaskFromMaintenanceWindow` with a CLI
<a name="ssm_example_ssm_DeregisterTaskFromMaintenanceWindow_section"></a>
The following code examples show how to use `DeregisterTaskFromMaintenanceWindow`.
------
#### [ CLI ]
**AWS CLI**
**To remove a task from a maintenance window**
The following `deregister-task-from-maintenance-window` example removes the specified task from the specified maintenance window.
```
aws ssm deregister-task-from-maintenance-window \
--window-id "mw-ab12cd34ef56gh78" \
--window-task-id "1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e6c"
```
Output:
```
{
"WindowTaskId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e6c",
"WindowId":"mw-ab12cd34ef56gh78"
}
```
For more information, see [Systems Manager Maintenance Windows Tutorials (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/maintenance-windows-tutorials.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DeregisterTaskFromMaintenanceWindow](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/deregister-task-from-maintenance-window.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example removes a task from a maintenance window.**
```
Unregister-SSMTaskFromMaintenanceWindow -WindowTaskId "f34a2c47-ddfd-4c85-a88d-72366b69af1b" -WindowId "mw-03a342e62c96d31b0"
```
**Output:**
```
WindowId WindowTaskId
-------- ------------
mw-03a342e62c96d31b0 f34a2c47-ddfd-4c85-a88d-72366b69af1b
```
+ For API details, see [DeregisterTaskFromMaintenanceWindow](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example removes a task from a maintenance window.**
```
Unregister-SSMTaskFromMaintenanceWindow -WindowTaskId "f34a2c47-ddfd-4c85-a88d-72366b69af1b" -WindowId "mw-03a342e62c96d31b0"
```
**Output:**
```
WindowId WindowTaskId
-------- ------------
mw-03a342e62c96d31b0 f34a2c47-ddfd-4c85-a88d-72366b69af1b
```
+ For API details, see [DeregisterTaskFromMaintenanceWindow](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeActivations` with a CLI
<a name="ssm_example_ssm_DescribeActivations_section"></a>
The following code examples show how to use `DescribeActivations`.
------
#### [ CLI ]
**AWS CLI**
**To describe activations**
The following `describe-activations` example lists details about the activations in your AWS account.
```
aws ssm describe-activations
```
Output:
```
{
"ActivationList": [
{
"ActivationId": "5743558d-563b-4457-8682-d16c3EXAMPLE",
"Description": "Example1",
"IamRole": "HybridWebServersRole,
"RegistrationLimit": 5,
"RegistrationsCount": 5,
"ExpirationDate": 1584316800.0,
"Expired": false,
"CreatedDate": 1581954699.792
},
{
"ActivationId": "3ee0322b-f62d-40eb-b672-13ebfEXAMPLE",
"Description": "Example2",
"IamRole": "HybridDatabaseServersRole",
"RegistrationLimit": 5,
"RegistrationsCount": 5,
"ExpirationDate": 1580515200.0,
"Expired": true,
"CreatedDate": 1578064132.002
},
]
}
```
For more information, see [Step 4: Create a Managed-Instance Activation for a Hybrid Environment](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-managed-instance-activation.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeActivations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-activations.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example provides details about the activations on your account.**
```
Get-SSMActivation
```
**Output:**
```
ActivationId : 08e51e79-1e36-446c-8e63-9458569c1363
CreatedDate : 3/1/2017 12:01:51 AM
DefaultInstanceName : MyWebServers
Description :
ExpirationDate : 3/2/2017 12:01:51 AM
Expired : False
IamRole : AutomationRole
RegistrationLimit : 10
RegistrationsCount : 0
```
+ For API details, see [DescribeActivations](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example provides details about the activations on your account.**
```
Get-SSMActivation
```
**Output:**
```
ActivationId : 08e51e79-1e36-446c-8e63-9458569c1363
CreatedDate : 3/1/2017 12:01:51 AM
DefaultInstanceName : MyWebServers
Description :
ExpirationDate : 3/2/2017 12:01:51 AM
Expired : False
IamRole : AutomationRole
RegistrationLimit : 10
RegistrationsCount : 0
```
+ For API details, see [DescribeActivations](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeAssociation` with a CLI
<a name="ssm_example_ssm_DescribeAssociation_section"></a>
The following code examples show how to use `DescribeAssociation`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To get details of an association**
The following `describe-association` example describes the association for the specified association ID.
```
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"
}
}
```
For more information, see [Editing and creating a new version of an association](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-state-assoc-edit.html) in the *AWS Systems Manager User Guide*.
**Example 2: To get details of an association for a specific instance and document**
The following `describe-association` example describes the association between an instance and a document.
```
aws ssm describe-association \
--instance-id "i-1234567890abcdef0" \
--name "AWS-UpdateSSMAgent"
```
Output:
```
{
"AssociationDescription": {
"Status": {
"Date": 1487876122.564,
"Message": "Associated with AWS-UpdateSSMAgent",
"Name": "Associated"
},
"Name": "AWS-UpdateSSMAgent",
"InstanceId": "i-1234567890abcdef0",
"Overview": {
"Status": "Pending",
"DetailedStatus": "Associated",
"AssociationStatusAggregatedCount": {
"Pending": 1
}
},
"AssociationId": "d8617c07-2079-4c18-9847-1234567890ab",
"DocumentVersion": "$DEFAULT",
"LastUpdateAssociationDate": 1487876122.564,
"Date": 1487876122.564,
"Targets": [
{
"Values": [
"i-1234567890abcdef0"
],
"Key": "InstanceIds"
}
]
}
}
```
For more information, see [Editing and creating a new version of an association](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-state-assoc-edit.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeAssociation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-association.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example describes the association between an instance and a document.**
```
Get-SSMAssociation -InstanceId "i-0000293ffd8c57862" -Name "AWS-UpdateSSMAgent"
```
**Output:**
```
Name : AWS-UpdateSSMAgent
InstanceId : i-0000293ffd8c57862
Date : 2/23/2017 6:55:22 PM
Status.Name : Pending
Status.Date : 2/20/2015 8:31:11 AM
Status.Message : temp_status_change
Status.AdditionalInfo : Additional-Config-Needed
```
+ For API details, see [DescribeAssociation](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example describes the association between an instance and a document.**
```
Get-SSMAssociation -InstanceId "i-0000293ffd8c57862" -Name "AWS-UpdateSSMAgent"
```
**Output:**
```
Name : AWS-UpdateSSMAgent
InstanceId : i-0000293ffd8c57862
Date : 2/23/2017 6:55:22 PM
Status.Name : Pending
Status.Date : 2/20/2015 8:31:11 AM
Status.Message : temp_status_change
Status.AdditionalInfo : Additional-Config-Needed
```
+ For API details, see [DescribeAssociation](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeAssociationExecutionTargets` with a CLI
<a name="ssm_example_ssm_DescribeAssociationExecutionTargets_section"></a>
The following code examples show how to use `DescribeAssociationExecutionTargets`.
------
#### [ CLI ]
**AWS CLI**
**To get details of an association execution**
The following `describe-association-execution-targets` example describes the specified association execution.
```
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"
}
}
]
}
```
For more information, see [Viewing association histories](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-state-assoc-history.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeAssociationExecutionTargets](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-association-execution-targets.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example displays the resource ID and its execution status that are part of the the association execution targets**
```
Get-SSMAssociationExecutionTarget -AssociationId 123a45a0-c678-9012-3456-78901234db5e -ExecutionId 123a45a0-c678-9012-3456-78901234db5e | Select-Object ResourceId, Status
```
**Output:**
```
ResourceId Status
---------- ------
i-0b1b2a3456f7a890b Success
i-01c12a45d6fc7a89f Success
i-0a1caf234f56d7dc8 Success
i-012a3fd45af6dbcfe Failed
i-0ddc1df23c4a5fb67 Success
```
**Example 2: This command checks the particular execution of a particular automation since yesterday, where a command document is associated. It further checkes if the association execution failed, and if so, it will display the command invocation details for the execution along with the instance id**
```
$AssociationExecution= Get-SSMAssociationExecutionTarget -AssociationId 1c234567-890f-1aca-a234-5a678d901cb0 -ExecutionId 12345ca12-3456-2345-2b45-23456789012 |
Where-Object {$_.LastExecutionDate -gt (Get-Date -Hour 00 -Minute 00).AddDays(-1)}
foreach ($execution in $AssociationExecution) {
if($execution.Status -ne 'Success'){
Write-Output "There was an issue executing the association $($execution.AssociationId) on $($execution.ResourceId)"
Get-SSMCommandInvocation -CommandId $execution.OutputSource.OutputSourceId -Detail:$true | Select-Object -ExpandProperty CommandPlugins
}
}
```
**Output:**
```
There was an issue executing the association 1c234567-890f-1aca-a234-5a678d901cb0 on i-0a1caf234f56d7dc8
Name : aws:runPowerShellScript
Output :
----------ERROR-------
failed to run commands: exit status 1
OutputS3BucketName :
OutputS3KeyPrefix :
OutputS3Region : eu-west-1
ResponseCode : 1
ResponseFinishDateTime : 5/29/2019 11:04:49 AM
ResponseStartDateTime : 5/29/2019 11:04:49 AM
StandardErrorUrl :
StandardOutputUrl :
Status : Failed
StatusDetails : Failed
```
+ For API details, see [DescribeAssociationExecutionTargets](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example displays the resource ID and its execution status that are part of the the association execution targets**
```
Get-SSMAssociationExecutionTarget -AssociationId 123a45a0-c678-9012-3456-78901234db5e -ExecutionId 123a45a0-c678-9012-3456-78901234db5e | Select-Object ResourceId, Status
```
**Output:**
```
ResourceId Status
---------- ------
i-0b1b2a3456f7a890b Success
i-01c12a45d6fc7a89f Success
i-0a1caf234f56d7dc8 Success
i-012a3fd45af6dbcfe Failed
i-0ddc1df23c4a5fb67 Success
```
**Example 2: This command checks the particular execution of a particular automation since yesterday, where a command document is associated. It further checkes if the association execution failed, and if so, it will display the command invocation details for the execution along with the instance id**
```
$AssociationExecution= Get-SSMAssociationExecutionTarget -AssociationId 1c234567-890f-1aca-a234-5a678d901cb0 -ExecutionId 12345ca12-3456-2345-2b45-23456789012 |
Where-Object {$_.LastExecutionDate -gt (Get-Date -Hour 00 -Minute 00).AddDays(-1)}
foreach ($execution in $AssociationExecution) {
if($execution.Status -ne 'Success'){
Write-Output "There was an issue executing the association $($execution.AssociationId) on $($execution.ResourceId)"
Get-SSMCommandInvocation -CommandId $execution.OutputSource.OutputSourceId -Detail:$true | Select-Object -ExpandProperty CommandPlugins
}
}
```
**Output:**
```
There was an issue executing the association 1c234567-890f-1aca-a234-5a678d901cb0 on i-0a1caf234f56d7dc8
Name : aws:runPowerShellScript
Output :
----------ERROR-------
failed to run commands: exit status 1
OutputS3BucketName :
OutputS3KeyPrefix :
OutputS3Region : eu-west-1
ResponseCode : 1
ResponseFinishDateTime : 5/29/2019 11:04:49 AM
ResponseStartDateTime : 5/29/2019 11:04:49 AM
StandardErrorUrl :
StandardOutputUrl :
Status : Failed
StatusDetails : Failed
```
+ For API details, see [DescribeAssociationExecutionTargets](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeAssociationExecutions` with a CLI
<a name="ssm_example_ssm_DescribeAssociationExecutions_section"></a>
The following code examples show how to use `DescribeAssociationExecutions`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To get details of all executions for an association**
The following `describe-association-executions` example describes all executions of the specified association.
```
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}"
},
...
]
}
```
For more information, see [Viewing association histories](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-state-assoc-history.html) in the *AWS Systems Manager User Guide*.
**Example 2: To get details of all executions for an association after a specific date and time**
The following `describe-association-executions` example describes all executions of an association after the specified date and time.
```
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}"
},
{
"AssociationId": "8dfe3659-4309-493a-8755-0123456789ab",
"AssociationVersion": "1",
"ExecutionId": "7abb6378-a4a5-4f10-8312-0123456789ab",
"Status": "Success",
"DetailedStatus": "Success",
"CreatedTime": 1550505536.843,
"ResourceCountByStatus": "{Success=1}"
},
...
]
}
```
For more information, see [Viewing association histories](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-state-assoc-history.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeAssociationExecutions](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-association-executions.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example returns the executions for the association ID provided**
```
Get-SSMAssociationExecution -AssociationId 123a45a0-c678-9012-3456-78901234db5e
```
**Output:**
```
AssociationId : 123a45a0-c678-9012-3456-78901234db5e
AssociationVersion : 2
CreatedTime : 3/2/2019 8:53:29 AM
DetailedStatus :
ExecutionId : 123a45a0-c678-9012-3456-78901234db5e
LastExecutionDate : 1/1/0001 12:00:00 AM
ResourceCountByStatus : {Success=4}
Status : Success
```
+ For API details, see [DescribeAssociationExecutions](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example returns the executions for the association ID provided**
```
Get-SSMAssociationExecution -AssociationId 123a45a0-c678-9012-3456-78901234db5e
```
**Output:**
```
AssociationId : 123a45a0-c678-9012-3456-78901234db5e
AssociationVersion : 2
CreatedTime : 3/2/2019 8:53:29 AM
DetailedStatus :
ExecutionId : 123a45a0-c678-9012-3456-78901234db5e
LastExecutionDate : 1/1/0001 12:00:00 AM
ResourceCountByStatus : {Success=4}
Status : Success
```
+ For API details, see [DescribeAssociationExecutions](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeAutomationExecutions` with a CLI
<a name="ssm_example_ssm_DescribeAutomationExecutions_section"></a>
The following code examples show how to use `DescribeAutomationExecutions`.
------
#### [ CLI ]
**AWS CLI**
**To describe an automation execution**
The following `describe-automation-executions` example displays details about an Automation execution.
```
aws ssm describe-automation-executions \
--filters Key=ExecutionId,Values=73c8eef8-f4ee-4a05-820c-e354fEXAMPLE
```
Output:
```
{
"AutomationExecutionMetadataList": [
{
"AutomationExecutionId": "73c8eef8-f4ee-4a05-820c-e354fEXAMPLE",
"DocumentName": "AWS-StartEC2Instance",
"DocumentVersion": "1",
"AutomationExecutionStatus": "Success",
"ExecutionStartTime": 1583737233.748,
"ExecutionEndTime": 1583737234.719,
"ExecutedBy": "arn:aws:sts::29884EXAMPLE:assumed-role/mw_service_role/OrchestrationService",
"LogFile": "",
"Outputs": {},
"Mode": "Auto",
"Targets": [],
"ResolvedTargets": {
"ParameterValues": [],
"Truncated": false
},
"AutomationType": "Local"
}
]
}
```
For more information, see [Running a Simple Automation Workflow](https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-working-executing.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeAutomationExecutions](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-automation-executions.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example describes all active and terminated Automation Executions associated with your account.**
```
Get-SSMAutomationExecutionList
```
**Output:**
```
AutomationExecutionId : 4105a4fc-f944-11e6-9d32-8fb2db27a909
AutomationExecutionStatus : Failed
DocumentName : AWS-UpdateLinuxAmi
DocumentVersion : 1
ExecutedBy : admin
ExecutionEndTime : 2/22/2017 9:17:08 PM
ExecutionStartTime : 2/22/2017 9:17:02 PM
LogFile :
Outputs : {[createImage.ImageId, Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
```
**Example 2: This example displays ExecutionID, document, execution start/end timestamp for executions with AutomationExecutionStatus other than 'Success'**
```
Get-SSMAutomationExecutionList | Where-Object AutomationExecutionStatus -ne "Success" | Select-Object AutomationExecutionId, DocumentName, AutomationExecutionStatus, ExecutionStartTime, ExecutionEndTime | Format-Table -AutoSize
```
**Output:**
```
AutomationExecutionId DocumentName AutomationExecutionStatus ExecutionStartTime ExecutionEndTime
--------------------- ------------ ------------------------- ------------------ ----------------
e1d2bad3-4567-8901-ae23-456c7c8901be AWS-UpdateWindowsAmi Cancelled 4/16/2019 5:37:04 AM 4/16/2019 5:47:29 AM
61234567-a7f8-90e1-2b34-567b8bf9012c Fixed-UpdateAmi Cancelled 4/16/2019 5:33:04 AM 4/16/2019 5:40:15 AM
91234d56-7e89-0ac1-2aee-34ea5d6a7c89 AWS-UpdateWindowsAmi Failed 4/16/2019 5:22:46 AM 4/16/2019 5:27:29 AM
```
+ For API details, see [DescribeAutomationExecutions](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example describes all active and terminated Automation Executions associated with your account.**
```
Get-SSMAutomationExecutionList
```
**Output:**
```
AutomationExecutionId : 4105a4fc-f944-11e6-9d32-8fb2db27a909
AutomationExecutionStatus : Failed
DocumentName : AWS-UpdateLinuxAmi
DocumentVersion : 1
ExecutedBy : admin
ExecutionEndTime : 2/22/2017 9:17:08 PM
ExecutionStartTime : 2/22/2017 9:17:02 PM
LogFile :
Outputs : {[createImage.ImageId, Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
```
**Example 2: This example displays ExecutionID, document, execution start/end timestamp for executions with AutomationExecutionStatus other than 'Success'**
```
Get-SSMAutomationExecutionList | Where-Object AutomationExecutionStatus -ne "Success" | Select-Object AutomationExecutionId, DocumentName, AutomationExecutionStatus, ExecutionStartTime, ExecutionEndTime | Format-Table -AutoSize
```
**Output:**
```
AutomationExecutionId DocumentName AutomationExecutionStatus ExecutionStartTime ExecutionEndTime
--------------------- ------------ ------------------------- ------------------ ----------------
e1d2bad3-4567-8901-ae23-456c7c8901be AWS-UpdateWindowsAmi Cancelled 4/16/2019 5:37:04 AM 4/16/2019 5:47:29 AM
61234567-a7f8-90e1-2b34-567b8bf9012c Fixed-UpdateAmi Cancelled 4/16/2019 5:33:04 AM 4/16/2019 5:40:15 AM
91234d56-7e89-0ac1-2aee-34ea5d6a7c89 AWS-UpdateWindowsAmi Failed 4/16/2019 5:22:46 AM 4/16/2019 5:27:29 AM
```
+ For API details, see [DescribeAutomationExecutions](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeAutomationStepExecutions` with a CLI
<a name="ssm_example_ssm_DescribeAutomationStepExecutions_section"></a>
The following code examples show how to use `DescribeAutomationStepExecutions`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To describe all steps for an automation execution**
The following `describe-automation-step-executions` example displays details about the steps of an Automation execution.
```
aws ssm describe-automation-step-executions \
--automation-execution-id 73c8eef8-f4ee-4a05-820c-e354fEXAMPLE
```
Output:
```
{
"StepExecutions": [
{
"StepName": "startInstances",
"Action": "aws:changeInstanceState",
"ExecutionStartTime": 1583737234.134,
"ExecutionEndTime": 1583737234.672,
"StepStatus": "Success",
"Inputs": {
"DesiredState": "\"running\"",
"InstanceIds": "[\"i-0cb99161f6EXAMPLE\"]"
},
"Outputs": {
"InstanceStates": [
"running"
]
},
"StepExecutionId": "95e70479-cf20-4d80-8018-7e4e2EXAMPLE",
"OverriddenParameters": {}
}
]
}
```
**Example 2: To describe a specific step for an automation execution**
The following `describe-automation-step-executions` example displays details about a specific step of an Automation execution.
```
aws ssm describe-automation-step-executions \
--automation-execution-id 73c8eef8-f4ee-4a05-820c-e354fEXAMPLE \
--filters Key=StepExecutionId,Values=95e70479-cf20-4d80-8018-7e4e2EXAMPLE
```
For more information, see [Running an Automation Workflow Step by Step (Command Line)](https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-working-executing-manually.html#automation-working-executing-manually-commandline) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeAutomationStepExecutions](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-automation-step-executions.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This exmaple displays information about all active and terminated step executions in an Automation workflow.**
```
Get-SSMAutomationStepExecution -AutomationExecutionId e1d2bad3-4567-8901-ae23-456c7c8901be | Select-Object StepName, Action, StepStatus
```
**Output:**
```
StepName Action StepStatus
-------- ------ ----------
LaunchInstance aws:runInstances Success
OSCompatibilityCheck aws:runCommand Success
RunPreUpdateScript aws:runCommand Success
UpdateEC2Config aws:runCommand Cancelled
UpdateSSMAgent aws:runCommand Pending
UpdateAWSPVDriver aws:runCommand Pending
UpdateAWSEnaNetworkDriver aws:runCommand Pending
UpdateAWSNVMe aws:runCommand Pending
InstallWindowsUpdates aws:runCommand Pending
RunPostUpdateScript aws:runCommand Pending
RunSysprepGeneralize aws:runCommand Pending
StopInstance aws:changeInstanceState Pending
CreateImage aws:createImage Pending
TerminateInstance aws:changeInstanceState Pending
```
+ For API details, see [DescribeAutomationStepExecutions](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This exmaple displays information about all active and terminated step executions in an Automation workflow.**
```
Get-SSMAutomationStepExecution -AutomationExecutionId e1d2bad3-4567-8901-ae23-456c7c8901be | Select-Object StepName, Action, StepStatus
```
**Output:**
```
StepName Action StepStatus
-------- ------ ----------
LaunchInstance aws:runInstances Success
OSCompatibilityCheck aws:runCommand Success
RunPreUpdateScript aws:runCommand Success
UpdateEC2Config aws:runCommand Cancelled
UpdateSSMAgent aws:runCommand Pending
UpdateAWSPVDriver aws:runCommand Pending
UpdateAWSEnaNetworkDriver aws:runCommand Pending
UpdateAWSNVMe aws:runCommand Pending
InstallWindowsUpdates aws:runCommand Pending
RunPostUpdateScript aws:runCommand Pending
RunSysprepGeneralize aws:runCommand Pending
StopInstance aws:changeInstanceState Pending
CreateImage aws:createImage Pending
TerminateInstance aws:changeInstanceState Pending
```
+ For API details, see [DescribeAutomationStepExecutions](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeAvailablePatches` with a CLI
<a name="ssm_example_ssm_DescribeAvailablePatches_section"></a>
The following code examples show how to use `DescribeAvailablePatches`.
------
#### [ CLI ]
**AWS CLI**
**To get available patches**
The following `describe-available-patches` example retrieves details about all available patches for Windows Server 2019 that have a MSRC severity of Critical.
```
aws ssm describe-available-patches \
--filters "Key=PRODUCT,Values=WindowsServer2019" "Key=MSRC_SEVERITY,Values=Critical"
```
Output:
```
{
"Patches": [
{
"Id": "fe6bd8c2-3752-4c8b-ab3e-1a7ed08767ba",
"ReleaseDate": 1544047205.0,
"Title": "2018-11 Update for Windows Server 2019 for x64-based Systems (KB4470788)",
"Description": "Install this update to resolve issues in Windows. For a complete listing of the issues that are included in this update, see the associated Microsoft Knowledge Base article for more information. After you install this item, you may have to restart your computer.",
"ContentUrl": "https://support.microsoft.com/en-us/kb/4470788",
"Vendor": "Microsoft",
"ProductFamily": "Windows",
"Product": "WindowsServer2019",
"Classification": "SecurityUpdates",
"MsrcSeverity": "Critical",
"KbNumber": "KB4470788",
"MsrcNumber": "",
"Language": "All"
},
{
"Id": "c96115e1-5587-4115-b851-22baa46a3f11",
"ReleaseDate": 1549994410.0,
"Title": "2019-02 Security Update for Adobe Flash Player for Windows Server 2019 for x64-based Systems (KB4487038)",
"Description": "A security issue has been identified in a Microsoft software product that could affect your system. You can help protect your system by installing this update from Microsoft. For a complete listing of the issues that are included in this update, see the associated Microsoft Knowledge Base article. After you install this update, you may have to restart your system.",
"ContentUrl": "https://support.microsoft.com/en-us/kb/4487038",
"Vendor": "Microsoft",
"ProductFamily": "Windows",
"Product": "WindowsServer2019",
"Classification": "SecurityUpdates",
"MsrcSeverity": "Critical",
"KbNumber": "KB4487038",
"MsrcNumber": "",
"Language": "All"
},
...
]
}
```
**To get details of a specific patch**
The following `describe-available-patches` example retrieves details about the specified patch.
```
aws ssm describe-available-patches \
--filters "Key=PATCH_ID,Values=KB4480979"
```
Output:
```
{
"Patches": [
{
"Id": "680861e3-fb75-432e-818e-d72e5f2be719",
"ReleaseDate": 1546970408.0,
"Title": "2019-01 Security Update for Adobe Flash Player for Windows Server 2016 for x64-based Systems (KB4480979)",
"Description": "A security issue has been identified in a Microsoft software product that could affect your system. You can help protect your system by installing this update from Microsoft. For a complete listing of the issues that are included in this update, see the associated Microsoft Knowledge Base article. After you install this update, you may have to restart your system.",
"ContentUrl": "https://support.microsoft.com/en-us/kb/4480979",
"Vendor": "Microsoft",
"ProductFamily": "Windows",
"Product": "WindowsServer2016",
"Classification": "SecurityUpdates",
"MsrcSeverity": "Critical",
"KbNumber": "KB4480979",
"MsrcNumber": "",
"Language": "All"
}
]
}
```
For more information, see [How Patch Manager Operations Work](https://docs.aws.amazon.com/systems-manager/latest/userguide/patch-manager-how-it-works.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeAvailablePatches](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-available-patches.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example gets all available patches for Windows Server 2012 that have a MSRC severity of Critical. The syntax used by this example requires PowerShell version 3 or later.**
```
$filter1 = @{Key="PRODUCT";Values=@("WindowsServer2012")}
$filter2 = @{Key="MSRC_SEVERITY";Values=@("Critical")}
Get-SSMAvailablePatch -Filter $filter1,$filter2
```
**Output:**
```
Classification : SecurityUpdates
ContentUrl : https://support.microsoft.com/en-us/kb/2727528
Description : A security issue has been identified that could allow an unauthenticated remote attacker to compromise your system and gain control
over it. You can help protect your system by installing this update from Microsoft. After you install this update, you may have to
restart your system.
Id : 1eb507be-2040-4eeb-803d-abc55700b715
KbNumber : KB2727528
Language : All
MsrcNumber : MS12-072
MsrcSeverity : Critical
Product : WindowsServer2012
ProductFamily : Windows
ReleaseDate : 11/13/2012 6:00:00 PM
Title : Security Update for Windows Server 2012 (KB2727528)
Vendor : Microsoft
...
```
**Example 2: With PowerShell version 2, you must use New-Object to create each filter.**
```
$filter1 = New-Object Amazon.SimpleSystemsManagement.Model.PatchOrchestratorFilter
$filter1.Key = "PRODUCT"
$filter1.Values = "WindowsServer2012"
$filter2 = New-Object Amazon.SimpleSystemsManagement.Model.PatchOrchestratorFilter
$filter2.Key = "MSRC_SEVERITY"
$filter2.Values = "Critical"
Get-SSMAvailablePatch -Filter $filter1,$filter2
```
**Example 3: This example fetches all the updates which are released in last 20 days and applicable to products matching WindowsServer2019**
```
Get-SSMAvailablePatch | Where-Object ReleaseDate -ge (Get-Date).AddDays(-20) | Where-Object Product -eq "WindowsServer2019" | Select-Object ReleaseDate, Product, Title
```
**Output:**
```
ReleaseDate Product Title
----------- ------- -----
4/9/2019 5:00:12 PM WindowsServer2019 2019-04 Security Update for Adobe Flash Player for Windows Server 2019 for x64-based Systems (KB4493478)
4/9/2019 5:00:06 PM WindowsServer2019 2019-04 Cumulative Update for Windows Server 2019 for x64-based Systems (KB4493509)
4/2/2019 5:00:06 PM WindowsServer2019 2019-03 Servicing Stack Update for Windows Server 2019 for x64-based Systems (KB4493510)
```
+ For API details, see [DescribeAvailablePatches](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example gets all available patches for Windows Server 2012 that have a MSRC severity of Critical. The syntax used by this example requires PowerShell version 3 or later.**
```
$filter1 = @{Key="PRODUCT";Values=@("WindowsServer2012")}
$filter2 = @{Key="MSRC_SEVERITY";Values=@("Critical")}
Get-SSMAvailablePatch -Filter $filter1,$filter2
```
**Output:**
```
Classification : SecurityUpdates
ContentUrl : https://support.microsoft.com/en-us/kb/2727528
Description : A security issue has been identified that could allow an unauthenticated remote attacker to compromise your system and gain control
over it. You can help protect your system by installing this update from Microsoft. After you install this update, you may have to
restart your system.
Id : 1eb507be-2040-4eeb-803d-abc55700b715
KbNumber : KB2727528
Language : All
MsrcNumber : MS12-072
MsrcSeverity : Critical
Product : WindowsServer2012
ProductFamily : Windows
ReleaseDate : 11/13/2012 6:00:00 PM
Title : Security Update for Windows Server 2012 (KB2727528)
Vendor : Microsoft
...
```
**Example 2: With PowerShell version 2, you must use New-Object to create each filter.**
```
$filter1 = New-Object Amazon.SimpleSystemsManagement.Model.PatchOrchestratorFilter
$filter1.Key = "PRODUCT"
$filter1.Values = "WindowsServer2012"
$filter2 = New-Object Amazon.SimpleSystemsManagement.Model.PatchOrchestratorFilter
$filter2.Key = "MSRC_SEVERITY"
$filter2.Values = "Critical"
Get-SSMAvailablePatch -Filter $filter1,$filter2
```
**Example 3: This example fetches all the updates which are released in last 20 days and applicable to products matching WindowsServer2019**
```
Get-SSMAvailablePatch | Where-Object ReleaseDate -ge (Get-Date).AddDays(-20) | Where-Object Product -eq "WindowsServer2019" | Select-Object ReleaseDate, Product, Title
```
**Output:**
```
ReleaseDate Product Title
----------- ------- -----
4/9/2019 5:00:12 PM WindowsServer2019 2019-04 Security Update for Adobe Flash Player for Windows Server 2019 for x64-based Systems (KB4493478)
4/9/2019 5:00:06 PM WindowsServer2019 2019-04 Cumulative Update for Windows Server 2019 for x64-based Systems (KB4493509)
4/2/2019 5:00:06 PM WindowsServer2019 2019-03 Servicing Stack Update for Windows Server 2019 for x64-based Systems (KB4493510)
```
+ For API details, see [DescribeAvailablePatches](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeDocument` with an AWS SDK or CLI
<a name="ssm_example_ssm_DescribeDocument_section"></a>
The following code examples show how to use `DescribeDocument`.
------
#### [ CLI ]
**AWS CLI**
**To display details of a document**
The following `describe-document` example displays details about a Systems Manager document in your AWS account.
```
aws ssm describe-document \
--name "Example"
```
Output:
```
{
"Document": {
"Hash": "fc2410281f40779e694a8b95975d0f9f316da8a153daa94e3d9921102EXAMPLE",
"HashType": "Sha256",
"Name": "Example",
"Owner": "29884EXAMPLE",
"CreatedDate": 1583257938.266,
"Status": "Active",
"DocumentVersion": "1",
"Description": "Document Example",
"Parameters": [
{
"Name": "AutomationAssumeRole",
"Type": "String",
"Description": "(Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to execute this document.",
"DefaultValue": ""
},
{
"Name": "InstanceId",
"Type": "String",
"Description": "(Required) The ID of the Amazon EC2 instance.",
"DefaultValue": ""
}
],
"PlatformTypes": [
"Windows",
"Linux"
],
"DocumentType": "Automation",
"SchemaVersion": "0.3",
"LatestVersion": "1",
"DefaultVersion": "1",
"DocumentFormat": "YAML",
"Tags": []
}
}
```
For more information, see [Creating Systems Manager Documents](https://docs.aws.amazon.com/systems-manager/latest/userguide/create-ssm-doc.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeDocument](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-document.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example returns information about a document.**
```
Get-SSMDocumentDescription -Name "RunShellScript"
```
**Output:**
```
CreatedDate : 2/24/2017 5:25:13 AM
DefaultVersion : 1
Description : Run an updated script
DocumentType : Command
DocumentVersion : 1
Hash : f775e5df4904c6fa46686c4722fae9de1950dace25cd9608ff8d622046b68d9b
HashType : Sha256
LatestVersion : 1
Name : RunShellScript
Owner : 123456789012
Parameters : {commands}
PlatformTypes : {Linux}
SchemaVersion : 2.0
Sha1 :
Status : Active
```
+ For API details, see [DescribeDocument](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example returns information about a document.**
```
Get-SSMDocumentDescription -Name "RunShellScript"
```
**Output:**
```
CreatedDate : 2/24/2017 5:25:13 AM
DefaultVersion : 1
Description : Run an updated script
DocumentType : Command
DocumentVersion : 1
Hash : f775e5df4904c6fa46686c4722fae9de1950dace25cd9608ff8d622046b68d9b
HashType : Sha256
LatestVersion : 1
Name : RunShellScript
Owner : 123456789012
Parameters : {commands}
PlatformTypes : {Linux}
SchemaVersion : 2.0
Sha1 :
Status : Active
```
+ For API details, see [DescribeDocument](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/ssm#code-examples).
```
TRY.
DATA(lo_result) = lo_ssm->describedocument( iv_name = iv_name ).
DATA(lo_document) = lo_result->get_document( ).
IF lo_document IS BOUND.
rv_status = lo_document->get_status( ).
MESSAGE |Document status: { rv_status }| TYPE 'I'.
ENDIF.
CATCH /aws1/cx_ssminvaliddocument.
MESSAGE 'Invalid document.' TYPE 'I'.
ENDTRY.
```
+ For API details, see [DescribeDocument](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------
# Use `DescribeDocumentPermission` with a CLI
<a name="ssm_example_ssm_DescribeDocumentPermission_section"></a>
The following code examples show how to use `DescribeDocumentPermission`.
------
#### [ CLI ]
**AWS CLI**
**To describe document permissions**
The following `describe-document-permission` example displays permission details about a Systems Manager document that is shared publicly.
```
aws ssm describe-document-permission \
--name "Example" \
--permission-type "Share"
```
Output:
```
{
"AccountIds": [
"all"
],
"AccountSharingInfoList": [
{
"AccountId": "all",
"SharedDocumentVersion": "$DEFAULT"
}
]
}
```
For more information, see [Share a Systems Manager Document](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-how-to-share.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeDocumentPermission](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-document-permission.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists all the versions for a document.**
```
Get-SSMDocumentVersionList -Name "RunShellScript"
```
**Output:**
```
CreatedDate DocumentVersion IsDefaultVersion Name
----------- --------------- ---------------- ----
2/24/2017 5:25:13 AM 1 True RunShellScript
```
+ For API details, see [DescribeDocumentPermission](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists all the versions for a document.**
```
Get-SSMDocumentVersionList -Name "RunShellScript"
```
**Output:**
```
CreatedDate DocumentVersion IsDefaultVersion Name
----------- --------------- ---------------- ----
2/24/2017 5:25:13 AM 1 True RunShellScript
```
+ For API details, see [DescribeDocumentPermission](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeEffectiveInstanceAssociations` with a CLI
<a name="ssm_example_ssm_DescribeEffectiveInstanceAssociations_section"></a>
The following code examples show how to use `DescribeEffectiveInstanceAssociations`.
------
#### [ CLI ]
**AWS CLI**
**To get details of the effective associations for an instance**
The following `describe-effective-instance-associations` example retrieves details about the effective associations for an instance.
Command:
```
aws ssm describe-effective-instance-associations --instance-id "i-1234567890abcdef0"
```
Output:
```
{
"Associations": [
{
"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",
"AssociationVersion": "1"
}
]
}
```
+ For API details, see [DescribeEffectiveInstanceAssociations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-effective-instance-associations.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example describes the effective associations for an instance.**
```
Get-SSMEffectiveInstanceAssociationList -InstanceId "i-0000293ffd8c57862" -MaxResult 5
```
**Output:**
```
AssociationId Content
------------- -------
d8617c07-2079-4c18-9847-1655fc2698b0 {...
```
**Example 2: This example displays the contents of the effective associations for an instance.**
```
(Get-SSMEffectiveInstanceAssociationList -InstanceId "i-0000293ffd8c57862" -MaxResult 5).Content
```
**Output:**
```
{
"schemaVersion": "1.2",
"description": "Update the Amazon SSM Agent to the latest version or specified version.",
"parameters": {
"version": {
"default": "",
"description": "(Optional) A specific version of the Amazon SSM Agent to install. If not specified, the agen
t will be updated to the latest version.",
"type": "String"
},
"allowDowngrade": {
"default": "false",
"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.",
"type": "String",
"allowedValues": [
"true",
"false"
]
}
},
"runtimeConfig": {
"aws:updateSsmAgent": {
"properties": [
{
"agentName": "amazon-ssm-agent",
"source": "https://s3.{Region}.amazonaws.com/amazon-ssm-{Region}/ssm-agent-manifest.json",
"allowDowngrade": "{{ allowDowngrade }}",
"targetVersion": "{{ version }}"
}
]
}
}
}
```
+ For API details, see [DescribeEffectiveInstanceAssociations](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example describes the effective associations for an instance.**
```
Get-SSMEffectiveInstanceAssociationList -InstanceId "i-0000293ffd8c57862" -MaxResult 5
```
**Output:**
```
AssociationId Content
------------- -------
d8617c07-2079-4c18-9847-1655fc2698b0 {...
```
**Example 2: This example displays the contents of the effective associations for an instance.**
```
(Get-SSMEffectiveInstanceAssociationList -InstanceId "i-0000293ffd8c57862" -MaxResult 5).Content
```
**Output:**
```
{
"schemaVersion": "1.2",
"description": "Update the Amazon SSM Agent to the latest version or specified version.",
"parameters": {
"version": {
"default": "",
"description": "(Optional) A specific version of the Amazon SSM Agent to install. If not specified, the agen
t will be updated to the latest version.",
"type": "String"
},
"allowDowngrade": {
"default": "false",
"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.",
"type": "String",
"allowedValues": [
"true",
"false"
]
}
},
"runtimeConfig": {
"aws:updateSsmAgent": {
"properties": [
{
"agentName": "amazon-ssm-agent",
"source": "https://s3.{Region}.amazonaws.com/amazon-ssm-{Region}/ssm-agent-manifest.json",
"allowDowngrade": "{{ allowDowngrade }}",
"targetVersion": "{{ version }}"
}
]
}
}
}
```
+ For API details, see [DescribeEffectiveInstanceAssociations](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeEffectivePatchesForPatchBaseline` with a CLI
<a name="ssm_example_ssm_DescribeEffectivePatchesForPatchBaseline_section"></a>
The following code examples show how to use `DescribeEffectivePatchesForPatchBaseline`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To get all patches defined by a custom patch baseline**
The following `describe-effective-patches-for-patch-baseline` example returns the patches defined by a custom patch baseline in the current AWS account. Note that for a custom baseline, only the ID is required for `--baseline-id`.
```
aws ssm describe-effective-patches-for-patch-baseline \
--baseline-id "pb-08b654cf9b9681f04"
```
Output:
```
{
"EffectivePatches": [
{
"Patch": {
"Id": "fe6bd8c2-3752-4c8b-ab3e-1a7ed08767ba",
"ReleaseDate": 1544047205.0,
"Title": "2018-11 Update for Windows Server 2019 for x64-based Systems (KB4470788)",
"Description": "Install this update to resolve issues in Windows. For a complete listing of the issues that are included in this update, see the associated Microsoft Knowledge Base article for more information. After you install this item, you may have to restart your computer.",
"ContentUrl": "https://support.microsoft.com/en-us/kb/4470788",
"Vendor": "Microsoft",
"ProductFamily": "Windows",
"Product": "WindowsServer2019",
"Classification": "SecurityUpdates",
"MsrcSeverity": "Critical",
"KbNumber": "KB4470788",
"MsrcNumber": "",
"Language": "All"
},
"PatchStatus": {
"DeploymentStatus": "APPROVED",
"ComplianceLevel": "CRITICAL",
"ApprovalDate": 1544047205.0
}
},
{
"Patch": {
"Id": "915a6b1a-f556-4d83-8f50-b2e75a9a7e58",
"ReleaseDate": 1549994400.0,
"Title": "2019-02 Cumulative Update for .NET Framework 3.5 and 4.7.2 for Windows Server 2019 for x64 (KB4483452)",
"Description": "A security issue has been identified in a Microsoft software product that could affect your system. You can help protect your system by installing this update from Microsoft. For a complete listing of the issues that are included in this update, see the associated Microsoft Knowledge Base article. After you install this update, you may have to restart your system.",
"ContentUrl": "https://support.microsoft.com/en-us/kb/4483452",
"Vendor": "Microsoft",
"ProductFamily": "Windows",
"Product": "WindowsServer2019",
"Classification": "SecurityUpdates",
"MsrcSeverity": "Important",
"KbNumber": "KB4483452",
"MsrcNumber": "",
"Language": "All"
},
"PatchStatus": {
"DeploymentStatus": "APPROVED",
"ComplianceLevel": "CRITICAL",
"ApprovalDate": 1549994400.0
}
},
...
],
"NextToken": "--token string truncated--"
}
```
**Example 2: To get all patches defined by an AWS managed patch baseline**
The following `describe-effective-patches-for-patch-baseline` example returns the patches defined by an AWS managed patch baseline. Note that for an AWS managed baseline, the complete baseline ARN is required for `--baseline-id`
```
aws ssm describe-effective-patches-for-patch-baseline \
--baseline-id "arn:aws:ssm:us-east-2:733109147000:patchbaseline/pb-020d361a05defe4ed"
```
See example 1 for sample output.
For more information, see [How Security Patches Are Selected](https://docs.aws.amazon.com/systems-manager/latest/userguide/patch-manager-how-it-works-selection.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeEffectivePatchesForPatchBaseline](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-effective-patches-for-patch-baseline.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists all patch baselines, with a maximum result list of 1.**
```
Get-SSMEffectivePatchesForPatchBaseline -BaselineId "pb-0a2f1059b670ebd31" -MaxResult 1
```
**Output:**
```
Patch PatchStatus
----- -----------
Amazon.SimpleSystemsManagement.Model.Patch Amazon.SimpleSystemsManagement.Model.PatchStatus
```
**Example 2: This example displays the patch status for all patch baselines, with a maximum result list of 1.**
```
(Get-SSMEffectivePatchesForPatchBaseline -BaselineId "pb-0a2f1059b670ebd31" -MaxResult 1).PatchStatus
```
**Output:**
```
ApprovalDate DeploymentStatus
------------ ----------------
12/21/2010 6:00:00 PM APPROVED
```
+ For API details, see [DescribeEffectivePatchesForPatchBaseline](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists all patch baselines, with a maximum result list of 1.**
```
Get-SSMEffectivePatchesForPatchBaseline -BaselineId "pb-0a2f1059b670ebd31" -MaxResult 1
```
**Output:**
```
Patch PatchStatus
----- -----------
Amazon.SimpleSystemsManagement.Model.Patch Amazon.SimpleSystemsManagement.Model.PatchStatus
```
**Example 2: This example displays the patch status for all patch baselines, with a maximum result list of 1.**
```
(Get-SSMEffectivePatchesForPatchBaseline -BaselineId "pb-0a2f1059b670ebd31" -MaxResult 1).PatchStatus
```
**Output:**
```
ApprovalDate DeploymentStatus
------------ ----------------
12/21/2010 6:00:00 PM APPROVED
```
+ For API details, see [DescribeEffectivePatchesForPatchBaseline](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeInstanceAssociationsStatus` with a CLI
<a name="ssm_example_ssm_DescribeInstanceAssociationsStatus_section"></a>
The following code examples show how to use `DescribeInstanceAssociationsStatus`.
------
#### [ CLI ]
**AWS CLI**
**To describe the status of an instance's associations**
This example shows details of the associations for an instance.
Command:
```
aws ssm describe-instance-associations-status --instance-id "i-1234567890abcdef0"
```
Output:
```
{
"InstanceAssociationStatusInfos": [
{
"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",
"DocumentVersion": "1",
"AssociationVersion": "1",
"InstanceId": "i-1234567890abcdef0",
"ExecutionDate": 1550505828.548,
"Status": "Success",
"DetailedStatus": "Success",
"AssociationName": "UpdateSSMAgent"
}
]
}
```
+ For API details, see [DescribeInstanceAssociationsStatus](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-instance-associations-status.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example shows details of the associations for an instance.**
```
Get-SSMInstanceAssociationsStatus -InstanceId "i-0000293ffd8c57862"
```
**Output:**
```
AssociationId : d8617c07-2079-4c18-9847-1655fc2698b0
DetailedStatus : Pending
DocumentVersion : 1
ErrorCode :
ExecutionDate : 2/20/2015 8:31:11 AM
ExecutionSummary : temp_status_change
InstanceId : i-0000293ffd8c57862
Name : AWS-UpdateSSMAgent
OutputUrl :
Status : Pending
```
**Example 2: This example checks the instance association status for the given instance id and further, displays the execution status of those associations**
```
Get-SSMInstanceAssociationsStatus -InstanceId i-012e3cb4df567e8aa | ForEach-Object {Get-SSMAssociationExecution -AssociationId .AssociationId}
```
**Output:**
```
AssociationId : 512a34a5-c678-1234-1234-12345678db9e
AssociationVersion : 2
CreatedTime : 3/2/2019 8:53:29 AM
DetailedStatus :
ExecutionId : 512a34a5-c678-1234-1234-12345678db9e
LastExecutionDate : 1/1/0001 12:00:00 AM
ResourceCountByStatus : {Success=9}
Status : Success
```
+ For API details, see [DescribeInstanceAssociationsStatus](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example shows details of the associations for an instance.**
```
Get-SSMInstanceAssociationsStatus -InstanceId "i-0000293ffd8c57862"
```
**Output:**
```
AssociationId : d8617c07-2079-4c18-9847-1655fc2698b0
DetailedStatus : Pending
DocumentVersion : 1
ErrorCode :
ExecutionDate : 2/20/2015 8:31:11 AM
ExecutionSummary : temp_status_change
InstanceId : i-0000293ffd8c57862
Name : AWS-UpdateSSMAgent
OutputUrl :
Status : Pending
```
**Example 2: This example checks the instance association status for the given instance id and further, displays the execution status of those associations**
```
Get-SSMInstanceAssociationsStatus -InstanceId i-012e3cb4df567e8aa | ForEach-Object {Get-SSMAssociationExecution -AssociationId .AssociationId}
```
**Output:**
```
AssociationId : 512a34a5-c678-1234-1234-12345678db9e
AssociationVersion : 2
CreatedTime : 3/2/2019 8:53:29 AM
DetailedStatus :
ExecutionId : 512a34a5-c678-1234-1234-12345678db9e
LastExecutionDate : 1/1/0001 12:00:00 AM
ResourceCountByStatus : {Success=9}
Status : Success
```
+ For API details, see [DescribeInstanceAssociationsStatus](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeInstanceInformation` with a CLI
<a name="ssm_example_ssm_DescribeInstanceInformation_section"></a>
The following code examples show how to use `DescribeInstanceInformation`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To describe managed instance information**
The following `describe-instance-information` example retrieves details of each of your managed instances.
```
aws ssm describe-instance-information
```
**Example 2: To describe information about a specific managed instance**
The following `describe-instance-information` example shows details of the managed instance `i-028ea792daEXAMPLE`.
```
aws ssm describe-instance-information \
--filters "Key=InstanceIds,Values=i-028ea792daEXAMPLE"
```
**Example 3: To describe information about managed instances with a specific tag key**
The following `describe-instance-information` example shows details for managed instances that have the tag key `DEV`.
```
aws ssm describe-instance-information \
--filters "Key=tag-key,Values=DEV"
```
Output:
```
{
"InstanceInformationList": [
{
"InstanceId": "i-028ea792daEXAMPLE",
"PingStatus": "Online",
"LastPingDateTime": 1582221233.421,
"AgentVersion": "2.3.842.0",
"IsLatestVersion": true,
"PlatformType": "Linux",
"PlatformName": "SLES",
"PlatformVersion": "15.1",
"ResourceType": "EC2Instance",
"IPAddress": "192.0.2.0",
"ComputerName": "ip-198.51.100.0.us-east-2.compute.internal",
"AssociationStatus": "Success",
"LastAssociationExecutionDate": 1582220806.0,
"LastSuccessfulAssociationExecutionDate": 1582220806.0,
"AssociationOverview": {
"DetailedStatus": "Success",
"InstanceAssociationStatusAggregatedCount": {
"Success": 2
}
}
}
]
}
```
For more information, see [Managed Instances](https://docs.aws.amazon.com/systems-manager/latest/userguide/managed_instances.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeInstanceInformation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-instance-information.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example shows details of each of your instances.**
```
Get-SSMInstanceInformation
```
**Output:**
```
ActivationId :
AgentVersion : 2.0.672.0
AssociationOverview : Amazon.SimpleSystemsManagement.Model.InstanceAggregatedAssociationOverview
AssociationStatus : Success
ComputerName : ip-172-31-44-222.us-west-2.compute.internal
IamRole :
InstanceId : i-0cb2b964d3e14fd9f
IPAddress : 172.31.44.222
IsLatestVersion : True
LastAssociationExecutionDate : 2/24/2017 3:18:09 AM
LastPingDateTime : 2/24/2017 3:35:03 AM
LastSuccessfulAssociationExecutionDate : 2/24/2017 3:18:09 AM
Name :
PingStatus : ConnectionLost
PlatformName : Amazon Linux AMI
PlatformType : Linux
PlatformVersion : 2016.09
RegistrationDate : 1/1/0001 12:00:00 AM
ResourceType : EC2Instance
```
**Example 2: This example shows how to use the -Filter parameter to filter results to only those AWS Systems Manager instances in region `us-east-1` with an `AgentVersion` of `2.2.800.0`. You can find a list of valid -Filter key values in the InstanceInformation API reference topic (https://docs.aws.amazon.com/systems-manager/latest/APIReference/API\$1InstanceInformation.html\$1systemsmanager-Type-InstanceInformation-ActivationId).**
```
$Filters = @{
Key="AgentVersion"
Values="2.2.800.0"
}
Get-SSMInstanceInformation -Region us-east-1 -Filter $Filters
```
**Output:**
```
ActivationId :
AgentVersion : 2.2.800.0
AssociationOverview : Amazon.SimpleSystemsManagement.Model.InstanceAggregatedAssociationOverview
AssociationStatus : Success
ComputerName : EXAMPLE-EXAMPLE.WORKGROUP
IamRole :
InstanceId : i-EXAMPLEb0792d98ce
IPAddress : 10.0.0.01
IsLatestVersion : False
LastAssociationExecutionDate : 8/16/2018 12:02:50 AM
LastPingDateTime : 8/16/2018 7:40:27 PM
LastSuccessfulAssociationExecutionDate : 8/16/2018 12:02:50 AM
Name :
PingStatus : Online
PlatformName : Microsoft Windows Server 2016 Datacenter
PlatformType : Windows
PlatformVersion : 10.0.14393
RegistrationDate : 1/1/0001 12:00:00 AM
ResourceType : EC2Instance
ActivationId :
AgentVersion : 2.2.800.0
AssociationOverview : Amazon.SimpleSystemsManagement.Model.InstanceAggregatedAssociationOverview
AssociationStatus : Success
ComputerName : EXAMPLE-EXAMPLE.WORKGROUP
IamRole :
InstanceId : i-EXAMPLEac7501d023
IPAddress : 10.0.0.02
IsLatestVersion : False
LastAssociationExecutionDate : 8/16/2018 12:00:20 AM
LastPingDateTime : 8/16/2018 7:40:35 PM
LastSuccessfulAssociationExecutionDate : 8/16/2018 12:00:20 AM
Name :
PingStatus : Online
PlatformName : Microsoft Windows Server 2016 Datacenter
PlatformType : Windows
PlatformVersion : 10.0.14393
RegistrationDate : 1/1/0001 12:00:00 AM
ResourceType : EC2Instance
```
**Example 3: This example shows how to use the -InstanceInformationFilterList parameter to filter results to only those AWS Systems Manager instances in region `us-east-1` with `PlatformTypes` of `Windows` or `Linux`. You can find a list of valid -InstanceInformationFilterList key values in the InstanceInformationFilter API reference topic (https://docs.aws.amazon.com/systems-manager/latest/APIReference/API\$1InstanceInformationFilter.html).**
```
$Filters = @{
Key="PlatformTypes"
ValueSet=("Windows","Linux")
}
Get-SSMInstanceInformation -Region us-east-1 -InstanceInformationFilterList $Filters
```
**Output:**
```
ActivationId :
AgentVersion : 2.2.800.0
AssociationOverview : Amazon.SimpleSystemsManagement.Model.InstanceAggregatedAssociationOverview
AssociationStatus : Success
ComputerName : EXAMPLE-EXAMPLE.WORKGROUP
IamRole :
InstanceId : i-EXAMPLEb0792d98ce
IPAddress : 10.0.0.27
IsLatestVersion : False
LastAssociationExecutionDate : 8/16/2018 12:02:50 AM
LastPingDateTime : 8/16/2018 7:40:27 PM
LastSuccessfulAssociationExecutionDate : 8/16/2018 12:02:50 AM
Name :
PingStatus : Online
PlatformName : Ubuntu Server 18.04 LTS
PlatformType : Linux
PlatformVersion : 18.04
RegistrationDate : 1/1/0001 12:00:00 AM
ResourceType : EC2Instance
ActivationId :
AgentVersion : 2.2.800.0
AssociationOverview : Amazon.SimpleSystemsManagement.Model.InstanceAggregatedAssociationOverview
AssociationStatus : Success
ComputerName : EXAMPLE-EXAMPLE.WORKGROUP
IamRole :
InstanceId : i-EXAMPLEac7501d023
IPAddress : 10.0.0.100
IsLatestVersion : False
LastAssociationExecutionDate : 8/16/2018 12:00:20 AM
LastPingDateTime : 8/16/2018 7:40:35 PM
LastSuccessfulAssociationExecutionDate : 8/16/2018 12:00:20 AM
Name :
PingStatus : Online
PlatformName : Microsoft Windows Server 2016 Datacenter
PlatformType : Windows
PlatformVersion : 10.0.14393
RegistrationDate : 1/1/0001 12:00:00 AM
ResourceType : EC2Instance
```
**Example 4: This example lists ssm managed instances and exports InstanceId, PingStatus, LastPingDateTime and PlatformName to a csv file.**
```
Get-SSMInstanceInformation | Select-Object InstanceId, PingStatus, LastPingDateTime, PlatformName | Export-Csv Instance-details.csv -NoTypeInformation
```
+ For API details, see [DescribeInstanceInformation](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example shows details of each of your instances.**
```
Get-SSMInstanceInformation
```
**Output:**
```
ActivationId :
AgentVersion : 2.0.672.0
AssociationOverview : Amazon.SimpleSystemsManagement.Model.InstanceAggregatedAssociationOverview
AssociationStatus : Success
ComputerName : ip-172-31-44-222.us-west-2.compute.internal
IamRole :
InstanceId : i-0cb2b964d3e14fd9f
IPAddress : 172.31.44.222
IsLatestVersion : True
LastAssociationExecutionDate : 2/24/2017 3:18:09 AM
LastPingDateTime : 2/24/2017 3:35:03 AM
LastSuccessfulAssociationExecutionDate : 2/24/2017 3:18:09 AM
Name :
PingStatus : ConnectionLost
PlatformName : Amazon Linux AMI
PlatformType : Linux
PlatformVersion : 2016.09
RegistrationDate : 1/1/0001 12:00:00 AM
ResourceType : EC2Instance
```
**Example 2: This example shows how to use the -Filter parameter to filter results to only those AWS Systems Manager instances in region `us-east-1` with an `AgentVersion` of `2.2.800.0`. You can find a list of valid -Filter key values in the InstanceInformation API reference topic (https://docs.aws.amazon.com/systems-manager/latest/APIReference/API\$1InstanceInformation.html\$1systemsmanager-Type-InstanceInformation-ActivationId).**
```
$Filters = @{
Key="AgentVersion"
Values="2.2.800.0"
}
Get-SSMInstanceInformation -Region us-east-1 -Filter $Filters
```
**Output:**
```
ActivationId :
AgentVersion : 2.2.800.0
AssociationOverview : Amazon.SimpleSystemsManagement.Model.InstanceAggregatedAssociationOverview
AssociationStatus : Success
ComputerName : EXAMPLE-EXAMPLE.WORKGROUP
IamRole :
InstanceId : i-EXAMPLEb0792d98ce
IPAddress : 10.0.0.01
IsLatestVersion : False
LastAssociationExecutionDate : 8/16/2018 12:02:50 AM
LastPingDateTime : 8/16/2018 7:40:27 PM
LastSuccessfulAssociationExecutionDate : 8/16/2018 12:02:50 AM
Name :
PingStatus : Online
PlatformName : Microsoft Windows Server 2016 Datacenter
PlatformType : Windows
PlatformVersion : 10.0.14393
RegistrationDate : 1/1/0001 12:00:00 AM
ResourceType : EC2Instance
ActivationId :
AgentVersion : 2.2.800.0
AssociationOverview : Amazon.SimpleSystemsManagement.Model.InstanceAggregatedAssociationOverview
AssociationStatus : Success
ComputerName : EXAMPLE-EXAMPLE.WORKGROUP
IamRole :
InstanceId : i-EXAMPLEac7501d023
IPAddress : 10.0.0.02
IsLatestVersion : False
LastAssociationExecutionDate : 8/16/2018 12:00:20 AM
LastPingDateTime : 8/16/2018 7:40:35 PM
LastSuccessfulAssociationExecutionDate : 8/16/2018 12:00:20 AM
Name :
PingStatus : Online
PlatformName : Microsoft Windows Server 2016 Datacenter
PlatformType : Windows
PlatformVersion : 10.0.14393
RegistrationDate : 1/1/0001 12:00:00 AM
ResourceType : EC2Instance
```
**Example 3: This example shows how to use the -InstanceInformationFilterList parameter to filter results to only those AWS Systems Manager instances in region `us-east-1` with `PlatformTypes` of `Windows` or `Linux`. You can find a list of valid -InstanceInformationFilterList key values in the InstanceInformationFilter API reference topic (https://docs.aws.amazon.com/systems-manager/latest/APIReference/API\$1InstanceInformationFilter.html).**
```
$Filters = @{
Key="PlatformTypes"
ValueSet=("Windows","Linux")
}
Get-SSMInstanceInformation -Region us-east-1 -InstanceInformationFilterList $Filters
```
**Output:**
```
ActivationId :
AgentVersion : 2.2.800.0
AssociationOverview : Amazon.SimpleSystemsManagement.Model.InstanceAggregatedAssociationOverview
AssociationStatus : Success
ComputerName : EXAMPLE-EXAMPLE.WORKGROUP
IamRole :
InstanceId : i-EXAMPLEb0792d98ce
IPAddress : 10.0.0.27
IsLatestVersion : False
LastAssociationExecutionDate : 8/16/2018 12:02:50 AM
LastPingDateTime : 8/16/2018 7:40:27 PM
LastSuccessfulAssociationExecutionDate : 8/16/2018 12:02:50 AM
Name :
PingStatus : Online
PlatformName : Ubuntu Server 18.04 LTS
PlatformType : Linux
PlatformVersion : 18.04
RegistrationDate : 1/1/0001 12:00:00 AM
ResourceType : EC2Instance
ActivationId :
AgentVersion : 2.2.800.0
AssociationOverview : Amazon.SimpleSystemsManagement.Model.InstanceAggregatedAssociationOverview
AssociationStatus : Success
ComputerName : EXAMPLE-EXAMPLE.WORKGROUP
IamRole :
InstanceId : i-EXAMPLEac7501d023
IPAddress : 10.0.0.100
IsLatestVersion : False
LastAssociationExecutionDate : 8/16/2018 12:00:20 AM
LastPingDateTime : 8/16/2018 7:40:35 PM
LastSuccessfulAssociationExecutionDate : 8/16/2018 12:00:20 AM
Name :
PingStatus : Online
PlatformName : Microsoft Windows Server 2016 Datacenter
PlatformType : Windows
PlatformVersion : 10.0.14393
RegistrationDate : 1/1/0001 12:00:00 AM
ResourceType : EC2Instance
```
**Example 4: This example lists ssm managed instances and exports InstanceId, PingStatus, LastPingDateTime and PlatformName to a csv file.**
```
Get-SSMInstanceInformation | Select-Object InstanceId, PingStatus, LastPingDateTime, PlatformName | Export-Csv Instance-details.csv -NoTypeInformation
```
+ For API details, see [DescribeInstanceInformation](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeInstancePatchStates` with a CLI
<a name="ssm_example_ssm_DescribeInstancePatchStates_section"></a>
The following code examples show how to use `DescribeInstancePatchStates`.
------
#### [ CLI ]
**AWS CLI**
**To get the patch summary states for instances**
This `describe-instance-patch-states` example gets the patch summary states for an instance.
```
aws ssm describe-instance-patch-states \
--instance-ids "i-1234567890abcdef0"
```
Output:
```
{
"InstancePatchStates": [
{
"InstanceId": "i-1234567890abcdef0",
"PatchGroup": "my-patch-group",
"BaselineId": "pb-0713accee01234567",
"SnapshotId": "521c3536-930c-4aa9-950e-01234567abcd",
"CriticalNonCompliantCount": 2,
"SecurityNonCompliantCount": 2,
"OtherNonCompliantCount": 1,
"InstalledCount": 123,
"InstalledOtherCount": 334,
"InstalledPendingRebootCount": 0,
"InstalledRejectedCount": 0,
"MissingCount": 1,
"FailedCount": 2,
"UnreportedNotApplicableCount": 11,
"NotApplicableCount": 2063,
"OperationStartTime": "2021-05-03T11:00:56-07:00",
"OperationEndTime": "2021-05-03T11:01:09-07:00",
"Operation": "Scan",
"LastNoRebootInstallOperationTime": "2020-06-14T12:17:41-07:00",
"RebootOption": "RebootIfNeeded"
}
]
}
```
For more information, see [About Patch Compliance](https://docs.aws.amazon.com/systems-manager/latest/userguide/about-patch-compliance.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeInstancePatchStates](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-instance-patch-states.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example gets the patch summary states for an instance.**
```
Get-SSMInstancePatchState -InstanceId "i-08ee91c0b17045407"
```
**Example 2: This example gets the patch summary states for two instances.**
```
Get-SSMInstancePatchState -InstanceId "i-08ee91c0b17045407","i-09a618aec652973a9"
```
+ For API details, see [DescribeInstancePatchStates](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example gets the patch summary states for an instance.**
```
Get-SSMInstancePatchState -InstanceId "i-08ee91c0b17045407"
```
**Example 2: This example gets the patch summary states for two instances.**
```
Get-SSMInstancePatchState -InstanceId "i-08ee91c0b17045407","i-09a618aec652973a9"
```
+ For API details, see [DescribeInstancePatchStates](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeInstancePatchStatesForPatchGroup` with a CLI
<a name="ssm_example_ssm_DescribeInstancePatchStatesForPatchGroup_section"></a>
The following code examples show how to use `DescribeInstancePatchStatesForPatchGroup`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To get the instance states for a patch group**
The following `describe-instance-patch-states-for-patch-group` example retrieves details about the patch summary states per-instance for the specified patch group.
```
aws ssm describe-instance-patch-states-for-patch-group \
--patch-group "Production"
```
Output:
```
{
"InstancePatchStates": [
{
"InstanceId": "i-02573cafcfEXAMPLE",
"PatchGroup": "Production",
"BaselineId": "pb-0c10e65780EXAMPLE",
"SnapshotId": "a3f5ff34-9bc4-4d2c-a665-4d1c1EXAMPLE",
"OwnerInformation": "",
"InstalledCount": 32,
"InstalledOtherCount": 1,
"InstalledPendingRebootCount": 0,
"InstalledRejectedCount": 0,
"MissingCount": 2,
"FailedCount": 0,
"UnreportedNotApplicableCount": 2671,
"NotApplicableCount": 400,
"OperationStartTime": "2021-08-04T11:03:50.590000-07:00",
"OperationEndTime": "2021-08-04T11:04:21.555000-07:00",
"Operation": "Scan",
"RebootOption": "NoReboot",
"CriticalNonCompliantCount": 0,
"SecurityNonCompliantCount": 1,
"OtherNonCompliantCount": 0
},
{
"InstanceId": "i-0471e04240EXAMPLE",
"PatchGroup": "Production",
"BaselineId": "pb-09ca3fb51fEXAMPLE",
"SnapshotId": "05d8ffb0-1bbe-4812-ba2d-d9b7bEXAMPLE",
"OwnerInformation": "",
"InstalledCount": 32,
"InstalledOtherCount": 1,
"InstalledPendingRebootCount": 0,
"InstalledRejectedCount": 0,
"MissingCount": 2,
"FailedCount": 0,
"UnreportedNotApplicableCount": 2671,
"NotApplicableCount": 400,
"OperationStartTime": "2021-08-04T22:06:20.340000-07:00",
"OperationEndTime": "2021-08-04T22:07:11.220000-07:00",
"Operation": "Scan",
"RebootOption": "NoReboot",
"CriticalNonCompliantCount": 0,
"SecurityNonCompliantCount": 1,
"OtherNonCompliantCount": 0
}
]
}
```
**Example 2: To get the instance states for a patch group with more than five missing patches**
The following `describe-instance-patch-states-for-patch-group` example retrieves details about the patch summary states for the specified patch group for instances with more than five missing patches.
```
aws ssm describe-instance-patch-states-for-patch-group \
--filters Key=MissingCount,Type=GreaterThan,Values=5 \
--patch-group "Production"
```
Output:
```
{
"InstancePatchStates": [
{
"InstanceId": "i-02573cafcfEXAMPLE",
"PatchGroup": "Production",
"BaselineId": "pb-0c10e65780EXAMPLE",
"SnapshotId": "a3f5ff34-9bc4-4d2c-a665-4d1c1EXAMPLE",
"OwnerInformation": "",
"InstalledCount": 46,
"InstalledOtherCount": 4,
"InstalledPendingRebootCount": 1,
"InstalledRejectedCount": 1,
"MissingCount": 7,
"FailedCount": 0,
"UnreportedNotApplicableCount": 232,
"NotApplicableCount": 654,
"OperationStartTime": "2021-08-04T11:03:50.590000-07:00",
"OperationEndTime": "2021-08-04T11:04:21.555000-07:00",
"Operation": "Scan",
"RebootOption": "NoReboot",
"CriticalNonCompliantCount": 0,
"SecurityNonCompliantCount": 1,
"OtherNonCompliantCount": 1
}
]
}
```
**Example 3: To get the instance states for a patch group with fewer than ten instances that require a reboot**
The following `describe-instance-patch-states-for-patch-group` example retrieves details about the patch summary states for the specified patch group for instances with fewer than ten instances requiring a reboot.
```
aws ssm describe-instance-patch-states-for-patch-group \
--filters Key=InstalledPendingRebootCount,Type=LessThan,Values=10 \
--patch-group "Production"
```
Output:
```
{
"InstancePatchStates": [
{
"InstanceId": "i-02573cafcfEXAMPLE",
"BaselineId": "pb-0c10e65780EXAMPLE",
"SnapshotId": "a3f5ff34-9bc4-4d2c-a665-4d1c1EXAMPLE",
"PatchGroup": "Production",
"OwnerInformation": "",
"InstalledCount": 32,
"InstalledOtherCount": 1,
"InstalledPendingRebootCount": 4,
"InstalledRejectedCount": 0,
"MissingCount": 2,
"FailedCount": 0,
"UnreportedNotApplicableCount": 846,
"NotApplicableCount": 212,
"OperationStartTime": "2021-08-046T11:03:50.590000-07:00",
"OperationEndTime": "2021-08-06T11:04:21.555000-07:00",
"Operation": "Scan",
"RebootOption": "NoReboot",
"CriticalNonCompliantCount": 0,
"SecurityNonCompliantCount": 1,
"OtherNonCompliantCount": 0
}
]
}
```
For more information, see [Understanding patch compliance state values](https://docs.aws.amazon.com/systems-manager/latest/userguide/about-patch-compliance-states.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeInstancePatchStatesForPatchGroup](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-instance-patch-states-for-patch-group.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example gets the patch summary states per-instance for a patch group.**
```
Get-SSMInstancePatchStatesForPatchGroup -PatchGroup "Production"
```
+ For API details, see [DescribeInstancePatchStatesForPatchGroup](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example gets the patch summary states per-instance for a patch group.**
```
Get-SSMInstancePatchStatesForPatchGroup -PatchGroup "Production"
```
+ For API details, see [DescribeInstancePatchStatesForPatchGroup](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeInstancePatches` with a CLI
<a name="ssm_example_ssm_DescribeInstancePatches_section"></a>
The following code examples show how to use `DescribeInstancePatches`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To get the patch state details for an instance**
The following `describe-instance-patches` example retrieves details about the patches for the specified instance.
```
aws ssm describe-instance-patches \
--instance-id "i-1234567890abcdef0"
```
Output:
```
{
"Patches": [
{
"Title": "2019-01 Security Update for Adobe Flash Player for Windows Server 2016 for x64-based Systems (KB4480979)",
"KBId": "KB4480979",
"Classification": "SecurityUpdates",
"Severity": "Critical",
"State": "Installed",
"InstalledTime": "2019-01-09T00:00:00+00:00"
},
{
"Title": "",
"KBId": "KB4481031",
"Classification": "",
"Severity": "",
"State": "InstalledOther",
"InstalledTime": "2019-02-08T00:00:00+00:00"
},
...
],
"NextToken": "--token string truncated--"
}
```
**Example 2: To get a list of patches in the Missing state for an instance**
The following `describe-instance-patches` example retrieves information about patches that are in the Missing state for the specified instance.
```
aws ssm describe-instance-patches \
--instance-id "i-1234567890abcdef0" \
--filters Key=State,Values=Missing
```
Output:
```
{
"Patches": [
{
"Title": "Windows Malicious Software Removal Tool x64 - February 2019 (KB890830)",
"KBId": "KB890830",
"Classification": "UpdateRollups",
"Severity": "Unspecified",
"State": "Missing",
"InstalledTime": "1970-01-01T00:00:00+00:00"
},
...
],
"NextToken": "--token string truncated--"
}
```
For more information, see [About Patch Compliance States](https://docs.aws.amazon.com/systems-manager/latest/userguide/about-patch-compliance-states.html) in the *AWS Systems Manager User Guide*.
**Example 3: To get a list of patches installed since a specified InstalledTime for an instance**
The following `describe-instance-patches` example retrieves information about patches installed since a specified time for the specified instance by combining the use of `--filters` and `--query`.
```
aws ssm describe-instance-patches \
--instance-id "i-1234567890abcdef0" \
--filters Key=State,Values=Installed \
--query "Patches[?InstalledTime >= `2023-01-01T16:00:00`]"
```
Output:
```
{
"Patches": [
{
"Title": "2023-03 Cumulative Update for Windows Server 2019 (1809) for x64-based Systems (KB5023702)",
"KBId": "KB5023702",
"Classification": "SecurityUpdates",
"Severity": "Critical",
"State": "Installed",
"InstalledTime": "2023-03-16T11:00:00+00:00"
},
...
],
"NextToken": "--token string truncated--"
}
```
+ For API details, see [DescribeInstancePatches](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-instance-patches.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example gets the patch compliance details for an instance.**
```
Get-SSMInstancePatch -InstanceId "i-08ee91c0b17045407"
```
+ For API details, see [DescribeInstancePatches](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example gets the patch compliance details for an instance.**
```
Get-SSMInstancePatch -InstanceId "i-08ee91c0b17045407"
```
+ For API details, see [DescribeInstancePatches](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeMaintenanceWindowExecutionTaskInvocations` with a CLI
<a name="ssm_example_ssm_DescribeMaintenanceWindowExecutionTaskInvocations_section"></a>
The following code examples show how to use `DescribeMaintenanceWindowExecutionTaskInvocations`.
------
#### [ CLI ]
**AWS CLI**
**To get the specific task invocations performed for a maintenance window task execution**
The following `describe-maintenance-window-execution-task-invocations` example lists the invocations for the specified task executed as part of the specified maintenance window execution.
```
aws ssm describe-maintenance-window-execution-task-invocations \
--window-execution-id "518d5565-5969-4cca-8f0e-da3b2a638355" \
--task-id "ac0c6ae1-daa3-4a89-832e-d384503b6586"
```
Output:
```
{
"WindowExecutionTaskInvocationIdentities": [
{
"Status": "SUCCESS",
"Parameters": "{\"documentName\":\"AWS-RunShellScript\",\"instanceIds\":[\"i-0000293ffd8c57862\"],\"parameters\":{\"commands\":[\"df\"]},\"maxConcurrency\":\"1\",\"maxErrors\":\"1\"}",
"InvocationId": "e274b6e1-fe56-4e32-bd2a-8073c6381d8b",
"StartTime": 1487692834.723,
"EndTime": 1487692834.871,
"WindowExecutionId": "518d5565-5969-4cca-8f0e-da3b2a638355",
"TaskExecutionId": "ac0c6ae1-daa3-4a89-832e-d384503b6586"
}
]
}
```
For more information, see [View Information About Tasks and Task Executions (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/mw-cli-tutorial-task-info.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeMaintenanceWindowExecutionTaskInvocations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-maintenance-window-execution-task-invocations.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists the invocations for a task executed as part of a maintenance window execution.**
```
Get-SSMMaintenanceWindowExecutionTaskInvocationList -TaskId "ac0c6ae1-daa3-4a89-832e-d384503b6586" -WindowExecutionId "518d5565-5969-4cca-8f0e-da3b2a638355"
```
**Output:**
```
EndTime : 2/21/2017 4:00:34 PM
ExecutionId :
InvocationId : e274b6e1-fe56-4e32-bd2a-8073c6381d8b
OwnerInformation :
Parameters : {"documentName":"AWS-RunShellScript","instanceIds":["i-0000293ffd8c57862"],"parameters":{"commands":["df"]},"maxConcurrency":"1",
"maxErrors":"1"}
StartTime : 2/21/2017 4:00:34 PM
Status : FAILED
StatusDetails : The instance IDs list contains an invalid entry.
TaskExecutionId : ac0c6ae1-daa3-4a89-832e-d384503b6586
WindowExecutionId : 518d5565-5969-4cca-8f0e-da3b2a638355
WindowTargetId :
```
+ For API details, see [DescribeMaintenanceWindowExecutionTaskInvocations](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists the invocations for a task executed as part of a maintenance window execution.**
```
Get-SSMMaintenanceWindowExecutionTaskInvocationList -TaskId "ac0c6ae1-daa3-4a89-832e-d384503b6586" -WindowExecutionId "518d5565-5969-4cca-8f0e-da3b2a638355"
```
**Output:**
```
EndTime : 2/21/2017 4:00:34 PM
ExecutionId :
InvocationId : e274b6e1-fe56-4e32-bd2a-8073c6381d8b
OwnerInformation :
Parameters : {"documentName":"AWS-RunShellScript","instanceIds":["i-0000293ffd8c57862"],"parameters":{"commands":["df"]},"maxConcurrency":"1",
"maxErrors":"1"}
StartTime : 2/21/2017 4:00:34 PM
Status : FAILED
StatusDetails : The instance IDs list contains an invalid entry.
TaskExecutionId : ac0c6ae1-daa3-4a89-832e-d384503b6586
WindowExecutionId : 518d5565-5969-4cca-8f0e-da3b2a638355
WindowTargetId :
```
+ For API details, see [DescribeMaintenanceWindowExecutionTaskInvocations](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeMaintenanceWindowExecutionTasks` with a CLI
<a name="ssm_example_ssm_DescribeMaintenanceWindowExecutionTasks_section"></a>
The following code examples show how to use `DescribeMaintenanceWindowExecutionTasks`.
------
#### [ CLI ]
**AWS CLI**
**To list all tasks associated with a maintenance window execution**
The following `ssm describe-maintenance-window-execution-tasks` example lists the tasks associated with the specified maintenance window execution.
```
aws ssm describe-maintenance-window-execution-tasks \
--window-execution-id "518d5565-5969-4cca-8f0e-da3b2EXAMPLE"
```
Output:
```
{
"WindowExecutionTaskIdentities": [
{
"Status": "SUCCESS",
"TaskArn": "AWS-RunShellScript",
"StartTime": 1487692834.684,
"TaskType": "RUN_COMMAND",
"EndTime": 1487692835.005,
"WindowExecutionId": "518d5565-5969-4cca-8f0e-da3b2EXAMPLE",
"TaskExecutionId": "ac0c6ae1-daa3-4a89-832e-d3845EXAMPLE"
}
]
}
```
For more information, see [View Information About Tasks and Task Executions (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/mw-cli-tutorial-task-info.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeMaintenanceWindowExecutionTasks](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-maintenance-window-execution-tasks.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists the tasks associated with a maintenance window execution.**
```
Get-SSMMaintenanceWindowExecutionTaskList -WindowExecutionId "518d5565-5969-4cca-8f0e-da3b2a638355"
```
**Output:**
```
EndTime : 2/21/2017 4:00:35 PM
StartTime : 2/21/2017 4:00:34 PM
Status : SUCCESS
TaskArn : AWS-RunShellScript
TaskExecutionId : ac0c6ae1-daa3-4a89-832e-d384503b6586
TaskType : RUN_COMMAND
WindowExecutionId : 518d5565-5969-4cca-8f0e-da3b2a638355
```
+ For API details, see [DescribeMaintenanceWindowExecutionTasks](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists the tasks associated with a maintenance window execution.**
```
Get-SSMMaintenanceWindowExecutionTaskList -WindowExecutionId "518d5565-5969-4cca-8f0e-da3b2a638355"
```
**Output:**
```
EndTime : 2/21/2017 4:00:35 PM
StartTime : 2/21/2017 4:00:34 PM
Status : SUCCESS
TaskArn : AWS-RunShellScript
TaskExecutionId : ac0c6ae1-daa3-4a89-832e-d384503b6586
TaskType : RUN_COMMAND
WindowExecutionId : 518d5565-5969-4cca-8f0e-da3b2a638355
```
+ For API details, see [DescribeMaintenanceWindowExecutionTasks](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeMaintenanceWindowExecutions` with a CLI
<a name="ssm_example_ssm_DescribeMaintenanceWindowExecutions_section"></a>
The following code examples show how to use `DescribeMaintenanceWindowExecutions`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To list all executions for a maintenance window**
The following `describe-maintenance-window-executions` example lists all of the executions for the specified maintenance window.
```
aws ssm describe-maintenance-window-executions \
--window-id "mw-ab12cd34eEXAMPLE"
```
Output:
```
{
"WindowExecutions": [
{
"WindowId": "mw-ab12cd34eEXAMPLE",
"WindowExecutionId": "6027b513-64fe-4cf0-be7d-1191aEXAMPLE",
"Status": "IN_PROGRESS",
"StartTime": "2021-08-04T11:00:00.000000-07:00"
},
{
"WindowId": "mw-ab12cd34eEXAMPLE",
"WindowExecutionId": "ff75b750-4834-4377-8f61-b3cadEXAMPLE",
"Status": "SUCCESS",
"StartTime": "2021-08-03T11:00:00.000000-07:00",
"EndTime": "2021-08-03T11:37:21.450000-07:00"
},
{
"WindowId": "mw-ab12cd34eEXAMPLE",
"WindowExecutionId": "9fac7dd9-ff21-42a5-96ad-bbc4bEXAMPLE",
"Status": "FAILED",
"StatusDetails": "One or more tasks in the orchestration failed.",
"StartTime": "2021-08-02T11:00:00.000000-07:00",
"EndTime": "2021-08-02T11:22:36.190000-07:00"
}
]
}
```
**Example 2: To list all executions for a maintenance window before a specified date**
The following `describe-maintenance-window-executions` example lists all of the executions for the specified maintenance window before the specified date.
```
aws ssm describe-maintenance-window-executions \
--window-id "mw-ab12cd34eEXAMPLE" \
--filters "Key=ExecutedBefore,Values=2021-08-03T00:00:00Z"
```
Output:
```
{
"WindowExecutions": [
{
"WindowId": "mw-ab12cd34eEXAMPLE",
"WindowExecutionId": "9fac7dd9-ff21-42a5-96ad-bbc4bEXAMPLE",
"Status": "FAILED",
"StatusDetails": "One or more tasks in the orchestration failed.",
"StartTime": "2021-08-02T11:00:00.000000-07:00",
"EndTime": "2021-08-02T11:22:36.190000-07:00"
}
]
}
```
**Example 3: To list all executions for a maintenance window after a specified date**
The following `describe-maintenance-window-executions` example lists all of the executions for the specified maintenance window after the specified date.
```
aws ssm describe-maintenance-window-executions \
--window-id "mw-ab12cd34eEXAMPLE" \
--filters "Key=ExecutedAfter,Values=2021-08-04T00:00:00Z"
```
Output:
```
{
"WindowExecutions": [
{
"WindowId": "mw-ab12cd34eEXAMPLE",
"WindowExecutionId": "6027b513-64fe-4cf0-be7d-1191aEXAMPLE",
"Status": "IN_PROGRESS",
"StartTime": "2021-08-04T11:00:00.000000-07:00"
}
]
}
```
For more information, see [View information about tasks and task executions (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/mw-cli-tutorial-task-info.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeMaintenanceWindowExecutions](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-maintenance-window-executions.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists all of the executions for a maintenance window.**
```
Get-SSMMaintenanceWindowExecutionList -WindowId "mw-03eb9db42890fb82d"
```
**Output:**
```
EndTime : 2/20/2017 6:30:17 PM
StartTime : 2/20/2017 6:30:16 PM
Status : FAILED
StatusDetails : One or more tasks in the orchestration failed.
WindowExecutionId : 6f3215cf-4101-4fa0-9b7b-9523269599c7
WindowId : mw-03eb9db42890fb82d
```
**Example 2: This example lists all of the executions for a maintenance window before a specified date.**
```
$option1 = @{Key="ExecutedBefore";Values=@("2016-11-04T05:00:00Z")}
Get-SSMMaintenanceWindowExecutionList -WindowId "mw-03eb9db42890fb82d" -Filter $option1
```
**Example 3: This example lists all of the executions for a maintenance window after a specified date.**
```
$option1 = @{Key="ExecutedAfter";Values=@("2016-11-04T05:00:00Z")}
Get-SSMMaintenanceWindowExecutionList -WindowId "mw-03eb9db42890fb82d" -Filter $option1
```
+ For API details, see [DescribeMaintenanceWindowExecutions](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists all of the executions for a maintenance window.**
```
Get-SSMMaintenanceWindowExecutionList -WindowId "mw-03eb9db42890fb82d"
```
**Output:**
```
EndTime : 2/20/2017 6:30:17 PM
StartTime : 2/20/2017 6:30:16 PM
Status : FAILED
StatusDetails : One or more tasks in the orchestration failed.
WindowExecutionId : 6f3215cf-4101-4fa0-9b7b-9523269599c7
WindowId : mw-03eb9db42890fb82d
```
**Example 2: This example lists all of the executions for a maintenance window before a specified date.**
```
$option1 = @{Key="ExecutedBefore";Values=@("2016-11-04T05:00:00Z")}
Get-SSMMaintenanceWindowExecutionList -WindowId "mw-03eb9db42890fb82d" -Filter $option1
```
**Example 3: This example lists all of the executions for a maintenance window after a specified date.**
```
$option1 = @{Key="ExecutedAfter";Values=@("2016-11-04T05:00:00Z")}
Get-SSMMaintenanceWindowExecutionList -WindowId "mw-03eb9db42890fb82d" -Filter $option1
```
+ For API details, see [DescribeMaintenanceWindowExecutions](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeMaintenanceWindowTargets` with a CLI
<a name="ssm_example_ssm_DescribeMaintenanceWindowTargets_section"></a>
The following code examples show how to use `DescribeMaintenanceWindowTargets`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To list all targets for a Maintenance Window**
The following `describe-maintenance-window-targets` example lists all of the targets for a maintenance window.
```
aws ssm describe-maintenance-window-targets \
--window-id "mw-06cf17cbefEXAMPLE"
```
Output:
```
{
"Targets": [
{
"ResourceType": "INSTANCE",
"OwnerInformation": "Single instance",
"WindowId": "mw-06cf17cbefEXAMPLE",
"Targets": [
{
"Values": [
"i-0000293ffdEXAMPLE"
],
"Key": "InstanceIds"
}
],
"WindowTargetId": "350d44e6-28cc-44e2-951f-4b2c9EXAMPLE"
},
{
"ResourceType": "INSTANCE",
"OwnerInformation": "Two instances in a list",
"WindowId": "mw-06cf17cbefEXAMPLE",
"Targets": [
{
"Values": [
"i-0000293ffdEXAMPLE",
"i-0cb2b964d3EXAMPLE"
],
"Key": "InstanceIds"
}
],
"WindowTargetId": "e078a987-2866-47be-bedd-d9cf4EXAMPLE"
}
]
}
```
**Example 2: To list all targets for a maintenance window matching a specific owner information value**
This `describe-maintenance-window-targets` example lists all of the targets for a maintenance window with a specific value.
```
aws ssm describe-maintenance-window-targets \
--window-id "mw-0ecb1226ddEXAMPLE" \
--filters "Key=OwnerInformation,Values=CostCenter1"
```
Output:
```
{
"Targets": [
{
"WindowId": "mw-0ecb1226ddEXAMPLE",
"WindowTargetId": "da89dcc3-7f9c-481d-ba2b-edcb7d0057f9",
"ResourceType": "INSTANCE",
"Targets": [
{
"Key": "tag:Environment",
"Values": [
"Prod"
]
}
],
"OwnerInformation": "CostCenter1",
"Name": "ProdTarget1"
}
]
}
```
For more information, see [View Information About Maintenance Windows (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/maintenance-windows-cli-tutorials-describe.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeMaintenanceWindowTargets](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-maintenance-window-targets.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists all of the targets for a maintenance window.**
```
Get-SSMMaintenanceWindowTarget -WindowId "mw-06cf17cbefcb4bf4f"
```
**Output:**
```
OwnerInformation : Single instance
ResourceType : INSTANCE
Targets : {InstanceIds}
WindowId : mw-06cf17cbefcb4bf4f
WindowTargetId : 350d44e6-28cc-44e2-951f-4b2c985838f6
OwnerInformation : Two instances in a list
ResourceType : INSTANCE
Targets : {InstanceIds}
WindowId : mw-06cf17cbefcb4bf4f
WindowTargetId : e078a987-2866-47be-bedd-d9cf49177d3a
```
+ For API details, see [DescribeMaintenanceWindowTargets](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists all of the targets for a maintenance window.**
```
Get-SSMMaintenanceWindowTarget -WindowId "mw-06cf17cbefcb4bf4f"
```
**Output:**
```
OwnerInformation : Single instance
ResourceType : INSTANCE
Targets : {InstanceIds}
WindowId : mw-06cf17cbefcb4bf4f
WindowTargetId : 350d44e6-28cc-44e2-951f-4b2c985838f6
OwnerInformation : Two instances in a list
ResourceType : INSTANCE
Targets : {InstanceIds}
WindowId : mw-06cf17cbefcb4bf4f
WindowTargetId : e078a987-2866-47be-bedd-d9cf49177d3a
```
+ For API details, see [DescribeMaintenanceWindowTargets](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeMaintenanceWindowTasks` with a CLI
<a name="ssm_example_ssm_DescribeMaintenanceWindowTasks_section"></a>
The following code examples show how to use `DescribeMaintenanceWindowTasks`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To list all tasks for a maintenance window**
The following `describe-maintenance-window-tasks` example lists all of the tasks for the specified maintenance window.
```
aws ssm describe-maintenance-window-tasks \
--window-id "mw-06cf17cbefEXAMPLE"
```
Output:
```
{
"Tasks": [
{
"WindowId": "mw-06cf17cbefEXAMPLE",
"WindowTaskId": "018b31c3-2d77-4b9e-bd48-c91edEXAMPLE",
"TaskArn": "AWS-RestartEC2Instance",
"TaskParameters": {},
"Type": "AUTOMATION",
"Description": "Restarting EC2 Instance for maintenance",
"MaxConcurrency": "1",
"MaxErrors": "1",
"Name": "My-Automation-Example-Task",
"Priority": 0,
"ServiceRoleArn": "arn:aws:iam::111222333444:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"da89dcc3-7f9c-481d-ba2b-edcb7EXAMPLE"
]
}
]
},
{
"WindowId": "mw-06cf17cbefEXAMPLE",
"WindowTaskId": "1943dee0-0a17-4978-9bf4-3cc2fEXAMPLE",
"TaskArn": "AWS-DisableS3BucketPublicReadWrite",
"TaskParameters": {},
"Type": "AUTOMATION",
"Description": "Automation task to disable read/write access on public S3 buckets",
"MaxConcurrency": "10",
"MaxErrors": "5",
"Name": "My-Disable-S3-Public-Read-Write-Access-Automation-Task",
"Priority": 0,
"ServiceRoleArn": "arn:aws:iam::111222333444:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"da89dcc3-7f9c-481d-ba2b-edcb7EXAMPLE"
]
}
]
}
]
}
```
**Example 2: To list all tasks for a maintenance window that invokes the AWS-RunPowerShellScript command document**
The following `describe-maintenance-window-tasks` example lists all of the tasks for the specified maintenance window that invokes the `AWS-RunPowerShellScript` command document.
```
aws ssm describe-maintenance-window-tasks \
--window-id "mw-ab12cd34eEXAMPLE" \
--filters "Key=TaskArn,Values=AWS-RunPowerShellScript"
```
Output:
```
{
"Tasks": [
{
"WindowId": "mw-ab12cd34eEXAMPLE",
"WindowTaskId": "0d36e6b4-3a4f-411e-adcb-3558eEXAMPLE",
"TaskArn": "AWS-RunPowerShellScript",
"Type": "RUN_COMMAND",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"da89dcc3-7f9c-481d-ba2b-edcb7EXAMPLE"
]
}
],
"TaskParameters": {},
"Priority": 1,
"ServiceRoleArn": "arn:aws:iam::111222333444:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"MaxConcurrency": "1",
"MaxErrors": "1",
"Name": "MyTask"
}
]
}
```
**Example 3: To list all tasks for a maintenance window that have a Priority of 3**
The following `describe-maintenance-window-tasks` example lists all of the tasks for the specified maintenance window that have a `Priority` of `3`.
```
aws ssm describe-maintenance-window-tasks \
--window-id "mw-ab12cd34eEXAMPLE" \
--filters "Key=Priority,Values=3"
```
Output:
```
{
"Tasks": [
{
"WindowId": "mw-ab12cd34eEXAMPLE",
"WindowTaskId": "0d36e6b4-3a4f-411e-adcb-3558eEXAMPLE",
"TaskArn": "AWS-RunPowerShellScript",
"Type": "RUN_COMMAND",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"da89dcc3-7f9c-481d-ba2b-edcb7EXAMPLE"
]
}
],
"TaskParameters": {},
"Priority": 3,
"ServiceRoleArn": "arn:aws:iam::111222333444:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"MaxConcurrency": "1",
"MaxErrors": "1",
"Name": "MyRunCommandTask"
},
{
"WindowId": "mw-ab12cd34eEXAMPLE",
"WindowTaskId": "ee45feff-ad65-4a6c-b478-5cab8EXAMPLE",
"TaskArn": "AWS-RestartEC2Instance",
"Type": "AUTOMATION",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"da89dcc3-7f9c-481d-ba2b-edcb7EXAMPLE"
]
}
],
"TaskParameters": {},
"Priority": 3,
"ServiceRoleArn": "arn:aws:iam::111222333444:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"MaxConcurrency": "10",
"MaxErrors": "5",
"Name": "My-Automation-Task",
"Description": "A description for my Automation task"
}
]
}
```
**Example 4: To list all tasks for a maintenance window that have a Priority of 1 and use Run Command**
This `describe-maintenance-window-tasks` example lists all of the tasks for the specified maintenance window that have a `Priority` of `1` and use `Run Command`.
```
aws ssm describe-maintenance-window-tasks \
--window-id "mw-ab12cd34eEXAMPLE" \
--filters "Key=Priority,Values=1" "Key=TaskType,Values=RUN_COMMAND"
```
Output:
```
{
"Tasks": [
{
"WindowId": "mw-ab12cd34eEXAMPLE",
"WindowTaskId": "0d36e6b4-3a4f-411e-adcb-3558eEXAMPLE",
"TaskArn": "AWS-RunPowerShellScript",
"Type": "RUN_COMMAND",
"Targets": [
{
"Key": "WindowTargetIds",
"Values": [
"da89dcc3-7f9c-481d-ba2b-edcb7EXAMPLE"
]
}
],
"TaskParameters": {},
"Priority": 1,
"ServiceRoleArn": "arn:aws:iam::111222333444:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"MaxConcurrency": "1",
"MaxErrors": "1",
"Name": "MyRunCommandTask"
}
]
}
```
For more information, see [View information about maintenance windows (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/maintenance-windows-cli-tutorials-describe.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeMaintenanceWindowTasks](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-maintenance-window-tasks.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists all of the tasks for a maintenance window.**
```
Get-SSMMaintenanceWindowTaskList -WindowId "mw-06cf17cbefcb4bf4f"
```
**Output:**
```
LoggingInfo :
MaxConcurrency : 1
MaxErrors : 1
Priority : 10
ServiceRoleArn : arn:aws:iam::123456789012:role/MaintenanceWindowsRole
Targets : {InstanceIds}
TaskArn : AWS-RunShellScript
TaskParameters : {[commands, Amazon.SimpleSystemsManagement.Model.MaintenanceWindowTaskParameterValueExpression]}
Type : RUN_COMMAND
WindowId : mw-06cf17cbefcb4bf4f
WindowTaskId : a23e338d-ff30-4398-8aa3-09cd052ebf17
```
+ For API details, see [DescribeMaintenanceWindowTasks](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists all of the tasks for a maintenance window.**
```
Get-SSMMaintenanceWindowTaskList -WindowId "mw-06cf17cbefcb4bf4f"
```
**Output:**
```
LoggingInfo :
MaxConcurrency : 1
MaxErrors : 1
Priority : 10
ServiceRoleArn : arn:aws:iam::123456789012:role/MaintenanceWindowsRole
Targets : {InstanceIds}
TaskArn : AWS-RunShellScript
TaskParameters : {[commands, Amazon.SimpleSystemsManagement.Model.MaintenanceWindowTaskParameterValueExpression]}
Type : RUN_COMMAND
WindowId : mw-06cf17cbefcb4bf4f
WindowTaskId : a23e338d-ff30-4398-8aa3-09cd052ebf17
```
+ For API details, see [DescribeMaintenanceWindowTasks](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeMaintenanceWindows` with a CLI
<a name="ssm_example_ssm_DescribeMaintenanceWindows_section"></a>
The following code examples show how to use `DescribeMaintenanceWindows`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To list all maintenance windows**
The following `describe-maintenance-windows` example lists all maintenance windows in your AWS account in the current Region.
```
aws ssm describe-maintenance-windows
```
Output:
```
{
"WindowIdentities": [
{
"WindowId": "mw-0ecb1226ddEXAMPLE",
"Name": "MyMaintenanceWindow-1",
"Enabled": true,
"Duration": 2,
"Cutoff": 1,
"Schedule": "rate(180 minutes)",
"NextExecutionTime": "2020-02-12T23:19:20.596Z"
},
{
"WindowId": "mw-03eb9db428EXAMPLE",
"Name": "MyMaintenanceWindow-2",
"Enabled": true,
"Duration": 3,
"Cutoff": 1,
"Schedule": "rate(7 days)",
"NextExecutionTime": "2020-02-17T23:22:00.956Z"
},
]
}
```
**Example 2: To list all enabled maintenance windows**
The following `describe-maintenance-windows` example lists all enabled maintenance windows.
```
aws ssm describe-maintenance-windows \
--filters "Key=Enabled,Values=true"
```
**Example 3: To list maintenance windows matching a specific name**
This `describe-maintenance-windows` example lists all maintenance windows with the specified name.
```
aws ssm describe-maintenance-windows \
--filters "Key=Name,Values=MyMaintenanceWindow"
```
For more information, see [View Information About Maintenance Windows (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/maintenance-windows-cli-tutorials-describe.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeMaintenanceWindows](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-maintenance-windows.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists all maintenance windows on your account.**
```
Get-SSMMaintenanceWindowList
```
**Output:**
```
Cutoff : 1
Duration : 4
Enabled : True
Name : My-First-Maintenance-Window
WindowId : mw-06d59c1a07c022145
```
+ For API details, see [DescribeMaintenanceWindows](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists all maintenance windows on your account.**
```
Get-SSMMaintenanceWindowList
```
**Output:**
```
Cutoff : 1
Duration : 4
Enabled : True
Name : My-First-Maintenance-Window
WindowId : mw-06d59c1a07c022145
```
+ For API details, see [DescribeMaintenanceWindows](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribeOpsItems` with an AWS SDK or CLI
<a name="ssm_example_ssm_DescribeOpsItems_section"></a>
The following code examples show how to use `DescribeOpsItems`.
------
#### [ CLI ]
**AWS CLI**
**To list a set of OpsItems**
The following `describe-ops-items` example displays a list of all open OpsItems in your AWS account.
```
aws ssm describe-ops-items \
--ops-item-filters "Key=Status,Values=Open,Operator=Equal"
```
Output:
```
{
"OpsItemSummaries": [
{
"CreatedBy": "arn:aws:sts::111222333444:assumed-role/OpsItem-CWE-Role/fbf77cbe264a33509569f23e4EXAMPLE",
"CreatedTime": "2020-03-14T17:02:46.375000-07:00",
"LastModifiedBy": "arn:aws:sts::111222333444:assumed-role/OpsItem-CWE-Role/fbf77cbe264a33509569f23e4EXAMPLE",
"LastModifiedTime": "2020-03-14T17:02:46.375000-07:00",
"Source": "SSM",
"Status": "Open",
"OpsItemId": "oi-7cfc5EXAMPLE",
"Title": "SSM Maintenance Window execution failed",
"OperationalData": {
"/aws/dedup": {
"Value": "{\"dedupString\":\"SSMOpsItems-SSM-maintenance-window-execution-failed\"}",
"Type": "SearchableString"
},
"/aws/resources": {
"Value": "[{\"arn\":\"arn:aws:ssm:us-east-2:111222333444:maintenancewindow/mw-034093d322EXAMPLE\"}]",
"Type": "SearchableString"
}
},
"Category": "Availability",
"Severity": "3"
},
{
"CreatedBy": "arn:aws:sts::1112223233444:assumed-role/OpsItem-CWE-Role/fbf77cbe264a33509569f23e4EXAMPLE",
"CreatedTime": "2020-02-26T11:43:15.426000-08:00",
"LastModifiedBy": "arn:aws:sts::111222333444:assumed-role/OpsItem-CWE-Role/fbf77cbe264a33509569f23e4EXAMPLE",
"LastModifiedTime": "2020-02-26T11:43:15.426000-08:00",
"Source": "EC2",
"Status": "Open",
"OpsItemId": "oi-6f966EXAMPLE",
"Title": "EC2 instance stopped",
"OperationalData": {
"/aws/automations": {
"Value": "[ { \"automationType\": \"AWS:SSM:Automation\", \"automationId\": \"AWS-RestartEC2Instance\" } ]",
"Type": "SearchableString"
},
"/aws/dedup": {
"Value": "{\"dedupString\":\"SSMOpsItems-EC2-instance-stopped\"}",
"Type": "SearchableString"
},
"/aws/resources": {
"Value": "[{\"arn\":\"arn:aws:ec2:us-east-2:111222333444:instance/i-0beccfbc02EXAMPLE\"}]",
"Type": "SearchableString"
}
},
"Category": "Availability",
"Severity": "3"
}
]
}
```
For more information, see [Working with OpsItems](https://docs.aws.amazon.com/systems-manager/latest/userguide/OpsCenter-working-with-OpsItems.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeOpsItems](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-ops-items.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/ssm#code-examples).
```
/**
* Describes AWS SSM OpsItems asynchronously.
*
* @param key The key to filter OpsItems by (e.g., OPS_ITEM_ID).
*
* This method initiates an asynchronous request to describe SSM OpsItems.
* If the request is successful, it prints the title and status of each OpsItem.
* If an exception occurs, it handles the error appropriately.
*/
public void describeOpsItems(String key) {
OpsItemFilter filter = OpsItemFilter.builder()
.key(OpsItemFilterKey.OPS_ITEM_ID)
.values(key)
.operator(OpsItemFilterOperator.EQUAL)
.build();
DescribeOpsItemsRequest itemsRequest = DescribeOpsItemsRequest.builder()
.maxResults(10)
.opsItemFilters(filter)
.build();
CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
getAsyncClient().describeOpsItems(itemsRequest)
.thenAccept(itemsResponse -> {
List<OpsItemSummary> items = itemsResponse.opsItemSummaries();
for (OpsItemSummary item : items) {
System.out.println("The item title is " + item.title() + " and the status is " + item.status().toString());
}
})
.exceptionally(ex -> {
throw new CompletionException(ex);
}).join();
}).exceptionally(ex -> {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw new RuntimeException("SSM error: " + cause.getMessage(), cause);
} else {
throw new RuntimeException("Unexpected error: " + cause.getMessage(), cause);
}
});
try {
future.join();
} catch (CompletionException ex) {
throw ex.getCause() instanceof RuntimeException ? (RuntimeException) ex.getCause() : ex;
}
}
```
+ For API details, see [DescribeOpsItems](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/DescribeOpsItems) in *AWS SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ssm#code-examples).
```
import {
OpsItemFilterOperator,
OpsItemFilterKey,
paginateDescribeOpsItems,
SSMClient,
} from "@aws-sdk/client-ssm";
import { parseArgs } from "node:util";
/**
* Describe SSM OpsItems.
* @param {{ opsItemId: string }}
*/
export const main = async ({ opsItemId }) => {
const client = new SSMClient({});
try {
const describeOpsItemsPaginated = [];
for await (const page of paginateDescribeOpsItems(
{ client },
{
OpsItemFilters: {
Key: OpsItemFilterKey.OPSITEM_ID,
Operator: OpsItemFilterOperator.EQUAL,
Values: opsItemId,
},
},
)) {
describeOpsItemsPaginated.push(...page.OpsItemSummaries);
}
console.log("Here are the ops items:");
console.log(describeOpsItemsPaginated);
return { OpsItemSummaries: describeOpsItemsPaginated };
} catch (caught) {
if (caught instanceof Error && caught.name === "MissingParameter") {
console.warn(`${caught.message}. Did you provide this value?`);
}
throw caught;
}
};
```
+ For API details, see [DescribeOpsItems](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/DescribeOpsItemsCommand) in *AWS SDK for JavaScript API Reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
```
class OpsItemWrapper:
"""Encapsulates AWS Systems Manager OpsItem actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.id = None
@classmethod
def from_client(cls):
"""
:return: A OpsItemWrapper instance.
"""
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def describe(self):
"""
Describe an OpsItem.
"""
try:
paginator = self.ssm_client.get_paginator("describe_ops_items")
ops_items = []
for page in paginator.paginate(
OpsItemFilters=[
{"Key": "OpsItemId", "Values": [self.id], "Operator": "Equal"}
]
):
ops_items.extend(page["OpsItemSummaries"])
for item in ops_items:
print(
f"The item title is {item['Title']} and the status is {item['Status']}"
)
return len(ops_items) > 0
except ClientError as err:
logger.error(
"Couldn't describe ops item %s. Here's why: %s: %s",
self.id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [DescribeOpsItems](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/DescribeOpsItems) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/ssm#code-examples).
```
TRY.
" Create filter for OpsItem ID
DATA(lt_filters) = VALUE /aws1/cl_ssmopsitemfilter=>tt_opsitemfilters(
( NEW /aws1/cl_ssmopsitemfilter(
iv_key = 'OpsItemId'
it_values = VALUE /aws1/cl_ssmopsitemfiltvals_w=>tt_opsitemfiltervalues(
( NEW /aws1/cl_ssmopsitemfiltvals_w( iv_value = iv_ops_item_id ) )
)
iv_operator = 'Equal'
) )
).
" Use paginator to get all results
DATA(lo_paginator) = lo_ssm->get_paginator( ).
DATA(lo_iterator) = lo_paginator->describeopsitems(
it_opsitemfilters = lt_filters ).
rv_found = abap_false.
WHILE lo_iterator->has_next( ).
DATA(lo_result) = CAST /aws1/cl_ssmdescropsitemsrsp( lo_iterator->get_next( ) ).
LOOP AT lo_result->get_opsitemsummaries( ) INTO DATA(lo_item).
DATA(lv_title) = lo_item->get_title( ).
DATA(lv_status) = lo_item->get_status( ).
MESSAGE |The OpsItem title is { lv_title } and the status is { lv_status }| TYPE 'I'.
rv_found = abap_true.
ENDLOOP.
ENDWHILE.
CATCH /aws1/cx_ssminternalservererr.
MESSAGE 'Internal server error occurred.' TYPE 'I'.
ENDTRY.
```
+ For API details, see [DescribeOpsItems](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------
# Use `DescribeParameters` with an AWS SDK or CLI
<a name="ssm_example_ssm_DescribeParameters_section"></a>
The following code examples show how to use `DescribeParameters`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To list all parameters**
The following `describe-parameters` example lists all parameters in the current AWS account and Region.
```
aws ssm describe-parameters
```
Output:
```
{
"Parameters": [
{
"Name": "MySecureStringParameter",
"Type": "SecureString",
"KeyId": "alias/aws/ssm",
"LastModifiedDate": 1582155479.205,
"LastModifiedUser": "arn:aws:sts::111222333444:assumed-role/Admin/Richard-Roe-Managed",
"Description": "This is a SecureString parameter",
"Version": 2,
"Tier": "Advanced",
"Policies": [
{
"PolicyText": "{\"Type\":\"Expiration\",\"Version\":\"1.0\",\"Attributes\":{\"Timestamp\":\"2020-07-07T22:30:00Z\"}}",
"PolicyType": "Expiration",
"PolicyStatus": "Pending"
},
{
"PolicyText": "{\"Type\":\"ExpirationNotification\",\"Version\":\"1.0\",\"Attributes\":{\"Before\":\"12\",\"Unit\":\"Hours\"}}",
"PolicyType": "ExpirationNotification",
"PolicyStatus": "Pending"
}
]
},
{
"Name": "MyStringListParameter",
"Type": "StringList",
"LastModifiedDate": 1582154764.222,
"LastModifiedUser": "arn:aws:iam::111222333444:user/Mary-Major",
"Description": "This is a StringList parameter",
"Version": 1,
"Tier": "Standard",
"Policies": []
},
{
"Name": "MyStringParameter",
"Type": "String",
"LastModifiedDate": 1582154711.976,
"LastModifiedUser": "arn:aws:iam::111222333444:user/Alejandro-Rosalez",
"Description": "This is a String parameter",
"Version": 1,
"Tier": "Standard",
"Policies": []
},
{
"Name": "latestAmi",
"Type": "String",
"LastModifiedDate": 1580862415.521,
"LastModifiedUser": "arn:aws:sts::111222333444:assumed-role/lambda-ssm-role/Automation-UpdateSSM-Param",
"Version": 3,
"Tier": "Standard",
"Policies": []
}
]
}
```
**Example 2: To list all parameters matching specific metadata**
This `describe-parameters` example lists all parameters matching a filter.
aws ssm describe-parameters --filters "Key=Type,Values=StringList"
Output:
```
{
"Parameters": [
{
"Name": "MyStringListParameter",
"Type": "StringList",
"LastModifiedDate": 1582154764.222,
"LastModifiedUser": "arn:aws:iam::111222333444:user/Mary-Major",
"Description": "This is a StringList parameter",
"Version": 1,
"Tier": "Standard",
"Policies": []
}
]
}
```
For more information, see [Searching for Systems Manager Parameters](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-search.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribeParameters](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-parameters.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/ssm#code-examples).
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ssm.SsmClient;
import software.amazon.awssdk.services.ssm.model.GetParameterRequest;
import software.amazon.awssdk.services.ssm.model.GetParameterResponse;
import software.amazon.awssdk.services.ssm.model.SsmException;
/**
* Before running this Java V2 code example, set up your development
* environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*/
public class GetParameter {
public static void main(String[] args) {
final String usage = """
Usage:
<paraName>
Where:
paraName - The name of the parameter.
""";
if (args.length != 1) {
System.out.println(usage);
System.exit(1);
}
String paraName = args[0];
Region region = Region.US_EAST_1;
SsmClient ssmClient = SsmClient.builder()
.region(region)
.build();
getParaValue(ssmClient, paraName);
ssmClient.close();
}
public static void getParaValue(SsmClient ssmClient, String paraName) {
try {
GetParameterRequest parameterRequest = GetParameterRequest.builder()
.name(paraName)
.build();
GetParameterResponse parameterResponse = ssmClient.getParameter(parameterRequest);
System.out.println("The parameter value is " + parameterResponse.parameter().value());
} catch (SsmException e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
}
```
+ For API details, see [DescribeParameters](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/DescribeParameters) in *AWS SDK for Java 2.x API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists all parameters.**
```
Get-SSMParameterList
```
**Output:**
```
Description :
KeyId :
LastModifiedDate : 3/3/2017 6:58:23 PM
LastModifiedUser : arn:aws:iam::123456789012:user/admin
Name : Welcome
Type : String
```
+ For API details, see [DescribeParameters](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists all parameters.**
```
Get-SSMParameterList
```
**Output:**
```
Description :
KeyId :
LastModifiedDate : 3/3/2017 6:58:23 PM
LastModifiedUser : arn:aws:iam::123456789012:user/admin
Name : Welcome
Type : String
```
+ For API details, see [DescribeParameters](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Rust ]
**SDK for Rust**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/ssm#code-examples).
```
async fn show_parameters(client: &Client) -> Result<(), Error> {
let resp = client.describe_parameters().send().await?;
for param in resp.parameters() {
println!(" {}", param.name().unwrap_or_default());
}
Ok(())
}
```
+ For API details, see [DescribeParameters](https://docs.rs/aws-sdk-ssm/latest/aws_sdk_ssm/client/struct.Client.html#method.describe_parameters) in *AWS SDK for Rust API reference*.
------
# Use `DescribePatchBaselines` with a CLI
<a name="ssm_example_ssm_DescribePatchBaselines_section"></a>
The following code examples show how to use `DescribePatchBaselines`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To list all patch baselines**
The following `describe-patch-baselines` example retrieves details for all patch baselines in your account in the current Region.
```
aws ssm describe-patch-baselines
```
Output:
```
{
"BaselineIdentities": [
{
"BaselineName": "AWS-SuseDefaultPatchBaseline",
"DefaultBaseline": true,
"BaselineDescription": "Default Patch Baseline for Suse Provided by AWS.",
"BaselineId": "arn:aws:ssm:us-east-2:733109147000:patchbaseline/pb-0123fdb36e334a3b2",
"OperatingSystem": "SUSE"
},
{
"BaselineName": "AWS-DefaultPatchBaseline",
"DefaultBaseline": false,
"BaselineDescription": "Default Patch Baseline Provided by AWS.",
"BaselineId": "arn:aws:ssm:us-east-2:733109147000:patchbaseline/pb-020d361a05defe4ed",
"OperatingSystem": "WINDOWS"
},
...
{
"BaselineName": "MyWindowsPatchBaseline",
"DefaultBaseline": true,
"BaselineDescription": "My patch baseline for EC2 instances for Windows Server",
"BaselineId": "pb-0ad00e0dd7EXAMPLE",
"OperatingSystem": "WINDOWS"
}
]
}
```
**Example 2: To list all patch baselines provided by AWS**
The following `describe-patch-baselines` example lists all patch baselines provided by AWS.
```
aws ssm describe-patch-baselines \
--filters "Key=OWNER,Values=[AWS]"
```
**Example 3: To list all patch baselines that you own**
The following `describe-patch-baselines` example lists all custom patch baselines created in your account in the current Region.
```
aws ssm describe-patch-baselines \
--filters "Key=OWNER,Values=[Self]"
```
For more information, see [About Predefined and Custom Patch Baselines](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-baselines.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribePatchBaselines](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-patch-baselines.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists all patch baselines.**
```
Get-SSMPatchBaseline
```
**Output:**
```
BaselineDescription BaselineId BaselineName
------------------- ---------- ------------
Default Patch Baseline Provided by AWS. arn:aws:ssm:us-west-2:123456789012:patchbaseline/pb-04fb4ae6142167966 AWS-DefaultP...
Baseline containing all updates approved for production systems pb-045f10b4f382baeda Production-B...
Baseline containing all updates approved for production systems pb-0a2f1059b670ebd31 Production-B...
```
**Example 2: This example lists all patch baselines provided by AWS. The syntax used by this example requires PowerShell version 3 or later.**
```
$filter1 = @{Key="OWNER";Values=@("AWS")}
```
**Output:**
```
Get-SSMPatchBaseline -Filter $filter1
```
**Example 3: This example lists all patch baselines with you as the owner. The syntax used by this example requires PowerShell version 3 or later.**
```
$filter1 = @{Key="OWNER";Values=@("Self")}
```
**Output:**
```
Get-SSMPatchBaseline -Filter $filter1
```
**Example 4: With PowerShell version 2, you must use New-Object to create each tag.**
```
$filter1 = New-Object Amazon.SimpleSystemsManagement.Model.PatchOrchestratorFilter
$filter1.Key = "OWNER"
$filter1.Values = "AWS"
Get-SSMPatchBaseline -Filter $filter1
```
**Output:**
```
BaselineDescription BaselineId BaselineName DefaultBaselin
e
------------------- ---------- ------------ --------------
Default Patch Baseline Provided by AWS. arn:aws:ssm:us-west-2:123456789012:patchbaseline/pb-04fb4ae6142167966 AWS-DefaultPatchBaseline True
```
+ For API details, see [DescribePatchBaselines](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists all patch baselines.**
```
Get-SSMPatchBaseline
```
**Output:**
```
BaselineDescription BaselineId BaselineName
------------------- ---------- ------------
Default Patch Baseline Provided by AWS. arn:aws:ssm:us-west-2:123456789012:patchbaseline/pb-04fb4ae6142167966 AWS-DefaultP...
Baseline containing all updates approved for production systems pb-045f10b4f382baeda Production-B...
Baseline containing all updates approved for production systems pb-0a2f1059b670ebd31 Production-B...
```
**Example 2: This example lists all patch baselines provided by AWS. The syntax used by this example requires PowerShell version 3 or later.**
```
$filter1 = @{Key="OWNER";Values=@("AWS")}
```
**Output:**
```
Get-SSMPatchBaseline -Filter $filter1
```
**Example 3: This example lists all patch baselines with you as the owner. The syntax used by this example requires PowerShell version 3 or later.**
```
$filter1 = @{Key="OWNER";Values=@("Self")}
```
**Output:**
```
Get-SSMPatchBaseline -Filter $filter1
```
**Example 4: With PowerShell version 2, you must use New-Object to create each tag.**
```
$filter1 = New-Object Amazon.SimpleSystemsManagement.Model.PatchOrchestratorFilter
$filter1.Key = "OWNER"
$filter1.Values = "AWS"
Get-SSMPatchBaseline -Filter $filter1
```
**Output:**
```
BaselineDescription BaselineId BaselineName DefaultBaselin
e
------------------- ---------- ------------ --------------
Default Patch Baseline Provided by AWS. arn:aws:ssm:us-west-2:123456789012:patchbaseline/pb-04fb4ae6142167966 AWS-DefaultPatchBaseline True
```
+ For API details, see [DescribePatchBaselines](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribePatchGroupState` with a CLI
<a name="ssm_example_ssm_DescribePatchGroupState_section"></a>
The following code examples show how to use `DescribePatchGroupState`.
------
#### [ CLI ]
**AWS CLI**
**To get the state of a patch group**
The following `describe-patch-group-state` example retrieves the high-level patch compliance summary for a patch group.
```
aws ssm describe-patch-group-state \
--patch-group "Production"
```
Output:
```
{
"Instances": 21,
"InstancesWithCriticalNonCompliantPatches": 1,
"InstancesWithFailedPatches": 2,
"InstancesWithInstalledOtherPatches": 3,
"InstancesWithInstalledPatches": 21,
"InstancesWithInstalledPendingRebootPatches": 2,
"InstancesWithInstalledRejectedPatches": 1,
"InstancesWithMissingPatches": 3,
"InstancesWithNotApplicablePatches": 4,
"InstancesWithOtherNonCompliantPatches": 1,
"InstancesWithSecurityNonCompliantPatches": 1,
"InstancesWithUnreportedNotApplicablePatches": 2
}
```
For more information, see About patch groups <https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-patchgroups.html>\$1\$1 and [Understanding patch compliance state values](https://docs.aws.amazon.com/systems-manager/latest/userguide/about-patch-compliance-states.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribePatchGroupState](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-patch-group-state.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example gets the high-level patch compliance summary for a patch group.**
```
Get-SSMPatchGroupState -PatchGroup "Production"
```
**Output:**
```
Instances : 4
InstancesWithFailedPatches : 1
InstancesWithInstalledOtherPatches : 4
InstancesWithInstalledPatches : 3
InstancesWithMissingPatches : 0
InstancesWithNotApplicablePatches : 0
```
+ For API details, see [DescribePatchGroupState](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example gets the high-level patch compliance summary for a patch group.**
```
Get-SSMPatchGroupState -PatchGroup "Production"
```
**Output:**
```
Instances : 4
InstancesWithFailedPatches : 1
InstancesWithInstalledOtherPatches : 4
InstancesWithInstalledPatches : 3
InstancesWithMissingPatches : 0
InstancesWithNotApplicablePatches : 0
```
+ For API details, see [DescribePatchGroupState](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `DescribePatchGroups` with a CLI
<a name="ssm_example_ssm_DescribePatchGroups_section"></a>
The following code examples show how to use `DescribePatchGroups`.
------
#### [ CLI ]
**AWS CLI**
**To display patch group registrations**
The following `describe-patch-groups` example lists the patch group registrations.
```
aws ssm describe-patch-groups
```
Output:
```
{
"Mappings": [
{
"PatchGroup": "Production",
"BaselineIdentity": {
"BaselineId": "pb-0123456789abcdef0",
"BaselineName": "ProdPatching",
"OperatingSystem": "WINDOWS",
"BaselineDescription": "Patches for Production",
"DefaultBaseline": false
}
},
{
"PatchGroup": "Development",
"BaselineIdentity": {
"BaselineId": "pb-0713accee01234567",
"BaselineName": "DevPatching",
"OperatingSystem": "WINDOWS",
"BaselineDescription": "Patches for Development",
"DefaultBaseline": true
}
},
...
]
}
```
For more information, see Create a Patch Group <https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-group-tagging.html>\$1\$1 and [Add a Patch Group to a Patch Baseline](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-group-patchbaseline.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [DescribePatchGroups](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/describe-patch-groups.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists the patch group registrations.**
```
Get-SSMPatchGroup
```
**Output:**
```
BaselineIdentity PatchGroup
---------------- ----------
Amazon.SimpleSystemsManagement.Model.PatchBaselineIdentity Production
```
+ For API details, see [DescribePatchGroups](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists the patch group registrations.**
```
Get-SSMPatchGroup
```
**Output:**
```
BaselineIdentity PatchGroup
---------------- ----------
Amazon.SimpleSystemsManagement.Model.PatchBaselineIdentity Production
```
+ For API details, see [DescribePatchGroups](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetAutomationExecution` with a CLI
<a name="ssm_example_ssm_GetAutomationExecution_section"></a>
The following code examples show how to use `GetAutomationExecution`.
------
#### [ CLI ]
**AWS CLI**
**To display details about an automation execution**
The following `get-automation-execution` example displays detailed information about an Automation execution.
```
aws ssm get-automation-execution \
--automation-execution-id 73c8eef8-f4ee-4a05-820c-e354fEXAMPLE
```
Output:
```
{
"AutomationExecution": {
"AutomationExecutionId": "73c8eef8-f4ee-4a05-820c-e354fEXAMPLE",
"DocumentName": "AWS-StartEC2Instance",
"DocumentVersion": "1",
"ExecutionStartTime": 1583737233.748,
"ExecutionEndTime": 1583737234.719,
"AutomationExecutionStatus": "Success",
"StepExecutions": [
{
"StepName": "startInstances",
"Action": "aws:changeInstanceState",
"ExecutionStartTime": 1583737234.134,
"ExecutionEndTime": 1583737234.672,
"StepStatus": "Success",
"Inputs": {
"DesiredState": "\"running\"",
"InstanceIds": "[\"i-0cb99161f6EXAMPLE\"]"
},
"Outputs": {
"InstanceStates": [
"running"
]
},
"StepExecutionId": "95e70479-cf20-4d80-8018-7e4e2EXAMPLE",
"OverriddenParameters": {}
}
],
"StepExecutionsTruncated": false,
"Parameters": {
"AutomationAssumeRole": [
""
],
"InstanceId": [
"i-0cb99161f6EXAMPLE"
]
},
"Outputs": {},
"Mode": "Auto",
"ExecutedBy": "arn:aws:sts::29884EXAMPLE:assumed-role/mw_service_role/OrchestrationService",
"Targets": [],
"ResolvedTargets": {
"ParameterValues": [],
"Truncated": false
}
}
}
```
For more information, see [Walkthrough: Patch a Linux AMI (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-walk-patch-linux-ami-cli.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [GetAutomationExecution](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-automation-execution.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example displays the details of an Automation Execution.**
```
Get-SSMAutomationExecution -AutomationExecutionId "4105a4fc-f944-11e6-9d32-8fb2db27a909"
```
**Output:**
```
AutomationExecutionId : 4105a4fc-f944-11e6-9d32-8fb2db27a909
AutomationExecutionStatus : Failed
DocumentName : AWS-UpdateLinuxAmi
DocumentVersion : 1
ExecutionEndTime : 2/22/2017 9:17:08 PM
ExecutionStartTime : 2/22/2017 9:17:02 PM
FailureMessage : Step launchInstance failed maximum allowed times. You are not authorized to perform this operation. Encoded
authorization failure message: B_V2QyyN7NhSZQYpmVzpEc4oSnj2GLTNYnXUHsTbqJkNMoDgubmbtthLmZyaiUYekORIrA42-fv1x-04q5Fjff6glh
Yb6TI5b0GQeeNrpwNvpDzmO-PSR1swlAbg9fdM9BcNjyrznspUkWpuKu9EC1Ou6v3OXU1KC9nZ7mPlWMFZNkSioQqpwWEvMw-GZktsQzm67qOhUhBNOLWYhbS
pkfiqzY-5nw3S0obx30fhd3EJa5O_-GjV_a0nFXQJa70ik40bFOrEh3MtCSbrQT6--DvFy_FQ8TKvkIXadyVskeJI84XOF5WmA60f1pi5GI08i-nRfZS6oDeU
gELBjjoFKD8s3L2aI0B6umWVxnQOjqhQRxwJ53b54sZJ2PW3v_mtg9-q0CK0ezS3xfh_y0ilaUGOAZG-xjQFuvU_JZedWpla3xi-MZsmblAifBI
(Service: AmazonEC2; Status Code: 403; Error Code: UnauthorizedOperation; Request ID:
6a002f94-ba37-43fd-99e6-39517715fce5)
Outputs : {[createImage.ImageId, Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
Parameters : {[AutomationAssumeRole, Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]], [InstanceIamRole,
Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]], [SourceAmiId,
Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
StepExecutions : {launchInstance, updateOSSoftware, stopInstance, createImage...}
```
**Example 2: This example lists step details for the given automation execution id**
```
Get-SSMAutomationExecution -AutomationExecutionId e1d2bad3-4567-8901-ae23-456c7c8901be | Select-Object -ExpandProperty StepExecutions | Select-Object StepName, Action, StepStatus, ValidNextSteps
```
**Output:**
```
StepName Action StepStatus ValidNextSteps
-------- ------ ---------- --------------
LaunchInstance aws:runInstances Success {OSCompatibilityCheck}
OSCompatibilityCheck aws:runCommand Success {RunPreUpdateScript}
RunPreUpdateScript aws:runCommand Success {UpdateEC2Config}
UpdateEC2Config aws:runCommand Cancelled {}
UpdateSSMAgent aws:runCommand Pending {}
UpdateAWSPVDriver aws:runCommand Pending {}
UpdateAWSEnaNetworkDriver aws:runCommand Pending {}
UpdateAWSNVMe aws:runCommand Pending {}
InstallWindowsUpdates aws:runCommand Pending {}
RunPostUpdateScript aws:runCommand Pending {}
RunSysprepGeneralize aws:runCommand Pending {}
StopInstance aws:changeInstanceState Pending {}
CreateImage aws:createImage Pending {}
TerminateInstance aws:changeInstanceState Pending {}
```
+ For API details, see [GetAutomationExecution](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example displays the details of an Automation Execution.**
```
Get-SSMAutomationExecution -AutomationExecutionId "4105a4fc-f944-11e6-9d32-8fb2db27a909"
```
**Output:**
```
AutomationExecutionId : 4105a4fc-f944-11e6-9d32-8fb2db27a909
AutomationExecutionStatus : Failed
DocumentName : AWS-UpdateLinuxAmi
DocumentVersion : 1
ExecutionEndTime : 2/22/2017 9:17:08 PM
ExecutionStartTime : 2/22/2017 9:17:02 PM
FailureMessage : Step launchInstance failed maximum allowed times. You are not authorized to perform this operation. Encoded
authorization failure message: B_V2QyyN7NhSZQYpmVzpEc4oSnj2GLTNYnXUHsTbqJkNMoDgubmbtthLmZyaiUYekORIrA42-fv1x-04q5Fjff6glh
Yb6TI5b0GQeeNrpwNvpDzmO-PSR1swlAbg9fdM9BcNjyrznspUkWpuKu9EC1Ou6v3OXU1KC9nZ7mPlWMFZNkSioQqpwWEvMw-GZktsQzm67qOhUhBNOLWYhbS
pkfiqzY-5nw3S0obx30fhd3EJa5O_-GjV_a0nFXQJa70ik40bFOrEh3MtCSbrQT6--DvFy_FQ8TKvkIXadyVskeJI84XOF5WmA60f1pi5GI08i-nRfZS6oDeU
gELBjjoFKD8s3L2aI0B6umWVxnQOjqhQRxwJ53b54sZJ2PW3v_mtg9-q0CK0ezS3xfh_y0ilaUGOAZG-xjQFuvU_JZedWpla3xi-MZsmblAifBI
(Service: AmazonEC2; Status Code: 403; Error Code: UnauthorizedOperation; Request ID:
6a002f94-ba37-43fd-99e6-39517715fce5)
Outputs : {[createImage.ImageId, Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
Parameters : {[AutomationAssumeRole, Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]], [InstanceIamRole,
Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]], [SourceAmiId,
Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
StepExecutions : {launchInstance, updateOSSoftware, stopInstance, createImage...}
```
**Example 2: This example lists step details for the given automation execution id**
```
Get-SSMAutomationExecution -AutomationExecutionId e1d2bad3-4567-8901-ae23-456c7c8901be | Select-Object -ExpandProperty StepExecutions | Select-Object StepName, Action, StepStatus, ValidNextSteps
```
**Output:**
```
StepName Action StepStatus ValidNextSteps
-------- ------ ---------- --------------
LaunchInstance aws:runInstances Success {OSCompatibilityCheck}
OSCompatibilityCheck aws:runCommand Success {RunPreUpdateScript}
RunPreUpdateScript aws:runCommand Success {UpdateEC2Config}
UpdateEC2Config aws:runCommand Cancelled {}
UpdateSSMAgent aws:runCommand Pending {}
UpdateAWSPVDriver aws:runCommand Pending {}
UpdateAWSEnaNetworkDriver aws:runCommand Pending {}
UpdateAWSNVMe aws:runCommand Pending {}
InstallWindowsUpdates aws:runCommand Pending {}
RunPostUpdateScript aws:runCommand Pending {}
RunSysprepGeneralize aws:runCommand Pending {}
StopInstance aws:changeInstanceState Pending {}
CreateImage aws:createImage Pending {}
TerminateInstance aws:changeInstanceState Pending {}
```
+ For API details, see [GetAutomationExecution](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetCommandInvocation` with a CLI
<a name="ssm_example_ssm_GetCommandInvocation_section"></a>
The following code examples show how to use `GetCommandInvocation`.
------
#### [ CLI ]
**AWS CLI**
**To display the details of a command invocation**
The following `get-command-invocation` example lists all the invocations of the specified command on the specified instance.
```
aws ssm get-command-invocation \
--command-id "ef7fdfd8-9b57-4151-a15c-db9a12345678" \
--instance-id "i-1234567890abcdef0"
```
Output:
```
{
"CommandId": "ef7fdfd8-9b57-4151-a15c-db9a12345678",
"InstanceId": "i-1234567890abcdef0",
"Comment": "b48291dd-ba76-43e0-b9df-13e11ddaac26:6960febb-2907-4b59-8e1a-d6ce8EXAMPLE",
"DocumentName": "AWS-UpdateSSMAgent",
"DocumentVersion": "",
"PluginName": "aws:updateSsmAgent",
"ResponseCode": 0,
"ExecutionStartDateTime": "2020-02-19T18:18:03.419Z",
"ExecutionElapsedTime": "PT0.091S",
"ExecutionEndDateTime": "2020-02-19T18:18:03.419Z",
"Status": "Success",
"StatusDetails": "Success",
"StandardOutputContent": "Updating amazon-ssm-agent from 2.3.842.0 to latest\nSuccessfully downloaded https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/ssm-agent-manifest.json\namazon-ssm-agent 2.3.842.0 has already been installed, update skipped\n",
"StandardOutputUrl": "",
"StandardErrorContent": "",
"StandardErrorUrl": "",
"CloudWatchOutputConfig": {
"CloudWatchLogGroupName": "",
"CloudWatchOutputEnabled": false
}
}
```
For more information, see [Understanding Command Statuses](https://docs.aws.amazon.com/systems-manager/latest/userguide/monitor-commands.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [GetCommandInvocation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-command-invocation.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example displays the details of a command executed on an instance.**
```
Get-SSMCommandInvocationDetail -InstanceId "i-0cb2b964d3e14fd9f" -CommandId "b8eac879-0541-439d-94ec-47a80d554f44"
```
**Output:**
```
CommandId : b8eac879-0541-439d-94ec-47a80d554f44
Comment : IP config
DocumentName : AWS-RunShellScript
ExecutionElapsedTime : PT0.004S
ExecutionEndDateTime : 2017-02-22T20:13:16.651Z
ExecutionStartDateTime : 2017-02-22T20:13:16.651Z
InstanceId : i-0cb2b964d3e14fd9f
PluginName : aws:runShellScript
ResponseCode : 0
StandardErrorContent :
StandardErrorUrl :
StandardOutputContent :
StandardOutputUrl :
Status : Success
StatusDetails : Success
```
+ For API details, see [GetCommandInvocation](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example displays the details of a command executed on an instance.**
```
Get-SSMCommandInvocationDetail -InstanceId "i-0cb2b964d3e14fd9f" -CommandId "b8eac879-0541-439d-94ec-47a80d554f44"
```
**Output:**
```
CommandId : b8eac879-0541-439d-94ec-47a80d554f44
Comment : IP config
DocumentName : AWS-RunShellScript
ExecutionElapsedTime : PT0.004S
ExecutionEndDateTime : 2017-02-22T20:13:16.651Z
ExecutionStartDateTime : 2017-02-22T20:13:16.651Z
InstanceId : i-0cb2b964d3e14fd9f
PluginName : aws:runShellScript
ResponseCode : 0
StandardErrorContent :
StandardErrorUrl :
StandardOutputContent :
StandardOutputUrl :
Status : Success
StatusDetails : Success
```
+ For API details, see [GetCommandInvocation](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetConnectionStatus` with a CLI
<a name="ssm_example_ssm_GetConnectionStatus_section"></a>
The following code examples show how to use `GetConnectionStatus`.
------
#### [ CLI ]
**AWS CLI**
**To display the connection status of a managed instance**
This `get-connection-status` example returns the connection status of the specified managed instance.
```
aws ssm get-connection-status \
--target i-1234567890abcdef0
```
Output:
```
{
"Target": "i-1234567890abcdef0",
"Status": "connected"
}
```
+ For API details, see [GetConnectionStatus](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-connection-status.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example retrieves the Session Manager connection status for an instance to determine whether it is connected and ready to receive Session Manager connections. **
```
Get-SSMConnectionStatus -Target i-0a1caf234f12d3dc4
```
**Output:**
```
Status Target
------ ------
Connected i-0a1caf234f12d3dc4
```
+ For API details, see [GetConnectionStatus](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example retrieves the Session Manager connection status for an instance to determine whether it is connected and ready to receive Session Manager connections. **
```
Get-SSMConnectionStatus -Target i-0a1caf234f12d3dc4
```
**Output:**
```
Status Target
------ ------
Connected i-0a1caf234f12d3dc4
```
+ For API details, see [GetConnectionStatus](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetDefaultPatchBaseline` with a CLI
<a name="ssm_example_ssm_GetDefaultPatchBaseline_section"></a>
The following code examples show how to use `GetDefaultPatchBaseline`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To display the default Windows patch baseline**
The following `get-default-patch-baseline` example retrieves details for the default patch baseline for Windows Server.
```
aws ssm get-default-patch-baseline
```
Output:
```
{
"BaselineId": "pb-0713accee01612345",
"OperatingSystem": "WINDOWS"
}
```
**Example 2: To display the default patch baseline for Amazon Linux**
The following `get-default-patch-baseline` example retrieves details for the default patch baseline for Amazon Linux.
```
aws ssm get-default-patch-baseline \
--operating-system AMAZON_LINUX
```
Output:
```
{
"BaselineId": "pb-047c6eb9c8fc12345",
"OperatingSystem": "AMAZON_LINUX"
}
```
For more information, see About Predefined and Custom Patch Baselines <https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-baselines.html>\$1\$1 and [Set an Existing Patch Baseline as the Default](https://docs.aws.amazon.com/systems-manager/latest/userguide/set-default-patch-baseline.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [GetDefaultPatchBaseline](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-default-patch-baseline.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example displays the default patch baseline.**
```
Get-SSMDefaultPatchBaseline
```
**Output:**
```
arn:aws:ssm:us-west-2:123456789012:patchbaseline/pb-04fb4ae6142167966
```
+ For API details, see [GetDefaultPatchBaseline](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example displays the default patch baseline.**
```
Get-SSMDefaultPatchBaseline
```
**Output:**
```
arn:aws:ssm:us-west-2:123456789012:patchbaseline/pb-04fb4ae6142167966
```
+ For API details, see [GetDefaultPatchBaseline](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetDeployablePatchSnapshotForInstance` with a CLI
<a name="ssm_example_ssm_GetDeployablePatchSnapshotForInstance_section"></a>
The following code examples show how to use `GetDeployablePatchSnapshotForInstance`.
------
#### [ CLI ]
**AWS CLI**
**To retrieve the current snapshot for the patch baseline an instance uses**
The following `get-deployable-patch-snapshot-for-instance` example retrieves details for the current snapshot for the specified patch baseline used by an instance. This command must be run from the instance using the instance credentials. To ensure it uses the instance credentials, run `aws configure` and specify only the Region of your instance. Leave the `Access Key` and `Secret Key` fields empty.
Tip: Use `uuidgen` to generate a `snapshot-id`.
```
aws ssm get-deployable-patch-snapshot-for-instance \
--instance-id "i-1234567890abcdef0" \
--snapshot-id "521c3536-930c-4aa9-950e-01234567abcd"
```
Output:
```
{
"InstanceId": "i-1234567890abcdef0",
"SnapshotId": "521c3536-930c-4aa9-950e-01234567abcd",
"Product": "AmazonLinux2018.03",
"SnapshotDownloadUrl": "https://patch-baseline-snapshot-us-east-1.s3.amazonaws.com/ed85194ef27214f5984f28b4d664d14f7313568fea7d4b6ac6c10ad1f729d7e7-773304212436/AMAZON_LINUX-521c3536-930c-4aa9-950e-01234567abcd?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190215T164031Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=AKIAJ5C56P35AEBRX2QQ%2F20190215%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=efaaaf6e3878e77f48a6697e015efdbda9c426b09c5822055075c062f6ad2149"
}
```
For more information, see [Parameter name: Snapshot ID](https://docs.aws.amazon.com/systems-manager/latest/userguide/patch-manager-about-aws-runpatchbaseline.html#patch-manager-about-aws-runpatchbaseline-parameters-snapshot-id) in the *AWS Systems Manager User Guide*.
+ For API details, see [GetDeployablePatchSnapshotForInstance](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-deployable-patch-snapshot-for-instance.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example displays the current snapshot for the patch baseline used by an Instance. This command must be run from the instance using the instance credentials. To ensure it uses the instance credentials, the example passes an `Amazon.Runtime.InstanceProfileAWSCredentials` object to the Credentials parameter.**
```
$credentials = [Amazon.Runtime.InstanceProfileAWSCredentials]::new()
Get-SSMDeployablePatchSnapshotForInstance -SnapshotId "4681775b-098f-4435-a956-0ef33373ac11" -InstanceId "i-0cb2b964d3e14fd9f" -Credentials $credentials
```
**Output:**
```
InstanceId SnapshotDownloadUrl
---------- -------------------
i-0cb2b964d3e14fd9f https://patch-baseline-snapshot-us-west-2.s3-us-west-2.amazonaws.com/853d0d3db0f0cafe...1692/4681775b-098f-4435...
```
**Example 2: This example shows how to get the full SnapshotDownloadUrl. This command must be run from the instance using the instance credentials. To ensure it uses the instance credentials, the example configures the PowerShell session to use an `Amazon.Runtime.InstanceProfileAWSCredentials` object.**
```
Set-AWSCredential -Credential ([Amazon.Runtime.InstanceProfileAWSCredentials]::new())
(Get-SSMDeployablePatchSnapshotForInstance -SnapshotId "4681775b-098f-4435-a956-0ef33373ac11" -InstanceId "i-0cb2b964d3e14fd9f").SnapshotDownloadUrl
```
**Output:**
```
https://patch-baseline-snapshot-us-west-2.s3-us-west-2.amazonaws.com/853d0d3db0f0cafe...
```
+ For API details, see [GetDeployablePatchSnapshotForInstance](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example displays the current snapshot for the patch baseline used by an Instance. This command must be run from the instance using the instance credentials. To ensure it uses the instance credentials, the example passes an `Amazon.Runtime.InstanceProfileAWSCredentials` object to the Credentials parameter.**
```
$credentials = [Amazon.Runtime.InstanceProfileAWSCredentials]::new()
Get-SSMDeployablePatchSnapshotForInstance -SnapshotId "4681775b-098f-4435-a956-0ef33373ac11" -InstanceId "i-0cb2b964d3e14fd9f" -Credentials $credentials
```
**Output:**
```
InstanceId SnapshotDownloadUrl
---------- -------------------
i-0cb2b964d3e14fd9f https://patch-baseline-snapshot-us-west-2.s3-us-west-2.amazonaws.com/853d0d3db0f0cafe...1692/4681775b-098f-4435...
```
**Example 2: This example shows how to get the full SnapshotDownloadUrl. This command must be run from the instance using the instance credentials. To ensure it uses the instance credentials, the example configures the PowerShell session to use an `Amazon.Runtime.InstanceProfileAWSCredentials` object.**
```
Set-AWSCredential -Credential ([Amazon.Runtime.InstanceProfileAWSCredentials]::new())
(Get-SSMDeployablePatchSnapshotForInstance -SnapshotId "4681775b-098f-4435-a956-0ef33373ac11" -InstanceId "i-0cb2b964d3e14fd9f").SnapshotDownloadUrl
```
**Output:**
```
https://patch-baseline-snapshot-us-west-2.s3-us-west-2.amazonaws.com/853d0d3db0f0cafe...
```
+ For API details, see [GetDeployablePatchSnapshotForInstance](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetDocument` with a CLI
<a name="ssm_example_ssm_GetDocument_section"></a>
The following code examples show how to use `GetDocument`.
------
#### [ CLI ]
**AWS CLI**
**To get document content**
The following `get-document` example displays the content of a Systems Manager document.
```
aws ssm get-document \
--name "AWS-RunShellScript"
```
Output:
```
{
"Name": "AWS-RunShellScript",
"DocumentVersion": "1",
"Status": "Active",
"Content": "{\n \"schemaVersion\":\"1.2\",\n \"description\":\"Run a shell script or specify the commands to run.\",\n \"parameters\":{\n \"commands\":{\n \"type\":\"StringList\",\n \"description\":\"(Required) Specify a shell script or a command to run.\",\n \"minItems\":1,\n \"displayType\":\"textarea\"\n },\n \"workingDirectory\":{\n \"type\":\"String\",\n \"default\":\"\",\n \"description\":\"(Optional) The path to the working directory on your instance.\",\n \"maxChars\":4096\n },\n \"executionTimeout\":{\n \"type\":\"String\",\n \"default\":\"3600\",\n \"description\":\"(Optional) The time in seconds for a command to complete before it is considered to have failed. Default is 3600 (1 hour). Maximum is 172800 (48 hours).\",\n \"allowedPattern\":\"([1-9][0-9]{0,4})|(1[0-6][0-9]{4})|(17[0-1][0-9]{3})|(172[0-7][0-9]{2})|(172800)\"\n }\n },\n \"runtimeConfig\":{\n \"aws:runShellScript\":{\n \"properties\":[\n {\n \"id\":\"0.aws:runShellScript\",\n \"runCommand\":\"{{ commands }}\",\n \"workingDirectory\":\"{{ workingDirectory }}\",\n \"timeoutSeconds\":\"{{ executionTimeout }}\"\n }\n ]\n }\n }\n}\n",
"DocumentType": "Command",
"DocumentFormat": "JSON"
}
```
For more information, see [AWS Systems Manager Documents](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-ssm-docs.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [GetDocument](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-document.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example returns the content of a document.**
```
Get-SSMDocument -Name "RunShellScript"
```
**Output:**
```
Content
-------
{...
```
**Example 2: This example displays the complete contents of a document.**
```
(Get-SSMDocument -Name "RunShellScript").Content
{
"schemaVersion":"2.0",
"description":"Run an updated script",
"parameters":{
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
}
},
"mainSteps":[
{
"action":"aws:runShellScript",
"name":"runShellScript",
"inputs":{
"commands":"{{ commands }}"
}
},
{
"action":"aws:runPowerShellScript",
"name":"runPowerShellScript",
"inputs":{
"commands":"{{ commands }}"
}
}
]
}
```
+ For API details, see [GetDocument](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example returns the content of a document.**
```
Get-SSMDocument -Name "RunShellScript"
```
**Output:**
```
Content
-------
{...
```
**Example 2: This example displays the complete contents of a document.**
```
(Get-SSMDocument -Name "RunShellScript").Content
{
"schemaVersion":"2.0",
"description":"Run an updated script",
"parameters":{
"commands":{
"type":"StringList",
"description":"(Required) Specify a shell script or a command to run.",
"minItems":1,
"displayType":"textarea"
}
},
"mainSteps":[
{
"action":"aws:runShellScript",
"name":"runShellScript",
"inputs":{
"commands":"{{ commands }}"
}
},
{
"action":"aws:runPowerShellScript",
"name":"runPowerShellScript",
"inputs":{
"commands":"{{ commands }}"
}
}
]
}
```
+ For API details, see [GetDocument](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetInventory` with a CLI
<a name="ssm_example_ssm_GetInventory_section"></a>
The following code examples show how to use `GetInventory`.
------
#### [ CLI ]
**AWS CLI**
**To view your inventory**
This example gets the custom metadata for your inventory.
Command:
```
aws ssm get-inventory
```
Output:
```
{
"Entities": [
{
"Data": {
"AWS:InstanceInformation": {
"Content": [
{
"ComputerName": "ip-172-31-44-222.us-west-2.compute.internal",
"InstanceId": "i-0cb2b964d3e14fd9f",
"IpAddress": "172.31.44.222",
"AgentType": "amazon-ssm-agent",
"ResourceType": "EC2Instance",
"AgentVersion": "2.0.672.0",
"PlatformVersion": "2016.09",
"PlatformName": "Amazon Linux AMI",
"PlatformType": "Linux"
}
],
"TypeName": "AWS:InstanceInformation",
"SchemaVersion": "1.0",
"CaptureTime": "2017-02-20T18:03:58Z"
}
},
"Id": "i-0cb2b964d3e14fd9f"
}
]
}
```
+ For API details, see [GetInventory](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-inventory.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example gets the custom metadata for your inventory.**
```
Get-SSMInventory
```
**Output:**
```
Data Id
---- --
{[AWS:InstanceInformation, Amazon.SimpleSystemsManagement.Model.InventoryResultItem]} i-0cb2b964d3e14fd9f
```
+ For API details, see [GetInventory](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example gets the custom metadata for your inventory.**
```
Get-SSMInventory
```
**Output:**
```
Data Id
---- --
{[AWS:InstanceInformation, Amazon.SimpleSystemsManagement.Model.InventoryResultItem]} i-0cb2b964d3e14fd9f
```
+ For API details, see [GetInventory](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetInventorySchema` with a CLI
<a name="ssm_example_ssm_GetInventorySchema_section"></a>
The following code examples show how to use `GetInventorySchema`.
------
#### [ CLI ]
**AWS CLI**
**To view your inventory schema**
This example returns a list of inventory type names for the account.
Command:
```
aws ssm get-inventory-schema
```
Output:
```
{
"Schemas": [
{
"TypeName": "AWS:AWSComponent",
"Version": "1.0",
"Attributes": [
{
"Name": "Name",
"DataType": "STRING"
},
{
"Name": "ApplicationType",
"DataType": "STRING"
},
{
"Name": "Publisher",
"DataType": "STRING"
},
{
"Name": "Version",
"DataType": "STRING"
},
{
"Name": "InstalledTime",
"DataType": "STRING"
},
{
"Name": "Architecture",
"DataType": "STRING"
},
{
"Name": "URL",
"DataType": "STRING"
}
]
},
...
],
"NextToken": "--token string truncated--"
}
```
**To view the inventory schema for a specific inventory type**
This example return the inventory schema for a the AWS:AWSComponent inventory type.
Command:
```
aws ssm get-inventory-schema --type-name "AWS:AWSComponent"
```
+ For API details, see [GetInventorySchema](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-inventory-schema.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example returns a list of inventory type names for the account.**
```
Get-SSMInventorySchema
```
+ For API details, see [GetInventorySchema](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example returns a list of inventory type names for the account.**
```
Get-SSMInventorySchema
```
+ For API details, see [GetInventorySchema](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetMaintenanceWindow` with a CLI
<a name="ssm_example_ssm_GetMaintenanceWindow_section"></a>
The following code examples show how to use `GetMaintenanceWindow`.
------
#### [ CLI ]
**AWS CLI**
**To get information about a maintenance window**
The following `get-maintenance-window` example retrieves details about the specified maintenance window.
```
aws ssm get-maintenance-window \
--window-id "mw-03eb9db428EXAMPLE"
```
Output:
```
{
"AllowUnassociatedTargets": true,
"CreatedDate": 1515006912.957,
"Cutoff": 1,
"Duration": 6,
"Enabled": true,
"ModifiedDate": 2020-01-01T10:04:04.099Z,
"Name": "My-Maintenance-Window",
"Schedule": "rate(3 days)",
"WindowId": "mw-03eb9db428EXAMPLE",
"NextExecutionTime": "2020-02-25T00:08:15.099Z"
}
```
For more information, see [View information about maintenance windows (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/maintenance-windows-cli-tutorials-describe.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [GetMaintenanceWindow](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-maintenance-window.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example gets details about a maintenance window.**
```
Get-SSMMaintenanceWindow -WindowId "mw-03eb9db42890fb82d"
```
**Output:**
```
AllowUnassociatedTargets : False
CreatedDate : 2/20/2017 6:14:05 PM
Cutoff : 1
Duration : 2
Enabled : True
ModifiedDate : 2/20/2017 6:14:05 PM
Name : TestMaintWin
Schedule : cron(0 */30 * * * ? *)
WindowId : mw-03eb9db42890fb82d
```
+ For API details, see [GetMaintenanceWindow](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example gets details about a maintenance window.**
```
Get-SSMMaintenanceWindow -WindowId "mw-03eb9db42890fb82d"
```
**Output:**
```
AllowUnassociatedTargets : False
CreatedDate : 2/20/2017 6:14:05 PM
Cutoff : 1
Duration : 2
Enabled : True
ModifiedDate : 2/20/2017 6:14:05 PM
Name : TestMaintWin
Schedule : cron(0 */30 * * * ? *)
WindowId : mw-03eb9db42890fb82d
```
+ For API details, see [GetMaintenanceWindow](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetMaintenanceWindowExecution` with a CLI
<a name="ssm_example_ssm_GetMaintenanceWindowExecution_section"></a>
The following code examples show how to use `GetMaintenanceWindowExecution`.
------
#### [ CLI ]
**AWS CLI**
**To get information about a maintenance window task execution**
The following `get-maintenance-window-execution` example lists information about a task executed as part of the specified maintenance window execution.
```
aws ssm get-maintenance-window-execution \
--window-execution-id "518d5565-5969-4cca-8f0e-da3b2EXAMPLE"
```
Output:
```
{
"Status": "SUCCESS",
"TaskIds": [
"ac0c6ae1-daa3-4a89-832e-d3845EXAMPLE"
],
"StartTime": 1487692834.595,
"EndTime": 1487692835.051,
"WindowExecutionId": "518d5565-5969-4cca-8f0e-da3b2EXAMPLE",
}
```
For more information, see [View Information About Tasks and Task Executions (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/mw-cli-tutorial-task-info.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [GetMaintenanceWindowExecution](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-maintenance-window-execution.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists information about a task executed as part of a maintenance window execution.**
```
Get-SSMMaintenanceWindowExecution -WindowExecutionId "518d5565-5969-4cca-8f0e-da3b2a638355"
```
**Output:**
```
EndTime : 2/21/2017 4:00:35 PM
StartTime : 2/21/2017 4:00:34 PM
Status : FAILED
StatusDetails : One or more tasks in the orchestration failed.
TaskIds : {ac0c6ae1-daa3-4a89-832e-d384503b6586}
WindowExecutionId : 518d5565-5969-4cca-8f0e-da3b2a638355
```
+ For API details, see [GetMaintenanceWindowExecution](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists information about a task executed as part of a maintenance window execution.**
```
Get-SSMMaintenanceWindowExecution -WindowExecutionId "518d5565-5969-4cca-8f0e-da3b2a638355"
```
**Output:**
```
EndTime : 2/21/2017 4:00:35 PM
StartTime : 2/21/2017 4:00:34 PM
Status : FAILED
StatusDetails : One or more tasks in the orchestration failed.
TaskIds : {ac0c6ae1-daa3-4a89-832e-d384503b6586}
WindowExecutionId : 518d5565-5969-4cca-8f0e-da3b2a638355
```
+ For API details, see [GetMaintenanceWindowExecution](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetMaintenanceWindowExecutionTask` with a CLI
<a name="ssm_example_ssm_GetMaintenanceWindowExecutionTask_section"></a>
The following code examples show how to use `GetMaintenanceWindowExecutionTask`.
------
#### [ CLI ]
**AWS CLI**
**To get information about a maintenance window task execution**
The following `get-maintenance-window-execution-task` example lists information about a task that is part of the specified maintenance window execution.
```
aws ssm get-maintenance-window-execution-task \
--window-execution-id "518d5565-5969-4cca-8f0e-da3b2EXAMPLE" \
--task-id "ac0c6ae1-daa3-4a89-832e-d3845EXAMPLE"
```
Output:
```
{
"WindowExecutionId": "518d5565-5969-4cca-8f0e-da3b2EXAMPLE",
"TaskExecutionId": "ac0c6ae1-daa3-4a89-832e-d3845EXAMPLE",
"TaskArn": "AWS-RunPatchBaseline",
"ServiceRole": "arn:aws:iam::111222333444:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"Type": "RUN_COMMAND",
"TaskParameters": [
{
"BaselineOverride": {
"Values": [
""
]
},
"InstallOverrideList": {
"Values": [
""
]
},
"Operation": {
"Values": [
"Scan"
]
},
"RebootOption": {
"Values": [
"RebootIfNeeded"
]
},
"SnapshotId": {
"Values": [
"{{ aws:ORCHESTRATION_ID }}"
]
},
"aws:InstanceId": {
"Values": [
"i-02573cafcfEXAMPLE",
"i-0471e04240EXAMPLE",
"i-07782c72faEXAMPLE"
]
}
}
],
"Priority": 1,
"MaxConcurrency": "1",
"MaxErrors": "3",
"Status": "SUCCESS",
"StartTime": "2021-08-04T11:45:35.088000-07:00",
"EndTime": "2021-08-04T11:53:09.079000-07:00"
}
```
For more information, see [View information about tasks and task executions (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/mw-cli-tutorial-task-info.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [GetMaintenanceWindowExecutionTask](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-maintenance-window-execution-task.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists information about a task that was part of a maintenance window execution.**
```
Get-SSMMaintenanceWindowExecutionTask -TaskId "ac0c6ae1-daa3-4a89-832e-d384503b6586" -WindowExecutionId "518d5565-5969-4cca-8f0e-da3b2a638355"
```
**Output:**
```
EndTime : 2/21/2017 4:00:35 PM
MaxConcurrency : 1
MaxErrors : 1
Priority : 10
ServiceRole : arn:aws:iam::123456789012:role/MaintenanceWindowsRole
StartTime : 2/21/2017 4:00:34 PM
Status : FAILED
StatusDetails : The maximum error count was exceeded.
TaskArn : AWS-RunShellScript
TaskExecutionId : ac0c6ae1-daa3-4a89-832e-d384503b6586
TaskParameters : {Amazon.Runtime.Internal.Util.AlwaysSendDictionary`2[System.String,Amazon.SimpleSystemsManagement.Model.MaintenanceWindowTaskPara
meterValueExpression]}
Type : RUN_COMMAND
WindowExecutionId : 518d5565-5969-4cca-8f0e-da3b2a638355
```
+ For API details, see [GetMaintenanceWindowExecutionTask](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists information about a task that was part of a maintenance window execution.**
```
Get-SSMMaintenanceWindowExecutionTask -TaskId "ac0c6ae1-daa3-4a89-832e-d384503b6586" -WindowExecutionId "518d5565-5969-4cca-8f0e-da3b2a638355"
```
**Output:**
```
EndTime : 2/21/2017 4:00:35 PM
MaxConcurrency : 1
MaxErrors : 1
Priority : 10
ServiceRole : arn:aws:iam::123456789012:role/MaintenanceWindowsRole
StartTime : 2/21/2017 4:00:34 PM
Status : FAILED
StatusDetails : The maximum error count was exceeded.
TaskArn : AWS-RunShellScript
TaskExecutionId : ac0c6ae1-daa3-4a89-832e-d384503b6586
TaskParameters : {Amazon.Runtime.Internal.Util.AlwaysSendDictionary`2[System.String,Amazon.SimpleSystemsManagement.Model.MaintenanceWindowTaskPara
meterValueExpression]}
Type : RUN_COMMAND
WindowExecutionId : 518d5565-5969-4cca-8f0e-da3b2a638355
```
+ For API details, see [GetMaintenanceWindowExecutionTask](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetParameter` with an AWS SDK or CLI
<a name="ssm_example_ssm_GetParameter_section"></a>
The following code examples show how to use `GetParameter`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To display the value of a parameter**
The following `get-parameter` example lists the value for the specified single parameter.
```
aws ssm get-parameter \
--name "MyStringParameter"
```
Output:
```
{
"Parameter": {
"Name": "MyStringParameter",
"Type": "String",
"Value": "Veni",
"Version": 1,
"LastModifiedDate": 1530018761.888,
"ARN": "arn:aws:ssm:us-east-2:111222333444:parameter/MyStringParameter"
"DataType": "text"
}
}
```
For more information, see [Working with Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-working-with.html) in the *AWS Systems Manager User Guide*.
**Example 2: To decrypt the value of a SecureString parameter**
The following `get-parameter` example decrypts the value of the specified `SecureString` parameter.
```
aws ssm get-parameter \
--name "MySecureStringParameter" \
--with-decryption
```
Output:
```
{
"Parameter": {
"Name": "MySecureStringParameter",
"Type": "SecureString",
"Value": "16679b88-310b-4895-a943-e0764EXAMPLE",
"Version": 2,
"LastModifiedDate": 1582155479.205,
"ARN": "arn:aws:ssm:us-east-2:111222333444:parameter/MySecureStringParameter"
"DataType": "text"
}
}
```
For more information, see [Working with Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-working-with.html) in the *AWS Systems Manager User Guide*.
**Example 3: To display the value of a parameter using labels**
The following `get-parameter` example lists the value for the specified single parameter with a specified label.
```
aws ssm get-parameter \
--name "MyParameter:label"
```
Output:
```
{
"Parameter": {
"Name": "MyParameter",
"Type": "String",
"Value": "parameter version 2",
"Version": 2,
"Selector": ":label",
"LastModifiedDate": "2021-07-12T09:49:15.865000-07:00",
"ARN": "arn:aws:ssm:us-west-2:786973925828:parameter/MyParameter",
"DataType": "text"
}
}
```
For more information, see [Working with parameter labels](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-labels.html) in the *AWS Systems Manager User Guide*.
**Example 4: To display the value of a parameter using versions**
The following `get-parameter` example lists the value for the specified single parameter version.
```
aws ssm get-parameter \
--name "MyParameter:2"
```
Output:
```
{
"Parameter": {
"Name": "MyParameter",
"Type": "String",
"Value": "parameter version 2",
"Version": 2,
"Selector": ":2",
"LastModifiedDate": "2021-07-12T09:49:15.865000-07:00",
"ARN": "arn:aws:ssm:us-west-2:786973925828:parameter/MyParameter",
"DataType": "text"
}
}
```
For more information, see [Working with parameter labels](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-labels.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [GetParameter](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-parameter.html) in *AWS CLI Command Reference*.
------
#### [ Rust ]
**SDK for Rust**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/ssm#code-examples).
```
pub async fn list_path(&self, path: &str) -> Result<Vec<Parameter>, EC2Error> {
let maybe_params: Vec<Result<Parameter, _>> = TryFlatMap::new(
self.inner
.get_parameters_by_path()
.path(path)
.into_paginator()
.send(),
)
.flat_map(|item| item.parameters.unwrap_or_default())
.collect()
.await;
// Fail on the first error
let params = maybe_params
.into_iter()
.collect::<Result<Vec<Parameter>, _>>()?;
Ok(params)
}
```
+ For API details, see [GetParameter](https://docs.rs/aws-sdk-ssm/latest/aws_sdk_ssm/client/struct.Client.html#method.get_parameter) in *AWS SDK for Rust API reference*.
------
# Use `GetParameterHistory` with a CLI
<a name="ssm_example_ssm_GetParameterHistory_section"></a>
The following code examples show how to use `GetParameterHistory`.
------
#### [ CLI ]
**AWS CLI**
**To get a value history for a parameter**
The following `get-parameter-history` example lists the history of changes for the specified parameter, including its value.
```
aws ssm get-parameter-history \
--name "MyStringParameter"
```
Output:
```
{
"Parameters": [
{
"Name": "MyStringParameter",
"Type": "String",
"LastModifiedDate": 1582154711.976,
"LastModifiedUser": "arn:aws:iam::111222333444:user/Mary-Major",
"Description": "This is the first version of my String parameter",
"Value": "Veni",
"Version": 1,
"Labels": [],
"Tier": "Standard",
"Policies": []
},
{
"Name": "MyStringParameter",
"Type": "String",
"LastModifiedDate": 1582156093.471,
"LastModifiedUser": "arn:aws:iam::111222333444:user/Mary-Major",
"Description": "This is the second version of my String parameter",
"Value": "Vidi",
"Version": 2,
"Labels": [],
"Tier": "Standard",
"Policies": []
},
{
"Name": "MyStringParameter",
"Type": "String",
"LastModifiedDate": 1582156117.545,
"LastModifiedUser": "arn:aws:iam::111222333444:user/Mary-Major",
"Description": "This is the third version of my String parameter",
"Value": "Vici",
"Version": 3,
"Labels": [],
"Tier": "Standard",
"Policies": []
}
]
}
```
For more information, see [Working with parameter versions](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-versions.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [GetParameterHistory](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-parameter-history.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists the value history for a parameter.**
```
Get-SSMParameterHistory -Name "Welcome"
```
**Output:**
```
Description :
KeyId :
LastModifiedDate : 3/3/2017 6:55:25 PM
LastModifiedUser : arn:aws:iam::123456789012:user/admin
Name : Welcome
Type : String
Value : helloWorld
```
+ For API details, see [GetParameterHistory](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists the value history for a parameter.**
```
Get-SSMParameterHistory -Name "Welcome"
```
**Output:**
```
Description :
KeyId :
LastModifiedDate : 3/3/2017 6:55:25 PM
LastModifiedUser : arn:aws:iam::123456789012:user/admin
Name : Welcome
Type : String
Value : helloWorld
```
+ For API details, see [GetParameterHistory](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetParameters` with a CLI
<a name="ssm_example_ssm_GetParameters_section"></a>
The following code examples show how to use `GetParameters`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Creating an Amazon ECS service for the EC2 launch type](ssm_example_ecs_GettingStarted_018_section.md)
------
#### [ CLI ]
**AWS CLI**
**Example 1: To list the values for a parameter**
The following `get-parameters` example lists the values for the three specified parameters.
```
aws ssm get-parameters \
--names "MyStringParameter" "MyStringListParameter" "MyInvalidParameterName"
```
Output:
```
{
"Parameters": [
{
"Name": "MyStringListParameter",
"Type": "StringList",
"Value": "alpha,beta,gamma",
"Version": 1,
"LastModifiedDate": 1582154764.222,
"ARN": "arn:aws:ssm:us-east-2:111222333444:parameter/MyStringListParameter"
"DataType": "text"
},
{
"Name": "MyStringParameter",
"Type": "String",
"Value": "Vici",
"Version": 3,
"LastModifiedDate": 1582156117.545,
"ARN": "arn:aws:ssm:us-east-2:111222333444:parameter/MyStringParameter"
"DataType": "text"
}
],
"InvalidParameters": [
"MyInvalidParameterName"
]
}
```
For more information, see [Working with Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-working-with.html) in the *AWS Systems Manager User Guide*.
**Example 2: To list names and values of multiple parameters using the ``--query`` option**
The following `get-parameters` example lists the names and values for the specified parameters.
```
aws ssm get-parameters \
--names MyStringParameter MyStringListParameter \
--query "Parameters[*].{Name:Name,Value:Value}"
```
Output:
```
[
{
"Name": "MyStringListParameter",
"Value": "alpha,beta,gamma"
},
{
"Name": "MyStringParameter",
"Value": "Vidi"
}
]
```
For more information, see [Working with Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-working-with.html) in the *AWS Systems Manager User Guide*.
**Example 3: To display the value of a parameter using labels**
The following `get-parameter` example lists the value for the specified single parameter with a specified label.
```
aws ssm get-parameter \
--name "MyParameter:label"
```
Output:
```
{
"Parameters": [
{
"Name": "MyLabelParameter",
"Type": "String",
"Value": "parameter by label",
"Version": 1,
"Selector": ":label",
"LastModifiedDate": "2021-07-12T09:49:15.865000-07:00",
"ARN": "arn:aws:ssm:us-west-2:786973925828:parameter/MyParameter",
"DataType": "text"
},
{
"Name": "MyVersionParameter",
"Type": "String",
"Value": "parameter by version",
"Version": 2,
"Selector": ":2",
"LastModifiedDate": "2021-03-24T16:20:28.236000-07:00",
"ARN": "arn:aws:ssm:us-west-2:786973925828:parameter/unlabel-param",
"DataType": "text"
}
],
"InvalidParameters": []
}
```
For more information, see [Working with parameter labels](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-labels.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [GetParameters](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-parameters.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists the values for a parameter.**
```
Get-SSMParameterValue -Name "Welcome"
```
**Output:**
```
InvalidParameters Parameters
----------------- ----------
{} {Welcome}
```
**Example 2: This example lists the details of the value.**
```
(Get-SSMParameterValue -Name "Welcome").Parameters
```
**Output:**
```
Name Type Value
---- ---- -----
Welcome String Good day, Sunshine!
```
+ For API details, see [GetParameters](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists the values for a parameter.**
```
Get-SSMParameterValue -Name "Welcome"
```
**Output:**
```
InvalidParameters Parameters
----------------- ----------
{} {Welcome}
```
**Example 2: This example lists the details of the value.**
```
(Get-SSMParameterValue -Name "Welcome").Parameters
```
**Output:**
```
Name Type Value
---- ---- -----
Welcome String Good day, Sunshine!
```
+ For API details, see [GetParameters](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetPatchBaseline` with a CLI
<a name="ssm_example_ssm_GetPatchBaseline_section"></a>
The following code examples show how to use `GetPatchBaseline`.
------
#### [ CLI ]
**AWS CLI**
**To display a patch baseline**
The following `get-patch-baseline` example retrieves the details for the specified patch baseline.
```
aws ssm get-patch-baseline \
--baseline-id "pb-0123456789abcdef0"
```
Output:
```
{
"BaselineId": "pb-0123456789abcdef0",
"Name": "WindowsPatching",
"OperatingSystem": "WINDOWS",
"GlobalFilters": {
"PatchFilters": []
},
"ApprovalRules": {
"PatchRules": [
{
"PatchFilterGroup": {
"PatchFilters": [
{
"Key": "PRODUCT",
"Values": [
"WindowsServer2016"
]
}
]
},
"ComplianceLevel": "CRITICAL",
"ApproveAfterDays": 0,
"EnableNonSecurity": false
}
]
},
"ApprovedPatches": [],
"ApprovedPatchesComplianceLevel": "UNSPECIFIED",
"ApprovedPatchesEnableNonSecurity": false,
"RejectedPatches": [],
"RejectedPatchesAction": "ALLOW_AS_DEPENDENCY",
"PatchGroups": [
"QA",
"DEV"
],
"CreatedDate": 1550244180.465,
"ModifiedDate": 1550244180.465,
"Description": "Patches for Windows Servers",
"Sources": []
}
```
For more information, see [About Patch Baselines](https://docs.aws.amazon.com/systems-manager/latest/userguide/about-patch-baselines.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [GetPatchBaseline](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-patch-baseline.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example displays the details for a patch baseline.**
```
Get-SSMPatchBaselineDetail -BaselineId "pb-03da896ca3b68b639"
```
**Output:**
```
ApprovalRules : Amazon.SimpleSystemsManagement.Model.PatchRuleGroup
ApprovedPatches : {}
BaselineId : pb-03da896ca3b68b639
CreatedDate : 3/3/2017 5:02:19 PM
Description : Baseline containing all updates approved for production systems
GlobalFilters : Amazon.SimpleSystemsManagement.Model.PatchFilterGroup
ModifiedDate : 3/3/2017 5:02:19 PM
Name : Production-Baseline
PatchGroups : {}
RejectedPatches : {}
```
+ For API details, see [GetPatchBaseline](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example displays the details for a patch baseline.**
```
Get-SSMPatchBaselineDetail -BaselineId "pb-03da896ca3b68b639"
```
**Output:**
```
ApprovalRules : Amazon.SimpleSystemsManagement.Model.PatchRuleGroup
ApprovedPatches : {}
BaselineId : pb-03da896ca3b68b639
CreatedDate : 3/3/2017 5:02:19 PM
Description : Baseline containing all updates approved for production systems
GlobalFilters : Amazon.SimpleSystemsManagement.Model.PatchFilterGroup
ModifiedDate : 3/3/2017 5:02:19 PM
Name : Production-Baseline
PatchGroups : {}
RejectedPatches : {}
```
+ For API details, see [GetPatchBaseline](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `GetPatchBaselineForPatchGroup` with a CLI
<a name="ssm_example_ssm_GetPatchBaselineForPatchGroup_section"></a>
The following code examples show how to use `GetPatchBaselineForPatchGroup`.
------
#### [ CLI ]
**AWS CLI**
**To display the patch baseline for a patch group**
The following `get-patch-baseline-for-patch-group` example retrieves details about the patch baseline for the specified patch group.
```
aws ssm get-patch-baseline-for-patch-group \
--patch-group "DEV"
```
Output:
```
{
"PatchGroup": "DEV",
"BaselineId": "pb-0123456789abcdef0",
"OperatingSystem": "WINDOWS"
}
```
For more information, see Create a Patch Group <https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-group-tagging.html>\$1\$1 and [Add a Patch Group to a Patch Baseline](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-group-patchbaseline.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [GetPatchBaselineForPatchGroup](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-patch-baseline-for-patch-group.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example displays the patch baseline for a patch group.**
```
Get-SSMPatchBaselineForPatchGroup -PatchGroup "Production"
```
**Output:**
```
BaselineId PatchGroup
---------- ----------
pb-045f10b4f382baeda Production
```
+ For API details, see [GetPatchBaselineForPatchGroup](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example displays the patch baseline for a patch group.**
```
Get-SSMPatchBaselineForPatchGroup -PatchGroup "Production"
```
**Output:**
```
BaselineId PatchGroup
---------- ----------
pb-045f10b4f382baeda Production
```
+ For API details, see [GetPatchBaselineForPatchGroup](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `ListAssociationVersions` with a CLI
<a name="ssm_example_ssm_ListAssociationVersions_section"></a>
The following code examples show how to use `ListAssociationVersions`.
------
#### [ CLI ]
**AWS CLI**
**To list all versions of an association for a specific association ID**
The following `list-association-versions` example lists all versions of the specified associations.
```
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"
}
]
}
```
For more information, see [Working with associations in Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-associations.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [ListAssociationVersions](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/list-association-versions.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example retrieves all versions of the association provided.**
```
Get-SSMAssociationVersionList -AssociationId 123a45a0-c678-9012-3456-78901234db5e
```
**Output:**
```
AssociationId : 123a45a0-c678-9012-3456-78901234db5e
AssociationName :
AssociationVersion : 2
ComplianceSeverity :
CreatedDate : 3/12/2019 9:21:01 AM
DocumentVersion :
MaxConcurrency :
MaxErrors :
Name : AWS-GatherSoftwareInventory
OutputLocation :
Parameters : {}
ScheduleExpression :
Targets : {InstanceIds}
AssociationId : 123a45a0-c678-9012-3456-78901234db5e
AssociationName : test-case-1234567890
AssociationVersion : 1
ComplianceSeverity :
CreatedDate : 3/2/2019 8:53:29 AM
DocumentVersion :
MaxConcurrency :
MaxErrors :
Name : AWS-GatherSoftwareInventory
OutputLocation :
Parameters : {}
ScheduleExpression : rate(30minutes)
Targets : {InstanceIds}
```
+ For API details, see [ListAssociationVersions](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example retrieves all versions of the association provided.**
```
Get-SSMAssociationVersionList -AssociationId 123a45a0-c678-9012-3456-78901234db5e
```
**Output:**
```
AssociationId : 123a45a0-c678-9012-3456-78901234db5e
AssociationName :
AssociationVersion : 2
ComplianceSeverity :
CreatedDate : 3/12/2019 9:21:01 AM
DocumentVersion :
MaxConcurrency :
MaxErrors :
Name : AWS-GatherSoftwareInventory
OutputLocation :
Parameters : {}
ScheduleExpression :
Targets : {InstanceIds}
AssociationId : 123a45a0-c678-9012-3456-78901234db5e
AssociationName : test-case-1234567890
AssociationVersion : 1
ComplianceSeverity :
CreatedDate : 3/2/2019 8:53:29 AM
DocumentVersion :
MaxConcurrency :
MaxErrors :
Name : AWS-GatherSoftwareInventory
OutputLocation :
Parameters : {}
ScheduleExpression : rate(30minutes)
Targets : {InstanceIds}
```
+ For API details, see [ListAssociationVersions](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `ListAssociations` with a CLI
<a name="ssm_example_ssm_ListAssociations_section"></a>
The following code examples show how to use `ListAssociations`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To list your associations for a specific instance**
The following list-associations example lists all associations with the AssociationName, UpdateSSMAgent.
```
aws ssm list-associations /
--association-filter-list "key=AssociationName,value=UpdateSSMAgent"
```
Output:
```
{
"Associations": [
{
"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",
"AssociationStatusAggregatedCount": {
"Pending": 1
}
},
"ScheduleExpression": "cron(0 00 12 ? * SUN *)",
"AssociationName": "UpdateSSMAgent"
}
]
}
```
For more information, see [Working with associations in Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-associations.html) in the *Systems Manager User Guide*.
**Example 2: To list your associations for a specific document**
The following list-associations example lists all associations for the specified document.
```
aws ssm list-associations /
--association-filter-list "key=Name,value=AWS-UpdateSSMAgent"
```
Output:
```
{
"Associations": [
{
"Name": "AWS-UpdateSSMAgent",
"InstanceId": "i-1234567890abcdef0",
"AssociationId": "8dfe3659-4309-493a-8755-0123456789ab",
"AssociationVersion": "1",
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-1234567890abcdef0"
]
}
],
"LastExecutionDate": 1550505828.548,
"Overview": {
"Status": "Success",
"DetailedStatus": "Success",
"AssociationStatusAggregatedCount": {
"Success": 1
}
},
"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-9876543210abcdef0"
]
}
],
"LastExecutionDate": 1550507531.0,
"Overview": {
"Status": "Success",
"AssociationStatusAggregatedCount": {
"Success": 1
}
}
}
]
}
```
For more information, see [Working with associations in Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-associations.html) in the *Systems Manager User Guide*.
+ For API details, see [ListAssociations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/list-associations.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists all the associations for an instance. The syntax used by this example requires PowerShell version 3 or later.**
```
$filter1 = @{Key="InstanceId";Value=@("i-0000293ffd8c57862")}
Get-SSMAssociationList -AssociationFilterList $filter1
```
**Output:**
```
AssociationId : d8617c07-2079-4c18-9847-1655fc2698b0
DocumentVersion :
InstanceId : i-0000293ffd8c57862
LastExecutionDate : 2/20/2015 8:31:11 AM
Name : AWS-UpdateSSMAgent
Overview : Amazon.SimpleSystemsManagement.Model.AssociationOverview
ScheduleExpression :
Targets : {InstanceIds}
```
**Example 2: This example lists all associations for a configuration document. The syntax used by this example requires PowerShell version 3 or later.**
```
$filter2 = @{Key="Name";Value=@("AWS-UpdateSSMAgent")}
Get-SSMAssociationList -AssociationFilterList $filter2
```
**Output:**
```
AssociationId : d8617c07-2079-4c18-9847-1655fc2698b0
DocumentVersion :
InstanceId : i-0000293ffd8c57862
LastExecutionDate : 2/20/2015 8:31:11 AM
Name : AWS-UpdateSSMAgent
Overview : Amazon.SimpleSystemsManagement.Model.AssociationOverview
ScheduleExpression :
Targets : {InstanceIds}
```
**Example 3: With PowerShell version 2, you must use New-Object to create each filter.**
```
$filter1 = New-Object Amazon.SimpleSystemsManagement.Model.AssociationFilter
$filter1.Key = "InstanceId"
$filter1.Value = "i-0000293ffd8c57862"
Get-SSMAssociationList -AssociationFilterList $filter1
```
**Output:**
```
AssociationId : d8617c07-2079-4c18-9847-1655fc2698b0
DocumentVersion :
InstanceId : i-0000293ffd8c57862
LastExecutionDate : 2/20/2015 8:31:11 AM
Name : AWS-UpdateSSMAgent
Overview : Amazon.SimpleSystemsManagement.Model.AssociationOverview
ScheduleExpression :
Targets : {InstanceIds}
```
+ For API details, see [ListAssociations](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists all the associations for an instance. The syntax used by this example requires PowerShell version 3 or later.**
```
$filter1 = @{Key="InstanceId";Value=@("i-0000293ffd8c57862")}
Get-SSMAssociationList -AssociationFilterList $filter1
```
**Output:**
```
AssociationId : d8617c07-2079-4c18-9847-1655fc2698b0
DocumentVersion :
InstanceId : i-0000293ffd8c57862
LastExecutionDate : 2/20/2015 8:31:11 AM
Name : AWS-UpdateSSMAgent
Overview : Amazon.SimpleSystemsManagement.Model.AssociationOverview
ScheduleExpression :
Targets : {InstanceIds}
```
**Example 2: This example lists all associations for a configuration document. The syntax used by this example requires PowerShell version 3 or later.**
```
$filter2 = @{Key="Name";Value=@("AWS-UpdateSSMAgent")}
Get-SSMAssociationList -AssociationFilterList $filter2
```
**Output:**
```
AssociationId : d8617c07-2079-4c18-9847-1655fc2698b0
DocumentVersion :
InstanceId : i-0000293ffd8c57862
LastExecutionDate : 2/20/2015 8:31:11 AM
Name : AWS-UpdateSSMAgent
Overview : Amazon.SimpleSystemsManagement.Model.AssociationOverview
ScheduleExpression :
Targets : {InstanceIds}
```
**Example 3: With PowerShell version 2, you must use New-Object to create each filter.**
```
$filter1 = New-Object Amazon.SimpleSystemsManagement.Model.AssociationFilter
$filter1.Key = "InstanceId"
$filter1.Value = "i-0000293ffd8c57862"
Get-SSMAssociationList -AssociationFilterList $filter1
```
**Output:**
```
AssociationId : d8617c07-2079-4c18-9847-1655fc2698b0
DocumentVersion :
InstanceId : i-0000293ffd8c57862
LastExecutionDate : 2/20/2015 8:31:11 AM
Name : AWS-UpdateSSMAgent
Overview : Amazon.SimpleSystemsManagement.Model.AssociationOverview
ScheduleExpression :
Targets : {InstanceIds}
```
+ For API details, see [ListAssociations](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `ListCommandInvocations` with an AWS SDK or CLI
<a name="ssm_example_ssm_ListCommandInvocations_section"></a>
The following code examples show how to use `ListCommandInvocations`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](ssm_example_ssm_Scenario_section.md)
------
#### [ CLI ]
**AWS CLI**
**To list the invocations of a specific command**
The following `list-command-invocations` example lists all the invocations of a command.
```
aws ssm list-command-invocations \
--command-id "ef7fdfd8-9b57-4151-a15c-db9a12345678" \
--details
```
Output:
```
{
"CommandInvocations": [
{
"CommandId": "ef7fdfd8-9b57-4151-a15c-db9a12345678",
"InstanceId": "i-02573cafcfEXAMPLE",
"InstanceName": "",
"Comment": "b48291dd-ba76-43e0-b9df-13e11ddaac26:6960febb-2907-4b59-8e1a-d6ce8EXAMPLE",
"DocumentName": "AWS-UpdateSSMAgent",
"DocumentVersion": "",
"RequestedDateTime": 1582136283.089,
"Status": "Success",
"StatusDetails": "Success",
"StandardOutputUrl": "",
"StandardErrorUrl": "",
"CommandPlugins": [
{
"Name": "aws:updateSsmAgent",
"Status": "Success",
"StatusDetails": "Success",
"ResponseCode": 0,
"ResponseStartDateTime": 1582136283.419,
"ResponseFinishDateTime": 1582136283.51,
"Output": "Updating amazon-ssm-agent from 2.3.842.0 to latest\nSuccessfully downloaded https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/ssm-agent-manifest.json\namazon-ssm-agent 2.3.842.0 has already been installed, update skipped\n",
"StandardOutputUrl": "",
"StandardErrorUrl": "",
"OutputS3Region": "us-east-2",
"OutputS3BucketName": "",
"OutputS3KeyPrefix": ""
}
],
"ServiceRole": "",
"NotificationConfig": {
"NotificationArn": "",
"NotificationEvents": [],
"NotificationType": ""
},
"CloudWatchOutputConfig": {
"CloudWatchLogGroupName": "",
"CloudWatchOutputEnabled": false
}
},
{
"CommandId": "ef7fdfd8-9b57-4151-a15c-db9a12345678",
"InstanceId": "i-0471e04240EXAMPLE",
"InstanceName": "",
"Comment": "b48291dd-ba76-43e0-b9df-13e11ddaac26:6960febb-2907-4b59-8e1a-d6ce8EXAMPLE",
"DocumentName": "AWS-UpdateSSMAgent",
"DocumentVersion": "",
"RequestedDateTime": 1582136283.02,
"Status": "Success",
"StatusDetails": "Success",
"StandardOutputUrl": "",
"StandardErrorUrl": "",
"CommandPlugins": [
{
"Name": "aws:updateSsmAgent",
"Status": "Success",
"StatusDetails": "Success",
"ResponseCode": 0,
"ResponseStartDateTime": 1582136283.812,
"ResponseFinishDateTime": 1582136295.031,
"Output": "Updating amazon-ssm-agent from 2.3.672.0 to latest\nSuccessfully downloaded https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/ssm-agent-manifest.json\nSuccessfully downloaded https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/amazon-ssm-agent-updater/2.3.842.0/amazon-ssm-agent-updater-snap-amd64.tar.gz\nSuccessfully downloaded https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/amazon-ssm-agent/2.3.672.0/amazon-ssm-agent-snap-amd64.tar.gz\nSuccessfully downloaded https://s3.us-east-2.amazonaws.com/amazon-ssm-us-east-2/amazon-ssm-agent/2.3.842.0/amazon-ssm-agent-snap-amd64.tar.gz\nInitiating amazon-ssm-agent update to 2.3.842.0\namazon-ssm-agent updated successfully to 2.3.842.0",
"StandardOutputUrl": "",
"StandardErrorUrl": "",
"OutputS3Region": "us-east-2",
"OutputS3BucketName": "",
"OutputS3KeyPrefix": "8bee3135-398c-4d31-99b6-e42d2EXAMPLE/i-0471e04240EXAMPLE/awsupdateSsmAgent"
}
],
"ServiceRole": "",
"NotificationConfig": {
"NotificationArn": "",
"NotificationEvents": [],
"NotificationType": ""
},
"CloudWatchOutputConfig": {
"CloudWatchLogGroupName": "",
"CloudWatchOutputEnabled": false
}
}
]
}
```
For more information, see [Understanding Command Statuses](https://docs.aws.amazon.com/systems-manager/latest/userguide/monitor-commands.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [ListCommandInvocations](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/list-command-invocations.html) in *AWS CLI Command Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ssm#code-examples).
```
import { paginateListCommandInvocations, SSMClient } from "@aws-sdk/client-ssm";
import { parseArgs } from "node:util";
/**
* List SSM command invocations on an instance.
* @param {{ instanceId: string }}
*/
export const main = async ({ instanceId }) => {
const client = new SSMClient({});
try {
const listCommandInvocationsPaginated = [];
// The paginate function is a wrapper around the base command.
const paginator = paginateListCommandInvocations(
{ client },
{
InstanceId: instanceId,
},
);
for await (const page of paginator) {
listCommandInvocationsPaginated.push(...page.CommandInvocations);
}
console.log("Here is the list of command invocations:");
console.log(listCommandInvocationsPaginated);
return { CommandInvocations: listCommandInvocationsPaginated };
} catch (caught) {
if (caught instanceof Error && caught.name === "ValidationError") {
console.warn(`${caught.message}. Did you provide a valid instance ID?`);
}
throw caught;
}
};
```
+ For API details, see [ListCommandInvocations](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/ListCommandInvocationsCommand) in *AWS SDK for JavaScript API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists all the invocations of a command.**
```
Get-SSMCommandInvocation -CommandId "b8eac879-0541-439d-94ec-47a80d554f44" -Detail $true
```
**Output:**
```
CommandId : b8eac879-0541-439d-94ec-47a80d554f44
CommandPlugins : {aws:runShellScript}
Comment : IP config
DocumentName : AWS-RunShellScript
InstanceId : i-0cb2b964d3e14fd9f
InstanceName :
NotificationConfig : Amazon.SimpleSystemsManagement.Model.NotificationConfig
RequestedDateTime : 2/22/2017 8:13:16 PM
ServiceRole :
StandardErrorUrl :
StandardOutputUrl :
Status : Success
StatusDetails : Success
TraceOutput :
```
**Example 2: This example lists CommandPlugins for invocation of the command id e1eb2e3c-ed4c-5123-45c1-234f5612345f**
```
Get-SSMCommandInvocation -CommandId e1eb2e3c-ed4c-5123-45c1-234f5612345f -Detail:$true | Select-Object -ExpandProperty CommandPlugins
```
**Output:**
```
Name : aws:runPowerShellScript
Output : Completed 17.7 KiB/17.7 KiB (40.1 KiB/s) with 1 file(s) remainingdownload: s3://dd-aess-r-ctmer/KUMO.png to ..\..\programdata\KUMO.png
kumo available
OutputS3BucketName :
OutputS3KeyPrefix :
OutputS3Region : eu-west-1
ResponseCode : 0
ResponseFinishDateTime : 4/3/2019 11:53:23 AM
ResponseStartDateTime : 4/3/2019 11:53:21 AM
StandardErrorUrl :
StandardOutputUrl :
Status : Success
StatusDetails : Success
```
+ For API details, see [ListCommandInvocations](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists all the invocations of a command.**
```
Get-SSMCommandInvocation -CommandId "b8eac879-0541-439d-94ec-47a80d554f44" -Detail $true
```
**Output:**
```
CommandId : b8eac879-0541-439d-94ec-47a80d554f44
CommandPlugins : {aws:runShellScript}
Comment : IP config
DocumentName : AWS-RunShellScript
InstanceId : i-0cb2b964d3e14fd9f
InstanceName :
NotificationConfig : Amazon.SimpleSystemsManagement.Model.NotificationConfig
RequestedDateTime : 2/22/2017 8:13:16 PM
ServiceRole :
StandardErrorUrl :
StandardOutputUrl :
Status : Success
StatusDetails : Success
TraceOutput :
```
**Example 2: This example lists CommandPlugins for invocation of the command id e1eb2e3c-ed4c-5123-45c1-234f5612345f**
```
Get-SSMCommandInvocation -CommandId e1eb2e3c-ed4c-5123-45c1-234f5612345f -Detail:$true | Select-Object -ExpandProperty CommandPlugins
```
**Output:**
```
Name : aws:runPowerShellScript
Output : Completed 17.7 KiB/17.7 KiB (40.1 KiB/s) with 1 file(s) remainingdownload: s3://dd-aess-r-ctmer/KUMO.png to ..\..\programdata\KUMO.png
kumo available
OutputS3BucketName :
OutputS3KeyPrefix :
OutputS3Region : eu-west-1
ResponseCode : 0
ResponseFinishDateTime : 4/3/2019 11:53:23 AM
ResponseStartDateTime : 4/3/2019 11:53:21 AM
StandardErrorUrl :
StandardOutputUrl :
Status : Success
StatusDetails : Success
```
+ For API details, see [ListCommandInvocations](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
```
class DocumentWrapper:
"""Encapsulates AWS Systems Manager Document actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def list_command_invocations(self, instance_id):
"""
Lists the commands for an instance.
:param instance_id: The ID of the instance.
:return: The list of commands.
"""
try:
paginator = self.ssm_client.get_paginator("list_command_invocations")
command_invocations = []
for page in paginator.paginate(InstanceId=instance_id):
command_invocations.extend(page["CommandInvocations"])
num_of_commands = len(command_invocations)
print(
f"{num_of_commands} command invocation(s) found for instance {instance_id}."
)
if num_of_commands > 10:
print("Displaying the first 10 commands:")
num_of_commands = 10
date_format = "%A, %d %B %Y %I:%M%p"
for command in command_invocations[:num_of_commands]:
print(
f" The time of command invocation is {command['RequestedDateTime'].strftime(date_format)}"
)
except ClientError as err:
logger.error(
"Couldn't list commands for %s. Here's why: %s: %s",
instance_id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [ListCommandInvocations](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/ListCommandInvocations) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/ssm#code-examples).
```
TRY.
" Use paginator to get all results
DATA(lo_paginator) = lo_ssm->get_paginator( ).
DATA(lo_iterator) = lo_paginator->listcommandinvocations(
iv_instanceid = iv_instance_id ).
DATA lv_count TYPE i VALUE 0.
WHILE lo_iterator->has_next( ).
DATA(lo_result) = CAST /aws1/cl_ssmlistcmdinvcsresult( lo_iterator->get_next( ) ).
LOOP AT lo_result->get_commandinvocations( ) INTO DATA(lo_invocation).
lv_count = lv_count + 1.
DATA(lv_requested_datetime) = lo_invocation->get_requesteddatetime( ).
MESSAGE |Command invocation requested at: { lv_requested_datetime }| TYPE 'I'.
ENDLOOP.
ENDWHILE.
MESSAGE |{ lv_count } command invocation(s) found for instance { iv_instance_id }.| TYPE 'I'.
CATCH /aws1/cx_ssminvalidinstanceid.
MESSAGE 'Invalid instance ID.' TYPE 'I'.
CATCH /aws1/cx_ssminvalidcommandid.
MESSAGE 'Invalid command ID.' TYPE 'I'.
ENDTRY.
```
+ For API details, see [ListCommandInvocations](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------
# Use `ListCommands` with a CLI
<a name="ssm_example_ssm_ListCommands_section"></a>
The following code examples show how to use `ListCommands`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To get the status of a specific command**
The following `list-commands` example retrieves and displays the status of the specified command.
```
aws ssm list-commands \
--command-id "0831e1a8-a1ac-4257-a1fd-c831bEXAMPLE"
```
**Example 2: To get the status of commands requested after a specific date**
The following `list-commands` example retrieves the details of commands requested after the specified date.
```
aws ssm list-commands \
--filter "key=InvokedAfter,value=2020-02-01T00:00:00Z"
```
**Example 3: To list all commands requested in an AWS account**
The following `list-commands` example lists all commands requested by users in the current AWS account and Region.
```
aws ssm list-commands
```
Output:
```
{
"Commands": [
{
"CommandId": "8bee3135-398c-4d31-99b6-e42d2EXAMPLE",
"DocumentName": "AWS-UpdateSSMAgent",
"DocumentVersion": "",
"Comment": "b48291dd-ba76-43e0-b9df-13e11ddaac26:6960febb-2907-4b59-8e1a-d6ce8EXAMPLE",
"ExpiresAfter": "2020-02-19T11:28:02.500000-08:00",
"Parameters": {},
"InstanceIds": [
"i-028ea792daEXAMPLE",
"i-02feef8c46EXAMPLE",
"i-038613f3f0EXAMPLE",
"i-03a530a2d4EXAMPLE",
"i-083b678d37EXAMPLE",
"i-0dee81debaEXAMPLE"
],
"Targets": [],
"RequestedDateTime": "2020-02-19T10:18:02.500000-08:00",
"Status": "Success",
"StatusDetails": "Success",
"OutputS3BucketName": "",
"OutputS3KeyPrefix": "",
"MaxConcurrency": "50",
"MaxErrors": "100%",
"TargetCount": 6,
"CompletedCount": 6,
"ErrorCount": 0,
"DeliveryTimedOutCount": 0,
"ServiceRole": "",
"NotificationConfig": {
"NotificationArn": "",
"NotificationEvents": [],
"NotificationType": ""
},
"CloudWatchOutputConfig": {
"CloudWatchLogGroupName": "",
"CloudWatchOutputEnabled": false
}
}
{
"CommandId": "e9ade581-c03d-476b-9b07-26667EXAMPLE",
"DocumentName": "AWS-FindWindowsUpdates",
"DocumentVersion": "1",
"Comment": "",
"ExpiresAfter": "2020-01-24T12:37:31.874000-08:00",
"Parameters": {
"KbArticleIds": [
""
],
"UpdateLevel": [
"All"
]
},
"InstanceIds": [],
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-00ec29b21eEXAMPLE",
"i-09911ddd90EXAMPLE"
]
}
],
"RequestedDateTime": "2020-01-24T11:27:31.874000-08:00",
"Status": "Success",
"StatusDetails": "Success",
"OutputS3BucketName": "my-us-east-2-bucket",
"OutputS3KeyPrefix": "my-rc-output",
"MaxConcurrency": "50",
"MaxErrors": "0",
"TargetCount": 2,
"CompletedCount": 2,
"ErrorCount": 0,
"DeliveryTimedOutCount": 0,
"ServiceRole": "arn:aws:iam::111222333444:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"NotificationConfig": {
"NotificationArn": "arn:aws:sns:us-east-2:111222333444:my-us-east-2-notification-arn",
"NotificationEvents": [
"All"
],
"NotificationType": "Invocation"
},
"CloudWatchOutputConfig": {
"CloudWatchLogGroupName": "",
"CloudWatchOutputEnabled": false
}
}
{
"CommandId": "d539b6c3-70e8-4853-80e5-0ce4fEXAMPLE",
"DocumentName": "AWS-RunPatchBaseline",
"DocumentVersion": "1",
"Comment": "",
"ExpiresAfter": "2020-01-24T12:21:04.350000-08:00",
"Parameters": {
"InstallOverrideList": [
""
],
"Operation": [
"Install"
],
"RebootOption": [
"RebootIfNeeded"
],
"SnapshotId": [
""
]
},
"InstanceIds": [],
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-00ec29b21eEXAMPLE",
"i-09911ddd90EXAMPLE"
]
}
],
"RequestedDateTime": "2020-01-24T11:11:04.350000-08:00",
"Status": "Success",
"StatusDetails": "Success",
"OutputS3BucketName": "my-us-east-2-bucket",
"OutputS3KeyPrefix": "my-rc-output",
"MaxConcurrency": "50",
"MaxErrors": "0",
"TargetCount": 2,
"CompletedCount": 2,
"ErrorCount": 0,
"DeliveryTimedOutCount": 0,
"ServiceRole": "arn:aws:iam::111222333444:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"NotificationConfig": {
"NotificationArn": "arn:aws:sns:us-east-2:111222333444:my-us-east-2-notification-arn",
"NotificationEvents": [
"All"
],
"NotificationType": "Invocation"
},
"CloudWatchOutputConfig": {
"CloudWatchLogGroupName": "",
"CloudWatchOutputEnabled": false
}
}
]
}
```
For more information, see [Running Commands Using Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [ListCommands](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/list-commands.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists all commands requested.**
```
Get-SSMCommand
```
**Output:**
```
CommandId : 4b75a163-d39a-4d97-87c9-98ae52c6be35
Comment : Apply association with id at update time: 4cc73e42-d5ae-4879-84f8-57e09c0efcd0
CompletedCount : 1
DocumentName : AWS-RefreshAssociation
ErrorCount : 0
ExpiresAfter : 2/24/2017 3:19:08 AM
InstanceIds : {i-0cb2b964d3e14fd9f}
MaxConcurrency : 50
MaxErrors : 0
NotificationConfig : Amazon.SimpleSystemsManagement.Model.NotificationConfig
OutputS3BucketName :
OutputS3KeyPrefix :
OutputS3Region :
Parameters : {[associationIds, Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
RequestedDateTime : 2/24/2017 3:18:08 AM
ServiceRole :
Status : Success
StatusDetails : Success
TargetCount : 1
Targets : {}
```
**Example 2: This example gets the status of a specific command.**
```
Get-SSMCommand -CommandId "4b75a163-d39a-4d97-87c9-98ae52c6be35"
```
**Example 3: This example retrieves all SSM commands invoked after 2019-04-01T00:00:00Z **
```
Get-SSMCommand -Filter @{Key="InvokedAfter";Value="2019-04-01T00:00:00Z"} | Select-Object CommandId, DocumentName, Status, RequestedDateTime | Sort-Object -Property RequestedDateTime -Descending
```
**Output:**
```
CommandId DocumentName Status RequestedDateTime
--------- ------------ ------ -----------------
edb1b23e-456a-7adb-aef8-90e-012ac34f AWS-RunPowerShellScript Cancelled 4/16/2019 5:45:23 AM
1a2dc3fb-4567-890d-a1ad-234b5d6bc7d9 AWS-ConfigureAWSPackage Success 4/6/2019 9:19:42 AM
12c3456c-7e90-4f12-1232-1234f5b67893 KT-Retrieve-Cloud-Type-Win Failed 4/2/2019 4:13:07 AM
fe123b45-240c-4123-a2b3-234bdd567ecf AWS-RunInspecChecks Failed 4/1/2019 2:27:31 PM
1eb23aa4-567d-4123-12a3-4c1c2ab34561 AWS-RunPowerShellScript Success 4/1/2019 1:05:55 PM
1c2f3bb4-ee12-4bc1-1a23-12345eea123e AWS-RunInspecChecks Failed 4/1/2019 11:13:09 AM
```
+ For API details, see [ListCommands](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists all commands requested.**
```
Get-SSMCommand
```
**Output:**
```
CommandId : 4b75a163-d39a-4d97-87c9-98ae52c6be35
Comment : Apply association with id at update time: 4cc73e42-d5ae-4879-84f8-57e09c0efcd0
CompletedCount : 1
DocumentName : AWS-RefreshAssociation
ErrorCount : 0
ExpiresAfter : 2/24/2017 3:19:08 AM
InstanceIds : {i-0cb2b964d3e14fd9f}
MaxConcurrency : 50
MaxErrors : 0
NotificationConfig : Amazon.SimpleSystemsManagement.Model.NotificationConfig
OutputS3BucketName :
OutputS3KeyPrefix :
OutputS3Region :
Parameters : {[associationIds, Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
RequestedDateTime : 2/24/2017 3:18:08 AM
ServiceRole :
Status : Success
StatusDetails : Success
TargetCount : 1
Targets : {}
```
**Example 2: This example gets the status of a specific command.**
```
Get-SSMCommand -CommandId "4b75a163-d39a-4d97-87c9-98ae52c6be35"
```
**Example 3: This example retrieves all SSM commands invoked after 2019-04-01T00:00:00Z **
```
Get-SSMCommand -Filter @{Key="InvokedAfter";Value="2019-04-01T00:00:00Z"} | Select-Object CommandId, DocumentName, Status, RequestedDateTime | Sort-Object -Property RequestedDateTime -Descending
```
**Output:**
```
CommandId DocumentName Status RequestedDateTime
--------- ------------ ------ -----------------
edb1b23e-456a-7adb-aef8-90e-012ac34f AWS-RunPowerShellScript Cancelled 4/16/2019 5:45:23 AM
1a2dc3fb-4567-890d-a1ad-234b5d6bc7d9 AWS-ConfigureAWSPackage Success 4/6/2019 9:19:42 AM
12c3456c-7e90-4f12-1232-1234f5b67893 KT-Retrieve-Cloud-Type-Win Failed 4/2/2019 4:13:07 AM
fe123b45-240c-4123-a2b3-234bdd567ecf AWS-RunInspecChecks Failed 4/1/2019 2:27:31 PM
1eb23aa4-567d-4123-12a3-4c1c2ab34561 AWS-RunPowerShellScript Success 4/1/2019 1:05:55 PM
1c2f3bb4-ee12-4bc1-1a23-12345eea123e AWS-RunInspecChecks Failed 4/1/2019 11:13:09 AM
```
+ For API details, see [ListCommands](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `ListComplianceItems` with a CLI
<a name="ssm_example_ssm_ListComplianceItems_section"></a>
The following code examples show how to use `ListComplianceItems`.
------
#### [ CLI ]
**AWS CLI**
**To list compliance items for a specific instance**
This example lists all compliance items for the specified instance.
Command:
```
aws ssm list-compliance-items --resource-ids "i-1234567890abcdef0" --resource-types "ManagedInstance"
```
Output:
```
{
"ComplianceItems": [
{
"ComplianceType": "Association",
"ResourceType": "ManagedInstance",
"ResourceId": "i-1234567890abcdef0",
"Id": "8dfe3659-4309-493a-8755-0123456789ab",
"Title": "",
"Status": "COMPLIANT",
"Severity": "UNSPECIFIED",
"ExecutionSummary": {
"ExecutionTime": 1550408470.0
},
"Details": {
"DocumentName": "AWS-GatherSoftwareInventory",
"DocumentVersion": "1"
}
},
{
"ComplianceType": "Association",
"ResourceType": "ManagedInstance",
"ResourceId": "i-1234567890abcdef0",
"Id": "e4c2ed6d-516f-41aa-aa2a-0123456789ab",
"Title": "",
"Status": "COMPLIANT",
"Severity": "UNSPECIFIED",
"ExecutionSummary": {
"ExecutionTime": 1550508475.0
},
"Details": {
"DocumentName": "AWS-UpdateSSMAgent",
"DocumentVersion": "1"
}
},
...
],
"NextToken": "--token string truncated--"
}
```
**To list compliance items for a specific instance and association ID**
This example lists all compliance items for the specified instance and association ID.
Command:
```
aws ssm list-compliance-items --resource-ids "i-1234567890abcdef0" --resource-types "ManagedInstance" --filters "Key=ComplianceType,Values=Association,Type=EQUAL" "Key=Id,Values=e4c2ed6d-516f-41aa-aa2a-0123456789ab,Type=EQUAL"
```
**To list compliance items for a instance after a specific date and time**
This example lists all compliance items for an instance after the specified date and time.
Command:
```
aws ssm list-compliance-items --resource-ids "i-1234567890abcdef0" --resource-types "ManagedInstance" --filters "Key=ExecutionTime,Values=2019-02-18T16:00:00Z,Type=GREATER_THAN"
```
+ For API details, see [ListComplianceItems](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/list-compliance-items.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists compliance items list for the given resource id and type, filtering compliance-type being 'Association'**
```
Get-SSMComplianceItemList -ResourceId i-1a2caf345f67d0dc2 -ResourceType ManagedInstance -Filter @{Key="ComplianceType";Values="Association"}
```
**Output:**
```
ComplianceType : Association
Details : {[DocumentName, AWS-GatherSoftwareInventory], [DocumentVersion, 1]}
ExecutionSummary : Amazon.SimpleSystemsManagement.Model.ComplianceExecutionSummary
Id : 123a45a1-c234-1234-1245-67891236db4e
ResourceId : i-1a2caf345f67d0dc2
ResourceType : ManagedInstance
Severity : UNSPECIFIED
Status : COMPLIANT
Title :
```
+ For API details, see [ListComplianceItems](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists compliance items list for the given resource id and type, filtering compliance-type being 'Association'**
```
Get-SSMComplianceItemList -ResourceId i-1a2caf345f67d0dc2 -ResourceType ManagedInstance -Filter @{Key="ComplianceType";Values="Association"}
```
**Output:**
```
ComplianceType : Association
Details : {[DocumentName, AWS-GatherSoftwareInventory], [DocumentVersion, 1]}
ExecutionSummary : Amazon.SimpleSystemsManagement.Model.ComplianceExecutionSummary
Id : 123a45a1-c234-1234-1245-67891236db4e
ResourceId : i-1a2caf345f67d0dc2
ResourceType : ManagedInstance
Severity : UNSPECIFIED
Status : COMPLIANT
Title :
```
+ For API details, see [ListComplianceItems](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `ListComplianceSummaries` with a CLI
<a name="ssm_example_ssm_ListComplianceSummaries_section"></a>
The following code examples show how to use `ListComplianceSummaries`.
------
#### [ CLI ]
**AWS CLI**
**To list compliance summaries for all compliance types**
This example lists compliance summaries for all compliance types in your account.
Command:
```
aws ssm list-compliance-summaries
```
Output:
```
{
"ComplianceSummaryItems": [
{
"ComplianceType": "Association",
"CompliantSummary": {
"CompliantCount": 2,
"SeveritySummary": {
"CriticalCount": 0,
"HighCount": 0,
"MediumCount": 0,
"LowCount": 0,
"InformationalCount": 0,
"UnspecifiedCount": 2
}
},
"NonCompliantSummary": {
"NonCompliantCount": 0,
"SeveritySummary": {
"CriticalCount": 0,
"HighCount": 0,
"MediumCount": 0,
"LowCount": 0,
"InformationalCount": 0,
"UnspecifiedCount": 0
}
}
},
{
"ComplianceType": "Patch",
"CompliantSummary": {
"CompliantCount": 1,
"SeveritySummary": {
"CriticalCount": 0,
"HighCount": 0,
"MediumCount": 0,
"LowCount": 0,
"InformationalCount": 0,
"UnspecifiedCount": 1
}
},
"NonCompliantSummary": {
"NonCompliantCount": 1,
"SeveritySummary": {
"CriticalCount": 1,
"HighCount": 0,
"MediumCount": 0,
"LowCount": 0,
"InformationalCount": 0,
"UnspecifiedCount": 0
}
}
},
...
],
"NextToken": "eyJOZXh0VG9rZW4iOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAyfQ=="
}
```
**To list compliance summaries for a specific compliance type**
This example lists the compliance summary for the Patch compliance type.
Command:
```
aws ssm list-compliance-summaries --filters "Key=ComplianceType,Values=Patch,Type=EQUAL"
```
+ For API details, see [ListComplianceSummaries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/list-compliance-summaries.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example returns a summary count of compliant and non-compliant resources for all compliance types. **
```
Get-SSMComplianceSummaryList
```
**Output:**
```
ComplianceType CompliantSummary NonCompliantSummary
-------------- ---------------- -------------------
FleetTotal Amazon.SimpleSystemsManagement.Model.CompliantSummary Amazon.SimpleSystemsManagement.Model.NonCompliantSummary
Association Amazon.SimpleSystemsManagement.Model.CompliantSummary Amazon.SimpleSystemsManagement.Model.NonCompliantSummary
Custom:InSpec Amazon.SimpleSystemsManagement.Model.CompliantSummary Amazon.SimpleSystemsManagement.Model.NonCompliantSummary
Patch Amazon.SimpleSystemsManagement.Model.CompliantSummary Amazon.SimpleSystemsManagement.Model.NonCompliantSummary
```
+ For API details, see [ListComplianceSummaries](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example returns a summary count of compliant and non-compliant resources for all compliance types. **
```
Get-SSMComplianceSummaryList
```
**Output:**
```
ComplianceType CompliantSummary NonCompliantSummary
-------------- ---------------- -------------------
FleetTotal Amazon.SimpleSystemsManagement.Model.CompliantSummary Amazon.SimpleSystemsManagement.Model.NonCompliantSummary
Association Amazon.SimpleSystemsManagement.Model.CompliantSummary Amazon.SimpleSystemsManagement.Model.NonCompliantSummary
Custom:InSpec Amazon.SimpleSystemsManagement.Model.CompliantSummary Amazon.SimpleSystemsManagement.Model.NonCompliantSummary
Patch Amazon.SimpleSystemsManagement.Model.CompliantSummary Amazon.SimpleSystemsManagement.Model.NonCompliantSummary
```
+ For API details, see [ListComplianceSummaries](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `ListDocumentVersions` with a CLI
<a name="ssm_example_ssm_ListDocumentVersions_section"></a>
The following code examples show how to use `ListDocumentVersions`.
------
#### [ CLI ]
**AWS CLI**
**To list document versions**
The following `list-document-versions` example lists all versions for a Systems Manager document.
```
aws ssm list-document-versions \
--name "Example"
```
Output:
```
{
"DocumentVersions": [
{
"Name": "Example",
"DocumentVersion": "1",
"CreatedDate": 1583257938.266,
"IsDefaultVersion": true,
"DocumentFormat": "YAML",
"Status": "Active"
}
]
}
```
For more information, see [Sending Commands that Use the Document Version Parameter](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command-version.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [ListDocumentVersions](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/list-document-versions.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists all the versions for a document.**
```
Get-SSMDocumentVersionList -Name "AWS-UpdateSSMAgent"
```
**Output:**
```
CreatedDate : 6/1/2021 5:19:10 PM
DocumentFormat : JSON
DocumentVersion : 1
IsDefaultVersion : True
Name : AWS-UpdateSSMAgent
Status : Active
```
+ For API details, see [ListDocumentVersions](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists all the versions for a document.**
```
Get-SSMDocumentVersionList -Name "AWS-UpdateSSMAgent"
```
**Output:**
```
CreatedDate : 6/1/2021 5:19:10 PM
DocumentFormat : JSON
DocumentVersion : 1
IsDefaultVersion : True
Name : AWS-UpdateSSMAgent
Status : Active
```
+ For API details, see [ListDocumentVersions](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `ListDocuments` with a CLI
<a name="ssm_example_ssm_ListDocuments_section"></a>
The following code examples show how to use `ListDocuments`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To list documents**
The following `list-documents` example lists documents owned by the requesting account tagged with the custom tag.
```
aws ssm list-documents \
--filters Key=Owner,Values=Self Key=tag:DocUse,Values=Testing
```
Output:
```
{
"DocumentIdentifiers": [
{
"Name": "Example",
"Owner": "29884EXAMPLE",
"PlatformTypes": [
"Windows",
"Linux"
],
"DocumentVersion": "1",
"DocumentType": "Automation",
"SchemaVersion": "0.3",
"DocumentFormat": "YAML",
"Tags": [
{
"Key": "DocUse",
"Value": "Testing"
}
]
}
]
}
```
For more information, see [AWS Systems Manager Documents](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-ssm-docs.html) in the *AWS Systems Manager User Guide*.
**Example 2: To list shared documents**
The following `list-documents` example lists shared documents, including private shared documents not owned by AWS.
```
aws ssm list-documents \
--filters Key=Name,Values=sharedDocNamePrefix Key=Owner,Values=Private
```
Output:
```
{
"DocumentIdentifiers": [
{
"Name": "Example",
"Owner": "12345EXAMPLE",
"PlatformTypes": [
"Windows",
"Linux"
],
"DocumentVersion": "1",
"DocumentType": "Command",
"SchemaVersion": "0.3",
"DocumentFormat": "YAML",
"Tags": []
}
]
}
```
For more information, see [AWS Systems Manager Documents](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-ssm-docs.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [ListDocuments](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/list-documents.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: Lists all the configuration documents in your account.**
```
Get-SSMDocumentList
```
**Output:**
```
DocumentType : Command
DocumentVersion : 1
Name : AWS-ApplyPatchBaseline
Owner : Amazon
PlatformTypes : {Windows}
SchemaVersion : 1.2
DocumentType : Command
DocumentVersion : 1
Name : AWS-ConfigureAWSPackage
Owner : Amazon
PlatformTypes : {Windows, Linux}
SchemaVersion : 2.0
DocumentType : Command
DocumentVersion : 1
Name : AWS-ConfigureCloudWatch
Owner : Amazon
PlatformTypes : {Windows}
SchemaVersion : 1.2
...
```
**Example 2: This example retrieves all automation documents with name matchingi 'Platform'**
```
Get-SSMDocumentList -DocumentFilterList @{Key="DocumentType";Value="Automation"} | Where-Object Name -Match "Platform"
```
**Output:**
```
DocumentFormat : JSON
DocumentType : Automation
DocumentVersion : 7
Name : KT-Get-Platform
Owner : 987654123456
PlatformTypes : {Windows, Linux}
SchemaVersion : 0.3
Tags : {}
TargetType :
VersionName :
```
+ For API details, see [ListDocuments](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: Lists all the configuration documents in your account.**
```
Get-SSMDocumentList
```
**Output:**
```
DocumentType : Command
DocumentVersion : 1
Name : AWS-ApplyPatchBaseline
Owner : Amazon
PlatformTypes : {Windows}
SchemaVersion : 1.2
DocumentType : Command
DocumentVersion : 1
Name : AWS-ConfigureAWSPackage
Owner : Amazon
PlatformTypes : {Windows, Linux}
SchemaVersion : 2.0
DocumentType : Command
DocumentVersion : 1
Name : AWS-ConfigureCloudWatch
Owner : Amazon
PlatformTypes : {Windows}
SchemaVersion : 1.2
...
```
**Example 2: This example retrieves all automation documents with name matchingi 'Platform'**
```
Get-SSMDocumentList -DocumentFilterList @{Key="DocumentType";Value="Automation"} | Where-Object Name -Match "Platform"
```
**Output:**
```
DocumentFormat : JSON
DocumentType : Automation
DocumentVersion : 7
Name : KT-Get-Platform
Owner : 987654123456
PlatformTypes : {Windows, Linux}
SchemaVersion : 0.3
Tags : {}
TargetType :
VersionName :
```
+ For API details, see [ListDocuments](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `ListInventoryEntries` with a CLI
<a name="ssm_example_ssm_ListInventoryEntries_section"></a>
The following code examples show how to use `ListInventoryEntries`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To view specific inventory type entries for an instance**
This following `list-inventory-entries` example lists the inventory entries for the AWS:Application inventory type on a specific instance.
```
aws ssm list-inventory-entries \
--instance-id "i-1234567890abcdef0" \
--type-name "AWS:Application"
```
Output:
```
{
"TypeName": "AWS:Application",
"InstanceId": "i-1234567890abcdef0",
"SchemaVersion": "1.1",
"CaptureTime": "2019-02-15T12:17:55Z",
"Entries": [
{
"Architecture": "i386",
"Name": "Amazon SSM Agent",
"PackageId": "{88a60be2-89a1-4df8-812a-80863c2a2b68}",
"Publisher": "Amazon Web Services",
"Version": "2.3.274.0"
},
{
"Architecture": "x86_64",
"InstalledTime": "2018-05-03T13:42:34Z",
"Name": "AmazonCloudWatchAgent",
"Publisher": "",
"Version": "1.200442.0"
}
]
}
```
**Example 2: To view custom inventory entries assigned to an instance**
The following `list-inventory-entries` example lists a custom inventory entry assigned to an instance.
```
aws ssm list-inventory-entries \
--instance-id "i-1234567890abcdef0" \
--type-name "Custom:RackInfo"
```
Output:
```
{
"TypeName": "Custom:RackInfo",
"InstanceId": "i-1234567890abcdef0",
"SchemaVersion": "1.0",
"CaptureTime": "2021-05-22T10:01:01Z",
"Entries": [
{
"RackLocation": "Bay B/Row C/Rack D/Shelf E"
}
]
}
```
+ For API details, see [ListInventoryEntries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/list-inventory-entries.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists all the custom inventory entries for an instance.**
```
Get-SSMInventoryEntriesList -InstanceId "i-0cb2b964d3e14fd9f" -TypeName "Custom:RackInfo"
```
**Output:**
```
CaptureTime : 2016-08-22T10:01:01Z
Entries : {Amazon.Runtime.Internal.Util.AlwaysSendDictionary`2[System.String,System.String]}
InstanceId : i-0cb2b964d3e14fd9f
NextToken :
SchemaVersion : 1.0
TypeName : Custom:RackInfo
```
**Example 2: This example lists the details.**
```
(Get-SSMInventoryEntriesList -InstanceId "i-0cb2b964d3e14fd9f" -TypeName "Custom:RackInfo").Entries
```
**Output:**
```
Key Value
--- -----
RackLocation Bay B/Row C/Rack D/Shelf E
```
+ For API details, see [ListInventoryEntries](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists all the custom inventory entries for an instance.**
```
Get-SSMInventoryEntriesList -InstanceId "i-0cb2b964d3e14fd9f" -TypeName "Custom:RackInfo"
```
**Output:**
```
CaptureTime : 2016-08-22T10:01:01Z
Entries : {Amazon.Runtime.Internal.Util.AlwaysSendDictionary`2[System.String,System.String]}
InstanceId : i-0cb2b964d3e14fd9f
NextToken :
SchemaVersion : 1.0
TypeName : Custom:RackInfo
```
**Example 2: This example lists the details.**
```
(Get-SSMInventoryEntriesList -InstanceId "i-0cb2b964d3e14fd9f" -TypeName "Custom:RackInfo").Entries
```
**Output:**
```
Key Value
--- -----
RackLocation Bay B/Row C/Rack D/Shelf E
```
+ For API details, see [ListInventoryEntries](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `ListResourceComplianceSummaries` with a CLI
<a name="ssm_example_ssm_ListResourceComplianceSummaries_section"></a>
The following code examples show how to use `ListResourceComplianceSummaries`.
------
#### [ CLI ]
**AWS CLI**
**To list resource-level compliance summary counts**
This example lists resource-level compliance summary counts.
Command:
```
aws ssm list-resource-compliance-summaries
```
Output:
```
{
"ResourceComplianceSummaryItems": [
{
"ComplianceType": "Association",
"ResourceType": "ManagedInstance",
"ResourceId": "i-1234567890abcdef0",
"Status": "COMPLIANT",
"OverallSeverity": "UNSPECIFIED",
"ExecutionSummary": {
"ExecutionTime": 1550509273.0
},
"CompliantSummary": {
"CompliantCount": 2,
"SeveritySummary": {
"CriticalCount": 0,
"HighCount": 0,
"MediumCount": 0,
"LowCount": 0,
"InformationalCount": 0,
"UnspecifiedCount": 2
}
},
"NonCompliantSummary": {
"NonCompliantCount": 0,
"SeveritySummary": {
"CriticalCount": 0,
"HighCount": 0,
"MediumCount": 0,
"LowCount": 0,
"InformationalCount": 0,
"UnspecifiedCount": 0
}
}
},
{
"ComplianceType": "Patch",
"ResourceType": "ManagedInstance",
"ResourceId": "i-9876543210abcdef0",
"Status": "COMPLIANT",
"OverallSeverity": "UNSPECIFIED",
"ExecutionSummary": {
"ExecutionTime": 1550248550.0,
"ExecutionId": "7abb6378-a4a5-4f10-8312-0123456789ab",
"ExecutionType": "Command"
},
"CompliantSummary": {
"CompliantCount": 397,
"SeveritySummary": {
"CriticalCount": 0,
"HighCount": 0,
"MediumCount": 0,
"LowCount": 0,
"InformationalCount": 0,
"UnspecifiedCount": 397
}
},
"NonCompliantSummary": {
"NonCompliantCount": 0,
"SeveritySummary": {
"CriticalCount": 0,
"HighCount": 0,
"MediumCount": 0,
"LowCount": 0,
"InformationalCount": 0,
"UnspecifiedCount": 0
}
}
}
],
"NextToken": "--token string truncated--"
}
```
**To list resource-level compliance summaries for a specific compliance type**
This example lists resource-level compliance summaries for the Patch compliance type.
Command:
```
aws ssm list-resource-compliance-summaries --filters "Key=ComplianceType,Values=Patch,Type=EQUAL"
```
+ For API details, see [ListResourceComplianceSummaries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/list-resource-compliance-summaries.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example gets a resource-level summary count. The summary includes information about compliant and non-compliant statuses and detailed compliance-item severity counts for products that match "Windows10". Because the MaxResult default is 100 if the parameter is not specified, and this value is not valid, MaxResult parameter is added, and the value is set to 50.**
```
$FilterValues = @{
"Key"="Product"
"Type"="EQUAL"
"Values"="Windows10"
}
Get-SSMResourceComplianceSummaryList -Filter $FilterValues -MaxResult 50
```
+ For API details, see [ListResourceComplianceSummaries](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example gets a resource-level summary count. The summary includes information about compliant and non-compliant statuses and detailed compliance-item severity counts for products that match "Windows10". Because the MaxResult default is 100 if the parameter is not specified, and this value is not valid, MaxResult parameter is added, and the value is set to 50.**
```
$FilterValues = @{
"Key"="Product"
"Type"="EQUAL"
"Values"="Windows10"
}
Get-SSMResourceComplianceSummaryList -Filter $FilterValues -MaxResult 50
```
+ For API details, see [ListResourceComplianceSummaries](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `ListTagsForResource` with a CLI
<a name="ssm_example_ssm_ListTagsForResource_section"></a>
The following code examples show how to use `ListTagsForResource`.
------
#### [ CLI ]
**AWS CLI**
**To list the tags applied to a patch baseline**
The following `list-tags-for-resource` example lists the tags for a patch baseline.
```
aws ssm list-tags-for-resource \
--resource-type "PatchBaseline" \
--resource-id "pb-0123456789abcdef0"
```
Output:
```
{
"TagList": [
{
"Key": "Environment",
"Value": "Production"
},
{
"Key": "Region",
"Value": "EMEA"
}
]
}
```
For more information, see [Tagging AWS Resources](https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html) in the *AWS General Reference*.
+ For API details, see [ListTagsForResource](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/list-tags-for-resource.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example lists the tags for a maintenance window.**
```
Get-SSMResourceTag -ResourceId "mw-03eb9db42890fb82d" -ResourceType "MaintenanceWindow"
```
**Output:**
```
Key Value
--- -----
Stack Production
```
+ For API details, see [ListTagsForResource](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example lists the tags for a maintenance window.**
```
Get-SSMResourceTag -ResourceId "mw-03eb9db42890fb82d" -ResourceType "MaintenanceWindow"
```
**Output:**
```
Key Value
--- -----
Stack Production
```
+ For API details, see [ListTagsForResource](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `ModifyDocumentPermission` with a CLI
<a name="ssm_example_ssm_ModifyDocumentPermission_section"></a>
The following code examples show how to use `ModifyDocumentPermission`.
------
#### [ CLI ]
**AWS CLI**
**To modify document permissions**
The following `modify-document-permission` example shares a Systems Manager document publicly.
```
aws ssm modify-document-permission \
--name "Example" \
--permission-type "Share" \
--account-ids-to-add "All"
```
This command produces no output.
For more information, see [Share a Systems Manager Document](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-how-to-share.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [ModifyDocumentPermission](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/modify-document-permission.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example adds "share" permissions to all accounts for a document. There is no output if the command succeeds.**
```
Edit-SSMDocumentPermission -Name "RunShellScript" -PermissionType "Share" -AccountIdsToAdd all
```
**Example 2: This example adds "share" permissions to a specific account for a document. There is no output if the command succeeds.**
```
Edit-SSMDocumentPermission -Name "RunShellScriptNew" -PermissionType "Share" -AccountIdsToAdd "123456789012"
```
+ For API details, see [ModifyDocumentPermission](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example adds "share" permissions to all accounts for a document. There is no output if the command succeeds.**
```
Edit-SSMDocumentPermission -Name "RunShellScript" -PermissionType "Share" -AccountIdsToAdd all
```
**Example 2: This example adds "share" permissions to a specific account for a document. There is no output if the command succeeds.**
```
Edit-SSMDocumentPermission -Name "RunShellScriptNew" -PermissionType "Share" -AccountIdsToAdd "123456789012"
```
+ For API details, see [ModifyDocumentPermission](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `PutComplianceItems` with a CLI
<a name="ssm_example_ssm_PutComplianceItems_section"></a>
The following code examples show how to use `PutComplianceItems`.
------
#### [ CLI ]
**AWS CLI**
**To register a compliance type and compliance details to a designated instance**
This example registers the compliance type `Custom:AVCheck` to the specified managed instance. There is no output if the command succeeds.
Command:
```
aws ssm put-compliance-items --resource-id "i-1234567890abcdef0" --resource-type "ManagedInstance" --compliance-type "Custom:AVCheck" --execution-summary "ExecutionTime=2019-02-18T16:00:00Z" --items "Id=Version2.0,Title=ScanHost,Severity=CRITICAL,Status=COMPLIANT"
```
+ For API details, see [PutComplianceItems](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/put-compliance-items.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example writes a custom compliance item for the given managed instance**
```
$item = [Amazon.SimpleSystemsManagement.Model.ComplianceItemEntry]::new()
$item.Id = "07Jun2019-3"
$item.Severity="LOW"
$item.Status="COMPLIANT"
$item.Title="Fin-test-1 - custom"
Write-SSMComplianceItem -ResourceId mi-012dcb3ecea45b678 -ComplianceType Custom:VSSCompliant2 -ResourceType ManagedInstance -Item $item -ExecutionSummary_ExecutionTime "07-Jun-2019"
```
+ For API details, see [PutComplianceItems](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example writes a custom compliance item for the given managed instance**
```
$item = [Amazon.SimpleSystemsManagement.Model.ComplianceItemEntry]::new()
$item.Id = "07Jun2019-3"
$item.Severity="LOW"
$item.Status="COMPLIANT"
$item.Title="Fin-test-1 - custom"
Write-SSMComplianceItem -ResourceId mi-012dcb3ecea45b678 -ComplianceType Custom:VSSCompliant2 -ResourceType ManagedInstance -Item $item -ExecutionSummary_ExecutionTime "07-Jun-2019"
```
+ For API details, see [PutComplianceItems](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `PutInventory` with a CLI
<a name="ssm_example_ssm_PutInventory_section"></a>
The following code examples show how to use `PutInventory`.
------
#### [ CLI ]
**AWS CLI**
**To assign customer metadata to an instance**
This example assigns rack location information to an instance. There is no output if the command succeeds.
Command (Linux):
```
aws ssm put-inventory --instance-id "i-016648b75dd622dab" --items '[{"TypeName": "Custom:RackInfo","SchemaVersion": "1.0","CaptureTime": "2019-01-22T10:01:01Z","Content":[{"RackLocation": "Bay B/Row C/Rack D/Shelf E"}]}]'
```
Command (Windows):
```
aws ssm put-inventory --instance-id "i-016648b75dd622dab" --items "TypeName=Custom:RackInfo,SchemaVersion=1.0,CaptureTime=2019-01-22T10:01:01Z,Content=[{RackLocation='Bay B/Row C/Rack D/Shelf F'}]"
```
+ For API details, see [PutInventory](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/put-inventory.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example assigns rack location information to an instance. There is no output if the command succeeds.**
```
$data = New-Object "System.Collections.Generic.Dictionary[System.String,System.String]"
$data.Add("RackLocation", "Bay B/Row C/Rack D/Shelf F")
$items = New-Object "System.Collections.Generic.List[System.Collections.Generic.Dictionary[System.String, System.String]]"
$items.Add($data)
$customInventoryItem = New-Object Amazon.SimpleSystemsManagement.Model.InventoryItem
$customInventoryItem.CaptureTime = "2016-08-22T10:01:01Z"
$customInventoryItem.Content = $items
$customInventoryItem.TypeName = "Custom:TestRackInfo2"
$customInventoryItem.SchemaVersion = "1.0"
$inventoryItems = @($customInventoryItem)
Write-SSMInventory -InstanceId "i-0cb2b964d3e14fd9f" -Item $inventoryItems
```
+ For API details, see [PutInventory](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example assigns rack location information to an instance. There is no output if the command succeeds.**
```
$data = New-Object "System.Collections.Generic.Dictionary[System.String,System.String]"
$data.Add("RackLocation", "Bay B/Row C/Rack D/Shelf F")
$items = New-Object "System.Collections.Generic.List[System.Collections.Generic.Dictionary[System.String, System.String]]"
$items.Add($data)
$customInventoryItem = New-Object Amazon.SimpleSystemsManagement.Model.InventoryItem
$customInventoryItem.CaptureTime = "2016-08-22T10:01:01Z"
$customInventoryItem.Content = $items
$customInventoryItem.TypeName = "Custom:TestRackInfo2"
$customInventoryItem.SchemaVersion = "1.0"
$inventoryItems = @($customInventoryItem)
Write-SSMInventory -InstanceId "i-0cb2b964d3e14fd9f" -Item $inventoryItems
```
+ For API details, see [PutInventory](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `PutParameter` with an AWS SDK or CLI
<a name="ssm_example_ssm_PutParameter_section"></a>
The following code examples show how to use `PutParameter`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To change a parameter value**
The following `put-parameter` example changes the value of the specified parameter.
```
aws ssm put-parameter \
--name "MyStringParameter" \
--type "String" \
--value "Vici" \
--overwrite
```
Output:
```
{
"Version": 2,
"Tier": "Standard"
}
```
For more information, see [Create a Systems Manager parameter (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/param-create-cli.html), [Managing parameter tiers](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-advanced-parameters.html), and [Working with parameter policies](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-policies.html) in the *AWS Systems Manager User Guide*.
**Example 2: To create an advanced parameter**
The following `put-parameter` example creates an advanced parameter.
```
aws ssm put-parameter \
--name "MyAdvancedParameter" \
--description "This is an advanced parameter" \
--value "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat [truncated]" \
--type "String" \
--tier Advanced
```
Output:
```
{
"Version": 1,
"Tier": "Advanced"
}
```
For more information, see [Create a Systems Manager parameter (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/param-create-cli.html), [Managing parameter tiers](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-advanced-parameters.html), and [Working with parameter policies](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-policies.html) in the *AWS Systems Manager User Guide*.
**Example 3: To convert a standard parameter to an advanced parameter**
The following `put-parameter` example converts an existing standard parameter into an advanced parameter.
```
aws ssm put-parameter \
--name "MyConvertedParameter" \
--value "abc123" \
--type "String" \
--tier Advanced \
--overwrite
```
Output:
```
{
"Version": 2,
"Tier": "Advanced"
}
```
For more information, see [Create a Systems Manager parameter (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/param-create-cli.html), [Managing parameter tiers](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-advanced-parameters.html), and [Working with parameter policies](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-policies.html) in the *AWS Systems Manager User Guide*.
**Example 4: To create a parameter with a policy attached**
The following `put-parameter` example creates an advanced parameter with a parameter policy attached.
```
aws ssm put-parameter \
--name "/Finance/Payroll/q2accesskey" \
--value "P@sSwW)rd" \
--type "SecureString" \
--tier Advanced \
--policies "[{\"Type\":\"Expiration\",\"Version\":\"1.0\",\"Attributes\":{\"Timestamp\":\"2020-06-30T00:00:00.000Z\"}},{\"Type\":\"ExpirationNotification\",\"Version\":\"1.0\",\"Attributes\":{\"Before\":\"5\",\"Unit\":\"Days\"}},{\"Type\":\"NoChangeNotification\",\"Version\":\"1.0\",\"Attributes\":{\"After\":\"60\",\"Unit\":\"Days\"}}]"
```
Output:
```
{
"Version": 1,
"Tier": "Advanced"
}
```
For more information, see [Create a Systems Manager parameter (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/param-create-cli.html), [Managing parameter tiers](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-advanced-parameters.html), and [Working with parameter policies](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-policies.html) in the *AWS Systems Manager User Guide*.
**Example 5: To add a policy to an existing parameter**
The following `put-parameter` example attaches a policy to an existing advanced parameter.
```
aws ssm put-parameter \
--name "/Finance/Payroll/q2accesskey" \
--value "N3wP@sSwW)rd" \
--type "SecureString" \
--tier Advanced \
--policies "[{\"Type\":\"Expiration\",\"Version\":\"1.0\",\"Attributes\":{\"Timestamp\":\"2020-06-30T00:00:00.000Z\"}},{\"Type\":\"ExpirationNotification\",\"Version\":\"1.0\",\"Attributes\":{\"Before\":\"5\",\"Unit\":\"Days\"}},{\"Type\":\"NoChangeNotification\",\"Version\":\"1.0\",\"Attributes\":{\"After\":\"60\",\"Unit\":\"Days\"}}]"
--overwrite
```
Output:
```
{
"Version": 2,
"Tier": "Advanced"
}
```
For more information, see [Create a Systems Manager parameter (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/param-create-cli.html), [Managing parameter tiers](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-advanced-parameters.html), and [Working with parameter policies](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-policies.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [PutParameter](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/put-parameter.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/ssm#code-examples).
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.ssm.SsmClient;
import software.amazon.awssdk.services.ssm.model.ParameterType;
import software.amazon.awssdk.services.ssm.model.PutParameterRequest;
import software.amazon.awssdk.services.ssm.model.SsmException;
public class PutParameter {
public static void main(String[] args) {
final String usage = """
Usage:
<paraName>
Where:
paraName - The name of the parameter.
paraValue - The value of the parameter.
""";
if (args.length != 2) {
System.out.println(usage);
System.exit(1);
}
String paraName = args[0];
String paraValue = args[1];
Region region = Region.US_EAST_1;
SsmClient ssmClient = SsmClient.builder()
.region(region)
.build();
putParaValue(ssmClient, paraName, paraValue);
ssmClient.close();
}
public static void putParaValue(SsmClient ssmClient, String paraName, String value) {
try {
PutParameterRequest parameterRequest = PutParameterRequest.builder()
.name(paraName)
.type(ParameterType.STRING)
.value(value)
.build();
ssmClient.putParameter(parameterRequest);
System.out.println("The parameter was successfully added.");
} catch (SsmException e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
}
```
+ For API details, see [PutParameter](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/PutParameter) in *AWS SDK for Java 2.x API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example creates a parameter. There is no output if the command succeeds.**
```
Write-SSMParameter -Name "Welcome" -Type "String" -Value "helloWorld"
```
**Example 2: This example changes a parameter. There is no output if the command succeeds.**
```
Write-SSMParameter -Name "Welcome" -Type "String" -Value "Good day, Sunshine!" -Overwrite $true
```
+ For API details, see [PutParameter](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example creates a parameter. There is no output if the command succeeds.**
```
Write-SSMParameter -Name "Welcome" -Type "String" -Value "helloWorld"
```
**Example 2: This example changes a parameter. There is no output if the command succeeds.**
```
Write-SSMParameter -Name "Welcome" -Type "String" -Value "Good day, Sunshine!" -Overwrite $true
```
+ For API details, see [PutParameter](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Rust ]
**SDK for Rust**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/ssm#code-examples).
```
async fn make_parameter(
client: &Client,
name: &str,
value: &str,
description: &str,
) -> Result<(), Error> {
let resp = client
.put_parameter()
.overwrite(true)
.r#type(ParameterType::String)
.name(name)
.value(value)
.description(description)
.send()
.await?;
println!("Success! Parameter now has version: {}", resp.version());
Ok(())
}
```
+ For API details, see [PutParameter](https://docs.rs/aws-sdk-ssm/latest/aws_sdk_ssm/client/struct.Client.html#method.put_parameter) in *AWS SDK for Rust API reference*.
------
# Use `RegisterDefaultPatchBaseline` with a CLI
<a name="ssm_example_ssm_RegisterDefaultPatchBaseline_section"></a>
The following code examples show how to use `RegisterDefaultPatchBaseline`.
------
#### [ CLI ]
**AWS CLI**
**To set the default patch baseline**
The following `register-default-patch-baseline` example registers the specified custom patch baseline as the default patch baseline for the operating system type that it supports.
```
aws ssm register-default-patch-baseline \
--baseline-id "pb-abc123cf9bEXAMPLE"
```
Output:
```
{
"BaselineId":"pb-abc123cf9bEXAMPLE"
}
```
The following `register-default-patch-baseline` example registers the default patch baseline provided by AWS for CentOS as the default patch baseline.
```
aws ssm register-default-patch-baseline \
--baseline-id "arn:aws:ssm:us-east-2:733109147000:patchbaseline/pb-0574b43a65ea646ed"
```
Output:
```
{
"BaselineId":"pb-abc123cf9bEXAMPLE"
}
```
For more information, see [About Predefined and Custom Patch Baselines](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-baselines.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [RegisterDefaultPatchBaseline](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/register-default-patch-baseline.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example registers a patch baseline as the default patch baseline.**
```
Register-SSMDefaultPatchBaseline -BaselineId "pb-03da896ca3b68b639"
```
**Output:**
```
pb-03da896ca3b68b639
```
+ For API details, see [RegisterDefaultPatchBaseline](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example registers a patch baseline as the default patch baseline.**
```
Register-SSMDefaultPatchBaseline -BaselineId "pb-03da896ca3b68b639"
```
**Output:**
```
pb-03da896ca3b68b639
```
+ For API details, see [RegisterDefaultPatchBaseline](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `RegisterPatchBaselineForPatchGroup` with a CLI
<a name="ssm_example_ssm_RegisterPatchBaselineForPatchGroup_section"></a>
The following code examples show how to use `RegisterPatchBaselineForPatchGroup`.
------
#### [ CLI ]
**AWS CLI**
**To register a patch baseline for a patch group**
The following `register-patch-baseline-for-patch-group` example registers a patch baseline for a patch group.
```
aws ssm register-patch-baseline-for-patch-group \
--baseline-id "pb-045f10b4f382baeda" \
--patch-group "Production"
```
Output:
```
{
"BaselineId": "pb-045f10b4f382baeda",
"PatchGroup": "Production"
}
```
For more information, see Create a Patch Group <https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-group-tagging.html>\$1\$1 and [Add a Patch Group to a Patch Baseline](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-patch-group-patchbaseline.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [RegisterPatchBaselineForPatchGroup](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/register-patch-baseline-for-patch-group.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example registers a patch baseline for a patch group.**
```
Register-SSMPatchBaselineForPatchGroup -BaselineId "pb-03da896ca3b68b639" -PatchGroup "Production"
```
**Output:**
```
BaselineId PatchGroup
---------- ----------
pb-03da896ca3b68b639 Production
```
+ For API details, see [RegisterPatchBaselineForPatchGroup](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example registers a patch baseline for a patch group.**
```
Register-SSMPatchBaselineForPatchGroup -BaselineId "pb-03da896ca3b68b639" -PatchGroup "Production"
```
**Output:**
```
BaselineId PatchGroup
---------- ----------
pb-03da896ca3b68b639 Production
```
+ For API details, see [RegisterPatchBaselineForPatchGroup](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `RegisterTargetWithMaintenanceWindow` with a CLI
<a name="ssm_example_ssm_RegisterTargetWithMaintenanceWindow_section"></a>
The following code examples show how to use `RegisterTargetWithMaintenanceWindow`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To register a single target with a maintenance window**
The following `register-target-with-maintenance-window` example registers an instance with a maintenance window.
```
aws ssm register-target-with-maintenance-window \
--window-id "mw-ab12cd34ef56gh78" \
--target "Key=InstanceIds,Values=i-0000293ffd8c57862" \
--owner-information "Single instance" \
--resource-type "INSTANCE"
```
Output:
```
{
"WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2"
}
```
**Example 2: To register multiple targets with a maintenance window using instance IDs**
The following `register-target-with-maintenance-window` example registers two instances with a maintenance window by specifying their instance IDs.
```
aws ssm register-target-with-maintenance-window \
--window-id "mw-ab12cd34ef56gh78" \
--target "Key=InstanceIds,Values=i-0000293ffd8c57862,i-0cb2b964d3e14fd9f" \
--owner-information "Two instances in a list" \
--resource-type "INSTANCE"
```
Output:
```
{
"WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2"
}
```
**Example 3: To register targets with a maintenance window using resource tags**
The following `register-target-with-maintenance-window` example registers instances with a maintenance window by specifying resource tags that have been applied to the instances.
```
aws ssm register-target-with-maintenance-window \
--window-id "mw-06cf17cbefcb4bf4f" \
--targets "Key=tag:Environment,Values=Prod" "Key=Role,Values=Web" \
--owner-information "Production Web Servers" \
--resource-type "INSTANCE"
```
Output:
```
{
"WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2"
}
```
**Example 4: To register targets using a group of tag keys**
The following `register-target-with-maintenance-window` example register instances that all have one or more tag keys assigned to them, regardless of their key values.
```
aws ssm register-target-with-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--resource-type "INSTANCE" \
--target "Key=tag-key,Values=Name,Instance-Type,CostCenter"
```
Output:
```
{
"WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2"
}
```
**Example 5: To register targets using a resource group name**
The following `register-target-with-maintenance-window` example register a specified resource group, regardless of the type of resources it contains.
```
aws ssm register-target-with-maintenance-window \
--window-id "mw-0c50858d01EXAMPLE" \
--resource-type "RESOURCE_GROUP" \
--target "Key=resource-groups:Name,Values=MyResourceGroup"
```
Output:
```
{
"WindowTargetId":"1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d-1a2"
}
```
For more information, see [Register a Target Instance with the Maintenance Window (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/mw-cli-tutorial-targets.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [RegisterTargetWithMaintenanceWindow](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/register-target-with-maintenance-window.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example registers an instance with a maintenance window.**
```
$option1 = @{Key="InstanceIds";Values=@("i-0000293ffd8c57862")}
Register-SSMTargetWithMaintenanceWindow -WindowId "mw-06cf17cbefcb4bf4f" -Target $option1 -OwnerInformation "Single instance" -ResourceType "INSTANCE"
```
**Output:**
```
d8e47760-23ed-46a5-9f28-927337725398
```
**Example 2: This example registers multiple instances with a maintenance window.**
```
$option1 = @{Key="InstanceIds";Values=@("i-0000293ffd8c57862","i-0cb2b964d3e14fd9f")}
Register-SSMTargetWithMaintenanceWindow -WindowId "mw-06cf17cbefcb4bf4f" -Target $option1 -OwnerInformation "Single instance" -ResourceType "INSTANCE"
```
**Output:**
```
6ab5c208-9fc4-4697-84b7-b02a6cc25f7d
```
**Example 3: This example registers an instance with a maintenance window using EC2 tags.**
```
$option1 = @{Key="tag:Environment";Values=@("Production")}
Register-SSMTargetWithMaintenanceWindow -WindowId "mw-06cf17cbefcb4bf4f" -Target $option1 -OwnerInformation "Production Web Servers" -ResourceType "INSTANCE"
```
**Output:**
```
2994977e-aefb-4a71-beac-df620352f184
```
+ For API details, see [RegisterTargetWithMaintenanceWindow](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example registers an instance with a maintenance window.**
```
$option1 = @{Key="InstanceIds";Values=@("i-0000293ffd8c57862")}
Register-SSMTargetWithMaintenanceWindow -WindowId "mw-06cf17cbefcb4bf4f" -Target $option1 -OwnerInformation "Single instance" -ResourceType "INSTANCE"
```
**Output:**
```
d8e47760-23ed-46a5-9f28-927337725398
```
**Example 2: This example registers multiple instances with a maintenance window.**
```
$option1 = @{Key="InstanceIds";Values=@("i-0000293ffd8c57862","i-0cb2b964d3e14fd9f")}
Register-SSMTargetWithMaintenanceWindow -WindowId "mw-06cf17cbefcb4bf4f" -Target $option1 -OwnerInformation "Single instance" -ResourceType "INSTANCE"
```
**Output:**
```
6ab5c208-9fc4-4697-84b7-b02a6cc25f7d
```
**Example 3: This example registers an instance with a maintenance window using EC2 tags.**
```
$option1 = @{Key="tag:Environment";Values=@("Production")}
Register-SSMTargetWithMaintenanceWindow -WindowId "mw-06cf17cbefcb4bf4f" -Target $option1 -OwnerInformation "Production Web Servers" -ResourceType "INSTANCE"
```
**Output:**
```
2994977e-aefb-4a71-beac-df620352f184
```
+ For API details, see [RegisterTargetWithMaintenanceWindow](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `RegisterTaskWithMaintenanceWindow` with a CLI
<a name="ssm_example_ssm_RegisterTaskWithMaintenanceWindow_section"></a>
The following code examples show how to use `RegisterTaskWithMaintenanceWindow`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To register an Automation task with a maintenance window**
The following `register-task-with-maintenance-window` example registers an Automation task with a maintenance window that is targeted at an instance.
```
aws ssm register-task-with-maintenance-window \
--window-id "mw-082dcd7649EXAMPLE" \
--targets Key=InstanceIds,Values=i-1234520122EXAMPLE \
--task-arn AWS-RestartEC2Instance \
--service-role-arn arn:aws:iam::111222333444:role/SSM --task-type AUTOMATION \
--task-invocation-parameters "{\"Automation\":{\"DocumentVersion\":\"\$LATEST\",\"Parameters\":{\"InstanceId\":[\"{{RESOURCE_ID}}\"]}}}" \
--priority 0 \
--max-concurrency 1 \
--max-errors 1 \
--name "AutomationExample" \
--description "Restarting EC2 Instance for maintenance"
```
Output:
```
{
"WindowTaskId":"11144444-5555-6666-7777-88888888"
}
```
For more information, see [Register a Task with the Maintenance Window (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/mw-cli-tutorial-tasks.html) in the *AWS Systems Manager User Guide*.
**Example 2: To register a Lambda task with a Maintenance Window**
The following `register-task-with-maintenance-window` example registers a Lambda task with a Maintenance Window that is targeted at an instance.
```
aws ssm register-task-with-maintenance-window \
--window-id "mw-082dcd7649dee04e4" \
--targets Key=InstanceIds,Values=i-12344d305eEXAMPLE \
--task-arn arn:aws:lambda:us-east-1:111222333444:function:SSMTestLAMBDA \
--service-role-arn arn:aws:iam::111222333444:role/SSM \
--task-type LAMBDA \
--task-invocation-parameters '{"Lambda":{"Payload":"{\"InstanceId\":\"{{RESOURCE_ID}}\",\"targetType\":\"{{TARGET_TYPE}}\"}","Qualifier":"$LATEST"}}' \
--priority 0 \
--max-concurrency 10 \
--max-errors 5 \
--name "Lambda_Example" \
--description "My Lambda Example"
```
Output:
```
{
"WindowTaskId":"22244444-5555-6666-7777-88888888"
}
```
For more information, see [Register a Task with the Maintenance Window (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/mw-cli-tutorial-tasks.html) in the *AWS Systems Manager User Guide*.
**Example 3: To register a Run Command task with a maintenance window**
The following `register-task-with-maintenance-window` example registers a Run Command task with a maintenance window that is targeted at an instance.
```
aws ssm register-task-with-maintenance-window \
--window-id "mw-082dcd7649dee04e4" \
--targets "Key=InstanceIds,Values=i-12344d305eEXAMPLE" \
--service-role-arn "arn:aws:iam::111222333444:role/SSM" \
--task-type "RUN_COMMAND" \
--name "SSMInstallPowerShellModule" \
--task-arn "AWS-InstallPowerShellModule" \
--task-invocation-parameters "{\"RunCommand\":{\"Comment\":\"\",\"OutputS3BucketName\":\"runcommandlogs\",\"Parameters\":{\"commands\":[\"Get-Module -ListAvailable\"],\"executionTimeout\":[\"3600\"],\"source\":[\"https:\/\/gallery.technet.microsoft.com\/EZOut-33ae0fb7\/file\/110351\/1\/EZOut.zip\"],\"workingDirectory\":[\"\\\\\"]},\"TimeoutSeconds\":600}}" \
--max-concurrency 1 \
--max-errors 1 \
--priority 10
```
Output:
```
{
"WindowTaskId":"33344444-5555-6666-7777-88888888"
}
```
For more information, see [Register a Task with the Maintenance Window (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/mw-cli-tutorial-tasks.html) in the *AWS Systems Manager User Guide*.
**Example 4: To register a Step Functions task with a maintenance window**
The following `register-task-with-maintenance-window` example registers a Step Functions task with a maintenance window that is targeted at an instance.
```
aws ssm register-task-with-maintenance-window \
--window-id "mw-1234d787d6EXAMPLE" \
--targets Key=WindowTargetIds,Values=12347414-69c3-49f8-95b8-ed2dcEXAMPLE \
--task-arn arn:aws:states:us-east-1:111222333444:stateMachine:SSMTestStateMachine \
--service-role-arn arn:aws:iam::111222333444:role/MaintenanceWindows \
--task-type STEP_FUNCTIONS \
--task-invocation-parameters '{"StepFunctions":{"Input":"{\"InstanceId\":\"{{RESOURCE_ID}}\"}"}}' \
--priority 0 \
--max-concurrency 10 \
--max-errors 5 \
--name "Step_Functions_Example" \
--description "My Step Functions Example"
```
Output:
```
{
"WindowTaskId":"44444444-5555-6666-7777-88888888"
}
```
For more information, see [Register a Task with the Maintenance Window (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/mw-cli-tutorial-tasks.html) in the *AWS Systems Manager User Guide*.
**Example 5: To register a task using a maintenance windows target ID**
The following `register-task-with-maintenance-window` example registers a task using a maintenance window target ID. The maintenance window target ID was in the output of the `aws ssm register-target-with-maintenance-window` command. You can also retrieve it from the output of the `aws ssm describe-maintenance-window-targets` command.
```
aws ssm register-task-with-maintenance-window \
--targets "Key=WindowTargetIds,Values=350d44e6-28cc-44e2-951f-4b2c9EXAMPLE" \
--task-arn "AWS-RunShellScript" \
--service-role-arn "arn:aws:iam::111222333444:role/MaintenanceWindowsRole" \
--window-id "mw-ab12cd34eEXAMPLE" \
--task-type "RUN_COMMAND" \
--task-parameters "{\"commands\":{\"Values\":[\"df\"]}}" \
--max-concurrency 1 \
--max-errors 1 \
--priority 10
```
Output:
```
{
"WindowTaskId":"33344444-5555-6666-7777-88888888"
}
```
For more information, see [Register a Task with the Maintenance Window (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/mw-cli-tutorial-tasks.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [RegisterTaskWithMaintenanceWindow](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/register-task-with-maintenance-window.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example registers a task with a maintenance window using an instance ID. The output is the Task ID.**
```
$parameters = @{}
$parameterValues = New-Object Amazon.SimpleSystemsManagement.Model.MaintenanceWindowTaskParameterValueExpression
$parameterValues.Values = @("Install")
$parameters.Add("Operation", $parameterValues)
Register-SSMTaskWithMaintenanceWindow -WindowId "mw-03a342e62c96d31b0" -ServiceRoleArn "arn:aws:iam::123456789012:role/MaintenanceWindowsRole" -MaxConcurrency 1 -MaxError 1 -TaskArn "AWS-RunShellScript" -Target @{ Key="InstanceIds";Values="i-0000293ffd8c57862" } -TaskType "RUN_COMMAND" -Priority 10 -TaskParameter $parameters
```
**Output:**
```
f34a2c47-ddfd-4c85-a88d-72366b69af1b
```
**Example 2: This example registers a task with a maintenance window using a target ID. The output is the Task ID.**
```
$parameters = @{}
$parameterValues = New-Object Amazon.SimpleSystemsManagement.Model.MaintenanceWindowTaskParameterValueExpression
$parameterValues.Values = @("Install")
$parameters.Add("Operation", $parameterValues)
register-ssmtaskwithmaintenancewindow -WindowId "mw-03a342e62c96d31b0" -ServiceRoleArn "arn:aws:iam::123456789012:role/MaintenanceWindowsRole" -MaxConcurrency 1 -MaxError 1 -TaskArn "AWS-RunShellScript" -Target @{ Key="WindowTargetIds";Values="350d44e6-28cc-44e2-951f-4b2c985838f6" } -TaskType "RUN_COMMAND" -Priority 10 -TaskParameter $parameters
```
**Output:**
```
f34a2c47-ddfd-4c85-a88d-72366b69af1b
```
**Example 3: This example creates a parameter object for the run command document `AWS-RunPowerShellScript` and creates a task with given maintenance window using target ID. The return output is the task ID.**
```
$parameters = [Collections.Generic.Dictionary[String,Collections.Generic.List[String]]]::new()
$parameters.Add("commands",@("ipconfig","dir env:\computername"))
$parameters.Add("executionTimeout",@(3600))
$props = @{
WindowId = "mw-0123e4cce56ff78ae"
ServiceRoleArn = "arn:aws:iam::123456789012:role/MaintenanceWindowsRole"
MaxConcurrency = 1
MaxError = 1
TaskType = "RUN_COMMAND"
TaskArn = "AWS-RunPowerShellScript"
Target = @{Key="WindowTargetIds";Values="fe1234ea-56d7-890b-12f3-456b789bee0f"}
Priority = 1
RunCommand_Parameter = $parameters
Name = "set-via-cmdlet"
}
Register-SSMTaskWithMaintenanceWindow @props
```
**Output:**
```
f1e2ef34-5678-12e3-456a-12334c5c6cbe
```
**Example 4: This example registers an AWS Systems Manager Automation task by using a document named `Create-Snapshots`.**
```
$automationParameters = @{}
$automationParameters.Add( "instanceId", @("{{ TARGET_ID }}") )
$automationParameters.Add( "AutomationAssumeRole", @("{arn:aws:iam::111111111111:role/AutomationRole}") )
$automationParameters.Add( "SnapshotTimeout", @("PT20M") )
Register-SSMTaskWithMaintenanceWindow -WindowId mw-123EXAMPLE456`
-ServiceRoleArn "arn:aws:iam::123456789012:role/MW-Role"`
-MaxConcurrency 1 -MaxError 1 -TaskArn "CreateVolumeSnapshots"`
-Target @{ Key="WindowTargetIds";Values="4b5acdf4-946c-4355-bd68-4329a43a5fd1" }`
-TaskType "AUTOMATION"`
-Priority 4`
-Automation_DocumentVersion '$DEFAULT' -Automation_Parameter $automationParameters -Name "Create-Snapshots"
```
+ For API details, see [RegisterTaskWithMaintenanceWindow](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example registers a task with a maintenance window using an instance ID. The output is the Task ID.**
```
$parameters = @{}
$parameterValues = New-Object Amazon.SimpleSystemsManagement.Model.MaintenanceWindowTaskParameterValueExpression
$parameterValues.Values = @("Install")
$parameters.Add("Operation", $parameterValues)
Register-SSMTaskWithMaintenanceWindow -WindowId "mw-03a342e62c96d31b0" -ServiceRoleArn "arn:aws:iam::123456789012:role/MaintenanceWindowsRole" -MaxConcurrency 1 -MaxError 1 -TaskArn "AWS-RunShellScript" -Target @{ Key="InstanceIds";Values="i-0000293ffd8c57862" } -TaskType "RUN_COMMAND" -Priority 10 -TaskParameter $parameters
```
**Output:**
```
f34a2c47-ddfd-4c85-a88d-72366b69af1b
```
**Example 2: This example registers a task with a maintenance window using a target ID. The output is the Task ID.**
```
$parameters = @{}
$parameterValues = New-Object Amazon.SimpleSystemsManagement.Model.MaintenanceWindowTaskParameterValueExpression
$parameterValues.Values = @("Install")
$parameters.Add("Operation", $parameterValues)
register-ssmtaskwithmaintenancewindow -WindowId "mw-03a342e62c96d31b0" -ServiceRoleArn "arn:aws:iam::123456789012:role/MaintenanceWindowsRole" -MaxConcurrency 1 -MaxError 1 -TaskArn "AWS-RunShellScript" -Target @{ Key="WindowTargetIds";Values="350d44e6-28cc-44e2-951f-4b2c985838f6" } -TaskType "RUN_COMMAND" -Priority 10 -TaskParameter $parameters
```
**Output:**
```
f34a2c47-ddfd-4c85-a88d-72366b69af1b
```
**Example 3: This example creates a parameter object for the run command document `AWS-RunPowerShellScript` and creates a task with given maintenance window using target ID. The return output is the task ID.**
```
$parameters = [Collections.Generic.Dictionary[String,Collections.Generic.List[String]]]::new()
$parameters.Add("commands",@("ipconfig","dir env:\computername"))
$parameters.Add("executionTimeout",@(3600))
$props = @{
WindowId = "mw-0123e4cce56ff78ae"
ServiceRoleArn = "arn:aws:iam::123456789012:role/MaintenanceWindowsRole"
MaxConcurrency = 1
MaxError = 1
TaskType = "RUN_COMMAND"
TaskArn = "AWS-RunPowerShellScript"
Target = @{Key="WindowTargetIds";Values="fe1234ea-56d7-890b-12f3-456b789bee0f"}
Priority = 1
RunCommand_Parameter = $parameters
Name = "set-via-cmdlet"
}
Register-SSMTaskWithMaintenanceWindow @props
```
**Output:**
```
f1e2ef34-5678-12e3-456a-12334c5c6cbe
```
**Example 4: This example registers an AWS Systems Manager Automation task by using a document named `Create-Snapshots`.**
```
$automationParameters = @{}
$automationParameters.Add( "instanceId", @("{{ TARGET_ID }}") )
$automationParameters.Add( "AutomationAssumeRole", @("{arn:aws:iam::111111111111:role/AutomationRole}") )
$automationParameters.Add( "SnapshotTimeout", @("PT20M") )
Register-SSMTaskWithMaintenanceWindow -WindowId mw-123EXAMPLE456`
-ServiceRoleArn "arn:aws:iam::123456789012:role/MW-Role"`
-MaxConcurrency 1 -MaxError 1 -TaskArn "CreateVolumeSnapshots"`
-Target @{ Key="WindowTargetIds";Values="4b5acdf4-946c-4355-bd68-4329a43a5fd1" }`
-TaskType "AUTOMATION"`
-Priority 4`
-Automation_DocumentVersion '$DEFAULT' -Automation_Parameter $automationParameters -Name "Create-Snapshots"
```
+ For API details, see [RegisterTaskWithMaintenanceWindow](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `RemoveTagsFromResource` with a CLI
<a name="ssm_example_ssm_RemoveTagsFromResource_section"></a>
The following code examples show how to use `RemoveTagsFromResource`.
------
#### [ CLI ]
**AWS CLI**
**To remove a tag from a patch baseline**
The following `remove-tags-from-resource` example removes tags from a patch baseline.
```
aws ssm remove-tags-from-resource \
--resource-type "PatchBaseline" \
--resource-id "pb-0123456789abcdef0" \
--tag-keys "Region"
```
This command produces no output.
For more information, see [Tagging AWS Resources](https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html) in the *AWS General Reference*.
+ For API details, see [RemoveTagsFromResource](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/remove-tags-from-resource.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example removes a tag from a maintenance window. There is no output if the command succeeds.**
```
Remove-SSMResourceTag -ResourceId "mw-03eb9db42890fb82d" -ResourceType "MaintenanceWindow" -TagKey "Production"
```
+ For API details, see [RemoveTagsFromResource](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example removes a tag from a maintenance window. There is no output if the command succeeds.**
```
Remove-SSMResourceTag -ResourceId "mw-03eb9db42890fb82d" -ResourceType "MaintenanceWindow" -TagKey "Production"
```
+ For API details, see [RemoveTagsFromResource](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `SendCommand` with an AWS SDK or CLI
<a name="ssm_example_ssm_SendCommand_section"></a>
The following code examples show how to use `SendCommand`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](ssm_example_ssm_Scenario_section.md)
------
#### [ CLI ]
**AWS CLI**
**Example 1: To run a command on one or more remote instances**
The following `send-command` example runs an `echo` command on a target instance.
```
aws ssm send-command \
--document-name "AWS-RunShellScript" \
--parameters 'commands=["echo HelloWorld"]' \
--targets "Key=instanceids,Values=i-1234567890abcdef0" \
--comment "echo HelloWorld"
```
Output:
```
{
"Command": {
"CommandId": "92853adf-ba41-4cd6-9a88-142d1EXAMPLE",
"DocumentName": "AWS-RunShellScript",
"DocumentVersion": "",
"Comment": "echo HelloWorld",
"ExpiresAfter": 1550181014.717,
"Parameters": {
"commands": [
"echo HelloWorld"
]
},
"InstanceIds": [
"i-0f00f008a2dcbefe2"
],
"Targets": [],
"RequestedDateTime": 1550173814.717,
"Status": "Pending",
"StatusDetails": "Pending",
"OutputS3BucketName": "",
"OutputS3KeyPrefix": "",
"MaxConcurrency": "50",
"MaxErrors": "0",
"TargetCount": 1,
"CompletedCount": 0,
"ErrorCount": 0,
"DeliveryTimedOutCount": 0,
"ServiceRole": "",
"NotificationConfig": {
"NotificationArn": "",
"NotificationEvents": [],
"NotificationType": ""
},
"CloudWatchOutputConfig": {
"CloudWatchLogGroupName": "",
"CloudWatchOutputEnabled": false
}
}
}
```
For more information, see [Running Commands Using Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html) in the *AWS Systems Manager User Guide*.
**Example 2: To get IP information about an instance**
The following `send-command` example retrieves the IP information about an instance.
```
aws ssm send-command \
--instance-ids "i-1234567890abcdef0" \
--document-name "AWS-RunShellScript" \
--comment "IP config" \
--parameters "commands=ifconfig"
```
See example 1 for sample output.
For more information, see [Running Commands Using Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html) in the *AWS Systems Manager User Guide*.
**Example 3: To run a command on instances with specific tags**
The following `send-command` example runs a command on instances that have the tag key "ENV" and the value "Dev".
```
aws ssm send-command \
--targets "Key=tag:ENV,Values=Dev" \
--document-name "AWS-RunShellScript" \
--parameters "commands=ifconfig"
```
See example 1 for sample output.
For more information, see [Running Commands Using Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html) in the *AWS Systems Manager User Guide*.
**Example 4: To run a command that sends SNS notifications**
The following `send-command` example runs a command that sends SNS notifications for all notification events and the `Command` notification type.
```
aws ssm send-command \
--instance-ids "i-1234567890abcdef0" \
--document-name "AWS-RunShellScript" \
--comment "IP config" \
--parameters "commands=ifconfig" \
--service-role-arn "arn:aws:iam::123456789012:role/SNS_Role" \
--notification-config "NotificationArn=arn:aws:sns:us-east-1:123456789012:SNSTopicName,NotificationEvents=All,NotificationType=Command"
```
See example 1 for sample output.
For more information, see [Running Commands Using Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html) in the *AWS Systems Manager User Guide*.
**Example 5: To run a command that outputs to S3 and CloudWatch**
The following `send-command` example runs a command that outputs command details to an S3 bucket and to a CloudWatch Logs log group.
```
aws ssm send-command \
--instance-ids "i-1234567890abcdef0" \
--document-name "AWS-RunShellScript" \
--comment "IP config" \
--parameters "commands=ifconfig" \
--output-s3-bucket-name "s3-bucket-name" \
--output-s3-key-prefix "runcommand" \
--cloud-watch-output-config "CloudWatchOutputEnabled=true,CloudWatchLogGroupName=CWLGroupName"
```
See example 1 for sample output.
For more information, see [Running Commands Using Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html) in the *AWS Systems Manager User Guide*.
**Example 6: To run commands on multiple instances with different tags**
The following `send-command` example runs a command on instances with two different tag keys and values.
```
aws ssm send-command \
--document-name "AWS-RunPowerShellScript" \
--parameters commands=["echo helloWorld"] \
--targets Key=tag:Env,Values=Dev Key=tag:Role,Values=WebServers
```
See example 1 for sample output.
For more information, see [Running Commands Using Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html) in the *AWS Systems Manager User Guide*.
**Example 7: To target multiple instances with the same tag key**
The following `send-command` example runs a command on instances that have the same tag key but with different values.
```
aws ssm send-command \
--document-name "AWS-RunPowerShellScript" \
--parameters commands=["echo helloWorld"] \
--targets Key=tag:Env,Values=Dev,Test
```
See example 1 for sample output.
For more information, see [Running Commands Using Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html) in the *AWS Systems Manager User Guide*.
**Example 8: To run a command that uses a shared document**
The following `send-command` example runs a shared document on a target instance.
```
aws ssm send-command \
--document-name "arn:aws:ssm:us-east-1:123456789012:document/ExampleDocument" \
--targets "Key=instanceids,Values=i-1234567890abcdef0"
```
See example 1 for sample output.
For more information, see [Using shared SSM documents](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-using-shared.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [SendCommand](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/send-command.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/ssm#code-examples).
```
/**
* Sends a SSM command to a managed node asynchronously.
*
* @param documentName The name of the document to use.
* @param instanceId The ID of the instance to send the command to.
* @return The command ID.
* <p>
* This method initiates asynchronous requests to send a SSM command to a managed node.
* It waits until the document is active, sends the command, and checks the command execution status.
*/
public String sendSSMCommand(String documentName, String instanceId) throws InterruptedException, SsmException {
// Before we use Document to send a command - make sure it is active.
CompletableFuture<Void> documentActiveFuture = CompletableFuture.runAsync(() -> {
boolean isDocumentActive = false;
DescribeDocumentRequest request = DescribeDocumentRequest.builder()
.name(documentName)
.build();
while (!isDocumentActive) {
CompletableFuture<DescribeDocumentResponse> response = getAsyncClient().describeDocument(request);
String documentStatus = response.join().document().statusAsString();
if (documentStatus.equals("Active")) {
System.out.println("The SSM document is active and ready to use.");
isDocumentActive = true;
} else {
System.out.println("The SSM document is not active. Status: " + documentStatus);
try {
Thread.sleep(5000);
} catch (InterruptedException e) {
throw new RuntimeException(e);
}
}
}
});
documentActiveFuture.join();
// Create the SendCommandRequest.
SendCommandRequest commandRequest = SendCommandRequest.builder()
.documentName(documentName)
.instanceIds(instanceId)
.build();
// Send the command.
CompletableFuture<SendCommandResponse> commandFuture = getAsyncClient().sendCommand(commandRequest);
final String[] commandId = {null};
commandFuture.whenComplete((commandResponse, ex) -> {
if (commandResponse != null) {
commandId[0] = commandResponse.command().commandId();
System.out.println("Command ID: " + commandId[0]);
// Wait for the command execution to complete.
GetCommandInvocationRequest invocationRequest = GetCommandInvocationRequest.builder()
.commandId(commandId[0])
.instanceId(instanceId)
.build();
try {
System.out.println("Wait 5 secs");
TimeUnit.SECONDS.sleep(5);
// Retrieve the command execution details.
CompletableFuture<GetCommandInvocationResponse> invocationFuture = getAsyncClient().getCommandInvocation(invocationRequest);
invocationFuture.whenComplete((commandInvocationResponse, invocationEx) -> {
if (commandInvocationResponse != null) {
// Check the status of the command execution.
CommandInvocationStatus status = commandInvocationResponse.status();
if (status == CommandInvocationStatus.SUCCESS) {
System.out.println("Command execution successful");
} else {
System.out.println("Command execution failed. Status: " + status);
}
} else {
Throwable invocationCause = (invocationEx instanceof CompletionException) ? invocationEx.getCause() : invocationEx;
throw new CompletionException(invocationCause);
}
}).join();
} catch (InterruptedException e) {
throw new RuntimeException(e);
}
} else {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw (SsmException) cause;
} else {
throw new RuntimeException(cause);
}
}
}).join();
return commandId[0];
}
```
+ For API details, see [SendCommand](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/SendCommand) in *AWS SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ssm#code-examples).
```
import { SendCommandCommand, SSMClient } from "@aws-sdk/client-ssm";
import { parseArgs } from "node:util";
/**
* Send an SSM command to a managed node.
* @param {{ documentName: string }}
*/
export const main = async ({ documentName }) => {
const client = new SSMClient({});
try {
await client.send(
new SendCommandCommand({
DocumentName: documentName,
}),
);
console.log("Command sent successfully.");
return { Success: true };
} catch (caught) {
if (caught instanceof Error && caught.name === "ValidationError") {
console.warn(`${caught.message}. Did you provide a valid document name?`);
} else {
throw caught;
}
}
};
```
+ For API details, see [SendCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/SendCommandCommand) in *AWS SDK for JavaScript API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example runs an echo command on a target instance.**
```
Send-SSMCommand -DocumentName "AWS-RunPowerShellScript" -Parameter @{commands = "echo helloWorld"} -Target @{Key="instanceids";Values=@("i-0cb2b964d3e14fd9f")}
```
**Output:**
```
CommandId : d8d190fc-32c1-4d65-a0df-ff5ff3965524
Comment :
CompletedCount : 0
DocumentName : AWS-RunPowerShellScript
ErrorCount : 0
ExpiresAfter : 3/7/2017 10:48:37 PM
InstanceIds : {}
MaxConcurrency : 50
MaxErrors : 0
NotificationConfig : Amazon.SimpleSystemsManagement.Model.NotificationConfig
OutputS3BucketName :
OutputS3KeyPrefix :
OutputS3Region :
Parameters : {[commands, Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
RequestedDateTime : 3/7/2017 9:48:37 PM
ServiceRole :
Status : Pending
StatusDetails : Pending
TargetCount : 0
Targets : {instanceids}
```
**Example 2: This example shows how to run a command that accepts nested parameters.**
```
Send-SSMCommand -DocumentName "AWS-RunRemoteScript" -Parameter @{ sourceType="GitHub";sourceInfo='{"owner": "me","repository": "amazon-ssm","path": "Examples/Install-Win32OpenSSH"}'; "commandLine"=".\Install-Win32OpenSSH.ps1"} -InstanceId i-0cb2b964d3e14fd9f
```
+ For API details, see [SendCommand](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example runs an echo command on a target instance.**
```
Send-SSMCommand -DocumentName "AWS-RunPowerShellScript" -Parameter @{commands = "echo helloWorld"} -Target @{Key="instanceids";Values=@("i-0cb2b964d3e14fd9f")}
```
**Output:**
```
CommandId : d8d190fc-32c1-4d65-a0df-ff5ff3965524
Comment :
CompletedCount : 0
DocumentName : AWS-RunPowerShellScript
ErrorCount : 0
ExpiresAfter : 3/7/2017 10:48:37 PM
InstanceIds : {}
MaxConcurrency : 50
MaxErrors : 0
NotificationConfig : Amazon.SimpleSystemsManagement.Model.NotificationConfig
OutputS3BucketName :
OutputS3KeyPrefix :
OutputS3Region :
Parameters : {[commands, Amazon.Runtime.Internal.Util.AlwaysSendList`1[System.String]]}
RequestedDateTime : 3/7/2017 9:48:37 PM
ServiceRole :
Status : Pending
StatusDetails : Pending
TargetCount : 0
Targets : {instanceids}
```
**Example 2: This example shows how to run a command that accepts nested parameters.**
```
Send-SSMCommand -DocumentName "AWS-RunRemoteScript" -Parameter @{ sourceType="GitHub";sourceInfo='{"owner": "me","repository": "amazon-ssm","path": "Examples/Install-Win32OpenSSH"}'; "commandLine"=".\Install-Win32OpenSSH.ps1"} -InstanceId i-0cb2b964d3e14fd9f
```
+ For API details, see [SendCommand](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
```
class DocumentWrapper:
"""Encapsulates AWS Systems Manager Document actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def send_command(self, instance_ids):
"""
Sends a command to one or more instances.
:param instance_ids: The IDs of the instances to send the command to.
:return: The ID of the command.
"""
try:
response = self.ssm_client.send_command(
InstanceIds=instance_ids, DocumentName=self.name, TimeoutSeconds=3600
)
return response["Command"]["CommandId"]
except ClientError as err:
logger.error(
"Couldn't send command to %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [SendCommand](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/SendCommand) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/ssm#code-examples).
```
TRY.
DATA(lo_result) = lo_ssm->sendcommand(
it_instanceids = it_instance_ids
iv_documentname = iv_document_name
iv_timeoutseconds = 3600 ).
DATA(lo_command) = lo_result->get_command( ).
IF lo_command IS BOUND.
rv_command_id = lo_command->get_commandid( ).
MESSAGE 'Command sent successfully.' TYPE 'I'.
ENDIF.
CATCH /aws1/cx_ssminvaliddocument.
MESSAGE 'Invalid document.' TYPE 'I'.
CATCH /aws1/cx_ssminvalidinstanceid.
MESSAGE 'Invalid instance ID.' TYPE 'I'.
ENDTRY.
```
+ For API details, see [SendCommand](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------
# Use `StartAutomationExecution` with a CLI
<a name="ssm_example_ssm_StartAutomationExecution_section"></a>
The following code examples show how to use `StartAutomationExecution`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To execute an automation document**
The following `start-automation-execution` example runs an Automation document.
```
aws ssm start-automation-execution \
--document-name "AWS-UpdateLinuxAmi" \
--parameters "AutomationAssumeRole=arn:aws:iam::123456789012:role/SSMAutomationRole,SourceAmiId=ami-EXAMPLE,IamInstanceProfileName=EC2InstanceRole"
```
Output:
```
{
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0a1b2EXAMPLE"
}
```
For more information, see [Running an Automation Workflow Manually](https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-working-executing-manually.html) in the *AWS Systems Manager User Guide*.
**Example 2: To run a shared automation document**
The following `start-automation-execution` example runs a shared Automation document.
```
aws ssm start-automation-execution \
--document-name "arn:aws:ssm:us-east-1:123456789012:document/ExampleDocument"
```
Output:
```
{
"AutomationExecutionId": "4105a4fc-f944-11e6-9d32-0a1b2EXAMPLE"
}
```
For more information, see [Using shared SSM documents](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-using-shared.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [StartAutomationExecution](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/start-automation-execution.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example runs a document specifying an Automation role, an AMI source ID, and an Amazon EC2 instance role.**
```
Start-SSMAutomationExecution -DocumentName AWS-UpdateLinuxAmi -Parameter @{'AutomationAssumeRole'='arn:aws:iam::123456789012:role/SSMAutomationRole';'SourceAmiId'='ami-f173cc91';'InstanceIamRole'='EC2InstanceRole'}
```
**Output:**
```
3a532a4f-0382-11e7-9df7-6f11185f6dd1
```
+ For API details, see [StartAutomationExecution](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example runs a document specifying an Automation role, an AMI source ID, and an Amazon EC2 instance role.**
```
Start-SSMAutomationExecution -DocumentName AWS-UpdateLinuxAmi -Parameter @{'AutomationAssumeRole'='arn:aws:iam::123456789012:role/SSMAutomationRole';'SourceAmiId'='ami-f173cc91';'InstanceIamRole'='EC2InstanceRole'}
```
**Output:**
```
3a532a4f-0382-11e7-9df7-6f11185f6dd1
```
+ For API details, see [StartAutomationExecution](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `StartSession` with a CLI
<a name="ssm_example_ssm_StartSession_section"></a>
The following code examples show how to use `StartSession`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To start a Session Manager session**
This `start-session` example establishes a connection with an instance for a Session Manager session. Note that this interactive command requires the Session Manager plugin to be installed on the client machine making the call.
```
aws ssm start-session \
--target "i-1234567890abcdef0"
```
Output:
```
Starting session with SessionId: Jane-Roe-07a16060613c408b5
```
**Example 2: To start a Session Manager session using SSH**
This `start-session` example establishes a connection with an instance for a Session Manager session using SSH. Note that this interactive command requires the Session Manager plugin to be installed on the client machine making the call, and that the command uses the default user on the instance, such as `ec2-user` for EC2 instances for Linux.
```
ssh -i /path/my-key-pair.pem ec2-user@i-02573cafcfEXAMPLE
```
Output:
```
Starting session with SessionId: ec2-user-07a16060613c408b5
```
For more information, see [Start a Session](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-sessions-start.html) and [Install the Session Manager Plugin for the AWS CLI](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [StartSession](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/start-session.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example initiates a connection to a target for a Session Manager session, enabling port forwarding.**
```
Start-SSMSession -Target 'i-064578e5e7454488f' -DocumentName 'AWS-StartPortForwardingSession' -Parameter @{ localPortNumber = '8080'; portNumber = '80' }
```
**Output:**
```
SessionId StreamUrl
---------- ----------
random-id0 wss://ssmmessages.amazonaws.com/v1/data-channel/random-id
```
+ For API details, see [StartSession](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example initiates a connection to a target for a Session Manager session, enabling port forwarding. Note: You need to add Region parameter if not already set using AWSCredentials.**
```
Start-SSMSession -Target 'i-064578e5e7454488f' -DocumentName 'AWS-StartPortForwardingSession' -Parameter @{ localPortNumber = '8080'; portNumber = '80' } -Region 'us-west-1'
```
**Output:**
```
Starting session with SessionId: testUser-xi4glew849asyeryde34u4dfsdfy
Port 8080 opened for sessionId testUser-xi4glew849asyeryde34u4dfsdfy.
Waiting for connections...
```
**Example 2: This example creates an interactive session with a specified instance for a Session Manager session.**
```
Start-SSMSession -Target 'i-1234567890abcdef0' -Region 'us-west-1'
```
**Output:**
```
Starting session with SessionId : testUser-xi4glew849asyeryde34u4dfsdfy
Windows PowerShell
Copyright (C) Microsoft Corporation. All rights reserved.
Install the latest PowerShell for new features and improvements!
PS C:\Windows\system32> whoami
ec2amaz-fnsdrwv\ec2-test-user
PS C:\Windows\system32>
```
**Example 3: This example creates a session without connecting to it and returns the SessionId, StreamUrl, and TokenValue properties required to connect to the session.**
```
Start-SSMSession -Target 'i-1234567890abcdef0' -Region 'us-west-1' -DisablePluginInvocation
```
**Output:**
```
SessionId : testUser-xi4glew849asyeryde34u4dfsdfy
StreamUrl : {StreamUrl value redacted}
TokenValue : {Token value redacted}
ContentLength : 1207
HttpStatusCode : OK
```
+ For API details, see [StartSession](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `StopAutomationExecution` with a CLI
<a name="ssm_example_ssm_StopAutomationExecution_section"></a>
The following code examples show how to use `StopAutomationExecution`.
------
#### [ CLI ]
**AWS CLI**
**To stop an automation execution**
The following `stop-automation-execution` example stops an Automation document.
```
aws ssm stop-automation-execution
--automation-execution-id "4105a4fc-f944-11e6-9d32-0a1b2EXAMPLE"
```
This command produces no output.
For more information, see [Running an Automation Workflow Manually](https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-working-executing-manually.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [StopAutomationExecution](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/stop-automation-execution.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example stops an Automation Execution. There is no output if the command succeeds.**
```
Stop-SSMAutomationExecution -AutomationExecutionId "4105a4fc-f944-11e6-9d32-8fb2db27a909"
```
+ For API details, see [StopAutomationExecution](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example stops an Automation Execution. There is no output if the command succeeds.**
```
Stop-SSMAutomationExecution -AutomationExecutionId "4105a4fc-f944-11e6-9d32-8fb2db27a909"
```
+ For API details, see [StopAutomationExecution](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `UpdateAssociation` with a CLI
<a name="ssm_example_ssm_UpdateAssociation_section"></a>
The following code examples show how to use `UpdateAssociation`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To update a document association**
The following `update-association` example updates an association with a new document version.
```
aws ssm update-association \
--association-id "8dfe3659-4309-493a-8755-0123456789ab" \
--document-version "\$LATEST"
```
Output:
```
{
"AssociationDescription": {
"Name": "AWS-UpdateSSMAgent",
"AssociationVersion": "2",
"Date": 1550508093.293,
"LastUpdateAssociationDate": 1550508106.596,
"Overview": {
"Status": "Pending",
"DetailedStatus": "Creating"
},
"DocumentVersion": "$LATEST",
"AssociationId": "8dfe3659-4309-493a-8755-0123456789ab",
"Targets": [
{
"Key": "tag:Name",
"Values": [
"Linux"
]
}
],
"LastExecutionDate": 1550508094.879,
"LastSuccessfulExecutionDate": 1550508094.879
}
}
```
For more information, see [Editing and creating a new version of an association](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-state-assoc-edit.html) in the *AWS Systems Manager User Guide*.
**Example 2: To update the schedule expression of an association**
The following `update-association` example updates the schedule expression for the specified association.
```
aws ssm update-association \
--association-id "8dfe3659-4309-493a-8755-0123456789ab" \
--schedule-expression "cron(0 0 0/4 1/1 * ? *)"
```
Output:
```
{
"AssociationDescription": {
"Name": "AWS-HelloWorld",
"AssociationVersion": "2",
"Date": "2021-02-08T13:54:19.203000-08:00",
"LastUpdateAssociationDate": "2021-06-29T11:51:07.933000-07:00",
"Overview": {
"Status": "Pending",
"DetailedStatus": "Creating"
},
"DocumentVersion": "$DEFAULT",
"AssociationId": "8dfe3659-4309-493a-8755-0123456789ab",
"Targets": [
{
"Key": "aws:NoOpAutomationTag",
"Values": [
"AWS-NoOpAutomationTarget-Value"
]
}
],
"ScheduleExpression": "cron(0 0 0/4 1/1 * ? *)",
"LastExecutionDate": "2021-06-26T19:00:48.110000-07:00",
"ApplyOnlyAtCronInterval": false
}
}
```
For more information, see [Editing and creating a new version of an association](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-state-assoc-edit.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [UpdateAssociation](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/update-association.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example updates an association with a new document version.**
```
Update-SSMAssociation -AssociationId "93285663-92df-44cb-9f26-2292d4ecc439" -DocumentVersion "1"
```
**Output:**
```
Name : AWS-UpdateSSMAgent
InstanceId :
Date : 3/1/2017 6:22:21 PM
Status.Name :
Status.Date :
Status.Message :
Status.AdditionalInfo :
```
+ For API details, see [UpdateAssociation](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example updates an association with a new document version.**
```
Update-SSMAssociation -AssociationId "93285663-92df-44cb-9f26-2292d4ecc439" -DocumentVersion "1"
```
**Output:**
```
Name : AWS-UpdateSSMAgent
InstanceId :
Date : 3/1/2017 6:22:21 PM
Status.Name :
Status.Date :
Status.Message :
Status.AdditionalInfo :
```
+ For API details, see [UpdateAssociation](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `UpdateAssociationStatus` with a CLI
<a name="ssm_example_ssm_UpdateAssociationStatus_section"></a>
The following code examples show how to use `UpdateAssociationStatus`.
------
#### [ CLI ]
**AWS CLI**
**To update the association status**
The following `update-association-status` example updates the association status of the association between an instance and a document.
```
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,
"Name": "Pending",
"Message": "temp_status_change",
"AdditionalInfo": "Additional-Config-Needed"
},
"Overview": {
"Status": "Success",
"AssociationStatusAggregatedCount": {
"Success": 1
}
},
"DocumentVersion": "$DEFAULT",
"AssociationId": "8dfe3659-4309-493a-8755-0123456789ab",
"Targets": [
{
"Key": "InstanceIds",
"Values": [
"i-1234567890abcdef0"
]
}
],
"LastExecutionDate": 1550507808.0,
"LastSuccessfulExecutionDate": 1550507808.0
}
}
```
For more information, see [Working with associations in Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-associations.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [UpdateAssociationStatus](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/update-association-status.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example updates the association status of the association between an instance and a configuration document.**
```
Update-SSMAssociationStatus -Name "AWS-UpdateSSMAgent" -InstanceId "i-0000293ffd8c57862" -AssociationStatus_Date "2015-02-20T08:31:11Z" -AssociationStatus_Name "Pending" -AssociationStatus_Message "temporary_status_change" -AssociationStatus_AdditionalInfo "Additional-Config-Needed"
```
**Output:**
```
Name : AWS-UpdateSSMAgent
InstanceId : i-0000293ffd8c57862
Date : 2/23/2017 6:55:22 PM
Status.Name : Pending
Status.Date : 2/20/2015 8:31:11 AM
Status.Message : temporary_status_change
Status.AdditionalInfo : Additional-Config-Needed
```
+ For API details, see [UpdateAssociationStatus](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example updates the association status of the association between an instance and a configuration document.**
```
Update-SSMAssociationStatus -Name "AWS-UpdateSSMAgent" -InstanceId "i-0000293ffd8c57862" -AssociationStatus_Date "2015-02-20T08:31:11Z" -AssociationStatus_Name "Pending" -AssociationStatus_Message "temporary_status_change" -AssociationStatus_AdditionalInfo "Additional-Config-Needed"
```
**Output:**
```
Name : AWS-UpdateSSMAgent
InstanceId : i-0000293ffd8c57862
Date : 2/23/2017 6:55:22 PM
Status.Name : Pending
Status.Date : 2/20/2015 8:31:11 AM
Status.Message : temporary_status_change
Status.AdditionalInfo : Additional-Config-Needed
```
+ For API details, see [UpdateAssociationStatus](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `UpdateDocument` with a CLI
<a name="ssm_example_ssm_UpdateDocument_section"></a>
The following code examples show how to use `UpdateDocument`.
------
#### [ CLI ]
**AWS CLI**
**To create a new version of a document**
The following `update-document` example creates a new version of a document when run on a Windows computer. The document specified by `--document` must be in JSON format. Note that `file://` must be referenced followed by the path of the content file. Because of the `$` at the beginning of the `--document-version` parameter, On Windows you must surround the value with double quotes. On Linux, MacOS, or at a PowerShell prompt, you must surround the value with single quotes.
**Windows version**:
```
aws ssm update-document \
--name "RunShellScript" \
--content "file://RunShellScript.json" \
--document-version "$LATEST"
```
**Linux/Mac version**:
```
aws ssm update-document \
--name "RunShellScript" \
--content "file://RunShellScript.json" \
--document-version '$LATEST'
```
Output:
```
{
"DocumentDescription": {
"Status": "Updating",
"Hash": "f775e5df4904c6fa46686c4722fae9de1950dace25cd9608ff8d622046b68d9b",
"Name": "RunShellScript",
"Parameters": [
{
"Type": "StringList",
"Name": "commands",
"Description": "(Required) Specify a shell script or a command to run."
}
],
"DocumentType": "Command",
"PlatformTypes": [
"Linux"
],
"DocumentVersion": "2",
"HashType": "Sha256",
"CreatedDate": 1487899655.152,
"Owner": "809632081692",
"SchemaVersion": "2.0",
"DefaultVersion": "1",
"LatestVersion": "2",
"Description": "Run an updated script"
}
}
```
+ For API details, see [UpdateDocument](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/update-document.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This creates a new version of a document with the updated contents of the json file you specify. The document must be in JSON format. You can obtain the document version with the "Get-SSMDocumentVersionList" cmdlet.**
```
Update-SSMDocument -Name RunShellScript -DocumentVersion "1" -Content (Get-Content -Raw "c:\temp\RunShellScript.json")
```
**Output:**
```
CreatedDate : 3/1/2017 2:59:17 AM
DefaultVersion : 1
Description : Run an updated script
DocumentType : Command
DocumentVersion : 2
Hash : 1d5ce820e999ff051eb4841ed887593daf77120fd76cae0d18a53cc42e4e22c1
HashType : Sha256
LatestVersion : 2
Name : RunShellScript
Owner : 809632081692
Parameters : {commands}
PlatformTypes : {Linux}
SchemaVersion : 2.0
Sha1 :
Status : Updating
```
+ For API details, see [UpdateDocument](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This creates a new version of a document with the updated contents of the json file you specify. The document must be in JSON format. You can obtain the document version with the "Get-SSMDocumentVersionList" cmdlet.**
```
Update-SSMDocument -Name RunShellScript -DocumentVersion "1" -Content (Get-Content -Raw "c:\temp\RunShellScript.json")
```
**Output:**
```
CreatedDate : 3/1/2017 2:59:17 AM
DefaultVersion : 1
Description : Run an updated script
DocumentType : Command
DocumentVersion : 2
Hash : 1d5ce820e999ff051eb4841ed887593daf77120fd76cae0d18a53cc42e4e22c1
HashType : Sha256
LatestVersion : 2
Name : RunShellScript
Owner : 809632081692
Parameters : {commands}
PlatformTypes : {Linux}
SchemaVersion : 2.0
Sha1 :
Status : Updating
```
+ For API details, see [UpdateDocument](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `UpdateDocumentDefaultVersion` with a CLI
<a name="ssm_example_ssm_UpdateDocumentDefaultVersion_section"></a>
The following code examples show how to use `UpdateDocumentDefaultVersion`.
------
#### [ CLI ]
**AWS CLI**
**To update the default version of a document**
The following `update-document-default-version` example updates the default version of a Systems Manager document.
```
aws ssm update-document-default-version \
--name "Example" \
--document-version "2"
```
Output:
```
{
"Description": {
"Name": "Example",
"DefaultVersion": "2"
}
}
```
For more information, see [Writing SSM Document Content](https://docs.aws.amazon.com/systems-manager/latest/userguide/create-ssm-doc.html#writing-ssm-doc-content) in the *AWS Systems Manager User Guide*.
+ For API details, see [UpdateDocumentDefaultVersion](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/update-document-default-version.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This updates the default version of a document. You can obtain the available document versions with the "Get-SSMDocumentVersionList" cmdlet.**
```
Update-SSMDocumentDefaultVersion -Name "RunShellScript" -DocumentVersion "2"
```
**Output:**
```
DefaultVersion Name
-------------- ----
2 RunShellScript
```
+ For API details, see [UpdateDocumentDefaultVersion](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This updates the default version of a document. You can obtain the available document versions with the "Get-SSMDocumentVersionList" cmdlet.**
```
Update-SSMDocumentDefaultVersion -Name "RunShellScript" -DocumentVersion "2"
```
**Output:**
```
DefaultVersion Name
-------------- ----
2 RunShellScript
```
+ For API details, see [UpdateDocumentDefaultVersion](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `UpdateMaintenanceWindow` with an AWS SDK or CLI
<a name="ssm_example_ssm_UpdateMaintenanceWindow_section"></a>
The following code examples show how to use `UpdateMaintenanceWindow`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To update a maintenance window**
The following `update-maintenance-window` example updates the name of a maintenance window.
```
aws ssm update-maintenance-window \
--window-id "mw-1a2b3c4d5e6f7g8h9" \
--name "My-Renamed-MW"
```
Output:
```
{
"Cutoff": 1,
"Name": "My-Renamed-MW",
"Schedule": "cron(0 16 ? * TUE *)",
"Enabled": true,
"AllowUnassociatedTargets": true,
"WindowId": "mw-1a2b3c4d5e6f7g8h9",
"Duration": 4
}
```
**Example 2: To disable a maintenance window**
The following `update-maintenance-window` example disables a maintenance window.
```
aws ssm update-maintenance-window \
--window-id "mw-1a2b3c4d5e6f7g8h9" \
--no-enabled
```
**Example 3: To enable a maintenance window**
The following `update-maintenance-window` example enables a maintenance window.
```
aws ssm update-maintenance-window \
--window-id "mw-1a2b3c4d5e6f7g8h9" \
--enabled
```
For more information, see [Update a Maintenance Window (AWS CLI)](https://docs.aws.amazon.com/systems-manager/latest/userguide/maintenance-windows-cli-tutorials-update.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [UpdateMaintenanceWindow](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/update-maintenance-window.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/ssm#code-examples).
```
/**
* Updates an SSM maintenance window asynchronously.
*
* @param id The ID of the maintenance window to update.
* @param name The new name for the maintenance window.
* <p>
* This method initiates an asynchronous request to update an SSM maintenance window.
* If the request is successful, it prints a success message.
* If an exception occurs, it handles the error appropriately.
*/
public void updateSSMMaintenanceWindow(String id, String name) throws SsmException {
UpdateMaintenanceWindowRequest updateRequest = UpdateMaintenanceWindowRequest.builder()
.windowId(id)
.allowUnassociatedTargets(true)
.duration(24)
.enabled(true)
.name(name)
.schedule("cron(0 0 ? * MON *)")
.build();
CompletableFuture<UpdateMaintenanceWindowResponse> future = getAsyncClient().updateMaintenanceWindow(updateRequest);
future.whenComplete((response, ex) -> {
if (response != null) {
System.out.println("The SSM maintenance window was successfully updated");
} else {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw new CompletionException(cause);
} else {
throw new RuntimeException(cause);
}
}
}).join();
}
```
+ For API details, see [UpdateMaintenanceWindow](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/UpdateMaintenanceWindow) in *AWS SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ssm#code-examples).
```
import { UpdateMaintenanceWindowCommand, SSMClient } from "@aws-sdk/client-ssm";
import { parseArgs } from "node:util";
/**
* Update an SSM maintenance window.
* @param {{ windowId: string, allowUnassociatedTargets?: boolean, duration?: number, enabled?: boolean, name?: string, schedule?: string }}
*/
export const main = async ({
windowId,
allowUnassociatedTargets = undefined, //Allow the maintenance window to run on managed nodes, even if you haven't registered those nodes as targets.
duration = undefined, //The duration of the maintenance window in hours.
enabled = undefined,
name = undefined,
schedule = undefined, //The schedule of the maintenance window in the form of a cron or rate expression.
}) => {
const client = new SSMClient({});
try {
const { opsItemArn, opsItemId } = await client.send(
new UpdateMaintenanceWindowCommand({
WindowId: windowId,
AllowUnassociatedTargets: allowUnassociatedTargets,
Duration: duration,
Enabled: enabled,
Name: name,
Schedule: schedule,
}),
);
console.log("Maintenance window updated.");
return { OpsItemArn: opsItemArn, OpsItemId: opsItemId };
} catch (caught) {
if (caught instanceof Error && caught.name === "ValidationError") {
console.warn(`${caught.message}. Are these values correct?`);
} else {
throw caught;
}
}
};
```
+ For API details, see [UpdateMaintenanceWindow](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/UpdateMaintenanceWindowCommand) in *AWS SDK for JavaScript API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example updates the name of a maintenance window.**
```
Update-SSMMaintenanceWindow -WindowId "mw-03eb9db42890fb82d" -Name "My-Renamed-MW"
```
**Output:**
```
AllowUnassociatedTargets : False
Cutoff : 1
Duration : 2
Enabled : True
Name : My-Renamed-MW
Schedule : cron(0 */30 * * * ? *)
WindowId : mw-03eb9db42890fb82d
```
**Example 2: This example enables a maintenance window.**
```
Update-SSMMaintenanceWindow -WindowId "mw-03eb9db42890fb82d" -Enabled $true
```
**Output:**
```
AllowUnassociatedTargets : False
Cutoff : 1
Duration : 2
Enabled : True
Name : My-Renamed-MW
Schedule : cron(0 */30 * * * ? *)
WindowId : mw-03eb9db42890fb82d
```
**Example 3: This example disables a maintenance window.**
```
Update-SSMMaintenanceWindow -WindowId "mw-03eb9db42890fb82d" -Enabled $false
```
**Output:**
```
AllowUnassociatedTargets : False
Cutoff : 1
Duration : 2
Enabled : False
Name : My-Renamed-MW
Schedule : cron(0 */30 * * * ? *)
WindowId : mw-03eb9db42890fb82d
```
+ For API details, see [UpdateMaintenanceWindow](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example updates the name of a maintenance window.**
```
Update-SSMMaintenanceWindow -WindowId "mw-03eb9db42890fb82d" -Name "My-Renamed-MW"
```
**Output:**
```
AllowUnassociatedTargets : False
Cutoff : 1
Duration : 2
Enabled : True
Name : My-Renamed-MW
Schedule : cron(0 */30 * * * ? *)
WindowId : mw-03eb9db42890fb82d
```
**Example 2: This example enables a maintenance window.**
```
Update-SSMMaintenanceWindow -WindowId "mw-03eb9db42890fb82d" -Enabled $true
```
**Output:**
```
AllowUnassociatedTargets : False
Cutoff : 1
Duration : 2
Enabled : True
Name : My-Renamed-MW
Schedule : cron(0 */30 * * * ? *)
WindowId : mw-03eb9db42890fb82d
```
**Example 3: This example disables a maintenance window.**
```
Update-SSMMaintenanceWindow -WindowId "mw-03eb9db42890fb82d" -Enabled $false
```
**Output:**
```
AllowUnassociatedTargets : False
Cutoff : 1
Duration : 2
Enabled : False
Name : My-Renamed-MW
Schedule : cron(0 */30 * * * ? *)
WindowId : mw-03eb9db42890fb82d
```
+ For API details, see [UpdateMaintenanceWindow](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
```
class MaintenanceWindowWrapper:
"""Encapsulates AWS Systems Manager maintenance window actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.window_id = None
self.name = None
@classmethod
def from_client(cls):
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def update(
self, name, enabled, schedule, duration, cutoff, allow_unassociated_targets
):
"""
Update an AWS Systems Manager maintenance window.
:param name: The name of the maintenance window.
:param enabled: Whether the maintenance window is enabled to run on managed nodes.
:param schedule: The schedule of the maintenance window.
:param duration: The duration of the maintenance window.
:param cutoff: The cutoff time of the maintenance window.
:param allow_unassociated_targets: Allow the maintenance window to run on managed nodes, even
if you haven't registered those nodes as targets.
"""
try:
self.ssm_client.update_maintenance_window(
WindowId=self.window_id,
Name=name,
Enabled=enabled,
Schedule=schedule,
Duration=duration,
Cutoff=cutoff,
AllowUnassociatedTargets=allow_unassociated_targets,
)
self.name = name
logger.info("Updated maintenance window %s.", self.window_id)
except ParamValidationError as error:
logger.error(
"Parameter validation error when trying to update maintenance window %s. Here's why: %s",
self.window_id,
error,
)
raise
except ClientError as err:
logger.error(
"Couldn't update maintenance window %s. Here's why: %s: %s",
self.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [UpdateMaintenanceWindow](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/UpdateMaintenanceWindow) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/ssm#code-examples).
```
TRY.
lo_ssm->updatemaintenancewindow(
iv_windowid = iv_window_id
iv_name = iv_name
iv_enabled = iv_enabled
iv_schedule = iv_schedule
iv_duration = iv_duration
iv_cutoff = iv_cutoff
iv_allowunassociatedtargets = iv_allow_unassociated_targets ).
MESSAGE 'Maintenance window updated.' TYPE 'I'.
CATCH /aws1/cx_ssmdoesnotexistex.
MESSAGE 'Maintenance window does not exist.' TYPE 'I'.
ENDTRY.
```
+ For API details, see [UpdateMaintenanceWindow](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------
# Use `UpdateManagedInstanceRole` with a CLI
<a name="ssm_example_ssm_UpdateManagedInstanceRole_section"></a>
The following code examples show how to use `UpdateManagedInstanceRole`.
------
#### [ CLI ]
**AWS CLI**
**To update the IAM role of a managed instance**
The following `update-managed-instance-role` example updates the IAM instance profile of a managed instance.
```
aws ssm update-managed-instance-role \
--instance-id "mi-08ab247cdfEXAMPLE" \
--iam-role "ExampleRole"
```
This command produces no output.
For more information, see [Step 4: Create an IAM Instance Profile for Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-instance-profile.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [UpdateManagedInstanceRole](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/update-managed-instance-role.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example updates the role of a managed instance. There is no output if the command succeeds.**
```
Update-SSMManagedInstanceRole -InstanceId "mi-08ab247cdf1046573" -IamRole "AutomationRole"
```
+ For API details, see [UpdateManagedInstanceRole](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example updates the role of a managed instance. There is no output if the command succeeds.**
```
Update-SSMManagedInstanceRole -InstanceId "mi-08ab247cdf1046573" -IamRole "AutomationRole"
```
+ For API details, see [UpdateManagedInstanceRole](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Use `UpdateOpsItem` with an AWS SDK or CLI
<a name="ssm_example_ssm_UpdateOpsItem_section"></a>
The following code examples show how to use `UpdateOpsItem`.
Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:
+ [Learn the basics](ssm_example_ssm_Scenario_section.md)
------
#### [ CLI ]
**AWS CLI**
**To update an OpsItem**
The following `update-ops-item` example updates the description, priority, and category for an OpsItem. In addition, the command specifies an SNS topic where the notifications are sent when this OpsItem is edited or changed.
```
aws ssm update-ops-item \
--ops-item-id "oi-287b5EXAMPLE" \
--description "Primary OpsItem for failover event 2020-01-01-fh398yf" \
--priority 2 \
--category "Security" \
--notifications "Arn=arn:aws:sns:us-east-2:111222333444:my-us-east-2-topic"
```
Output:
```
This command produces no output.
```
For more information, see [Working with OpsItems](https://docs.aws.amazon.com/systems-manager/latest/userguide/OpsCenter-working-with-OpsItems.html) in the *AWS Systems Manager User Guide*.
+ For API details, see [UpdateOpsItem](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/update-ops-item.html) in *AWS CLI Command Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/ssm#code-examples).
```
/**
* Resolves an AWS SSM OpsItem asynchronously.
*
* @param opsID The ID of the OpsItem to resolve.
* <p>
* This method initiates an asynchronous request to resolve an SSM OpsItem.
* If an exception occurs, it handles the error appropriately.
*/
public void resolveOpsItem(String opsID) {
UpdateOpsItemRequest opsItemRequest = UpdateOpsItemRequest.builder()
.opsItemId(opsID)
.status(OpsItemStatus.RESOLVED)
.build();
CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
getAsyncClient().updateOpsItem(opsItemRequest)
.thenAccept(response -> {
System.out.println("OpsItem resolved successfully.");
})
.exceptionally(ex -> {
throw new CompletionException(ex);
}).join();
}).exceptionally(ex -> {
Throwable cause = (ex instanceof CompletionException) ? ex.getCause() : ex;
if (cause instanceof SsmException) {
throw new RuntimeException("SSM error: " + cause.getMessage(), cause);
} else {
throw new RuntimeException("Unexpected error: " + cause.getMessage(), cause);
}
});
try {
future.join();
} catch (CompletionException ex) {
throw ex.getCause() instanceof RuntimeException ? (RuntimeException) ex.getCause() : ex;
}
}
```
+ For API details, see [UpdateOpsItem](https://docs.aws.amazon.com/goto/SdkForJavaV2/ssm-2014-11-06/UpdateOpsItem) in *AWS SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ssm#code-examples).
```
import { UpdateOpsItemCommand, SSMClient } from "@aws-sdk/client-ssm";
import { parseArgs } from "node:util";
/**
* Update an SSM OpsItem.
* @param {{ opsItemId: string, status?: OpsItemStatus }}
*/
export const main = async ({
opsItemId,
status = undefined, // The OpsItem status. Status can be Open, In Progress, or Resolved
}) => {
const client = new SSMClient({});
try {
await client.send(
new UpdateOpsItemCommand({
OpsItemId: opsItemId,
Status: status,
}),
);
console.log("Ops item updated.");
return { Success: true };
} catch (caught) {
if (
caught instanceof Error &&
caught.name === "OpsItemLimitExceededException"
) {
console.warn(
`Couldn't create ops item because you have exceeded your open OpsItem limit. ${caught.message}.`,
);
} else {
throw caught;
}
}
};
```
+ For API details, see [UpdateOpsItem](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/ssm/command/UpdateOpsItemCommand) in *AWS SDK for JavaScript API Reference*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/ssm#code-examples).
```
class OpsItemWrapper:
"""Encapsulates AWS Systems Manager OpsItem actions."""
def __init__(self, ssm_client):
"""
:param ssm_client: A Boto3 Systems Manager client.
"""
self.ssm_client = ssm_client
self.id = None
@classmethod
def from_client(cls):
"""
:return: A OpsItemWrapper instance.
"""
ssm_client = boto3.client("ssm")
return cls(ssm_client)
def update(self, title=None, description=None, status=None):
"""
Update an OpsItem.
:param title: The new OpsItem title.
:param description: The new OpsItem description.
:param status: The new OpsItem status.
:return:
"""
args = dict(OpsItemId=self.id)
if title is not None:
args["Title"] = title
if description is not None:
args["Description"] = description
if status is not None:
args["Status"] = status
try:
self.ssm_client.update_ops_item(**args)
except ClientError as err:
logger.error(
"Couldn't update ops item %s. Here's why: %s: %s",
self.id,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [UpdateOpsItem](https://docs.aws.amazon.com/goto/boto3/ssm-2014-11-06/UpdateOpsItem) in *AWS SDK for Python (Boto3) API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/ssm#code-examples).
```
TRY.
lo_ssm->updateopsitem(
iv_opsitemid = iv_ops_item_id
iv_title = iv_title
iv_description = iv_description
iv_status = iv_status ).
MESSAGE 'OpsItem updated.' TYPE 'I'.
CATCH /aws1/cx_ssmopsitemnotfoundex.
MESSAGE 'OpsItem not found.' TYPE 'I'.
CATCH /aws1/cx_ssmopsiteminvparamex.
MESSAGE 'Invalid OpsItem parameter.' TYPE 'I'.
ENDTRY.
```
+ For API details, see [UpdateOpsItem](https://docs.aws.amazon.com/sdk-for-sap-abap/v1/api/latest/index.html) in *AWS SDK for SAP ABAP API reference*.
------
# Use `UpdatePatchBaseline` with a CLI
<a name="ssm_example_ssm_UpdatePatchBaseline_section"></a>
The following code examples show how to use `UpdatePatchBaseline`.
------
#### [ CLI ]
**AWS CLI**
**Example 1: To update a patch baseline**
The following `update-patch-baseline` example adds the specified two patches as rejected and one patch as approved to the specified patch baseline.
```
aws ssm update-patch-baseline \
--baseline-id "pb-0123456789abcdef0" \
--rejected-patches "KB2032276" "MS10-048" \
--approved-patches "KB2124261"
```
Output:
```
{
"BaselineId": "pb-0123456789abcdef0",
"Name": "WindowsPatching",
"OperatingSystem": "WINDOWS",
"GlobalFilters": {
"PatchFilters": []
},
"ApprovalRules": {
"PatchRules": [
{
"PatchFilterGroup": {
"PatchFilters": [
{
"Key": "PRODUCT",
"Values": [
"WindowsServer2016"
]
}
]
},
"ComplianceLevel": "CRITICAL",
"ApproveAfterDays": 0,
"EnableNonSecurity": false
}
]
},
"ApprovedPatches": [
"KB2124261"
],
"ApprovedPatchesComplianceLevel": "UNSPECIFIED",
"ApprovedPatchesEnableNonSecurity": false,
"RejectedPatches": [
"KB2032276",
"MS10-048"
],
"RejectedPatchesAction": "ALLOW_AS_DEPENDENCY",
"CreatedDate": 1550244180.465,
"ModifiedDate": 1550244180.465,
"Description": "Patches for Windows Servers",
"Sources": []
}
```
**Example 2: To rename a patch baseline**
The following `update-patch-baseline` example renames the specified patch baseline.
```
aws ssm update-patch-baseline \
--baseline-id "pb-0713accee01234567" \
--name "Windows-Server-2012-R2-Important-and-Critical-Security-Updates"
```
For more information, see Update or Delete a Patch Baseline <https://docs.aws.amazon.com/systems-manager/latest/userguide/patch-baseline-update-or-delete.html>`\$1\$1 in the *AWS Systems Manager User Guide*.
+ For API details, see [UpdatePatchBaseline](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/update-patch-baseline.html) in *AWS CLI Command Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example adds two patches as rejected and one patch as approved to an existing patch baseline.**
```
Update-SSMPatchBaseline -BaselineId "pb-03da896ca3b68b639" -RejectedPatch "KB2032276","MS10-048" -ApprovedPatch "KB2124261"
```
**Output:**
```
ApprovalRules : Amazon.SimpleSystemsManagement.Model.PatchRuleGroup
ApprovedPatches : {KB2124261}
BaselineId : pb-03da896ca3b68b639
CreatedDate : 3/3/2017 5:02:19 PM
Description : Baseline containing all updates approved for production systems
GlobalFilters : Amazon.SimpleSystemsManagement.Model.PatchFilterGroup
ModifiedDate : 3/3/2017 5:22:10 PM
Name : Production-Baseline
RejectedPatches : {KB2032276, MS10-048}
```
+ For API details, see [UpdatePatchBaseline](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example adds two patches as rejected and one patch as approved to an existing patch baseline.**
```
Update-SSMPatchBaseline -BaselineId "pb-03da896ca3b68b639" -RejectedPatch "KB2032276","MS10-048" -ApprovedPatch "KB2124261"
```
**Output:**
```
ApprovalRules : Amazon.SimpleSystemsManagement.Model.PatchRuleGroup
ApprovedPatches : {KB2124261}
BaselineId : pb-03da896ca3b68b639
CreatedDate : 3/3/2017 5:02:19 PM
Description : Baseline containing all updates approved for production systems
GlobalFilters : Amazon.SimpleSystemsManagement.Model.PatchFilterGroup
ModifiedDate : 3/3/2017 5:22:10 PM
Name : Production-Baseline
RejectedPatches : {KB2032276, MS10-048}
```
+ For API details, see [UpdatePatchBaseline](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*.
------
# Scenarios for Systems Manager using AWS SDKs
<a name="ssm_code_examples_scenarios"></a>
The following code examples show you how to implement common scenarios in Systems Manager with AWS SDKs. These scenarios show you how to accomplish specific tasks by calling multiple functions within Systems Manager or combined with other AWS services. Each scenario includes a link to the complete source code, where you can find instructions on how to set up and run the code.
Scenarios target an intermediate level of experience to help you understand service actions in context.
**Topics**
+ [Creating an Amazon ECS service for the EC2 launch type](ssm_example_ecs_GettingStarted_018_section.md)
+ [Getting started with Amazon EC2](ssm_example_ec2_GettingStarted_013_section.md)
+ [Setting up Systems Manager](ssm_example_iam_GettingStarted_046_section.md)
# Creating an Amazon ECS service for the EC2 launch type
<a name="ssm_example_ecs_GettingStarted_018_section"></a>
The following code example shows how to:
+ Create an ECS cluster
+ Create and monitor a service
+ Clean up resources
------
#### [ Bash ]
**AWS CLI with Bash script**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Sample developer tutorials](https://github.com/aws-samples/sample-developer-tutorials/tree/main/tuts/018-ecs-ec2) repository.
```
#!/bin/bash
# ECS EC2 Launch Type Tutorial Script - UPDATED VERSION
# This script demonstrates creating an ECS cluster, launching a container instance,
# registering a task definition, and creating a service using the EC2 launch type.
# Updated to match the tutorial draft with nginx web server and service creation.
#
# - UPDATED: Changed from sleep task to nginx web server with service
set -e # Exit on any error
# Configuration
SCRIPT_NAME="ecs-ec2-tutorial"
LOG_FILE="${SCRIPT_NAME}-$(date +%Y%m%d-%H%M%S).log"
CLUSTER_NAME="tutorial-cluster-$(openssl rand -hex 4)"
TASK_FAMILY="nginx-task-$(openssl rand -hex 4)"
SERVICE_NAME="nginx-service-$(openssl rand -hex 4)"
KEY_PAIR_NAME="ecs-tutorial-key-$(openssl rand -hex 4)"
SECURITY_GROUP_NAME="ecs-tutorial-sg-$(openssl rand -hex 4)"
# Get current AWS region dynamically
AWS_REGION=$(aws configure get region || echo "us-east-1")
# Resource tracking arrays
CREATED_RESOURCES=()
CLEANUP_ORDER=()
# Logging function
log() {
echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE"
}
# Error handling function
handle_error() {
local exit_code=$?
log "ERROR: Script failed with exit code $exit_code"
log "ERROR: Last command: $BASH_COMMAND"
echo ""
echo "==========================================="
echo "ERROR OCCURRED - ATTEMPTING CLEANUP"
echo "==========================================="
echo "Resources created before error:"
for resource in "${CREATED_RESOURCES[@]}"; do
echo " - $resource"
done
cleanup_resources
exit $exit_code
}
# Set error trap
trap handle_error ERR
# FIXED: Enhanced cleanup function with proper error handling and logging
cleanup_resources() {
log "Starting cleanup process..."
local cleanup_errors=0
# Delete service first (this will stop tasks automatically)
if [[ -n "${SERVICE_ARN:-}" ]]; then
log "Updating service to desired count 0: $SERVICE_NAME"
if ! aws ecs update-service --cluster "$CLUSTER_NAME" --service "$SERVICE_NAME" --desired-count 0 2>>"$LOG_FILE"; then
log "WARNING: Failed to update service desired count to 0"
((cleanup_errors++))
else
log "Waiting for service tasks to stop..."
sleep 30 # Give time for tasks to stop
fi
log "Deleting service: $SERVICE_NAME"
if ! aws ecs delete-service --cluster "$CLUSTER_NAME" --service "$SERVICE_NAME" 2>>"$LOG_FILE"; then
log "WARNING: Failed to delete service $SERVICE_NAME"
((cleanup_errors++))
fi
fi
# Stop and delete any remaining tasks
if [[ -n "${TASK_ARN:-}" ]]; then
log "Stopping task: $TASK_ARN"
if ! aws ecs stop-task --cluster "$CLUSTER_NAME" --task "$TASK_ARN" --reason "Tutorial cleanup" 2>>"$LOG_FILE"; then
log "WARNING: Failed to stop task $TASK_ARN"
((cleanup_errors++))
else
log "Waiting for task to stop..."
if ! aws ecs wait tasks-stopped --cluster "$CLUSTER_NAME" --tasks "$TASK_ARN" 2>>"$LOG_FILE"; then
log "WARNING: Task stop wait failed for $TASK_ARN"
((cleanup_errors++))
fi
fi
fi
# Deregister task definition
if [[ -n "${TASK_DEFINITION_ARN:-}" ]]; then
log "Deregistering task definition: $TASK_DEFINITION_ARN"
if ! aws ecs deregister-task-definition --task-definition "$TASK_DEFINITION_ARN" 2>>"$LOG_FILE"; then
log "WARNING: Failed to deregister task definition $TASK_DEFINITION_ARN"
((cleanup_errors++))
fi
fi
# Terminate EC2 instance
if [[ -n "${INSTANCE_ID:-}" ]]; then
log "Terminating EC2 instance: $INSTANCE_ID"
if ! aws ec2 terminate-instances --instance-ids "$INSTANCE_ID" 2>>"$LOG_FILE"; then
log "WARNING: Failed to terminate instance $INSTANCE_ID"
((cleanup_errors++))
else
log "Waiting for instance to terminate..."
if ! aws ec2 wait instance-terminated --instance-ids "$INSTANCE_ID" 2>>"$LOG_FILE"; then
log "WARNING: Instance termination wait failed for $INSTANCE_ID"
((cleanup_errors++))
fi
fi
fi
# Delete security group with retry logic
if [[ -n "${SECURITY_GROUP_ID:-}" ]]; then
log "Deleting security group: $SECURITY_GROUP_ID"
local retry_count=0
local max_retries=3
while [[ $retry_count -lt $max_retries ]]; do
if aws ec2 delete-security-group --group-id "$SECURITY_GROUP_ID" 2>>"$LOG_FILE"; then
log "Successfully deleted security group"
break
else
((retry_count++))
if [[ $retry_count -lt $max_retries ]]; then
log "Retry $retry_count/$max_retries: Waiting 10 seconds before retrying security group deletion..."
sleep 10
else
log "ERROR: Failed to delete security group after $max_retries attempts"
((cleanup_errors++))
fi
fi
done
fi
# Delete key pair
if [[ -n "${KEY_PAIR_NAME:-}" ]]; then
log "Deleting key pair: $KEY_PAIR_NAME"
if ! aws ec2 delete-key-pair --key-name "$KEY_PAIR_NAME" 2>>"$LOG_FILE"; then
log "WARNING: Failed to delete key pair $KEY_PAIR_NAME"
((cleanup_errors++))
fi
rm -f "${KEY_PAIR_NAME}.pem" 2>>"$LOG_FILE" || log "WARNING: Failed to remove local key file"
fi
# Delete ECS cluster
if [[ -n "${CLUSTER_NAME:-}" ]]; then
log "Deleting ECS cluster: $CLUSTER_NAME"
if ! aws ecs delete-cluster --cluster "$CLUSTER_NAME" 2>>"$LOG_FILE"; then
log "WARNING: Failed to delete cluster $CLUSTER_NAME"
((cleanup_errors++))
fi
fi
if [[ $cleanup_errors -eq 0 ]]; then
log "Cleanup completed successfully"
else
log "Cleanup completed with $cleanup_errors warnings/errors. Check log file for details."
fi
}
# Function to check prerequisites
check_prerequisites() {
log "Checking prerequisites..."
# Check AWS CLI
if ! command -v aws &> /dev/null; then
log "ERROR: AWS CLI is not installed"
exit 1
fi
# Check AWS credentials
if ! aws sts get-caller-identity &> /dev/null; then
log "ERROR: AWS credentials not configured"
exit 1
fi
# Get caller identity
CALLER_IDENTITY=$(aws sts get-caller-identity --output text --query 'Account')
log "AWS Account: $CALLER_IDENTITY"
log "AWS Region: $AWS_REGION"
# Check for default VPC
DEFAULT_VPC=$(aws ec2 describe-vpcs --filters "Name=is-default,Values=true" --query 'Vpcs[0].VpcId' --output text)
if [[ "$DEFAULT_VPC" == "None" ]]; then
log "ERROR: No default VPC found. Please create a VPC first."
exit 1
fi
log "Using default VPC: $DEFAULT_VPC"
# Get default subnet
DEFAULT_SUBNET=$(aws ec2 describe-subnets --filters "Name=vpc-id,Values=$DEFAULT_VPC" "Name=default-for-az,Values=true" --query 'Subnets[0].SubnetId' --output text)
if [[ "$DEFAULT_SUBNET" == "None" ]]; then
log "ERROR: No default subnet found"
exit 1
fi
log "Using default subnet: $DEFAULT_SUBNET"
log "Prerequisites check completed successfully"
}
# Function to create ECS cluster
create_cluster() {
log "Creating ECS cluster: $CLUSTER_NAME"
CLUSTER_ARN=$(aws ecs create-cluster --cluster-name "$CLUSTER_NAME" --query 'cluster.clusterArn' --output text)
if [[ -z "$CLUSTER_ARN" ]]; then
log "ERROR: Failed to create cluster"
exit 1
fi
log "Created cluster: $CLUSTER_ARN"
CREATED_RESOURCES+=("ECS Cluster: $CLUSTER_NAME")
}
# Function to create key pair
create_key_pair() {
log "Creating EC2 key pair: $KEY_PAIR_NAME"
# FIXED: Set secure umask before key creation
umask 077
aws ec2 create-key-pair --key-name "$KEY_PAIR_NAME" --query 'KeyMaterial' --output text > "${KEY_PAIR_NAME}.pem"
chmod 400 "${KEY_PAIR_NAME}.pem"
umask 022 # Reset umask
log "Created key pair: $KEY_PAIR_NAME"
CREATED_RESOURCES+=("EC2 Key Pair: $KEY_PAIR_NAME")
}
# Function to create security group
create_security_group() {
log "Creating security group: $SECURITY_GROUP_NAME"
SECURITY_GROUP_ID=$(aws ec2 create-security-group \
--group-name "$SECURITY_GROUP_NAME" \
--description "ECS tutorial security group" \
--vpc-id "$DEFAULT_VPC" \
--query 'GroupId' --output text)
if [[ -z "$SECURITY_GROUP_ID" ]]; then
log "ERROR: Failed to create security group"
exit 1
fi
# Add HTTP access rule for nginx web server
aws ec2 authorize-security-group-ingress \
--group-id "$SECURITY_GROUP_ID" \
--protocol tcp \
--port 80 \
--cidr "0.0.0.0/0"
log "Created security group: $SECURITY_GROUP_ID"
log "Added HTTP access on port 80"
CREATED_RESOURCES+=("Security Group: $SECURITY_GROUP_ID")
}
# Function to get ECS optimized AMI
get_ecs_ami() {
log "Getting ECS-optimized AMI ID..."
ECS_AMI_ID=$(aws ssm get-parameters \
--names /aws/service/ecs/optimized-ami/amazon-linux-2/recommended \
--query 'Parameters[0].Value' --output text | jq -r '.image_id')
if [[ -z "$ECS_AMI_ID" ]]; then
log "ERROR: Failed to get ECS-optimized AMI ID"
exit 1
fi
log "ECS-optimized AMI ID: $ECS_AMI_ID"
}
# Function to create IAM role for ECS instance (if it doesn't exist)
ensure_ecs_instance_role() {
log "Checking for ecsInstanceRole..."
if ! aws iam get-role --role-name ecsInstanceRole &> /dev/null; then
log "Creating ecsInstanceRole..."
# Create trust policy
cat > ecs-instance-trust-policy.json << 'EOF'
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "ec2.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
EOF
# Create role
aws iam create-role \
--role-name ecsInstanceRole \
--assume-role-policy-document file://ecs-instance-trust-policy.json
# Attach managed policy
aws iam attach-role-policy \
--role-name ecsInstanceRole \
--policy-arn arn:aws:iam::aws:policy/service-role/AmazonEC2ContainerServiceforEC2Role
# Create instance profile
aws iam create-instance-profile --instance-profile-name ecsInstanceRole
# Add role to instance profile
aws iam add-role-to-instance-profile \
--instance-profile-name ecsInstanceRole \
--role-name ecsInstanceRole
# FIXED: Enhanced wait for role to be ready
log "Waiting for IAM role to be ready..."
aws iam wait role-exists --role-name ecsInstanceRole
sleep 30 # Additional buffer for eventual consistency
rm -f ecs-instance-trust-policy.json
log "Created ecsInstanceRole"
CREATED_RESOURCES+=("IAM Role: ecsInstanceRole")
else
log "ecsInstanceRole already exists"
fi
}
# Function to launch container instance
launch_container_instance() {
log "Launching ECS container instance..."
# Create user data script
cat > ecs-user-data.sh << EOF
#!/bin/bash
echo ECS_CLUSTER=$CLUSTER_NAME >> /etc/ecs/ecs.config
EOF
INSTANCE_ID=$(aws ec2 run-instances \
--image-id "$ECS_AMI_ID" \
--instance-type t3.micro \
--key-name "$KEY_PAIR_NAME" \
--security-group-ids "$SECURITY_GROUP_ID" \
--subnet-id "$DEFAULT_SUBNET" \
--iam-instance-profile Name=ecsInstanceRole \
--user-data file://ecs-user-data.sh \
--tag-specifications "ResourceType=instance,Tags=[{Key=Name,Value=ecs-tutorial-instance}]" \
--query 'Instances[0].InstanceId' --output text)
if [[ -z "$INSTANCE_ID" ]]; then
log "ERROR: Failed to launch EC2 instance"
exit 1
fi
log "Launched EC2 instance: $INSTANCE_ID"
CREATED_RESOURCES+=("EC2 Instance: $INSTANCE_ID")
# Wait for instance to be running
log "Waiting for instance to be running..."
aws ec2 wait instance-running --instance-ids "$INSTANCE_ID"
# Wait for ECS agent to register
log "Waiting for ECS agent to register with cluster..."
local max_attempts=30
local attempt=0
while [[ $attempt -lt $max_attempts ]]; do
CONTAINER_INSTANCES=$(aws ecs list-container-instances --cluster "$CLUSTER_NAME" --query 'containerInstanceArns' --output text)
if [[ -n "$CONTAINER_INSTANCES" && "$CONTAINER_INSTANCES" != "None" ]]; then
log "Container instance registered successfully"
break
fi
attempt=$((attempt + 1))
log "Waiting for container instance registration... (attempt $attempt/$max_attempts)"
sleep 10
done
if [[ $attempt -eq $max_attempts ]]; then
log "ERROR: Container instance failed to register within expected time"
exit 1
fi
rm -f ecs-user-data.sh
}
# Function to register task definition
register_task_definition() {
log "Creating task definition..."
# Create nginx task definition JSON matching the tutorial
cat > task-definition.json << EOF
{
"family": "$TASK_FAMILY",
"containerDefinitions": [
{
"name": "nginx",
"image": "public.ecr.aws/docker/library/nginx:latest",
"cpu": 256,
"memory": 512,
"essential": true,
"portMappings": [
{
"containerPort": 80,
"hostPort": 80,
"protocol": "tcp"
}
]
}
],
"requiresCompatibilities": ["EC2"],
"networkMode": "bridge"
}
EOF
# FIXED: Validate JSON before registration
if ! jq empty task-definition.json 2>/dev/null; then
log "ERROR: Invalid JSON in task definition"
exit 1
fi
TASK_DEFINITION_ARN=$(aws ecs register-task-definition \
--cli-input-json file://task-definition.json \
--query 'taskDefinition.taskDefinitionArn' --output text)
if [[ -z "$TASK_DEFINITION_ARN" ]]; then
log "ERROR: Failed to register task definition"
exit 1
fi
log "Registered task definition: $TASK_DEFINITION_ARN"
CREATED_RESOURCES+=("Task Definition: $TASK_DEFINITION_ARN")
rm -f task-definition.json
}
# Function to create service
create_service() {
log "Creating ECS service..."
SERVICE_ARN=$(aws ecs create-service \
--cluster "$CLUSTER_NAME" \
--service-name "$SERVICE_NAME" \
--task-definition "$TASK_FAMILY" \
--desired-count 1 \
--query 'service.serviceArn' --output text)
if [[ -z "$SERVICE_ARN" ]]; then
log "ERROR: Failed to create service"
exit 1
fi
log "Created service: $SERVICE_ARN"
CREATED_RESOURCES+=("ECS Service: $SERVICE_NAME")
# Wait for service to be stable
log "Waiting for service to be stable..."
aws ecs wait services-stable --cluster "$CLUSTER_NAME" --services "$SERVICE_NAME"
log "Service is now stable and running"
# Get the task ARN for monitoring
TASK_ARN=$(aws ecs list-tasks --cluster "$CLUSTER_NAME" --service-name "$SERVICE_NAME" --query 'taskArns[0]' --output text)
if [[ -n "$TASK_ARN" && "$TASK_ARN" != "None" ]]; then
log "Service task: $TASK_ARN"
CREATED_RESOURCES+=("ECS Task: $TASK_ARN")
fi
}
# Function to demonstrate monitoring and testing
demonstrate_monitoring() {
log "Demonstrating monitoring capabilities..."
# List services
log "Listing services in cluster:"
aws ecs list-services --cluster "$CLUSTER_NAME" --output table
# Describe service
log "Service details:"
aws ecs describe-services --cluster "$CLUSTER_NAME" --services "$SERVICE_NAME" --output table --query 'services[0].{ServiceName:serviceName,Status:status,RunningCount:runningCount,DesiredCount:desiredCount,TaskDefinition:taskDefinition}'
# List tasks
log "Listing tasks in service:"
aws ecs list-tasks --cluster "$CLUSTER_NAME" --service-name "$SERVICE_NAME" --output table
# Describe task
if [[ -n "$TASK_ARN" && "$TASK_ARN" != "None" ]]; then
log "Task details:"
aws ecs describe-tasks --cluster "$CLUSTER_NAME" --tasks "$TASK_ARN" --output table --query 'tasks[0].{TaskArn:taskArn,LastStatus:lastStatus,DesiredStatus:desiredStatus,CreatedAt:createdAt}'
fi
# List container instances
log "Container instances in cluster:"
aws ecs list-container-instances --cluster "$CLUSTER_NAME" --output table
# Describe container instance
CONTAINER_INSTANCE_ARN=$(aws ecs list-container-instances --cluster "$CLUSTER_NAME" --query 'containerInstanceArns[0]' --output text)
if [[ -n "$CONTAINER_INSTANCE_ARN" && "$CONTAINER_INSTANCE_ARN" != "None" ]]; then
log "Container instance details:"
aws ecs describe-container-instances --cluster "$CLUSTER_NAME" --container-instances "$CONTAINER_INSTANCE_ARN" --output table --query 'containerInstances[0].{Arn:containerInstanceArn,Status:status,RunningTasks:runningTasksCount,PendingTasks:pendingTasksCount}'
fi
# Test the nginx web server
log "Testing nginx web server..."
PUBLIC_IP=$(aws ec2 describe-instances --instance-ids "$INSTANCE_ID" --query 'Reservations[0].Instances[0].PublicIpAddress' --output text)
if [[ -n "$PUBLIC_IP" && "$PUBLIC_IP" != "None" ]]; then
log "Container instance public IP: $PUBLIC_IP"
log "Testing HTTP connection to nginx..."
# Wait a moment for nginx to be fully ready
sleep 10
if curl -s --connect-timeout 10 "http://$PUBLIC_IP" | grep -q "Welcome to nginx"; then
log "SUCCESS: Nginx web server is responding correctly"
echo ""
echo "==========================================="
echo "WEB SERVER TEST SUCCESSFUL"
echo "==========================================="
echo "You can access your nginx web server at: http://$PUBLIC_IP"
echo "The nginx welcome page should be visible in your browser."
else
log "WARNING: Nginx web server may not be fully ready yet. Try accessing http://$PUBLIC_IP in a few minutes."
fi
else
log "WARNING: Could not retrieve public IP address"
fi
}
# Main execution
main() {
log "Starting ECS EC2 Launch Type Tutorial (UPDATED VERSION)"
log "Log file: $LOG_FILE"
check_prerequisites
create_cluster
create_key_pair
create_security_group
get_ecs_ami
ensure_ecs_instance_role
launch_container_instance
register_task_definition
create_service
demonstrate_monitoring
log "Tutorial completed successfully!"
echo ""
echo "==========================================="
echo "TUTORIAL COMPLETED SUCCESSFULLY"
echo "==========================================="
echo "Resources created:"
for resource in "${CREATED_RESOURCES[@]}"; do
echo " - $resource"
done
echo ""
echo "The nginx service will continue running and maintain the desired task count."
echo "You can monitor the service status using:"
echo " aws ecs describe-services --cluster $CLUSTER_NAME --services $SERVICE_NAME"
echo ""
if [[ -n "${PUBLIC_IP:-}" ]]; then
echo "Access your web server at: http://$PUBLIC_IP"
echo ""
fi
echo "==========================================="
echo "CLEANUP CONFIRMATION"
echo "==========================================="
echo "Do you want to clean up all created resources? (y/n): "
read -r CLEANUP_CHOICE
if [[ "$CLEANUP_CHOICE" =~ ^[Yy]$ ]]; then
cleanup_resources
log "All resources have been cleaned up"
else
log "Resources left running. Remember to clean them up manually to avoid charges."
echo ""
echo "To clean up manually later, run these commands:"
echo " aws ecs update-service --cluster $CLUSTER_NAME --service $SERVICE_NAME --desired-count 0"
echo " aws ecs delete-service --cluster $CLUSTER_NAME --service $SERVICE_NAME"
echo " aws ecs delete-cluster --cluster $CLUSTER_NAME"
echo " aws ec2 terminate-instances --instance-ids $INSTANCE_ID"
echo " aws ec2 delete-security-group --group-id $SECURITY_GROUP_ID"
echo " aws ec2 delete-key-pair --key-name $KEY_PAIR_NAME"
fi
log "Script execution completed"
}
# Run main function
main "$@"
```
+ For API details, see the following topics in *AWS CLI Command Reference*.
+ [AddRoleToInstanceProfile](https://docs.aws.amazon.com/goto/aws-cli/iam-2010-05-08/AddRoleToInstanceProfile)
+ [AttachRolePolicy](https://docs.aws.amazon.com/goto/aws-cli/iam-2010-05-08/AttachRolePolicy)
+ [AuthorizeSecurityGroupIngress](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/AuthorizeSecurityGroupIngress)
+ [CreateCluster](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/CreateCluster)
+ [CreateInstanceProfile](https://docs.aws.amazon.com/goto/aws-cli/iam-2010-05-08/CreateInstanceProfile)
+ [CreateKeyPair](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/CreateKeyPair)
+ [CreateRole](https://docs.aws.amazon.com/goto/aws-cli/iam-2010-05-08/CreateRole)
+ [CreateSecurityGroup](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/CreateSecurityGroup)
+ [CreateService](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/CreateService)
+ [DeleteCluster](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/DeleteCluster)
+ [DeleteKeyPair](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/DeleteKeyPair)
+ [DeleteSecurityGroup](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/DeleteSecurityGroup)
+ [DeleteService](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/DeleteService)
+ [DeregisterTaskDefinition](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/DeregisterTaskDefinition)
+ [DescribeContainerInstances](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/DescribeContainerInstances)
+ [DescribeInstances](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/DescribeInstances)
+ [DescribeServices](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/DescribeServices)
+ [DescribeSubnets](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/DescribeSubnets)
+ [DescribeTasks](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/DescribeTasks)
+ [DescribeVpcs](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/DescribeVpcs)
+ [GetCallerIdentity](https://docs.aws.amazon.com/goto/aws-cli/sts-2011-06-15/GetCallerIdentity)
+ [GetParameters](https://docs.aws.amazon.com/goto/aws-cli/ssm-2014-11-06/GetParameters)
+ [GetRole](https://docs.aws.amazon.com/goto/aws-cli/iam-2010-05-08/GetRole)
+ [ListContainerInstances](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/ListContainerInstances)
+ [ListServices](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/ListServices)
+ [ListTasks](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/ListTasks)
+ [RegisterTaskDefinition](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/RegisterTaskDefinition)
+ [RunInstances](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/RunInstances)
+ [StopTask](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/StopTask)
+ [TerminateInstances](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/TerminateInstances)
+ [UpdateService](https://docs.aws.amazon.com/goto/aws-cli/ecs-2014-11-13/UpdateService)
+ [Wait](https://docs.aws.amazon.com/goto/aws-cli/iam-2010-05-08/Wait)
------
# Getting started with Amazon EC2
<a name="ssm_example_ec2_GettingStarted_013_section"></a>
The following code example shows how to:
+ Create a key pair
+ Create a security group
+ Stop and start your instance
+ Test Elastic IP persistence
+ Clean up resources
------
#### [ Bash ]
**AWS CLI with Bash script**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Sample developer tutorials](https://github.com/aws-samples/sample-developer-tutorials/tree/main/tuts/013-ec2-basics) repository.
```
#!/bin/bash
# EC2 Basics Tutorial Script - Revised
# This script demonstrates the basics of working with EC2 instances using AWS CLI
# Updated to use Amazon Linux 2023 and enhanced security settings
# Set up logging
LOG_FILE="ec2_tutorial_$(date +%Y%m%d_%H%M%S).log"
exec > >(tee -a "$LOG_FILE") 2>&1
# Function to log messages
log() {
echo "$(date '+%Y-%m-%d %H:%M:%S') - $1"
}
# Function to handle errors
handle_error() {
log "ERROR: $1"
log "Cleaning up resources..."
cleanup
exit 1
}
# Function to clean up resources
cleanup() {
log "Resources created:"
if [ -n "$ASSOCIATION_ID" ]; then
log "- Elastic IP Association: $ASSOCIATION_ID"
fi
if [ -n "$ALLOCATION_ID" ]; then
log "- Elastic IP Allocation: $ALLOCATION_ID (IP: $ELASTIC_IP)"
fi
if [ -n "$INSTANCE_ID" ]; then
log "- EC2 Instance: $INSTANCE_ID"
fi
if [ -n "$SECURITY_GROUP_ID" ]; then
log "- Security Group: $SECURITY_GROUP_ID"
fi
if [ -n "$KEY_NAME" ]; then
log "- Key Pair: $KEY_NAME (File: $KEY_FILE)"
fi
read -p "Do you want to delete these resources? (y/n): " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
log "Starting cleanup..."
# Track cleanup failures
CLEANUP_FAILURES=0
# Disassociate Elastic IP if it exists
if [ -n "$ASSOCIATION_ID" ]; then
log "Disassociating Elastic IP..."
if ! aws ec2 disassociate-address --association-id "$ASSOCIATION_ID"; then
log "Failed to disassociate Elastic IP"
((CLEANUP_FAILURES++))
fi
fi
# Release Elastic IP if it exists
if [ -n "$ALLOCATION_ID" ]; then
log "Releasing Elastic IP..."
if ! aws ec2 release-address --allocation-id "$ALLOCATION_ID"; then
log "Failed to release Elastic IP"
((CLEANUP_FAILURES++))
fi
fi
# Terminate instance if it exists
if [ -n "$INSTANCE_ID" ]; then
log "Terminating instance $INSTANCE_ID..."
if ! aws ec2 terminate-instances --instance-ids "$INSTANCE_ID" > /dev/null; then
log "Failed to terminate instance"
((CLEANUP_FAILURES++))
else
log "Waiting for instance to terminate..."
if ! aws ec2 wait instance-terminated --instance-ids "$INSTANCE_ID"; then
log "Failed while waiting for instance to terminate"
((CLEANUP_FAILURES++))
fi
fi
fi
# Delete security group if it exists
if [ -n "$SECURITY_GROUP_ID" ]; then
log "Deleting security group..."
if ! aws ec2 delete-security-group --group-id "$SECURITY_GROUP_ID"; then
log "Failed to delete security group"
((CLEANUP_FAILURES++))
fi
fi
# Delete key pair if it exists
if [ -n "$KEY_NAME" ]; then
log "Deleting key pair..."
if ! aws ec2 delete-key-pair --key-name "$KEY_NAME"; then
log "Failed to delete key pair"
((CLEANUP_FAILURES++))
fi
# Remove key file
if [ -f "$KEY_FILE" ]; then
log "Removing key file..."
if ! rm -f "$KEY_FILE"; then
log "Failed to remove key file"
((CLEANUP_FAILURES++))
fi
fi
fi
# Report cleanup status
if [ $CLEANUP_FAILURES -eq 0 ]; then
log "Cleanup completed successfully."
else
log "WARNING: Cleanup completed with $CLEANUP_FAILURES failures. Some resources may not have been deleted properly."
fi
else
log "Resources were not deleted."
fi
}
# Generate random identifier for resource names
RANDOM_ID=$(openssl rand -hex 4)
KEY_NAME="ec2-tutorial-key-$RANDOM_ID"
SG_NAME="ec2-tutorial-sg-$RANDOM_ID"
# Create a directory for the key file
KEY_DIR=$(mktemp -d)
KEY_FILE="$KEY_DIR/$KEY_NAME.pem"
log "Starting EC2 basics tutorial script"
log "Random identifier: $RANDOM_ID"
log "Key name: $KEY_NAME"
log "Security group name: $SG_NAME"
# Step 1: Create a key pair
log "Creating key pair..."
KEY_RESULT=$(aws ec2 create-key-pair --key-name "$KEY_NAME" --query 'KeyMaterial' --output text)
if [ $? -ne 0 ] || [ -z "$KEY_RESULT" ]; then
handle_error "Failed to create key pair"
fi
echo "$KEY_RESULT" > "$KEY_FILE"
chmod 400 "$KEY_FILE"
log "Created key pair and saved to $KEY_FILE"
# Step 2: Create a security group
log "Creating security group..."
SECURITY_GROUP_ID=$(aws ec2 create-security-group \
--group-name "$SG_NAME" \
--description "Security group for EC2 tutorial" \
--query "GroupId" \
--output text)
if [ $? -ne 0 ] || [ -z "$SECURITY_GROUP_ID" ]; then
handle_error "Failed to create security group"
fi
log "Created security group: $SECURITY_GROUP_ID"
# Get current public IP address for SSH access
MY_IP=$(curl -s http://checkip.amazonaws.com)
if [ $? -ne 0 ] || [ -z "$MY_IP" ]; then
handle_error "Failed to get current IP address"
fi
log "Adding SSH ingress rule for IP $MY_IP..."
aws ec2 authorize-security-group-ingress \
--group-id "$SECURITY_GROUP_ID" \
--protocol tcp \
--port 22 \
--cidr "$MY_IP/32" > /dev/null
if [ $? -ne 0 ]; then
handle_error "Failed to add security group ingress rule"
fi
log "Added SSH ingress rule for IP $MY_IP"
# Step 3: Find an Amazon Linux 2023 AMI (updated from AL2)
log "Finding latest Amazon Linux 2023 AMI..."
AMI_ID=$(aws ssm get-parameters-by-path \
--path "/aws/service/ami-amazon-linux-latest" \
--query "Parameters[?contains(Name, 'al2023-ami-kernel-default-x86_64')].Value" \
--output text | head -1)
if [ $? -ne 0 ] || [ -z "$AMI_ID" ]; then
handle_error "Failed to find Amazon Linux 2023 AMI"
fi
log "Selected AMI: $AMI_ID"
# Get the architecture of the AMI
log "Getting AMI architecture..."
AMI_ARCH=$(aws ec2 describe-images \
--image-ids "$AMI_ID" \
--query "Images[0].Architecture" \
--output text)
if [ $? -ne 0 ] || [ -z "$AMI_ARCH" ]; then
handle_error "Failed to get AMI architecture"
fi
log "AMI architecture: $AMI_ARCH"
# Find a compatible instance type
log "Finding compatible instance type..."
# Directly use t2.micro for simplicity
INSTANCE_TYPE="t2.micro"
log "Using instance type: $INSTANCE_TYPE"
# Step 4: Launch an EC2 instance with enhanced security
log "Launching EC2 instance with IMDSv2 and encryption enabled..."
INSTANCE_ID=$(aws ec2 run-instances \
--image-id "$AMI_ID" \
--instance-type "$INSTANCE_TYPE" \
--key-name "$KEY_NAME" \
--security-group-ids "$SECURITY_GROUP_ID" \
--metadata-options "HttpTokens=required,HttpEndpoint=enabled" \
--block-device-mappings "DeviceName=/dev/xvda,Ebs={Encrypted=true}" \
--count 1 \
--query 'Instances[0].InstanceId' \
--output text)
if [ $? -ne 0 ] || [ -z "$INSTANCE_ID" ]; then
handle_error "Failed to launch EC2 instance"
fi
log "Launched instance $INSTANCE_ID. Waiting for it to start..."
# Wait for the instance to be running
aws ec2 wait instance-running --instance-ids "$INSTANCE_ID"
if [ $? -ne 0 ]; then
handle_error "Failed while waiting for instance to start"
fi
# Get instance details
INSTANCE_DETAILS=$(aws ec2 describe-instances \
--instance-ids "$INSTANCE_ID" \
--query 'Reservations[0].Instances[0].{ID:InstanceId,Type:InstanceType,State:State.Name,PublicIP:PublicIpAddress}' \
--output json)
if [ $? -ne 0 ]; then
handle_error "Failed to get instance details"
fi
log "Instance details: $INSTANCE_DETAILS"
# Get the public IP address
PUBLIC_IP=$(echo "$INSTANCE_DETAILS" | grep -oP '"PublicIP": "\K[^"]+')
if [ -z "$PUBLIC_IP" ]; then
handle_error "Failed to get instance public IP"
fi
log "Instance public IP: $PUBLIC_IP"
log "To connect to your instance, run: ssh -i $KEY_FILE ec2-user@$PUBLIC_IP"
# Pause to allow user to connect if desired
read -p "Press Enter to continue to the next step (stopping and starting the instance)..."
# Step 6: Stop and Start the Instance
log "Stopping instance $INSTANCE_ID..."
aws ec2 stop-instances --instance-ids "$INSTANCE_ID" > /dev/null
if [ $? -ne 0 ]; then
handle_error "Failed to stop instance"
fi
log "Waiting for instance to stop..."
aws ec2 wait instance-stopped --instance-ids "$INSTANCE_ID"
if [ $? -ne 0 ]; then
handle_error "Failed while waiting for instance to stop"
fi
log "Instance stopped. Starting instance again..."
aws ec2 start-instances --instance-ids "$INSTANCE_ID" > /dev/null
if [ $? -ne 0 ]; then
handle_error "Failed to start instance"
fi
log "Waiting for instance to start..."
aws ec2 wait instance-running --instance-ids "$INSTANCE_ID"
if [ $? -ne 0 ]; then
handle_error "Failed while waiting for instance to start"
fi
# Get the new public IP address
NEW_PUBLIC_IP=$(aws ec2 describe-instances \
--instance-ids "$INSTANCE_ID" \
--query 'Reservations[0].Instances[0].PublicIpAddress' \
--output text)
if [ $? -ne 0 ] || [ -z "$NEW_PUBLIC_IP" ]; then
handle_error "Failed to get new public IP"
fi
log "Instance restarted with new public IP: $NEW_PUBLIC_IP"
log "To connect to your instance, run: ssh -i $KEY_FILE ec2-user@$NEW_PUBLIC_IP"
# Step 7: Allocate and Associate an Elastic IP Address
log "Allocating Elastic IP address..."
ALLOCATION_RESULT=$(aws ec2 allocate-address \
--domain vpc \
--query '[PublicIp,AllocationId]' \
--output text)
if [ $? -ne 0 ] || [ -z "$ALLOCATION_RESULT" ]; then
handle_error "Failed to allocate Elastic IP"
fi
ELASTIC_IP=$(echo "$ALLOCATION_RESULT" | awk '{print $1}')
ALLOCATION_ID=$(echo "$ALLOCATION_RESULT" | awk '{print $2}')
log "Allocated Elastic IP: $ELASTIC_IP with ID: $ALLOCATION_ID"
log "Associating Elastic IP with instance..."
ASSOCIATION_ID=$(aws ec2 associate-address \
--instance-id "$INSTANCE_ID" \
--allocation-id "$ALLOCATION_ID" \
--query "AssociationId" \
--output text)
if [ $? -ne 0 ] || [ -z "$ASSOCIATION_ID" ]; then
handle_error "Failed to associate Elastic IP"
fi
log "Associated Elastic IP with instance. Association ID: $ASSOCIATION_ID"
log "To connect to your instance using the Elastic IP, run: ssh -i $KEY_FILE ec2-user@$ELASTIC_IP"
# Pause to allow user to connect if desired
read -p "Press Enter to continue to the next step (testing Elastic IP persistence)..."
# Step 8: Test the Elastic IP by Stopping and Starting the Instance
log "Stopping instance $INSTANCE_ID to test Elastic IP persistence..."
aws ec2 stop-instances --instance-ids "$INSTANCE_ID" > /dev/null
if [ $? -ne 0 ]; then
handle_error "Failed to stop instance"
fi
log "Waiting for instance to stop..."
aws ec2 wait instance-stopped --instance-ids "$INSTANCE_ID"
if [ $? -ne 0 ]; then
handle_error "Failed while waiting for instance to stop"
fi
log "Instance stopped. Starting instance again..."
aws ec2 start-instances --instance-ids "$INSTANCE_ID" > /dev/null
if [ $? -ne 0 ]; then
handle_error "Failed to start instance"
fi
log "Waiting for instance to start..."
aws ec2 wait instance-running --instance-ids "$INSTANCE_ID"
if [ $? -ne 0 ]; then
handle_error "Failed while waiting for instance to start"
fi
# Verify the Elastic IP is still associated
CURRENT_IP=$(aws ec2 describe-instances \
--instance-ids "$INSTANCE_ID" \
--query 'Reservations[0].Instances[0].PublicIpAddress' \
--output text)
if [ $? -ne 0 ] || [ -z "$CURRENT_IP" ]; then
handle_error "Failed to get current public IP"
fi
log "Current public IP address: $CURRENT_IP"
log "Elastic IP address: $ELASTIC_IP"
if [ "$CURRENT_IP" = "$ELASTIC_IP" ]; then
log "Success! The Elastic IP is still associated with your instance."
else
log "Something went wrong. The Elastic IP is not associated with your instance."
fi
log "To connect to your instance, run: ssh -i $KEY_FILE ec2-user@$ELASTIC_IP"
# Step 9: Clean up resources
log "Tutorial completed successfully!"
cleanup
exit 0
```
+ For API details, see the following topics in *AWS CLI Command Reference*.
+ [AllocateAddress](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/AllocateAddress)
+ [AssociateAddress](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/AssociateAddress)
+ [AuthorizeSecurityGroupIngress](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/AuthorizeSecurityGroupIngress)
+ [CreateKeyPair](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/CreateKeyPair)
+ [CreateSecurityGroup](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/CreateSecurityGroup)
+ [DeleteKeyPair](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/DeleteKeyPair)
+ [DeleteSecurityGroup](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/DeleteSecurityGroup)
+ [DescribeImages](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/DescribeImages)
+ [DescribeInstances](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/DescribeInstances)
+ [DisassociateAddress](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/DisassociateAddress)
+ [GetParametersByPath](https://docs.aws.amazon.com/goto/aws-cli/ssm-2014-11-06/GetParametersByPath)
+ [ReleaseAddress](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/ReleaseAddress)
+ [RunInstances](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/RunInstances)
+ [StartInstances](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/StartInstances)
+ [StopInstances](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/StopInstances)
+ [TerminateInstances](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/TerminateInstances)
+ [Wait](https://docs.aws.amazon.com/goto/aws-cli/ec2-2016-11-15/Wait)
------
# Setting up Systems Manager
<a name="ssm_example_iam_GettingStarted_046_section"></a>
The following code example shows how to:
+ Create IAM permissions for Systems Manager
+ Create an IAM role for Systems Manager
+ Configure Systems Manager
+ Verify the setup
+ Clean up resources
------
#### [ Bash ]
**AWS CLI with Bash script**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Sample developer tutorials](https://github.com/aws-samples/sample-developer-tutorials/tree/main/tuts/046-aws-systems-manager-gs) repository.
```
#!/bin/bash
# AWS Systems Manager Setup Script
# This script sets up AWS Systems Manager for a single account and region
#
# Version 17 fixes:
# 1. Added cloudformation.amazonaws.com to the IAM role trust policy
# 2. Systems Manager Quick Setup uses CloudFormation for deployments, so the role must trust CloudFormation service
# Initialize log file
LOG_FILE="ssm_setup_$(date +%Y%m%d_%H%M%S).log"
echo "Starting AWS Systems Manager setup at $(date)" > "$LOG_FILE"
# Function to log commands and their outputs with immediate terminal display
log_cmd() {
echo "$(date): Running command: $1" | tee -a "$LOG_FILE"
local output
output=$(eval "$1" 2>&1)
local status=$?
echo "$output" | tee -a "$LOG_FILE"
return $status
}
# Function to check for errors in command output
check_error() {
local cmd_output="$1"
local cmd_status="$2"
local error_msg="$3"
if [[ $cmd_status -ne 0 || "$cmd_output" =~ [Ee][Rr][Rr][Oo][Rr] ]]; then
echo "ERROR: $error_msg" | tee -a "$LOG_FILE"
echo "Command output: $cmd_output" | tee -a "$LOG_FILE"
cleanup_on_error
exit 1
fi
}
# Array to track created resources for cleanup
declare -a CREATED_RESOURCES
# Function to add a resource to the tracking array
track_resource() {
local resource_type="$1"
local resource_id="$2"
CREATED_RESOURCES+=("$resource_type:$resource_id")
echo "Tracked resource: $resource_type:$resource_id" | tee -a "$LOG_FILE"
}
# Function to clean up resources on error
cleanup_on_error() {
echo "" | tee -a "$LOG_FILE"
echo "==========================================" | tee -a "$LOG_FILE"
echo "ERROR OCCURRED - CLEANING UP RESOURCES" | tee -a "$LOG_FILE"
echo "==========================================" | tee -a "$LOG_FILE"
echo "The following resources were created:" | tee -a "$LOG_FILE"
# Display resources in reverse order
for ((i=${#CREATED_RESOURCES[@]}-1; i>=0; i--)); do
echo "${CREATED_RESOURCES[$i]}" | tee -a "$LOG_FILE"
done
echo "" | tee -a "$LOG_FILE"
echo "Attempting to clean up resources..." | tee -a "$LOG_FILE"
# Clean up resources in reverse order
cleanup_resources
}
# Function to clean up all created resources
cleanup_resources() {
# Process resources in reverse order (last created, first deleted)
for ((i=${#CREATED_RESOURCES[@]}-1; i>=0; i--)); do
IFS=':' read -r resource_type resource_id <<< "${CREATED_RESOURCES[$i]}"
echo "Deleting $resource_type: $resource_id" | tee -a "$LOG_FILE"
case "$resource_type" in
"IAM_POLICY")
# Delete the policy (detachment should have been handled when the role was deleted)
log_cmd "aws iam delete-policy --policy-arn $resource_id" || true
;;
"IAM_ROLE")
# Detach all policies from the role first
if [[ -n "$POLICY_ARN" ]]; then
log_cmd "aws iam detach-role-policy --role-name $resource_id --policy-arn $POLICY_ARN" || true
fi
# Delete the role
log_cmd "aws iam delete-role --role-name $resource_id" || true
;;
"SSM_CONFIG_MANAGER")
log_cmd "aws ssm-quicksetup delete-configuration-manager --manager-arn $resource_id" || true
;;
*)
echo "Unknown resource type: $resource_type, cannot delete automatically" | tee -a "$LOG_FILE"
;;
esac
done
echo "Cleanup completed" | tee -a "$LOG_FILE"
# Clean up temporary files
rm -f ssm-onboarding-policy.json trust-policy.json ssm-config.json 2>/dev/null || true
}
# Main script execution
echo "AWS Systems Manager Setup Script"
echo "================================"
echo "This script will set up AWS Systems Manager for a single account and region."
echo "It will create IAM policies and roles, then enable Systems Manager features."
echo ""
# Get the current AWS region
CURRENT_REGION=$(aws configure get region)
if [[ -z "$CURRENT_REGION" ]]; then
echo "No AWS region configured. Please specify a region:"
read -r CURRENT_REGION
if [[ -z "$CURRENT_REGION" ]]; then
echo "ERROR: A region must be specified" | tee -a "$LOG_FILE"
exit 1
fi
fi
echo "Using AWS region: $CURRENT_REGION" | tee -a "$LOG_FILE"
# Step 1: Create IAM policy for Systems Manager onboarding
echo "Step 1: Creating IAM policy for Systems Manager onboarding..."
# Create policy document
cat > ssm-onboarding-policy.json << 'EOF'
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "QuickSetupActions",
"Effect": "Allow",
"Action": [
"ssm-quicksetup:*"
],
"Resource": "*"
},
{
"Sid": "SsmReadOnly",
"Effect": "Allow",
"Action": [
"ssm:DescribeAutomationExecutions",
"ssm:GetAutomationExecution",
"ssm:ListAssociations",
"ssm:DescribeAssociation",
"ssm:ListDocuments",
"ssm:ListResourceDataSync",
"ssm:DescribePatchBaselines",
"ssm:GetPatchBaseline",
"ssm:DescribeMaintenanceWindows",
"ssm:DescribeMaintenanceWindowTasks"
],
"Resource": "*"
},
{
"Sid": "SsmDocument",
"Effect": "Allow",
"Action": [
"ssm:GetDocument",
"ssm:DescribeDocument"
],
"Resource": [
"arn:aws:ssm:*:*:document/AWSQuickSetupType-*",
"arn:aws:ssm:*:*:document/AWS-EnableExplorer"
]
},
{
"Sid": "SsmEnableExplorer",
"Effect": "Allow",
"Action": "ssm:StartAutomationExecution",
"Resource": "arn:aws:ssm:*:*:automation-definition/AWS-EnableExplorer:*"
},
{
"Sid": "SsmExplorerRds",
"Effect": "Allow",
"Action": [
"ssm:GetOpsSummary",
"ssm:CreateResourceDataSync",
"ssm:UpdateResourceDataSync"
],
"Resource": "arn:aws:ssm:*:*:resource-data-sync/AWS-QuickSetup-*"
},
{
"Sid": "OrgsReadOnly",
"Effect": "Allow",
"Action": [
"organizations:DescribeAccount",
"organizations:DescribeOrganization",
"organizations:ListDelegatedAdministrators",
"organizations:ListRoots",
"organizations:ListParents",
"organizations:ListOrganizationalUnitsForParent",
"organizations:DescribeOrganizationalUnit",
"organizations:ListAWSServiceAccessForOrganization"
],
"Resource": "*"
},
{
"Sid": "OrgsAdministration",
"Effect": "Allow",
"Action": [
"organizations:EnableAWSServiceAccess",
"organizations:RegisterDelegatedAdministrator",
"organizations:DeregisterDelegatedAdministrator"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"organizations:ServicePrincipal": [
"ssm.amazonaws.com",
"ssm-quicksetup.amazonaws.com",
"member.org.stacksets.cloudformation.amazonaws.com",
"resource-explorer-2.amazonaws.com"
]
}
}
},
{
"Sid": "CfnReadOnly",
"Effect": "Allow",
"Action": [
"cloudformation:ListStacks",
"cloudformation:DescribeStacks",
"cloudformation:ListStackSets",
"cloudformation:DescribeOrganizationsAccess"
],
"Resource": "*"
},
{
"Sid": "OrgCfnAccess",
"Effect": "Allow",
"Action": [
"cloudformation:ActivateOrganizationsAccess"
],
"Resource": "*"
},
{
"Sid": "CfnStackActions",
"Effect": "Allow",
"Action": [
"cloudformation:CreateStack",
"cloudformation:DeleteStack",
"cloudformation:DescribeStackResources",
"cloudformation:DescribeStackEvents",
"cloudformation:GetTemplate",
"cloudformation:RollbackStack",
"cloudformation:TagResource",
"cloudformation:UntagResource",
"cloudformation:UpdateStack"
],
"Resource": [
"arn:aws:cloudformation:*:*:stack/StackSet-AWS-QuickSetup-*",
"arn:aws:cloudformation:*:*:stack/AWS-QuickSetup-*",
"arn:aws:cloudformation:*:*:type/resource/*"
]
},
{
"Sid": "CfnStackSetActions",
"Effect": "Allow",
"Action": [
"cloudformation:CreateStackInstances",
"cloudformation:CreateStackSet",
"cloudformation:DeleteStackInstances",
"cloudformation:DeleteStackSet",
"cloudformation:DescribeStackInstance",
"cloudformation:DetectStackSetDrift",
"cloudformation:ListStackInstanceResourceDrifts",
"cloudformation:DescribeStackSet",
"cloudformation:DescribeStackSetOperation",
"cloudformation:ListStackInstances",
"cloudformation:ListStackSetOperations",
"cloudformation:ListStackSetOperationResults",
"cloudformation:TagResource",
"cloudformation:UntagResource",
"cloudformation:UpdateStackSet"
],
"Resource": [
"arn:aws:cloudformation:*:*:stackset/AWS-QuickSetup-*",
"arn:aws:cloudformation:*:*:type/resource/*",
"arn:aws:cloudformation:*:*:stackset-target/AWS-QuickSetup-*:*"
]
},
{
"Sid": "ValidationReadonlyActions",
"Effect": "Allow",
"Action": [
"iam:ListRoles",
"iam:GetRole"
],
"Resource": "*"
},
{
"Sid": "IamRolesMgmt",
"Effect": "Allow",
"Action": [
"iam:CreateRole",
"iam:DeleteRole",
"iam:GetRole",
"iam:AttachRolePolicy",
"iam:DetachRolePolicy",
"iam:GetRolePolicy",
"iam:ListRolePolicies"
],
"Resource": [
"arn:aws:iam::*:role/AWS-QuickSetup-*",
"arn:aws:iam::*:role/service-role/AWS-QuickSetup-*"
]
},
{
"Sid": "IamPassRole",
"Effect": "Allow",
"Action": [
"iam:PassRole"
],
"Resource": [
"arn:aws:iam::*:role/AWS-QuickSetup-*",
"arn:aws:iam::*:role/service-role/AWS-QuickSetup-*"
],
"Condition": {
"StringEquals": {
"iam:PassedToService": [
"ssm.amazonaws.com",
"ssm-quicksetup.amazonaws.com",
"cloudformation.amazonaws.com"
]
}
}
},
{
"Sid": "IamRolesPoliciesMgmt",
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy",
"iam:DetachRolePolicy"
],
"Resource": [
"arn:aws:iam::*:role/AWS-QuickSetup-*",
"arn:aws:iam::*:role/service-role/AWS-QuickSetup-*"
],
"Condition": {
"ArnEquals": {
"iam:PolicyARN": [
"arn:aws:iam::aws:policy/AWSSystemsManagerEnableExplorerExecutionPolicy",
"arn:aws:iam::aws:policy/AWSQuickSetupSSMDeploymentRolePolicy"
]
}
}
},
{
"Sid": "CfnStackSetsSLR",
"Effect": "Allow",
"Action": [
"iam:CreateServiceLinkedRole"
],
"Resource": [
"arn:aws:iam::*:role/aws-service-role/stacksets.cloudformation.amazonaws.com/AWSServiceRoleForCloudFormationStackSetsOrgAdmin",
"arn:aws:iam::*:role/aws-service-role/ssm.amazonaws.com/AWSServiceRoleForAmazonSSM",
"arn:aws:iam::*:role/aws-service-role/accountdiscovery.ssm.amazonaws.com/AWSServiceRoleForAmazonSSM_AccountDiscovery",
"arn:aws:iam::*:role/aws-service-role/ssm-quicksetup.amazonaws.com/AWSServiceRoleForSSMQuickSetup",
"arn:aws:iam::*:role/aws-service-role/resource-explorer-2.amazonaws.com/AWSServiceRoleForResourceExplorer"
]
}
]
}
EOF
# Create the IAM policy
POLICY_OUTPUT=$(log_cmd "aws iam create-policy --policy-name SSMOnboardingPolicy --policy-document file://ssm-onboarding-policy.json --output json")
POLICY_STATUS=$?
check_error "$POLICY_OUTPUT" $POLICY_STATUS "Failed to create IAM policy"
# Extract the policy ARN
POLICY_ARN=$(echo "$POLICY_OUTPUT" | grep -o 'arn:aws:iam::[0-9]*:policy/SSMOnboardingPolicy')
if [[ -z "$POLICY_ARN" ]]; then
echo "ERROR: Failed to extract policy ARN" | tee -a "$LOG_FILE"
exit 1
fi
# Track the created policy
track_resource "IAM_POLICY" "$POLICY_ARN"
echo "Created policy: $POLICY_ARN" | tee -a "$LOG_FILE"
# Step 2: Create and configure IAM role for Systems Manager
echo ""
echo "Step 2: Creating IAM role for Systems Manager..."
# Get current user name
USER_OUTPUT=$(log_cmd "aws sts get-caller-identity --output json")
USER_STATUS=$?
check_error "$USER_OUTPUT" $USER_STATUS "Failed to get caller identity"
# Extract account ID
ACCOUNT_ID=$(echo "$USER_OUTPUT" | grep -o '"Account": "[0-9]*"' | cut -d'"' -f4)
if [[ -z "$ACCOUNT_ID" ]]; then
echo "ERROR: Failed to extract account ID" | tee -a "$LOG_FILE"
exit 1
fi
# Generate a unique role name
ROLE_NAME="SSMTutorialRole-$(openssl rand -hex 4)"
# Create trust policy for the role - FIXED: Added cloudformation.amazonaws.com
cat > trust-policy.json << 'EOF'
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"ssm.amazonaws.com",
"ssm-quicksetup.amazonaws.com",
"cloudformation.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
},
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::ACCOUNT_ID:root"
},
"Action": "sts:AssumeRole"
}
]
}
EOF
# Replace ACCOUNT_ID placeholder in trust policy
sed -i "s/ACCOUNT_ID/$ACCOUNT_ID/g" trust-policy.json
# Create the IAM role
ROLE_OUTPUT=$(log_cmd "aws iam create-role --role-name $ROLE_NAME --assume-role-policy-document file://trust-policy.json --description 'Role for Systems Manager tutorial' --output json")
ROLE_STATUS=$?
check_error "$ROLE_OUTPUT" $ROLE_STATUS "Failed to create IAM role"
# Extract the role ARN
ROLE_ARN=$(echo "$ROLE_OUTPUT" | grep -o 'arn:aws:iam::[0-9]*:role/[^"]*')
if [[ -z "$ROLE_ARN" ]]; then
echo "ERROR: Failed to extract role ARN" | tee -a "$LOG_FILE"
cleanup_on_error
exit 1
fi
# Track the created role
track_resource "IAM_ROLE" "$ROLE_NAME"
echo "Created IAM role: $ROLE_NAME" | tee -a "$LOG_FILE"
echo "Role ARN: $ROLE_ARN" | tee -a "$LOG_FILE"
# Set identity variables for cleanup
IDENTITY_TYPE="role"
IDENTITY_NAME="$ROLE_NAME"
# Attach the policy to the role
ATTACH_OUTPUT=$(log_cmd "aws iam attach-role-policy --role-name $ROLE_NAME --policy-arn $POLICY_ARN")
ATTACH_STATUS=$?
check_error "$ATTACH_OUTPUT" $ATTACH_STATUS "Failed to attach policy to role $ROLE_NAME"
echo "Policy attached to role: $ROLE_NAME" | tee -a "$LOG_FILE"
# Step 3: Create Systems Manager configuration using Host Management
echo ""
echo "Step 3: Creating Systems Manager configuration..."
# Generate a random identifier for the configuration name
CONFIG_NAME="SSMSetup-$(openssl rand -hex 4)"
# Create configuration file for Systems Manager setup using Host Management
# Added both required parameters for single account deployment based on CloudFormation documentation
cat > ssm-config.json << EOF
[
{
"Type": "AWSQuickSetupType-SSMHostMgmt",
"LocalDeploymentAdministrationRoleArn": "$ROLE_ARN",
"LocalDeploymentExecutionRoleName": "$ROLE_NAME",
"Parameters": {
"TargetAccounts": "$ACCOUNT_ID",
"TargetRegions": "$CURRENT_REGION"
}
}
]
EOF
echo "Configuration file created:" | tee -a "$LOG_FILE"
cat ssm-config.json | tee -a "$LOG_FILE"
# Create the configuration manager
CONFIG_OUTPUT=$(log_cmd "aws ssm-quicksetup create-configuration-manager --name \"$CONFIG_NAME\" --configuration-definitions file://ssm-config.json --region $CURRENT_REGION")
CONFIG_STATUS=$?
check_error "$CONFIG_OUTPUT" $CONFIG_STATUS "Failed to create Systems Manager configuration"
# Extract the manager ARN
MANAGER_ARN=$(echo "$CONFIG_OUTPUT" | grep -o 'arn:aws:ssm-quicksetup:[^"]*')
if [[ -z "$MANAGER_ARN" ]]; then
echo "ERROR: Failed to extract manager ARN" | tee -a "$LOG_FILE"
exit 1
fi
# Track the created configuration manager
track_resource "SSM_CONFIG_MANAGER" "$MANAGER_ARN"
echo "Created Systems Manager configuration: $MANAGER_ARN" | tee -a "$LOG_FILE"
# Step 4: Verify the setup
echo ""
echo "Step 4: Verifying the setup..."
# Wait for the configuration to be fully deployed
echo "Waiting for the configuration to be deployed (this may take a few minutes)..."
sleep 30
# Check the configuration manager status
VERIFY_OUTPUT=$(log_cmd "aws ssm-quicksetup get-configuration-manager --manager-arn $MANAGER_ARN --region $CURRENT_REGION")
VERIFY_STATUS=$?
check_error "$VERIFY_OUTPUT" $VERIFY_STATUS "Failed to verify configuration manager"
echo "Systems Manager setup completed successfully!" | tee -a "$LOG_FILE"
# List the created resources
echo ""
echo "==========================================="
echo "CREATED RESOURCES"
echo "==========================================="
for resource in "${CREATED_RESOURCES[@]}"; do
echo "$resource"
done
# Prompt for cleanup
echo ""
echo "==========================================="
echo "CLEANUP CONFIRMATION"
echo "==========================================="
echo "Do you want to clean up all created resources? (y/n): "
read -r CLEANUP_CHOICE
if [[ "$CLEANUP_CHOICE" =~ ^[Yy]$ ]]; then
echo "Cleaning up resources..." | tee -a "$LOG_FILE"
cleanup_resources
echo "Cleanup completed." | tee -a "$LOG_FILE"
else
echo "Resources will not be cleaned up. You can manually clean them up later." | tee -a "$LOG_FILE"
fi
echo ""
echo "Script execution completed. See $LOG_FILE for details."
# Clean up temporary files
rm -f ssm-onboarding-policy.json trust-policy.json ssm-config.json 2>/dev/null || true
```
+ For API details, see the following topics in *AWS CLI Command Reference*.
+ [AttachRolePolicy](https://docs.aws.amazon.com/goto/aws-cli/iam-2010-05-08/AttachRolePolicy)
+ [CreateConfigurationManager](https://docs.aws.amazon.com/goto/aws-cli/ssm-2014-11-06/CreateConfigurationManager)
+ [CreatePolicy](https://docs.aws.amazon.com/goto/aws-cli/iam-2010-05-08/CreatePolicy)
+ [CreateRole](https://docs.aws.amazon.com/goto/aws-cli/iam-2010-05-08/CreateRole)
+ [DeleteConfigurationManager](https://docs.aws.amazon.com/goto/aws-cli/ssm-2014-11-06/DeleteConfigurationManager)
+ [DeletePolicy](https://docs.aws.amazon.com/goto/aws-cli/iam-2010-05-08/DeletePolicy)
+ [DeleteRole](https://docs.aws.amazon.com/goto/aws-cli/iam-2010-05-08/DeleteRole)
+ [DetachRolePolicy](https://docs.aws.amazon.com/goto/aws-cli/iam-2010-05-08/DetachRolePolicy)
+ [GetCallerIdentity](https://docs.aws.amazon.com/goto/aws-cli/sts-2011-06-15/GetCallerIdentity)
+ [GetConfigurationManager](https://docs.aws.amazon.com/goto/aws-cli/ssm-2014-11-06/GetConfigurationManager)
------