Fjall Docs — deploy AWS infrastructure into your own account

Buildkite is a CDK construct inside a Fjall application, not a standalone stack. Add it with fjall add buildkite, then ship it with fjall deploy <app>. There is no cdk deploy step and no BuildkiteDefaultProps export.

Overview

The fleet runs Buildkite agents on the pinned Elastic CI Stack AMIs inside your own AWS account. Agents poll the Buildkite API for jobs, so the fleet creates no load balancer and needs no inbound access. Three properties define the posture:

Scale to zero. agentMinInstances defaults to 0, so an idle queue costs nothing beyond storage.
On-demand only by default. spotCapacityPercentage defaults to 0. A spot reclaim mid-deploy is a rollback incident, so raise it only for idempotent, auto-retried jobs.
No secret transits synth. The construct receives SSM parameter names. Token values move from SSM to the instance at job runtime.

AMIs are pinned per region, and only us-east-1 is pinned today. Synth throws in any other region and names the supported list. Deploy the fleet to a *-use1 target.

What it provisions

Component	Detail
EC2 agent Auto Scaling group	Pinned Elastic CI Stack AMI, public subnet, public IP, zero ingress
buildkite-agent-scaler	Serverless Application Repository app, pinned version, `DisableScaleIn: true`
Artefact S3 bucket	Build artefact storage, versioning follows the application’s backup tier
Managed secrets S3 bucket	Versioned and retained on stack delete, holds the per-job `env` hook
Instance IAM role	Allowlist-only, scoped to the fleet’s own parameters and buckets
CloudWatch alarms	Scaler heartbeat, plus jobs-queued-with-zero-capacity
CloudFormation outputs	Queue name, Auto Scaling group name, secrets bucket, artefact bucket

The instance profile deliberately carries no registry credentials and no AmazonSSMManagedInstanceCore. Deploy jobs authenticate through server-minted Fjall credentials, exactly as they do on hosted agents.

Prerequisites

Node 22 or later
A Fjall application with networking enabled (the fleet attaches to the application’s VPC)
A Buildkite organisation slug, such as acme-eng
A cluster-scoped Buildkite agent token, stored in SSM before the first deploy

Store the agent token

The agent token is load-bearing: the boot script and the scaler both read it, and an unresolvable parameter fails synth. Provision it first with the Fjall secrets tooling:

fjall secrets set agent-token=bkua_xxx --app api --cluster agents

That writes the SecureString /api/agents/agent-token, which is the path the construct derives by default from the application name. Store the Fjall API key the same way when your pipelines call the Fjall CLI:

fjall secrets set fjall-api-key=fj_xxx --app api --cluster agents

The construct ships a per-job env hook into the managed secrets bucket. The hook reads both parameters at the start of every job, so rotating a token takes effect on the next job with no instance replacement.

Quick start

Add the fleet to an existing application. Both --buildkiteQueue and --buildkiteOrgSlug are required, and a missing one is refused before the file is written:

fjall add buildkite --app api --name Buildkite \
  --buildkiteQueue api-deploy \
  --buildkiteOrgSlug acme-eng

That appends one statement to fjall/api/infrastructure.ts and adds the factory import:

import { App, BuildkiteFactory } from "@fjall/components-infrastructure";

const app = App.getApp("api", {
  network: { maxAzs: 2, natGateways: false },
});

app.addBuildkite(
  BuildkiteFactory.build("Buildkite", {
    buildkiteQueue: "api-deploy",
    buildkiteOrgSlug: "acme-eng",
  }),
);

Deploy it:

fjall deploy api --target production-use1

App.addBuildkite places the fleet in the application’s compute stack and injects the application id, the shared alarm topic and the cost-allocation environment. Defaults from the schema are applied at synth, so infrastructure.ts keeps only the properties you set.

Configuration

Every property is a camelCase key on the construct’s schema, which is .strict(). An unknown key is rejected at write time by fjall add and at synth by the construct, so a stale property name fails loudly rather than being ignored. Set properties either as flags on fjall add and fjall modify, or directly in the factory call:

fjall modify buildkite --app api --name Buildkite --agentMaxInstances 6

app.addBuildkite(
  BuildkiteFactory.build("Buildkite", {
    buildkiteQueue: "api-deploy",
    buildkiteOrgSlug: "acme-eng",
    agentMaxInstances: 6,
    instanceType: "c8g.2xlarge",
  }),
);

Required

Property	Type	Description
`buildkiteQueue`	string	Queue this fleet serves. Alphanumeric with hyphens and underscores, 1 to 100 characters.
`buildkiteOrgSlug`	string	Buildkite organisation slug, lowercase. The fleet’s alarms query metrics dimensioned by organisation and queue, so a wrong slug reads no data.

Secrets and identity

