Systems Manager examples using SDK for JavaScript (v3) (original) (raw)
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: <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>e</mi><mi mathvariant="normal">.</mi><mi>o</mi><mi>p</mi><mi>s</mi><mi>I</mi><mi>t</mi><mi>e</mi><mi>m</mi><mi>I</mi><mi>d</mi></mrow><mi mathvariant="normal">.</mi><mi>P</mi><mi>l</mi><mi>e</mi><mi>a</mi><mi>s</mi><mi>e</mi><mi>d</mi><mi>e</mi><mi>l</mi><mi>e</mi><mi>t</mi><mi>e</mi><mi>i</mi><mi>t</mi><mi>m</mi><mi>a</mi><mi>n</mi><mi>u</mi><mi>a</mi><mi>l</mi><mi>l</mi><mi>y</mi><mi mathvariant="normal">.</mi><mi>E</mi><mi>r</mi><mi>r</mi><mi>o</mi><mi>r</mi><mo>:</mo></mrow><annotation encoding="application/x-tex">{state.opsItemId}. Please delete it manually. Error: </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord"><span class="mord mathnormal">s</span><span class="mord mathnormal">t</span><span class="mord mathnormal">a</span><span class="mord mathnormal">t</span><span class="mord mathnormal">e</span><span class="mord">.</span><span class="mord mathnormal">o</span><span class="mord mathnormal">p</span><span class="mord mathnormal">s</span><span class="mord mathnormal" style="margin-right:0.07847em;">I</span><span class="mord mathnormal">t</span><span class="mord mathnormal">e</span><span class="mord mathnormal">m</span><span class="mord mathnormal" style="margin-right:0.07847em;">I</span><span class="mord mathnormal">d</span></span><span class="mord">.</span><span class="mord mathnormal" style="margin-right:0.01968em;">Pl</span><span class="mord mathnormal">e</span><span class="mord mathnormal">a</span><span class="mord mathnormal">se</span><span class="mord mathnormal">d</span><span class="mord mathnormal">e</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">e</span><span class="mord mathnormal">t</span><span class="mord mathnormal">e</span><span class="mord mathnormal">i</span><span class="mord mathnormal">t</span><span class="mord mathnormal">man</span><span class="mord mathnormal">u</span><span class="mord mathnormal">a</span><span class="mord mathnormal" style="margin-right:0.01968em;">ll</span><span class="mord mathnormal" style="margin-right:0.03588em;">y</span><span class="mord">.</span><span class="mord mathnormal" style="margin-right:0.05764em;">E</span><span class="mord mathnormal" style="margin-right:0.02778em;">rror</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span></span></span></span>{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: <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>e</mi><mi mathvariant="normal">.</mi><mi>o</mi><mi>p</mi><mi>s</mi><mi>I</mi><mi>t</mi><mi>e</mi><mi>m</mi><mi>I</mi><mi>d</mi></mrow><mi mathvariant="normal">.</mi><mi>P</mi><mi>l</mi><mi>e</mi><mi>a</mi><mi>s</mi><mi>e</mi><mi>d</mi><mi>e</mi><mi>l</mi><mi>e</mi><mi>t</mi><mi>e</mi><mi>i</mi><mi>t</mi><mi>m</mi><mi>a</mi><mi>n</mi><mi>u</mi><mi>a</mi><mi>l</mi><mi>l</mi><mi>y</mi><mi mathvariant="normal">.</mi><mi>E</mi><mi>r</mi><mi>r</mi><mi>o</mi><mi>r</mi><mo>:</mo></mrow><annotation encoding="application/x-tex">{state.opsItemId}. Please delete it manually. Error: </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord"><span class="mord mathnormal">s</span><span class="mord mathnormal">t</span><span class="mord mathnormal">a</span><span class="mord mathnormal">t</span><span class="mord mathnormal">e</span><span class="mord">.</span><span class="mord mathnormal">o</span><span class="mord mathnormal">p</span><span class="mord mathnormal">s</span><span class="mord mathnormal" style="margin-right:0.07847em;">I</span><span class="mord mathnormal">t</span><span class="mord mathnormal">e</span><span class="mord mathnormal">m</span><span class="mord mathnormal" style="margin-right:0.07847em;">I</span><span class="mord mathnormal">d</span></span><span class="mord">.</span><span class="mord mathnormal" style="margin-right:0.01968em;">Pl</span><span class="mord mathnormal">e</span><span class="mord mathnormal">a</span><span class="mord mathnormal">se</span><span class="mord mathnormal">d</span><span class="mord mathnormal">e</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">e</span><span class="mord mathnormal">t</span><span class="mord mathnormal">e</span><span class="mord mathnormal">i</span><span class="mord mathnormal">t</span><span class="mord mathnormal">man</span><span class="mord mathnormal">u</span><span class="mord mathnormal">a</span><span class="mord mathnormal" style="margin-right:0.01968em;">ll</span><span class="mord mathnormal" style="margin-right:0.03588em;">y</span><span class="mord">.</span><span class="mord mathnormal" style="margin-right:0.05764em;">E</span><span class="mord mathnormal" style="margin-right:0.02778em;">rror</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span></span></span></span>{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: <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>e</mi><mi mathvariant="normal">.</mi><mi>d</mi><mi>o</mi><mi>c</mi><mi>u</mi><mi>m</mi><mi>e</mi><mi>n</mi><mi>t</mi><mi>N</mi><mi>a</mi><mi>m</mi><mi>e</mi></mrow><mi mathvariant="normal">.</mi><mi>P</mi><mi>l</mi><mi>e</mi><mi>a</mi><mi>s</mi><mi>e</mi><mi>d</mi><mi>e</mi><mi>l</mi><mi>e</mi><mi>t</mi><mi>e</mi><mi>i</mi><mi>t</mi><mi>m</mi><mi>a</mi><mi>n</mi><mi>u</mi><mi>a</mi><mi>l</mi><mi>l</mi><mi>y</mi><mi mathvariant="normal">.</mi><mi>E</mi><mi>r</mi><mi>r</mi><mi>o</mi><mi>r</mi><mo>:</mo></mrow><annotation encoding="application/x-tex">{state.documentName}. Please delete it manually. Error: </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8889em;vertical-align:-0.1944em;"></span><span class="mord"><span class="mord mathnormal">s</span><span class="mord mathnormal">t</span><span class="mord mathnormal">a</span><span class="mord mathnormal">t</span><span class="mord mathnormal">e</span><span class="mord">.</span><span class="mord mathnormal">d</span><span class="mord mathnormal">oc</span><span class="mord mathnormal">u</span><span class="mord mathnormal">m</span><span class="mord mathnormal">e</span><span class="mord mathnormal">n</span><span class="mord mathnormal" style="margin-right:0.10903em;">tN</span><span class="mord mathnormal">am</span><span class="mord mathnormal">e</span></span><span class="mord">.</span><span class="mord mathnormal" style="margin-right:0.01968em;">Pl</span><span class="mord mathnormal">e</span><span class="mord mathnormal">a</span><span class="mord mathnormal">se</span><span class="mord mathnormal">d</span><span class="mord mathnormal">e</span><span class="mord mathnormal" style="margin-right:0.01968em;">l</span><span class="mord mathnormal">e</span><span class="mord mathnormal">t</span><span class="mord mathnormal">e</span><span class="mord mathnormal">i</span><span class="mord mathnormal">t</span><span class="mord mathnormal">man</span><span class="mord mathnormal">u</span><span class="mord mathnormal">a</span><span class="mord mathnormal" style="margin-right:0.01968em;">ll</span><span class="mord mathnormal" style="margin-right:0.03588em;">y</span><span class="mord">.</span><span class="mord mathnormal" style="margin-right:0.05764em;">E</span><span class="mord mathnormal" style="margin-right:0.02778em;">rror</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span></span></span></span>{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.