There are more AWS SDK examples available in the AWS Doc SDK Examples
Learn the basics of Systems Manager with an AWS SDK
The following code examples show how to work with Systems Manager maintenance windows, documents, and OpsItems.
- Java
-
- SDK for Java 2.x
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository
. import software.amazon.awssdk.services.ssm.model.DocumentAlreadyExistsException; import software.amazon.awssdk.services.ssm.model.SsmException; import java.util.Scanner; public class SSMScenario { public static final String DASHES = new String(new char[80]).replace("\0", "-"); public static void main(String[] args) { String usage = """ Usage: <instanceId> <title> <source> <category> <severity> Where: instanceId - The Amazon EC2 Linux/UNIX instance Id that AWS Systems Manager uses (ie, i-0149338494ed95f06). 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). """; if (args.length != 1) { System.out.println(usage); System.exit(1); } Scanner scanner = new Scanner(System.in); SSMActions actions = new SSMActions(); String documentName; String windowName; String instanceId = args[0]; String title = args[1]; String source = args[2]; String category = args[3]; String severity = args[4]; 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); 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_EAST_1) .httpClient(httpClient) .overrideConfiguration(overrideConfig) .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .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.
-
- JavaScript
-
- SDK for JavaScript (v3)
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository
. 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.
-
- Python
-
- SDK for Python (Boto3)
-
Note
There's more on GitHub. Find the complete example and learn how to set up and run in the AWS Code Examples Repository
. 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.
-