Systems Manager Basics

Seven short examples covering the two things you will do most with Systems Manager from code: manage configuration in Parameter Store, and confirm/run something against a managed instance.

Each example shows the same operation in both Python (boto3) and TypeScript (AWS SDK for JavaScript v3).

Prerequisites

• Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-ssm (Node.js 18+).
• Credentials configured via aws configure, environment variables, or an IAM role with ssm:PutParameter, ssm:GetParameter*, and (for the Run Command examples) ssm:SendCommand and ssm:GetCommandInvocation.
• For the Run Command examples, at least one target instance must already be a managed instance - the SSM Agent running plus an instance profile with AmazonSSMManagedInstanceCore.

Basic Examples

1. Store a Plain-Text Parameter

PutParameter writes a value under a name. Path-like names (/app/prod/...) make later queries easier.

# --- Python (boto3) ---
import boto3
 
ssm = boto3.client("ssm", region_name="us-east-1")
ssm.put_parameter(
    Name="/app/prod/log-level",
    Value="info",
    Type="String",
)

// --- TypeScript (AWS SDK v3) ---
import { SSMClient, PutParameterCommand } from "@aws-sdk/client-ssm";
 
const ssm = new SSMClient({ region: "us-east-1" });
await ssm.send(new PutParameterCommand({
  Name: "/app/prod/log-level",
  Value: "info",
  Type: "String",
}));

• Type: "String" is a plain, unencrypted value - fine for non-sensitive config.
• A PutParameter call to an existing name fails unless you also pass Overwrite: true.
• Standard-tier parameters (the default) are free, up to 4 KB, and up to 10,000 per account per region.
• Path-like naming (/app/prod/log-level) lets you group and later query related parameters together.

2. Read a Parameter Back

GetParameter returns the value, plus metadata like its type and version.

# --- Python (boto3) ---
import boto3
 
ssm = boto3.client("ssm", region_name="us-east-1")
resp = ssm.get_parameter(Name="/app/prod/log-level")
print(resp["Parameter"]["Value"])   # "info"

// --- TypeScript (AWS SDK v3) ---
import { SSMClient, GetParameterCommand } from "@aws-sdk/client-ssm";
 
const ssm = new SSMClient({ region: "us-east-1" });
const resp = await ssm.send(new GetParameterCommand({ Name: "/app/prod/log-level" }));
console.log(resp.Parameter?.Value);   // "info"

• A missing name raises ParameterNotFound (boto3) or a typed ParameterNotFound error (SDK v3).
• resp.Parameter.Version increments on every overwrite, useful for cache-busting or auditing changes.
• Reading a String or StringList parameter needs no special flag.
• Any IAM principal with ssm:GetParameter on this name can read it - no managed instance required.

3. Store a Secret as a SecureString

Type: "SecureString" encrypts the value with a KMS key (the account default alias/aws/ssm unless you specify one).

# --- Python (boto3) ---
import boto3
 
ssm = boto3.client("ssm", region_name="us-east-1")
ssm.put_parameter(
    Name="/app/prod/db-password",
    Value="s3cr3t-value",
    Type="SecureString",
    KeyId="alias/app-secrets",   # optional: a customer-managed KMS key
)

// --- TypeScript (AWS SDK v3) ---
import { SSMClient, PutParameterCommand } from "@aws-sdk/client-ssm";
 
const ssm = new SSMClient({ region: "us-east-1" });
await ssm.send(new PutParameterCommand({
  Name: "/app/prod/db-password",
  Value: "s3cr3t-value",
  Type: "SecureString",
  KeyId: "alias/app-secrets",   // optional: a customer-managed KMS key
}));

• Omit KeyId to use the account's default AWS-managed key; pass a customer-managed key ARN or alias for tighter control over who can decrypt.
• The stored ciphertext, not the plaintext, is what you would see if you read the parameter without decryption.
• Callers need kms:Decrypt on the key in addition to ssm:GetParameter to read the plaintext back.
• SecureString is the right choice for anything you would not want visible in the console or CLI output by default.

4. Read a SecureString With Decryption

Reading a SecureString requires WithDecryption: true; otherwise you get back the ciphertext.

# --- Python (boto3) ---
import boto3
 
ssm = boto3.client("ssm", region_name="us-east-1")
resp = ssm.get_parameter(
    Name="/app/prod/db-password",
    WithDecryption=True,
)
print(resp["Parameter"]["Value"])   # plaintext