Property	Type	Description	Default
`agentTokenSsmParameterName`	string	Full path of the SecureString holding the agent token	`/<applicationId>/agents/agent-token`
`agentTokenKmsKeyArn`	string	Customer-managed KMS key encrypting that parameter	AWS-managed `aws/ssm` key
`fjallApiKeySsmParameterName`	string	Full path of the SecureString holding `FJALL_API_KEY`	`/<applicationId>/agents/fjall-api-key`
`applicationId`	string	Application the fleet belongs to, used for derived secret paths, alarm descriptions and the `fjall:applicationId` tag	injected by `App.addBuildkite`

Both parameter paths must start with /. An unresolvable agent-token path throws at synth. An unresolvable API-key path skips the env hook and emits a warning instead.

Capacity

Property	Type	Description	Default
`instanceType`	string	EC2 instance type. The default is Graviton, so agent images must be ARM64.	`c8g.xlarge`
`agentVolumeSizeGib`	number, 20 to 1000	Root EBS volume size in GiB	`250`
`agentMinInstances`	number, 0 or more	Minimum instances. `0` scales to zero.	`0`
`agentMaxInstances`	number, 1 or more	Maximum instances	`2`
`agentsPerInstance`	number, 1 or more	Buildkite agents per instance	`1`
`spotCapacityPercentage`	number, 0 to 100	Percentage of capacity on spot	`0`

agentMinInstances must be less than or equal to agentMaxInstances. The pair is validated together, so an inverted range is rejected at synth.

Instance lifecycle

Property	Type	Description	Default
`scaleInIdlePeriodSeconds`	number, 60 or more	Idle seconds before an agent self-terminates	`600`
`disconnectAfterUptimeSeconds`	number, 3600 or more	Uptime after which an agent disconnects	`86400`
`maxInstanceLifetimeDays`	number, 1 to 365	Auto Scaling group instance replacement age	`7`
`terminateInstanceAfterJob`	boolean	Terminate the instance once a job completes	`false`
`purgeBuildsOnDiskFull`	boolean	Purge build directories as a last resort on a full disk	`true`
`terminateInstanceOnDiskFull`	boolean	Terminate rather than fail the job on a full disk	`false`

Instances leave the group by self-termination or by lifetime replacement. The scaler runs with scale-in disabled, so it never reduces desired capacity.

Agent behaviour

Property	Type	Description	Default
`buildkiteAgentRelease`	`stable`, `beta`, `edge`	Agent release channel	`"stable"`
`buildkiteAgentTags`	string	Agent metadata tags	`""`
`buildkiteAgentTimestampLines`	boolean	Prefix log lines with timestamps	`false`
`buildkiteAgentExperiments`	string	Comma-separated experimental features	`""`
`buildkiteAgentTracingBackend`	`""`, `datadog`, `opentelemetry`	Tracing backend	`""`
`buildkiteAgentCancelGracePeriodSeconds`	number, 10 or more	Seconds before a cancelled job is killed	`60`
`buildkiteAgentEnableGitMirrors`	boolean	Git mirrors for faster clones	`false`
`bootstrapScriptUrl`	string	URL of a custom bootstrap script	`""`
`agentEnvFileUrl`	string	URL of an environment file for agents	`""`

Plugins and Docker

Property	Type	Description	Default
`enableSecretsPlugin`	boolean	S3 secrets hooks, required for the `FJALL_API_KEY` env hook	`true`
`enableEcrPlugin`	boolean	ECR plugin for Docker images	`false`
`enableDockerLoginPlugin`	boolean	Docker Hub login plugin	`false`
`enableDockerUserNamespaceRemap`	boolean	User-namespace remapping	`true`
`enableDockerExperimental`	boolean	Docker experimental features	`false`
`dockerNetworkingProtocol`	`ipv4`, `dualstack`	Docker networking protocol	`"ipv4"`

The ECR and Docker login plugins default off because the instance profile confers no registry credentials. Turn them on only when the fleet’s jobs genuinely need instance-level registry access.

Storage and logs

Property	Type	Description	Default
`enableInstanceStorage`	boolean	Use instance storage rather than the EBS root volume	`false`
`mountTmpfsAtTmp`	boolean	Mount tmpfs at `/tmp` for faster builds	`true`
`logRetentionDays`	number, 1 or more	CloudWatch retention for the scaler Lambda’s log group	`30`
`agentLogRetentionDays`	allowed CloudWatch value	Retention for the agent’s `/buildkite/*` runtime log groups	`7`

agentLogRetentionDays accepts one of 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, 3653. Retention is always applied, so pick a longer value rather than looking for a disable switch.

Scaler

Property	Type	Description	Default
`scalerEventSchedulePeriod`	string	How often the scaler evaluates the queue	`"1 minute"`
`scalerMinPollInterval`	string	Minimum interval between polls	`"10s"`
`scaleOutFactor`	string	Scale-out multiplier, `"1.0"` is linear	`"1.0"`
`scaleOutWaitingForJobs`	boolean	Scale out for jobs in the waiting state	`false`

Alarms and governance

