@zuke/aws

Settings for aws cloudformation delete-stack.

Settings for aws cloudformation deploy.

Settings for aws cloudformation describe-stacks.

The waiters aws cloudformation wait offers for a stack.

Settings for aws cloudformation wait <waiter>: block until the stack reaches the waiter's state. The CLI polls every 30 seconds and exits non-zero after 120 attempts, or as soon as the stack lands in a failed state — which surfaces as a CommandError.

How AwsCloudwatchMetricValueSettings turns a series into one number: its newest datapoint, or the sum, average, maximum or minimum of all of them.

The states a CloudWatch alarm can be in.

The kinds of alarm describe-alarms can return.

A health check run against a canary, in the shape @zuke/canary's c.analysis(...) accepts: throw to fail it, which rolls the rollout back.

The part of the canary engine's context the analysis uses: the run's redactor, applied to every failure message. The engine hands a richer context; this is the narrow view.

Settings for cloudwatch: the metric, the window and the bounds.

The metric itself — namespace, metricName, dimension, stat, period, unit — is set with the same setters as a get-metric-data query, which these settings extend; it is queried as m1.

Settings for aws cloudwatch describe-alarms.

Settings for one metric-math expression in a get-metric-data request.

Settings for aws cloudwatch get-metric-data.

Settings for aws cloudwatch get-metric-statistics.

Settings for one metric in a get-metric-data request (a MetricStat query).

Settings for AwsTasks.metricValue: a get-metric-data request, and how to read it.

A CloudWatch statistic: one of the five basic statistics, the interquartile mean IQM, or a percentile (p99, p99.9) or other extended statistic (tm90, TM(10%:90%), PR(100:2000), …).

Settings for aws configure get.

Reading a credential — aws_secret_access_key, aws_session_token, in any profile — runs quietly and registers what it printed with the run's redactor.

Settings for aws configure set.

aws configure set takes the value on its command line, where every user on the host can read it from the process table. Setting aws_secret_access_key or aws_session_token this way registers the value with the run's redactor so Zuke's own output masks it, but that does not hide it from the process table — prefer the AWS_* environment variables or a role for credentials.

Settings for aws ecr batch-delete-image.

Settings for aws ecr describe-images.

Settings for aws ecr describe-repositories.

Settings for aws ecr get-login-password.

The password is a registry credential, so the command always runs quietly and the password is registered with the run's redactor once it returns. Hand it to docker login --password-stdin (DockerTasks.login with .passwordStdin(...)), never to -p.

Settings for aws ecs describe-services.

Settings for aws ecs register-task-definition.

Either hand the whole definition over with cliInputJson — the usual form, a file:// path to a JSON document — or set the family and its container definitions. Environment values in a container definition land on the command line; keep secrets in the definition's secrets (Secrets Manager or SSM references) rather than its environment.

Settings for aws ecs run-task.

Settings for aws ecs update-service.

Settings for aws ecs wait services-stable: block until every named service has its desired count running on one deployment. The CLI polls every 15 seconds and gives up after 40 attempts with a non-zero exit, which surfaces as a CommandError.

Settings for aws eks describe-cluster.

Settings for aws eks update-kubeconfig.

A Lambda alias as a canary platform. Create one with lambdaCanary; hand it to @zuke/canary's c.platform(...).

Exposure is a share of the alias's invocations, set exactly.

The part of the canary engine's context the Lambda platform uses: the rollout's durable state, where the staged versions are recorded, and the build summary. The engine hands a richer context; this is the narrow view.

How lambdaCanary reaches the alias and finds the candidate, configured through its lambda.

Settings for aws lambda get-alias.

Settings for aws lambda get-function.

Settings for aws lambda invoke.

The function's response is written to the outfile; what the CLI prints is the invocation's status. A function that throws still exits 0: the CLI reports it in the printed FunctionError field, so read that (or the outfile) before treating an invocation as a success.

Settings for aws lambda publish-version.

Settings for aws lambda update-alias.

Settings for aws lambda update-function-code.

Settings for aws lambda update-function-configuration.

The states aws lambda wait can wait for. function-updated-v2 waits for an update in progress to finish; published-version-active for a version just published to leave Pending — SnapStart and image functions take a while, and Lambda fails invocations of a version until it is Active.

Settings for aws lambda wait: poll the function until it reaches the state named, exiting non-zero — a CommandError — when it fails or the waiter gives up.

Settings for aws logs filter-log-events.

Settings for aws logs get-query-results.

Settings for AwsTasks.logsInsightsQuery: the query, and how long to wait for it.

One row of a Logs Insights result: each field the query returned, by name.

A CloudWatch Logs Insights query did not complete: the service reported it Failed, Cancelled or Timeout, or it was still running when the reader's own timeout ran out.

Settings for aws logs start-query.

