AWS.FIS reference

ExperimentTemplate

Source: src/AWS/FIS/ExperimentTemplate.ts

An AWS Fault Injection Service (FIS) experiment template — a reusable definition of a chaos-engineering experiment: the targets to disrupt, the fault actions to run against them, and the stop conditions that abort a runaway experiment.

Creating a template is free and does not disrupt any resources — faults are only injected when an experiment is explicitly started from the template.

ExperimentTemplate: Creating Experiment Templates

Stop EC2 instances selected by tag

import * as AWS from "alchemy/AWS";

const role = yield* AWS.IAM.Role("FisRole", {
  assumeRolePolicyDocument: {
    Version: "2012-10-17",
    Statement: [{
      Effect: "Allow",
      Principal: { Service: "fis.amazonaws.com" },
      Action: ["sts:AssumeRole"],
    }],
  },
  managedPolicyArns: [
    "arn:aws:iam::aws:policy/service-role/AWSFaultInjectionSimulatorEC2Access",
  ],
});

const template = yield* AWS.FIS.ExperimentTemplate("StopInstances", {
  description: "Stop one tagged instance for two minutes",
  roleArn: role.roleArn,
  targets: {
    Instances: {
      resourceType: "aws:ec2:instance",
      resourceTags: { ChaosReady: "true" },
      selectionMode: "COUNT(1)",
    },
  },
  actions: {
    StopInstances: {
      actionId: "aws:ec2:stop-instances",
      parameters: { startInstancesAfterDuration: "PT2M" },
      targets: { Instances: "Instances" },
    },
  },
});

Stop condition backed by a CloudWatch alarm

const template = yield* AWS.FIS.ExperimentTemplate("GuardedExperiment", {
  roleArn: role.roleArn,
  targets: {
    Instances: {
      resourceType: "aws:ec2:instance",
      resourceTags: { ChaosReady: "true" },
      selectionMode: "ALL",
    },
  },
  actions: {
    StopInstances: {
      actionId: "aws:ec2:stop-instances",
      targets: { Instances: "Instances" },
    },
  },
  stopConditions: [
    {
      source: "aws:cloudwatch:alarm",
      value: alarmArn,
    },
  ],
});

Wait action sequenced after a fault

const template = yield* AWS.FIS.ExperimentTemplate("SequencedExperiment", {
  roleArn: role.roleArn,
  actions: {
    Wait: {
      actionId: "aws:fis:wait",
      parameters: { duration: "PT1M" },
    },
    WaitAgain: {
      actionId: "aws:fis:wait",
      parameters: { duration: "PT1M" },
      startAfter: ["Wait"],
    },
  },
});

GetAction

Source: src/AWS/FIS/GetAction.ts

Runtime binding for fis:GetAction.

Reads a single FIS action from the service’s action catalog — its description, parameters, and the targets it applies to (e.g. aws:ec2:stop-instances). Provide the implementation with Effect.provide(AWS.FIS.GetActionHttp).

GetAction: Browsing the Action Catalog

// init — account-level binding, no resource argument
const getAction = yield* AWS.FIS.GetAction();

// runtime
const { action } = yield* getAction({ id: "aws:fis:wait" });
console.log(Object.keys(action?.parameters ?? {}));

GetExperiment

Source: src/AWS/FIS/GetExperiment.ts

Runtime binding for fis:GetExperiment.

Reads a running or finished experiment — its state (pending, initiating, running, completed, stopped, failed), per-action progress, and log/report configuration. Experiments are created dynamically, so this is an account-level binding addressed by experiment id. Provide the implementation with Effect.provide(AWS.FIS.GetExperimentHttp).

GetExperiment: Running Experiments

// init — account-level binding, no resource argument
const getExperiment = yield* AWS.FIS.GetExperiment();

// runtime
const { experiment } = yield* getExperiment({ id: experimentId });
console.log(experiment?.state?.status);

GetExperimentTargetAccountConfiguration

Source: src/AWS/FIS/GetExperimentTargetAccountConfiguration.ts

Runtime binding for fis:GetExperimentTargetAccountConfiguration.

Reads the target account configuration a multi-account experiment resolved for a specific account — the role and description FIS uses to act in that account. Provide the implementation with Effect.provide(AWS.FIS.GetExperimentTargetAccountConfigurationHttp).

GetExperimentTargetAccountConfiguration: Multi-Account Experiments

// init — account-level binding, no resource argument
const getTargetAccount =
  yield* AWS.FIS.GetExperimentTargetAccountConfiguration();

// runtime
const { targetAccountConfiguration } = yield* getTargetAccount({
  experimentId,
  accountId,
});
console.log(targetAccountConfiguration?.roleArn);

GetExperimentTemplate

Source: src/AWS/FIS/GetExperimentTemplate.ts