// --- TypeScript (AWS SDK v3) ---
import { SSMClient, GetParameterCommand } from "@aws-sdk/client-ssm";
 
const ssm = new SSMClient({ region: "us-east-1" });
const resp = await ssm.send(new GetParameterCommand({
  Name: "/app/prod/db-password",
  WithDecryption: true,
}));
console.log(resp.Parameter?.Value);   // plaintext

• Without WithDecryption, Value is the base64 ciphertext, not usable directly.
• Decryption happens server-side via KMS; the caller never handles key material.
• GetParameters (plural) also accepts WithDecryption for fetching several names at once.
• Set WithDecryption only where the plaintext is actually needed - logging a decrypted secret defeats the purpose of using SecureString.

Intermediate Examples

5. Fetch a Whole Config Tree by Path

GetParametersByPath returns every parameter under a prefix in one call, instead of one GetParameter per key.

# --- Python (boto3) ---
import boto3
 
ssm = boto3.client("ssm", region_name="us-east-1")
resp = ssm.get_parameters_by_path(
    Path="/app/prod/",
    Recursive=True,
    WithDecryption=True,
)
config = {p["Name"]: p["Value"] for p in resp["Parameters"]}

// --- TypeScript (AWS SDK v3) ---
import { SSMClient, GetParametersByPathCommand } from "@aws-sdk/client-ssm";
 
const ssm = new SSMClient({ region: "us-east-1" });
const resp = await ssm.send(new GetParametersByPathCommand({
  Path: "/app/prod/",
  Recursive: true,
  WithDecryption: true,
}));
const config = Object.fromEntries((resp.Parameters ?? []).map((p) => [p.Name, p.Value]));

• Recursive: true includes nested paths like /app/prod/db/host, not just direct children.
• Results are paginated beyond 10 items per page by default; use a paginator or NextToken loop for large trees.
• This is the standard way applications load their whole configuration at startup.
• WithDecryption applies uniformly, decrypting any SecureString values found under the path.

6. Confirm an Instance Is Managed

Before sending a command, verify the target actually shows up as managed.

# --- Python (boto3) ---
import boto3
 
ssm = boto3.client("ssm", region_name="us-east-1")
resp = ssm.describe_instance_information(
    Filters=[{"Key": "InstanceIds", "Values": ["i-0abc123"]}],
)
print(resp["InstanceInformationList"])

// --- TypeScript (AWS SDK v3) ---
import { SSMClient, DescribeInstanceInformationCommand } from "@aws-sdk/client-ssm";
 
const ssm = new SSMClient({ region: "us-east-1" });
const resp = await ssm.send(new DescribeInstanceInformationCommand({
  Filters: [{ Key: "InstanceIds", Values: ["i-0abc123"] }],
}));
console.log(resp.InstanceInformationList);

• An empty InstanceInformationList means the instance is not managed - the Agent is not reporting in, or the IAM role is missing AmazonSSMManagedInstanceCore.
• PingStatus: "Online" is what you want to see before targeting the instance.
• This check saves time debugging a SendCommand that silently has no eligible targets.
• Managed on-premises servers and EC2 instances both appear here identically.

7. Send a Simple Run Command

Once an instance is confirmed managed, SendCommand executes a document against it.

# --- Python (boto3) ---
import boto3
 
ssm = boto3.client("ssm", region_name="us-east-1")
resp = ssm.send_command(
    InstanceIds=["i-0abc123"],
    DocumentName="AWS-RunShellScript",
    Parameters={"commands": ["uptime"]},
)
command_id = resp["Command"]["CommandId"]
print(command_id)

// --- TypeScript (AWS SDK v3) ---
import { SSMClient, SendCommandCommand } from "@aws-sdk/client-ssm";
 
const ssm = new SSMClient({ region: "us-east-1" });
const resp = await ssm.send(new SendCommandCommand({
  InstanceIds: ["i-0abc123"],
  DocumentName: "AWS-RunShellScript",
  Parameters: { commands: ["uptime"] },
}));
const commandId = resp.Command?.CommandId;
console.log(commandId);

• SendCommand returns immediately with a CommandId - execution is asynchronous, not inline.
• AWS-RunShellScript is an AWS-owned document; AWS-RunPowerShellScript is its Windows equivalent.
• Use GetCommandInvocation (covered in the Run Command page) with the CommandId and instance ID to poll for output.
• InstanceIds works for a handful of targets; larger fleets should target by tag instead, shown on the Run Command page.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).