Settings for aws logs stop-query.

Settings for aws logs tail. With follow the command never ends on its own — bound it with .killAfter(ms).

The AWS CLI succeeded but printed something a reader cannot use: output that is not JSON, JSON of an unexpected shape, an empty or multi-line answer where one value was expected, or a capture that was truncated.

The message never quotes the output itself. Several readers return credentials and secret payloads, and an error that echoed what the CLI printed would put the secret in the build log it was read to stay out of.

The values the AWS CLI's --output option accepts.

Settings for aws s3 cp.

Settings for aws s3 ls.

Settings for aws s3 mb.

Settings for aws s3 presign.

A presigned URL is a bearer credential for the object until it expires: anyone holding it can read the object, and when the build runs on temporary credentials it also carries the session token itself (X-Amz-Security-Token), which is good for far more than one object. So the command always runs quietly — the URL is captured, never streamed — and the URL and that token are registered with the run's redactor.

Settings for aws s3 rm.

Settings for aws s3 sync.

Settings for aws secretsmanager get-secret-value.

The response is the secret, so the command always runs quietly — captured, never streamed — with --output json pinned, and the SecretString or SecretBinary it returns is registered with the run's redactor.

Settings for an aws invocation.

Every instance sets two variables in the child's environment so the CLI can never sit waiting for a keypress in a build: AWS_PAGER to the empty string (CLI v2 pipes output through less by default) and AWS_CLI_AUTO_PROMPT to off (a profile's cli_auto_prompt would otherwise open the interactive prompt). Setting them there keeps the argv exactly what the settings say; override either with .env({...}), or add the explicit flag with noCliPager.

Runs one prepared aws command and returns what the process produced. The default spawns the CLI; a test, or a build that executes the CLI some other way, injects its own with AwsSettings.runner. The runner only produces the output: the exit code is judged afterwards exactly as for a spawned process, so a non-zero code still raises a CommandError unless the settings say .noThrow().

Settings for aws ssm get-parameter.

A parameter may be a SecureString, so the command always runs quietly — captured, never streamed — with --output json pinned, and the value it returns is registered with the run's redactor.

The kinds of parameter Parameter Store keeps.

Settings for aws ssm put-parameter.

--value is a command-line argument, which every user on the host can read from the process table. For a SecureString, write the value to a file with owner-only permissions and use valueFile: the CLI reads it, so it never appears in the argv. A literal value given to a SecureString is registered with the run's redactor, which masks Zuke's own output but not the process table.

Settings for aws sts assume-role.

The response carries a secret access key and a session token, so the command always runs quietly — its output is captured, never streamed — with --output json pinned whatever the settings or the user's config say, and both values are registered with the run's redactor once it returns.

Settings for aws sts get-caller-identity.

Typed task functions for the aws CLI.

The shape of AwsTasks.

A time given as a Date or as a string the CLI parses (ISO 8601).

An analysis that reads a CloudWatch metric over a recent window and fails the canary when any datapoint is out of bounds — or when there is no data, unless AwsCloudwatchAnalysisSettings.missingDataAs says what no data means. Each datapoint covers one period, so a .max(5) on a per-minute Sum means "no minute with more than five".

The lambda runs on each check, so it may read resolved parameters, and every failure message — one from the lambda included — passes through the run's redactor.

A Lambda alias as a canary platform, for @zuke/canary:

c.platform(lambdaCanary((l) =>
  l.functionName("api").alias("live").zipFile("dist/api.zip")
    .aws((a) => a.profile("deploy").region("eu-west-1"))
))

The lambda runs on every call, so it may read resolved parameters.

- stage — reads the alias (get-alias), whose version becomes the stable one; waits out an update in progress (wait function-updated-v2) and publishes the candidate with update-function-code --publish, or takes .version(...); reads it back with get-function; waits for it to be Active (wait published-version-active); records the rollout. The alias is not changed. - expose — update-alias --routing-config AdditionalVersionWeights={"<candidate>": <n/100>} --revision-id <rev>. - promote — update-alias --function-version <candidate> with the routing cleared. - abort — takes the candidate's weight off mid-rollout; run by hand, --function-version <stable> with the routing cleared. A rollback with nothing recorded runs nothing: nothing was staged.

Every call after stage that has its record — expose, promote, and abort mid-rollout — compares the configured function, alias and AWS flags with the record, reads the alias and checks its ARN (which names the account and region), and refuses on any difference before changing anything. Expose and promote also check that the alias splits only as the rollout left it and that the candidate still has the code staged. Each update-alias carries the alias's --revision-id, so a change made between the read and the update fails it. A hand-run abort has no record and uses the configuration as it is.

Lambda's weighted routing needs the two versions to share an execution role and a dead-letter configuration; the update fails, and the canary rolls back, when they do not.