Runtime binding for fis:GetExperimentTemplate.

Reads the bound ExperimentTemplate’s full definition — targets, actions, stop conditions, log and report configuration — so a runtime function can inspect the experiment it is about to start. The template id is injected from the binding. Provide the implementation with Effect.provide(AWS.FIS.GetExperimentTemplateHttp).

GetExperimentTemplate: Inspecting Templates

// init — bind the operation to the experiment template
const getExperimentTemplate = yield* AWS.FIS.GetExperimentTemplate(template);

// runtime
const { experimentTemplate } = yield* getExperimentTemplate();
console.log(Object.keys(experimentTemplate?.actions ?? {}));

GetSafetyLever

Source: src/AWS/FIS/GetSafetyLever.ts

Runtime binding for fis:GetSafetyLever.

Reads the account’s safety lever — the emergency switch that, when engaged, stops all running experiments and prevents new ones from starting. The account’s lever has the well-known id default. Provide the implementation with Effect.provide(AWS.FIS.GetSafetyLeverHttp).

GetSafetyLever: The Safety Lever

// init — account-level binding, no resource argument
const getSafetyLever = yield* AWS.FIS.GetSafetyLever();

// runtime
const { safetyLever } = yield* getSafetyLever({ id: "default" });
console.log(safetyLever?.state?.status); // "disengaged"

GetTargetResourceType

Source: src/AWS/FIS/GetTargetResourceType.ts

Runtime binding for fis:GetTargetResourceType.

Reads a single targetable resource type from the FIS catalog — its description and the parameters targets of that type accept (e.g. aws:ec2:instance). Provide the implementation with Effect.provide(AWS.FIS.GetTargetResourceTypeHttp).

GetTargetResourceType: Browsing the Action Catalog

// init — account-level binding, no resource argument
const getTargetResourceType = yield* AWS.FIS.GetTargetResourceType();

// runtime
const { targetResourceType } = yield* getTargetResourceType({
  resourceType: "aws:ec2:instance",
});
console.log(targetResourceType?.description);

ListActions

Source: src/AWS/FIS/ListActions.ts

Runtime binding for fis:ListActions.

Enumerates the FIS action catalog — every fault the service can inject (aws:ec2:stop-instances, aws:ssm:send-command, aws:fis:wait, …). Provide the implementation with Effect.provide(AWS.FIS.ListActionsHttp).

ListActions: Browsing the Action Catalog

// init — account-level binding, no resource argument
const listActions = yield* AWS.FIS.ListActions();

// runtime
const { actions } = yield* listActions();
console.log((actions ?? []).map((a) => a.id));

ListExperimentResolvedTargets

Source: src/AWS/FIS/ListExperimentResolvedTargets.ts

Runtime binding for fis:ListExperimentResolvedTargets.

Lists the concrete resources an experiment’s targets resolved to — the exact instances, tasks, or functions the faults were injected into — so a post-run report can name the blast radius. Provide the implementation with Effect.provide(AWS.FIS.ListExperimentResolvedTargetsHttp).

ListExperimentResolvedTargets: Running Experiments

// init — account-level binding, no resource argument
const listResolvedTargets = yield* AWS.FIS.ListExperimentResolvedTargets();

// runtime
const { resolvedTargets } = yield* listResolvedTargets({
  experimentId,
});
for (const target of resolvedTargets ?? []) {
  console.log(target.targetName, target.targetInformation);
}

ListExperiments

Source: src/AWS/FIS/ListExperiments.ts

Runtime binding for fis:ListExperiments.

Enumerates the account’s experiments, optionally filtered to those started from a specific template — the building block of a chaos-run dashboard or a guard that refuses to start a new experiment while one is already running. Provide the implementation with Effect.provide(AWS.FIS.ListExperimentsHttp).

ListExperiments: Running Experiments

// init — account-level binding, no resource argument
const listExperiments = yield* AWS.FIS.ListExperiments();

// runtime
const { experiments } = yield* listExperiments({
  experimentTemplateId: templateId,
});
const running = (experiments ?? []).filter(
  (e) => e.state?.status === "running",
);

ListExperimentTargetAccountConfigurations

Source: src/AWS/FIS/ListExperimentTargetAccountConfigurations.ts

Runtime binding for fis:ListExperimentTargetAccountConfigurations.

Lists the target account configurations a multi-account experiment resolved — every account the experiment injects faults into. Provide the implementation with Effect.provide(AWS.FIS.ListExperimentTargetAccountConfigurationsHttp).

ListExperimentTargetAccountConfigurations: Multi-Account Experiments

// init — account-level binding, no resource argument
const listTargetAccounts =
  yield* AWS.FIS.ListExperimentTargetAccountConfigurations();

