Local Testing — AWS (Floci)

AWS keeps CloudFormation as its native format. awsApply deploys the built template by calling the CloudFormation API directly — create-or-update the stack, then poll it to a settled state — against Floci’s emulated control plane or real AWS by endpoint override. Like azApply and gcpApply, it calls the API over HTTP instead of running aws cloudformation deploy.

Tip

This page is one cloud of examples/local-cloud-trio. Start from Local Testing for the cross-cloud picture.

The resource

An S3 bucket, described as data. It synthesizes to CloudFormation:

src/aws/infra.ts

export const bucket = new Bucket({
  BucketName: "chant-trio-bucket",
  PublicAccessBlockConfiguration: {
    BlockPublicAcls: true,
    BlockPublicPolicy: true,
    IgnorePublicAcls: true,
    RestrictPublicBuckets: true,
  },
});

The op

chant run aws boots Floci, builds the stack, applies it with awsApply, verifies the bucket over the S3 API, and tears the emulator down. Every phase is a modeled activity — no raw shell.

ops/aws.op.ts

export default Op({
  name: "aws",
  taskQueue: "trio-aws",
  phases: [
    phase("Emulator", [flociUp({ dockerSocket: true })]),
    phase("Build",    [build(".", { script: "build:aws" })]),
    phase("Apply",    [awsApply("dist/aws.json", { stackName: "trio-aws", endpoint: "http://localhost:4566" })]),
    phase("Verify",   [httpCheck("http://localhost:4566/chant-trio-bucket")]),
    phase("Teardown", [flociDown()]),
  ],
});

flociUp starts the pinned floci/floci:1.5.34 image unless image names another one. Pass network to join the container to a Docker network, and loopback: true to publish its port on 127.0.0.1 only. Extra Floci variables go in settings and reach the container as -e KEY=VALUE; a key that does not start with FLOCI_ is refused.

flociUp({ image: "floci/floci:<tag>", network: "loom-local", loopback: true })

The same options exist on chant emulator up as --image, --network, --setting and --loopback.

How awsApply works

CloudFormation is a control plane: you submit a template to a named stack and it reconciles. awsApply drives that plane through its API, no CLI in between:

• Reads the built template and calls DescribeStacks to decide create vs update.
• CreateStack or UpdateStack with the template body and capabilities. A no-op update (real AWS’s “No updates are to be performed”) is treated as unchanged.
• Polls DescribeStacks until the stack settles — CREATE_COMPLETE / UPDATE_COMPLETE — and fails the phase on a *_FAILED / ROLLBACK state.

The stack is the deploy boundary, so deletes ride CloudFormation itself — awsDelete calls DeleteStack and polls until the stack is gone. No separate prune.

Run it

Requires Docker.

cd examples/local-cloud-trio
npm install
chant run aws

From local to real cloud

Drop the endpoint override and awsApply targets real CloudFormation. The template, the create-or-update logic, and the settle-polling are unchanged — only the API host differs.

Note

Against a local Floci the API calls are unsigned, which the emulator accepts. Real AWS requires SigV4-signed requests — the same credential layer the Azure and GCP appliers need for real cloud. Floci’s emulated coverage is reported at /_localstack/health; a resource whose service isn’t listed there can’t run locally, though synthesis and lint still validate it.