Property	Type	Description	Default
`alarmSnsTopicArn`	string	SNS topic receiving the fleet’s two alarms	the shared alarm topic
`rolePermissionsBoundaryArn`	string	IAM permissions boundary for the scaler’s roles	none
`costAllocationEnvironment`	string	Cost-allocation environment tag	the application’s environment
`costAllocationOwner`	string	Cost-allocation owner tag	none

rolePermissionsBoundaryArn is this stack’s own knob: it applies a boundary you nominate to the roles the agent fleet creates, and it is off unless you set it. It is unrelated to the deploy-role permissions boundary, which Fjall installs and attaches to FjallDeploy<orgId> by default and which you do not configure here.

Cost controls

The fleet has no fixed monthly floor. Four properties drive the bill:

agentMinInstances at 0 means an idle queue runs no instances.
agentMaxInstances caps concurrent capacity, and defaults to 2.
spotCapacityPercentage trades reliability for price. Keep it at 0 for deploy fleets.
logRetentionDays and agentLogRetentionDays bound CloudWatch storage.

The buckets, the scaler Lambda and the log groups are the only always-on costs.

Customisation

A second fleet for a different queue

Each fleet serves one queue. Add a second statement with its own name and queue:

fjall add buildkite --app api --name ArmBuilders \
  --buildkiteQueue arm-builders \
  --buildkiteOrgSlug acme-eng \
  --agentMaxInstances 8 \
  --spotCapacityPercentage 100

An explicit token path

Point the fleet at a parameter outside the derived namespace, for example a token shared by several applications:

app.addBuildkite(
  BuildkiteFactory.build("Buildkite", {
    buildkiteQueue: "api-deploy",
    buildkiteOrgSlug: "acme-eng",
    agentTokenSsmParameterName: "/platform/agents/agent-token",
    agentTokenKmsKeyArn:
      "arn:aws:kms:us-east-1:123456789012:key/1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  }),
);

Container workflows

Turn on the registry plugins when jobs pull private images from the account’s own ECR:

fjall modify buildkite --app api --name Buildkite \
  --enableEcrPlugin true \
  --enableDockerLoginPlugin true

Property flags carry no value-less booleans, so pass true or false explicitly.

Monitoring

The fleet ships two CloudWatch alarms on five-minute periods:

Alarm	Fires when
Scaler heartbeat	The scaler stops publishing metrics, so jobs queue with no scale-out
Queued with zero capacity	Jobs are scheduled while the Auto Scaling group has no in-service instances

Both are wired to the shared alarm topic unless alarmSnsTopicArn overrides it. Without a topic they still appear in the console, silently. Agent runtime logs land in /buildkite/* log groups in the fleet’s region. Scaling activity and instance health are visible under EC2 Auto Scaling Groups.

Managing an existing fleet

Task	Command
List the fleet’s statement	`fjall list buildkite --app api`
Change a property	`fjall modify buildkite --app api --name Buildkite --<key> <value>`
Remove the fleet	`fjall remove buildkite --app api --name Buildkite`
Apply the change	`fjall deploy api --target production-use1`

A statement written in the older app.addBuildkite({ … }) form is listed as (unmanaged). Re-add it through fjall add buildkite to bring it onto the managed path.

Next Steps

fjall add

Add resources through the codemod engine

fjall secrets

Store the agent token and API key in SSM

fjall ci

Scaffold pipelines and mint deploy tokens

CI/CD Integration

Deploy from Buildkite with scoped tokens

Factory Patterns

Application Patterns

Architecture Patterns

Buildkite Agent Fleet

Overview

What it provisions

Prerequisites

Store the agent token

Quick start

Configuration

Required

Secrets and identity

Capacity

Instance lifecycle

Agent behaviour

Plugins and Docker

Storage and logs

Scaler

Alarms and governance

Cost controls

Customisation

A second fleet for a different queue

An explicit token path

Container workflows

Monitoring

Managing an existing fleet

Next Steps

fjall add

fjall secrets

fjall ci

CI/CD Integration

​Overview

​What it provisions

​Prerequisites

​Store the agent token

​Quick start

​Configuration

​Required

​Secrets and identity

​Capacity

​Instance lifecycle

​Agent behaviour

​Plugins and Docker

​Storage and logs

​Scaler

​Alarms and governance

​Cost controls

​Customisation

​A second fleet for a different queue

​An explicit token path

​Container workflows

​Monitoring

​Managing an existing fleet

​Next Steps

fjall add

fjall secrets

fjall ci

CI/CD Integration

Overview

What it provisions

Prerequisites

Store the agent token

Quick start

Configuration

Required

Secrets and identity

Capacity

Instance lifecycle

Agent behaviour

Plugins and Docker

Storage and logs

Scaler

Alarms and governance

Cost controls

Customisation

A second fleet for a different queue

An explicit token path

Container workflows

Monitoring

Managing an existing fleet

Next Steps