// runtime
const { targetAccountConfigurations } = yield* listTargetAccounts({
  experimentId,
});
console.log(
  (targetAccountConfigurations ?? []).map((c) => c.accountId),
);

ListExperimentTemplates

Source: src/AWS/FIS/ListExperimentTemplates.ts

Runtime binding for fis:ListExperimentTemplates.

Enumerates the account’s experiment templates — the catalog a chaos orchestrator picks its next run from. Provide the implementation with Effect.provide(AWS.FIS.ListExperimentTemplatesHttp).

ListExperimentTemplates: Inspecting Templates

// init — account-level binding, no resource argument
const listExperimentTemplates = yield* AWS.FIS.ListExperimentTemplates();

// runtime
const { experimentTemplates } = yield* listExperimentTemplates();
console.log((experimentTemplates ?? []).map((t) => t.id));

ListTargetResourceTypes

Source: src/AWS/FIS/ListTargetResourceTypes.ts

Runtime binding for fis:ListTargetResourceTypes.

Enumerates the resource types FIS experiments can target (aws:ec2:instance, aws:ecs:task, aws:rds:cluster, …). Provide the implementation with Effect.provide(AWS.FIS.ListTargetResourceTypesHttp).

ListTargetResourceTypes: Browsing the Action Catalog

// init — account-level binding, no resource argument
const listTargetResourceTypes = yield* AWS.FIS.ListTargetResourceTypes();

// runtime
const { targetResourceTypes } = yield* listTargetResourceTypes();
console.log((targetResourceTypes ?? []).map((t) => t.resourceType));

StartExperiment

Source: src/AWS/FIS/StartExperiment.ts

Runtime binding for fis:StartExperiment.

Starts a fault-injection experiment from the bound ExperimentTemplate — the template’s id is injected and the idempotency clientToken is generated automatically. The IAM grant covers both the template and the experiment/* ARN the started experiment is created under. Provide the implementation with Effect.provide(AWS.FIS.StartExperimentHttp).

StartExperiment: Running Experiments

// init — bind the operation to the experiment template
const startExperiment = yield* AWS.FIS.StartExperiment(template);

// runtime
const { experiment } = yield* startExperiment();
console.log(experiment?.id, experiment?.state?.status);

StopExperiment

Source: src/AWS/FIS/StopExperiment.ts

Runtime binding for fis:StopExperiment.

Stops a running experiment — the manual abort switch for a chaos-engineering run that a monitoring function decides has gone far enough. Experiments are created dynamically, so this is an account-level binding addressed by experiment id. Provide the implementation with Effect.provide(AWS.FIS.StopExperimentHttp).

StopExperiment: Running Experiments

// init — account-level binding, no resource argument
const stopExperiment = yield* AWS.FIS.StopExperiment();

// runtime
const { experiment } = yield* stopExperiment({ id: experimentId });
console.log(experiment?.state?.status); // "stopping"

TargetAccountConfiguration

Source: src/AWS/FIS/TargetAccountConfiguration.ts

A target account configuration for a multi-account AWS Fault Injection Service (FIS) experiment template — registers an AWS account (and the IAM role FIS assumes there) as a target of the experiment, so a single experiment can inject faults into resources across accounts.

The parent ExperimentTemplate must declare experimentOptions: { accountTargeting: "multi-account" }.

TargetAccountConfiguration: Registering Target Accounts

import * as AWS from "alchemy/AWS";

const template = yield* AWS.FIS.ExperimentTemplate("CrossAccount", {
  roleArn: orchestratorRole.roleArn,
  experimentOptions: { accountTargeting: "multi-account" },
  actions: {
    Wait: { actionId: "aws:fis:wait", parameters: { duration: "PT1M" } },
  },
});

const target = yield* AWS.FIS.TargetAccountConfiguration("WorkloadAccount", {
  experimentTemplateId: template.id,
  accountId: "111122223333",
  roleArn: "arn:aws:iam::111122223333:role/FisTargetRole",
  description: "the workload account faults are injected into",
});

UpdateSafetyLeverState

Source: src/AWS/FIS/UpdateSafetyLeverState.ts

Runtime binding for fis:UpdateSafetyLeverState.

Engages or disengages the account’s safety lever — engaging it stops all running experiments and blocks new ones until it is disengaged, the account-wide chaos kill switch an ops function flips when a stop condition outside FIS’s view fires. The account’s lever has the well-known id default. Provide the implementation with Effect.provide(AWS.FIS.UpdateSafetyLeverStateHttp).

UpdateSafetyLeverState: The Safety Lever

// init — account-level binding, no resource argument
const updateSafetyLeverState = yield* AWS.FIS.UpdateSafetyLeverState();

// runtime
yield* updateSafetyLeverState({
  id: "default",
  state: { status: "engaged", reason: "elevated error budget burn" },
});