AWS.SSM reference

GetParameter

Source: src/AWS/SSM/GetParameter.ts

Runtime binding for ssm:GetParameter.

Bind this operation to a Parameter inside a function runtime to get a callable that automatically injects the parameter name. For SecureString parameters the binding also grants kms:Decrypt on the parameter’s encryption key so WithDecryption: true works out of the box.

GetParameter: Reading a Parameter

Read a String Parameter

const getParameter = yield* SSM.GetParameter(config);

const result = yield* getParameter();
const value = result.Parameter?.Value;

Read a SecureString Parameter with Decryption

const getSecret = yield* SSM.GetParameter(apiKey);

const result = yield* getSecret({ WithDecryption: true });

GetParameterHistory

Source: src/AWS/SSM/GetParameterHistory.ts

Runtime binding for ssm:GetParameterHistory.

Bind this operation to a Parameter inside a function runtime to get a callable that retrieves the change history (all versions, labels, and metadata) of the bound parameter. The binding also grants kms:Decrypt on the parameter’s encryption key so WithDecryption: true works on SecureString parameters.

GetParameterHistory: Reading Parameter History

const getHistory = yield* SSM.GetParameterHistory(config);

const result = yield* getHistory();
for (const version of result.Parameters ?? []) {
  yield* Effect.log(`v${version.Version}: ${version.Value}`);
}

GetParameters

Source: src/AWS/SSM/GetParameters.ts

Runtime binding for ssm:GetParameters.

Bind this operation to one or more Parameters inside a function runtime to get a callable that fetches all of them in a single API call. The binding grants ssm:GetParameters on the exact parameter ARNs and kms:Decrypt on the encryption keys of any SecureString parameters.

GetParameters: Reading Multiple Parameters

const getParameters = yield* SSM.GetParameters(dbUrl, apiKey);

const result = yield* getParameters({ WithDecryption: true });
for (const parameter of result.Parameters ?? []) {
  yield* Effect.log(`${parameter.Name} = ${parameter.Value}`);
}

GetParametersByPath

Source: src/AWS/SSM/GetParametersByPath.ts

Runtime binding for ssm:GetParametersByPath.

Bind this operation to a Parameter with a hierarchical name (e.g. /my-app/config) to get a callable that reads every parameter stored under that name — the bound parameter acts as the subtree root. The binding grants ssm:GetParametersByPath on the parameter’s ARN and its /* subtree wildcard, plus kms:Decrypt on the bound parameter’s encryption key so WithDecryption: true works for SecureString children encrypted with the same key.

GetParametersByPath: Reading a Parameter Subtree

const root = yield* SSM.Parameter("ConfigRoot", {
  name: "/my-app/config",
  value: "v1",
});
const getByPath = yield* SSM.GetParametersByPath(root);

// returns /my-app/config/db-url, /my-app/config/flags/beta, …
const result = yield* getByPath({ Recursive: true });

LabelParameterVersion

Source: src/AWS/SSM/LabelParameterVersion.ts

Runtime binding for ssm:LabelParameterVersion.

Bind this operation to a Parameter inside a function runtime to get a callable that attaches labels (e.g. current, stable) to a version of the bound parameter. Omitting ParameterVersion labels the latest version. Labels enable versioned rollouts: readers pass Name:label selectors to GetParameter while writers move the label between versions.

LabelParameterVersion: Labeling Parameter Versions

const label = yield* SSM.LabelParameterVersion(config);

const result = yield* label({ Labels: ["current"] });
yield* Effect.log(`labeled version ${result.ParameterVersion}`);

Parameter

Source: src/AWS/SSM/Parameter.ts

An AWS Systems Manager (SSM) Parameter Store parameter.

Parameter owns the lifecycle of a String, StringList, or SecureString parameter. A parameter name is auto-generated from the app, stage, and logical ID unless you provide one explicitly. Standard-tier parameters are free, making them ideal for configuration values, feature flags, and small secrets.

Parameter: Creating Parameters

String Parameter

import * as SSM from "alchemy/AWS/SSM";

const config = yield* SSM.Parameter("DatabaseUrl", {
  value: "postgres://db.example.com:5432/app",
});

StringList Parameter

const subnets = yield* SSM.Parameter("AllowedOrigins", {
  type: "StringList",
  value: "https://a.example.com,https://b.example.com",
});

Parameter with a Hierarchical Name

const param = yield* SSM.Parameter("DbUrl", {
  name: "/my-app/prod/db-url",
  value: "postgres://db.example.com:5432/app",
});

Parameter: SecureString Parameters

Encrypted with the AWS-managed key

import * as Redacted from "effect/Redacted";

const apiKey = yield* SSM.Parameter("ApiKey", {
  type: "SecureString",
  value: Redacted.make("super-secret-value"),
});

Encrypted with a customer-managed KMS key

const key = yield* KMS.Key("SecretsKey");
const apiKey = yield* SSM.Parameter("ApiKey", {
  type: "SecureString",
  value: Redacted.make("super-secret-value"),
  keyId: key.keyId,
});

Parameter: Validation

const port = yield* SSM.Parameter("Port", {
  value: "5432",
  allowedPattern: "^\\d+$",
});

Parameter: Reading Parameters at Runtime

Bind read operations in the init phase and use them in runtime handlers.

// init
const getParameter = yield* SSM.GetParameter(config);

return {
  fetch: Effect.gen(function* () {
    // runtime
    const result = yield* getParameter({ WithDecryption: true });
    return HttpServerResponse.text(String(result.Parameter?.Value));
  }),
};

PutParameter

Source: src/AWS/SSM/PutParameter.ts

Runtime binding for ssm:PutParameter.

Bind this operation to a Parameter inside a function runtime to get a callable that writes a new version of the bound parameter — e.g. flipping a feature flag or rotating a stored secret at runtime. For SecureString parameters the binding also grants kms:Encrypt and kms:GenerateDataKey on the parameter’s encryption key.

Pass Overwrite: true to update the existing parameter (the parameter already exists — it is managed by the Parameter resource). Note that a runtime write drifts the value from the deployed desired state; the next deploy converges it back.

PutParameter: Writing a Parameter

const putFlag = yield* SSM.PutParameter(flag);

const result = yield* putFlag({ Value: "on", Overwrite: true });
yield* Effect.log(`flag now at version ${result.Version}`);

UnlabelParameterVersion

Source: src/AWS/SSM/UnlabelParameterVersion.ts

Runtime binding for ssm:UnlabelParameterVersion.

Bind this operation to a Parameter inside a function runtime to get a callable that removes labels from a specific version of the bound parameter — the counterpart to LabelParameterVersion when moving a label during a rollout or rollback.

UnlabelParameterVersion: Labeling Parameter Versions

const unlabel = yield* SSM.UnlabelParameterVersion(config);

const result = yield* unlabel({
  ParameterVersion: 3,
  Labels: ["current"],
});
yield* Effect.log(`removed: ${result.RemovedLabels?.join(", ")}`);