@fjall/components-infrastructure 3.0.0 → 3.2.1

package/dist/lib/patterns/aws/buildkite/userData.js

@@ -0,0 +1,226 @@
+import { MultipartBody, MultipartUserData, UserData } from "aws-cdk-lib/aws-ec2";
+import { BUILDKITE_STACK_PINS } from "./pins.js";
+/**
+ * The pinned AMI's boot scripts run under `set -Eeuo pipefail` and
+ * dereference every variable the upstream template passes — an OMITTED key
+ * is not "use the default", it is an unbound-variable crash at boot and an
+ * ASG boot-loop. Each part therefore mirrors the upstream v6.68.1 user data
+ * env block EXACTLY (same keys, upstream parameter defaults where we expose
+ * no knob), and the parity test asserts set equality per part against the
+ * vendored template in both directions: a key we emit that upstream does not
+ * pass is silently ignored; a key upstream passes that we omit is the
+ * boot-loop. Bumping the pins regenerates the fixture
+ * (runbook: `aiDocs/runbooks/buildkite-stack-bump-runbook.md`).
+ */
+export const BUILDKITE_MOUNT_PART_ENV_KEYS = [
+    "BUILDKITE_ENABLE_INSTANCE_STORAGE",
+    "BUILDKITE_MOUNT_TMPFS_AT_TMP"
+];
+/**
+ * Docker-GC values upstream derives from a single CloudFormation parameter
+ * feeding BOTH the docker part and the install part — the two emissions must
+ * carry the same value or boot-time docker GC and the per-job disk-cleanup
+ * hooks silently disagree (coupled values, shared source at 2 occurrences).
+ */
+const DOCKER_PRUNE_UNTIL = "4h";
+const ENABLE_PRE_EXIT_DISK_CLEANUP = "false";
+const DOCKER_BUILDER_PRUNE_ENABLED = "false";
+export const BUILDKITE_DOCKER_PART_ENV_KEYS = [
+    "DOCKER_USERNS_REMAP",
+    "DOCKER_EXPERIMENTAL",
+    "DOCKER_PRUNE_UNTIL",
+    "ENABLE_PRE_EXIT_DISK_CLEANUP",
+    "DOCKER_BUILDER_PRUNE_ENABLED",
+    "DOCKER_NETWORKING_PROTOCOL",
+    "DOCKER_IPV4_ADDRESS_POOL_1",
+    "DOCKER_IPV4_ADDRESS_POOL_2",
+    "DOCKER_IPV6_ADDRESS_POOL",
+    "DOCKER_FIXED_CIDR_V4",
+    "DOCKER_FIXED_CIDR_V6",
+    "BUILDKITE_ENABLE_INSTANCE_STORAGE"
+];
+export const BUILDKITE_USER_DATA_ENV_KEYS = [
+    "BUILDKITE_STACK_NAME",
+    "BUILDKITE_STACK_VERSION",
+    "BUILDKITE_STACK_DEPLOYED_BY",
+    "BUILDKITE_SCALE_IN_IDLE_PERIOD",
+    "BUILDKITE_SECRETS_BUCKET",
+    "BUILDKITE_SECRETS_BUCKET_REGION",
+    "BUILDKITE_SECRETS_PLUGIN_SKIP_SSH_KEY_NOT_FOUND_WARNING",
+    "BUILDKITE_ARTIFACTS_BUCKET",
+    "BUILDKITE_S3_DEFAULT_REGION",
+    "BUILDKITE_S3_ACL",
+    "BUILDKITE_AGENT_TOKEN_PATH",
+    "BUILDKITE_AGENTS_PER_INSTANCE",
+    "BUILDKITE_AGENT_ENDPOINT",
+    "BUILDKITE_AGENT_TAGS",
+    "BUILDKITE_AGENT_TIMESTAMP_LINES",
+    "BUILDKITE_AGENT_EXPERIMENTS",
+    "BUILDKITE_AGENT_TRACING_BACKEND",
+    "BUILDKITE_AGENT_SIGNING_KEY_PATH",
+    "BUILDKITE_AGENT_SIGNING_KEY_ID",
+    "BUILDKITE_AGENT_VERIFICATION_KEY_PATH",
+    "BUILDKITE_AGENT_RELEASE",
+    "BUILDKITE_AGENT_CANCEL_GRACE_PERIOD",
+    "BUILDKITE_AGENT_SIGNAL_GRACE_PERIOD_SECONDS",
+    "BUILDKITE_AGENT_SIGNING_KMS_KEY",
+    "BUILDKITE_AGENT_JOB_VERIFICATION_NO_SIGNATURE_BEHAVIOR",
+    "BUILDKITE_QUEUE",
+    "BUILDKITE_AGENT_ENABLE_GIT_MIRRORS",
+    "BUILDKITE_ELASTIC_BOOTSTRAP_SCRIPT",
+    "BUILDKITE_ENV_FILE_URL",
+    "BUILDKITE_ENABLE_INSTANCE_STORAGE",
+    "BUILDKITE_AUTHORIZED_USERS_URL",
+    "BUILDKITE_ECR_POLICY",
+    "BUILDKITE_TERMINATE_INSTANCE_AFTER_JOB",
+    "BUILDKITE_AGENT_DISCONNECT_AFTER_UPTIME",
+    "BUILDKITE_TERMINATE_INSTANCE_ON_DISK_FULL",
+    "BUILDKITE_PURGE_BUILDS_ON_DISK_FULL",
+    "BUILDKITE_ADDITIONAL_SUDO_PERMISSIONS",
+    "AWS_DEFAULT_REGION",
+    "SECRETS_PLUGIN_ENABLED",
+    "ECR_PLUGIN_ENABLED",
+    "ECR_CREDENTIAL_HELPER_ENABLED",
+    "DOCKER_LOGIN_PLUGIN_ENABLED",
+    "DOCKER_EXPERIMENTAL",
+    "DOCKER_PRUNE_UNTIL",
+    "ENABLE_PRE_EXIT_DISK_CLEANUP",
+    "DOCKER_BUILDER_PRUNE_ENABLED",
+    "DOCKER_USERNS_REMAP",
+    "AWS_REGION",
+    "ENABLE_RESOURCE_LIMITS",
+    "RESOURCE_LIMITS_MEMORY_HIGH",
+    "RESOURCE_LIMITS_MEMORY_MAX",
+    "RESOURCE_LIMITS_MEMORY_SWAP_MAX",
+    "RESOURCE_LIMITS_CPU_WEIGHT",
+    "RESOURCE_LIMITS_CPU_QUOTA",
+    "RESOURCE_LIMITS_IO_WEIGHT",
+    "ENABLE_EC2_LOG_RETENTION_POLICY",
+    "EC2_LOG_RETENTION_DAYS"
+];
+function shellScriptPart(commands) {
+    const userData = UserData.forLinux({ shebang: "#!/bin/bash -v" });
+    userData.addCommands(...commands);
+    return MultipartBody.fromUserData(userData, "text/x-shellscript; charset='us-ascii'");
+}
+/**
+ * Build the agent instance's multipart user data against the pinned elastic
+ * stack's boot scripts (cloud-config re-run marker, storage mount, docker
+ * config, `bk-install-elastic-stack.sh`).
+ */
+export function buildBuildkiteUserData(props, context) {
+    const multipartUserData = new MultipartUserData();
+    const cloudConfigUserData = UserData.forLinux({ shebang: "#cloud-config" });
+    cloudConfigUserData.addCommands("cloud_final_modules:", "  - [scripts-user, always]");
+    multipartUserData.addPart(MultipartBody.fromUserData(cloudConfigUserData, "text/cloud-config; charset='us-ascii'"));
+    multipartUserData.addPart(shellScriptPart(buildBuildkiteMountCommands(props)));
+    multipartUserData.addPart(shellScriptPart(buildBuildkiteDockerCommands(props)));
+    multipartUserData.addPart(shellScriptPart(buildBuildkiteInstallCommands(props, context)));
+    return multipartUserData;
+}
+/** Storage-mount part — `bk-mount-instance-storage.sh` env assignments. */
+export function buildBuildkiteMountCommands(props) {
+    return [
+        `BUILDKITE_ENABLE_INSTANCE_STORAGE='${props.enableInstanceStorage}' \\`,
+        `BUILDKITE_MOUNT_TMPFS_AT_TMP='${props.mountTmpfsAtTmp}' \\`,
+        "/usr/local/bin/bk-mount-instance-storage.sh"
+    ];
+}
+/** Docker-configure part — `bk-configure-docker.sh` env assignments. */
+export function buildBuildkiteDockerCommands(props) {
+    return [
+        `DOCKER_USERNS_REMAP='${props.enableDockerUserNamespaceRemap}' \\`,
+        `DOCKER_EXPERIMENTAL='${props.enableDockerExperimental}' \\`,
+        `DOCKER_PRUNE_UNTIL='${DOCKER_PRUNE_UNTIL}' \\`,
+        `ENABLE_PRE_EXIT_DISK_CLEANUP='${ENABLE_PRE_EXIT_DISK_CLEANUP}' \\`,
+        `DOCKER_BUILDER_PRUNE_ENABLED='${DOCKER_BUILDER_PRUNE_ENABLED}' \\`,
+        `DOCKER_NETWORKING_PROTOCOL='${props.dockerNetworkingProtocol}' \\`,
+        "DOCKER_IPV4_ADDRESS_POOL_1='172.17.0.0/12' \\",
+        "DOCKER_IPV4_ADDRESS_POOL_2='192.168.0.0/16' \\",
+        "DOCKER_IPV6_ADDRESS_POOL='2001:db8:2::/104' \\",
+        "DOCKER_FIXED_CIDR_V4='' \\",
+        "DOCKER_FIXED_CIDR_V6='2001:db8:1::/64' \\",
+        `BUILDKITE_ENABLE_INSTANCE_STORAGE='${props.enableInstanceStorage}' \\`,
+        "/usr/local/bin/bk-configure-docker.sh"
+    ];
+}
+/**
+ * Install part — the env assignments handed to the pinned
+ * `bk-install-elastic-stack.sh`, mirroring the upstream block key-for-key in
+ * upstream order (so a fixture-bump diff reads line-by-line). Keys with no
+ * schema knob carry the upstream v6.68.1 parameter default verbatim, with
+ * three deliberate deviations:
+ *
+ * - `BUILDKITE_S3_ACL`: our artifact bucket is BucketOwnerEnforced (ACLs
+ *   disabled), where S3 rejects every canned ACL EXCEPT
+ *   `bucket-owner-full-control` — upstream's `private` default would fail
+ *   every artifact upload with AccessControlListNotSupported.
+ * - `BUILDKITE_ECR_POLICY`: hard-pinned `none` (design § D9 — the instance
+ *   profile confers no registry credentials).
+ * - `BUILDKITE_AGENT_SIGNING_KMS_KEY`: hard-pinned empty. Pipeline signing
+ *   is out of scope for the Phase-1 deploy fleet; a future signing knob must
+ *   land WITH the kms:Sign/Verify/GetPublicKey grants it needs (the prior
+ *   knob shipped without them — a dead toggle that broke agents when set).
+ */
+export function buildBuildkiteInstallCommands(props, context) {
+    return [
+        `BUILDKITE_STACK_NAME='${context.stackName}' \\`,
+        `BUILDKITE_STACK_VERSION='${BUILDKITE_STACK_PINS.elasticStackVersion}' \\`,
+        "BUILDKITE_STACK_DEPLOYED_BY='fjall' \\",
+        `BUILDKITE_SCALE_IN_IDLE_PERIOD='${props.scaleInIdlePeriodSeconds}' \\`,
+        `BUILDKITE_SECRETS_BUCKET='${context.secretsBucketName}' \\`,
+        `BUILDKITE_SECRETS_BUCKET_REGION='${context.region}' \\`,
+        "BUILDKITE_SECRETS_PLUGIN_SKIP_SSH_KEY_NOT_FOUND_WARNING='false' \\",
+        `BUILDKITE_ARTIFACTS_BUCKET='${context.artifactBucketName}' \\`,
+        `BUILDKITE_S3_DEFAULT_REGION='${context.region}' \\`,
+        "BUILDKITE_S3_ACL='bucket-owner-full-control' \\",
+        `BUILDKITE_AGENT_TOKEN_PATH='${props.agentTokenSsmParameterName}' \\`,
+        `BUILDKITE_AGENTS_PER_INSTANCE='${props.agentsPerInstance}' \\`,
+        "BUILDKITE_AGENT_ENDPOINT='https://agent-edge.buildkite.com/v3' \\",
+        `BUILDKITE_AGENT_TAGS='${props.buildkiteAgentTags}' \\`,
+        `BUILDKITE_AGENT_TIMESTAMP_LINES='${props.buildkiteAgentTimestampLines}' \\`,
+        `BUILDKITE_AGENT_EXPERIMENTS='${props.buildkiteAgentExperiments}' \\`,
+        `BUILDKITE_AGENT_TRACING_BACKEND='${props.buildkiteAgentTracingBackend}' \\`,
+        "BUILDKITE_AGENT_SIGNING_KEY_PATH='' \\",
+        "BUILDKITE_AGENT_SIGNING_KEY_ID='' \\",
+        "BUILDKITE_AGENT_VERIFICATION_KEY_PATH='' \\",
+        `BUILDKITE_AGENT_RELEASE='${props.buildkiteAgentRelease}' \\`,
+        `BUILDKITE_AGENT_CANCEL_GRACE_PERIOD='${props.buildkiteAgentCancelGracePeriodSeconds}' \\`,
+        "BUILDKITE_AGENT_SIGNAL_GRACE_PERIOD_SECONDS='-1' \\",
+        "BUILDKITE_AGENT_SIGNING_KMS_KEY='' \\",
+        "BUILDKITE_AGENT_JOB_VERIFICATION_NO_SIGNATURE_BEHAVIOR='block' \\",
+        `BUILDKITE_QUEUE='${props.buildkiteQueue}' \\`,
+        `BUILDKITE_AGENT_ENABLE_GIT_MIRRORS='${props.buildkiteAgentEnableGitMirrors}' \\`,
+        `BUILDKITE_ELASTIC_BOOTSTRAP_SCRIPT='${props.bootstrapScriptUrl}' \\`,
+        `BUILDKITE_ENV_FILE_URL='${props.agentEnvFileUrl}' \\`,
+        `BUILDKITE_ENABLE_INSTANCE_STORAGE='${props.enableInstanceStorage}' \\`,
+        "BUILDKITE_AUTHORIZED_USERS_URL='' \\",
+        "BUILDKITE_ECR_POLICY='none' \\",
+        `BUILDKITE_TERMINATE_INSTANCE_AFTER_JOB='${props.terminateInstanceAfterJob}' \\`,
+        `BUILDKITE_AGENT_DISCONNECT_AFTER_UPTIME='${props.disconnectAfterUptimeSeconds}' \\`,
+        `BUILDKITE_TERMINATE_INSTANCE_ON_DISK_FULL='${props.terminateInstanceOnDiskFull}' \\`,
+        `BUILDKITE_PURGE_BUILDS_ON_DISK_FULL='${props.purgeBuildsOnDiskFull}' \\`,
+        "BUILDKITE_ADDITIONAL_SUDO_PERMISSIONS='' \\",
+        `AWS_DEFAULT_REGION='${context.region}' \\`,
+        `SECRETS_PLUGIN_ENABLED='${props.enableSecretsPlugin}' \\`,
+        `ECR_PLUGIN_ENABLED='${props.enableEcrPlugin}' \\`,
+        "ECR_CREDENTIAL_HELPER_ENABLED='false' \\",
+        `DOCKER_LOGIN_PLUGIN_ENABLED='${props.enableDockerLoginPlugin}' \\`,
+        `DOCKER_EXPERIMENTAL='${props.enableDockerExperimental}' \\`,
+        `DOCKER_PRUNE_UNTIL='${DOCKER_PRUNE_UNTIL}' \\`,
+        `ENABLE_PRE_EXIT_DISK_CLEANUP='${ENABLE_PRE_EXIT_DISK_CLEANUP}' \\`,
+        `DOCKER_BUILDER_PRUNE_ENABLED='${DOCKER_BUILDER_PRUNE_ENABLED}' \\`,
+        `DOCKER_USERNS_REMAP='${props.enableDockerUserNamespaceRemap}' \\`,
+        `AWS_REGION='${context.region}' \\`,
+        "ENABLE_RESOURCE_LIMITS='false' \\",
+        "RESOURCE_LIMITS_MEMORY_HIGH='90%' \\",
+        "RESOURCE_LIMITS_MEMORY_MAX='90%' \\",
+        "RESOURCE_LIMITS_MEMORY_SWAP_MAX='90%' \\",
+        "RESOURCE_LIMITS_CPU_WEIGHT='100' \\",
+        "RESOURCE_LIMITS_CPU_QUOTA='90%' \\",
+        "RESOURCE_LIMITS_IO_WEIGHT='80' \\",
+        "ENABLE_EC2_LOG_RETENTION_POLICY='false' \\",
+        "EC2_LOG_RETENTION_DAYS='7' \\",
+        "/usr/local/bin/bk-install-elastic-stack.sh"
+    ];
+}

package/dist/lib/patterns/aws/buildkite.d.ts

@@ -1,59 +1,11 @@
-import { type StackProps, Stack } from "aws-cdk-lib";
-import { InstanceType } from "aws-cdk-lib/aws-ec2";
-import { type Construct } from "constructs";
-import { type KeyValue } from "../../types.js";
-export declare enum AgentRelease {
-    STABLE = "stable",
-    BETA = "beta",
-    EDGE = "edge"
-}
-export interface BuildkiteProps extends StackProps {
-    accountId?: string;
-    elasticStackVersion: string;
-    keyName: string;
-    buildkiteAgentRelease: AgentRelease;
-    buildkiteAgentTags: string;
-    buildkiteAgentTimestampLines: boolean;
-    buildkiteAgentExperiments: string;
-    buildkiteAgentScalerVersion: string;
-    logRetentionDays: number;
-    buildkiteAgentTracingBackend: "" | "datadog" | "opentelemetry";
-    buildkiteAgentCancelGracePeriod: number;
-    buildkiteTerminateInstanceAfterJob: boolean;
-    buildkiteAdditionalSudoPermissions: string;
-    buildkiteQueue: string;
-    agentsPerInstance: number;
-    bootstrapScriptUrl: string;
-    agentEnvFileUrl: string;
-    authorizedUsersUrl: string;
-    agentInstanceType: InstanceType;
-    agentVolumeSize: number;
-    agentMinInstances: number;
-    agentMaxInstances: number;
-    scalerEventSchedulePeriod: string;
-    scalerMinPollInterval: string;
-    spotCapacityPercentage: number;
-    scaleOutFactor: string;
-    ecrAccessPolicy: string;
-    scaleInIdlePeriod: number;
-    scaleOutWaitingForJobs: boolean;
-    dockerNetworkingProtocol: "ipv4" | "dualstack";
-    enableSecretsPlugin: boolean;
-    enableEcrPlugin: boolean;
-    enableDockerLoginPlugin: boolean;
-    enableDockerUserNamespaceRemap: boolean;
-    enableDockerExperimental: boolean;
-    enableInstanceStorage: boolean;
-    mountTmpfsAtTmp: boolean;
-    buildkiteAgentEnableGitMirrors: boolean;
-    pipelineSigningKMSKey: string;
-    pipelineSigningVerificationFailureBehavior: "block" | "warn";
-    tags: KeyValue;
-    environment: string;
-    owner?: string;
-}
-export declare const BuildkiteDefaultProps: Pick<BuildkiteProps, "elasticStackVersion" | "keyName" | "buildkiteAgentRelease" | "buildkiteAgentTags" | "buildkiteAgentTimestampLines" | "buildkiteAgentExperiments" | "buildkiteAgentScalerVersion" | "logRetentionDays" | "buildkiteAgentTracingBackend" | "buildkiteAgentCancelGracePeriod" | "buildkiteTerminateInstanceAfterJob" | "buildkiteAdditionalSudoPermissions" | "buildkiteQueue" | "agentsPerInstance" | "bootstrapScriptUrl" | "agentEnvFileUrl" | "authorizedUsersUrl" | "agentInstanceType" | "agentVolumeSize" | "agentMinInstances" | "agentMaxInstances" | "scalerEventSchedulePeriod" | "scalerMinPollInterval" | "spotCapacityPercentage" | "scaleOutFactor" | "scaleInIdlePeriod" | "scaleOutWaitingForJobs" | "ecrAccessPolicy" | "dockerNetworkingProtocol" | "enableSecretsPlugin" | "enableEcrPlugin" | "enableDockerLoginPlugin" | "enableDockerUserNamespaceRemap" | "enableDockerExperimental" | "enableInstanceStorage" | "mountTmpfsAtTmp" | "buildkiteAgentEnableGitMirrors" | "pipelineSigningKMSKey" | "pipelineSigningVerificationFailureBehavior" | "environment" | "owner">;
-export declare class Buildkite extends Stack {
-    constructor(scope: Construct, id: string, props: BuildkiteProps);
-}
-export default Buildkite;
+/**
+ * Self-hosted Buildkite agent fleet — barrel for the `buildkite/` modules.
+ * The pre-2026-07 `Buildkite extends Stack` implementation is replaced by a
+ * Construct instantiated via `App.addBuildkite()`; design:
+ * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`.
+ */
+export { Buildkite, FJALL_ENV_HOOK_OBJECT_KEY, buildFjallApiKeyEnvHookScript, type BuildkiteConstructProps } from "./buildkite/buildkite.js";
+export { BUILDKITE_AMI_OWNER_ACCOUNT_ID, BUILDKITE_CPU_ARCHITECTURES, BUILDKITE_STACK_PINS, resolvePinnedAmiId, resolveScalerSarApplicationArn, type BuildkiteCpuArchitecture } from "./buildkite/pins.js";
+export { BuildkitePropsSchema, validateBuildkiteProps, type BuildkiteProps, type BuildkitePropsInput } from "./buildkite/schema.js";
+export { BUILDKITE_AGENT_IAM_ACTION_ALLOWLIST, buildAgentRole, type BuildkiteAgentRoleParams } from "./buildkite/iam.js";
+export { BUILDKITE_DOCKER_PART_ENV_KEYS, BUILDKITE_MOUNT_PART_ENV_KEYS, BUILDKITE_USER_DATA_ENV_KEYS, buildBuildkiteDockerCommands, buildBuildkiteInstallCommands, buildBuildkiteMountCommands, buildBuildkiteUserData, type BuildkiteUserDataContext } from "./buildkite/userData.js";

package/dist/lib/patterns/aws/buildkite.js

@@ -1,310 +1,11 @@
-import { Stack, Tags } from "aws-cdk-lib";
-import { CompositePrincipal, ServicePrincipal, PolicyDocument, PolicyStatement } from "aws-cdk-lib/aws-iam";
-import { FjallLogger } from "../../utils/validationLogger.js";
-import { InstanceClass, InstanceSize, InstanceType, MachineImage, MultipartBody, MultipartUserData, SubnetType, UserData } from "aws-cdk-lib/aws-ec2";
-import { safeEbs } from "../../resources/aws/compute/blockDeviceVolume.js";
-import { Source } from "aws-cdk-lib/aws-s3-deployment";
-import { Vpc } from "../../resources/aws/networking/vpc.js";
-import { Policy, Role } from "../../resources/aws/iam/index.js";
-import { BucketDeployment, S3Bucket } from "../../resources/aws/storage/index.js";
-import { SecureStringParameter } from "../../resources/aws/secrets/index.js";
-import { Ec2Instance } from "../../resources/aws/compute/ec2.js";
-import { SamApplication } from "../../resources/aws/compute/samApplication.js";
-import { applyCostAllocationTags } from "../../utils/costAllocationTags.js";
-export var AgentRelease;
-(function (AgentRelease) {
-    AgentRelease["STABLE"] = "stable";
-    AgentRelease["BETA"] = "beta";
-    AgentRelease["EDGE"] = "edge";
-})(AgentRelease || (AgentRelease = {}));
-export const BuildkiteDefaultProps = {
-    // Buildkite Agent Configuration
-    elasticStackVersion: "v6.30.0",
-    keyName: "",
-    buildkiteAgentRelease: AgentRelease.STABLE,
-    buildkiteAgentTags: "",
-    buildkiteAgentTimestampLines: false,
-    buildkiteAgentExperiments: "",
-    buildkiteAgentScalerVersion: "1.8.0",
-    logRetentionDays: 1,
-    buildkiteAgentTracingBackend: "",
-    buildkiteAgentCancelGracePeriod: 60,
-    buildkiteTerminateInstanceAfterJob: false,
-    buildkiteAdditionalSudoPermissions: "",
-    buildkiteQueue: "default",
-    agentsPerInstance: 1,
-    bootstrapScriptUrl: "",
-    agentEnvFileUrl: "",
-    authorizedUsersUrl: "",
-    // Infrastructure
-    agentInstanceType: InstanceType.of(InstanceClass.M5, InstanceSize.LARGE),
-    agentMinInstances: 0,
-    agentMaxInstances: 10,
-    agentVolumeSize: 250,
-    scalerEventSchedulePeriod: "1 minute",
-    scalerMinPollInterval: "10s",
-    spotCapacityPercentage: 75,
-    scaleOutFactor: "1.0",
-    scaleInIdlePeriod: 600,
-    scaleOutWaitingForJobs: false,
-    ecrAccessPolicy: "",
-    dockerNetworkingProtocol: "ipv4",
-    enableSecretsPlugin: true,
-    enableEcrPlugin: true,
-    enableDockerLoginPlugin: true,
-    enableDockerUserNamespaceRemap: true,
-    enableDockerExperimental: false,
-    enableInstanceStorage: false,
-    mountTmpfsAtTmp: true,
-    buildkiteAgentEnableGitMirrors: false,
-    pipelineSigningKMSKey: "",
-    pipelineSigningVerificationFailureBehavior: "block",
-    // Tags
-    environment: "platform",
-    owner: "engineer"
-};
-export class Buildkite extends Stack {
-    constructor(scope, id, props) {
-        super(scope, id, props);
-        applyCostAllocationTags(this, {
-            service: "buildkite",
-            domain: "platform",
-            environment: props.environment || "platform",
-            owner: props.owner ?? "engineer"
-        });
-        const tags = { ...props.tags };
-        // VPC
-        const vpc = new Vpc(this, `${id}Vpc`, {
-            accountId: props.accountId,
-            subnetConfiguration: [
-                {
-                    name: `${id}`,
-                    subnetType: SubnetType.PUBLIC
-                }
-            ]
-        });
-        // Artifacts Bucket
-        const artifactBucket = new S3Bucket(this, `${id}ArtifactBucket`);
-        const managedSecretsBucket = new S3Bucket(this, `${id}ManagedSecretsBucket`);
-        const buildkitePrivateSshKey = process.env.BUILDKITE_PRIVATE_SSH_KEY;
-        const hasBuildkitePrivateSshKey = buildkitePrivateSshKey !== undefined && buildkitePrivateSshKey !== "";
-        if (hasBuildkitePrivateSshKey) {
-            // Synth-time secret bake: Source.data() inlines the env var into the
-            // CDK asset bundle uploaded to the bootstrap S3 staging bucket. The
-            // synth host MUST hold the secret in env, and the CDK staging bucket
-            // inherits the secret's blast radius. Treat as Buildkite-only opt-in.
-            new BucketDeployment(this, `${id}SshKeyDeployment`, {
-                sources: [Source.data("private_ssh_key", buildkitePrivateSshKey)],
-                destinationBucket: managedSecretsBucket
-            });
-        }
-        else {
-            FjallLogger.warn("'BUILDKITE_PRIVATE_SSH_KEY' environment variable not declared. Skipping upload of private SSH key.");
-        }
-        const buildkiteAgentToken = process.env.BUILDKITE_AGENT_TOKEN;
-        const hasBuildkiteAgentToken = buildkiteAgentToken !== undefined && buildkiteAgentToken !== "";
-        const agentToken = new SecureStringParameter(this, `${id}AgentToken`, {
-            name: `/buildkite/agentToken`,
-            aliasName: `buildkiteAgentToken`,
-            value: buildkiteAgentToken,
-            overwrite: hasBuildkiteAgentToken,
-            tags: tags,
-            accountId: this.account,
-            region: this.region
-        });
-        // Buildkite Agent Execution Role
-        const agentRole = new Role(this, `${id}AgentRole`, {
-            roleName: `${id}AgentRole`,
-            description: "Buildkite Agent IAM Role",
-            inlinePolicies: {
-                ["decryptBuildkiteAgentToken"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: ["kms:Decrypt"],
-                            resources: [agentToken.cmk.key.keyArn]
-                        })
-                    ]
-                }),
-                ["readBuildkiteAgentToken"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: ["ssm:GetParameter"],
-                            resources: [
-                                `arn:${this.partition}:ssm:${this.region}:${this.account}:parameter${agentToken.name}`
-                            ]
-                        })
-                    ]
-                }),
-                ["readManagedSecretsBucket"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: ["s3:Get*", "s3:List*"],
-                            resources: [
-                                managedSecretsBucket.bucketArn,
-                                `${managedSecretsBucket.bucketArn}/*`
-                            ]
-                        })
-                    ]
-                }),
-                ["writeArtifactBucket"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: [
-                                "s3:GetObject",
-                                "s3:GetObjectAcl",
-                                "s3:GetObjectVersion",
-                                "s3:GetObjectVersionAcl",
-                                "s3:ListBucket",
-                                "s3:PutObject",
-                                "s3:PutObjectAcl",
-                                "s3:PutObjectVersionAcl"
-                            ],
-                            resources: [
-                                artifactBucket.bucketArn,
-                                `${artifactBucket.bucketArn}/*`
-                            ]
-                        })
-                    ]
-                }),
-                ["describeInstance"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: [
-                                "autoscaling:DescribeAutoScalingInstances",
-                                "cloudwatch:PutMetricData",
-                                "cloudformation:DescribeStackResource",
-                                "ec2:DescribeTags"
-                            ],
-                            resources: ["*"]
-                        })
-                    ]
-                }),
-                ["logging"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: [
-                                "logs:CreateLogGroup",
-                                "logs:CreateLogStream",
-                                "logs:PutLogEvents",
-                                "logs:DescribeLogGroups",
-                                "logs:DescribeLogStreams"
-                            ],
-                            resources: ["*"]
-                        })
-                    ]
-                }),
-                ["ssm"]: new PolicyDocument({
-                    statements: [
-                        new PolicyStatement({
-                            actions: [
-                                "ssm:DescribeInstanceProperties",
-                                "ssm:ListAssociations",
-                                "ssm:PutInventory",
-                                "ssm:UpdateInstanceInformation",
-                                "ssmmessages:CreateControlChannel",
-                                "ssmmessages:CreateDataChannel",
-                                "ssmmessages:OpenControlChannel",
-                                "ssmmessages:OpenDataChannel",
-                                "ec2messages:AcknowledgeMessage",
-                                "ec2messages:DeleteMessage",
-                                "ec2messages:FailMessage",
-                                "ec2messages:GetEndpoint",
-                                "ec2messages:GetMessages",
-                                "ec2messages:SendReply"
-                            ],
-                            resources: ["*"]
-                        })
-                    ]
-                })
-            },
-            assumedBy: new CompositePrincipal(new ServicePrincipal("autoscaling.amazonaws.com"), new ServicePrincipal("ec2.amazonaws.com"))
-        });
-        // Buildkite Agent EC2 User Data
-        const multipartUserData = new MultipartUserData();
-        // Cloud Config
-        const cloudConfigUserData = UserData.forLinux({
-            shebang: "#cloud-config"
-        });
-        cloudConfigUserData.addCommands("cloud_final_modules:", "  - [scripts-user, always]");
-        multipartUserData.addPart(MultipartBody.fromUserData(cloudConfigUserData, "text/cloud-config; charset='us-ascii'"));
-        // Mount Storage
-        const mountStorageUserData = UserData.forLinux({
-            shebang: "#!/bin/bash -v"
-        });
-        mountStorageUserData.addCommands(`BUILDKITE_ENABLE_INSTANCE_STORAGE='${props.enableInstanceStorage}' \\`, `BUILDKITE_MOUNT_TMPFS_AT_TMP='${props.mountTmpfsAtTmp}' \\`, "/usr/local/bin/bk-mount-instance-storage.sh");
-        multipartUserData.addPart(MultipartBody.fromUserData(mountStorageUserData, "text/x-shellscript; charset='us-ascii'"));
-        // Configure Docker
-        const configureDockerUserData = UserData.forLinux({
-            shebang: "#!/bin/bash -v"
-        });
-        configureDockerUserData.addCommands(`DOCKER_USERNS_REMAP='${props.enableDockerUserNamespaceRemap}' \\`, `DOCKER_EXPERIMENTAL='${props.enableDockerExperimental}' \\`, `DOCKER_NETWORKING_PROTOCOL='${props.dockerNetworkingProtocol}' \\`, `BUILDKITE_ENABLE_INSTANCE_STORAGE='${props.enableInstanceStorage}' \\`, "/usr/local/bin/bk-configure-docker.sh");
-        multipartUserData.addPart(MultipartBody.fromUserData(configureDockerUserData, "text/x-shellscript; charset='us-ascii'"));
-        const installElasticStackUserData = UserData.forLinux({
-            shebang: "#!/bin/bash -v"
-        });
-        installElasticStackUserData.addCommands(`BUILDKITE_STACK_NAME='${id}' \\`, `BUILDKITE_STACK_VERSION='${props.elasticStackVersion}' \\`, `BUILDKITE_SCALE_IN_IDLE_PERIOD='${props.scaleInIdlePeriod}' \\`, `BUILDKITE_SECRETS_BUCKET='${managedSecretsBucket.bucketName}' \\`, `BUILDKITE_SECRETS_BUCKET_REGION='${props.env?.region}' \\`, `BUILDKITE_AGENT_TOKEN_PATH='${agentToken.name}' \\`, `BUILDKITE_AGENTS_PER_INSTANCE='${props.agentsPerInstance}' \\`, `BUILDKITE_AGENT_TAGS='${props.buildkiteAgentTags}' \\`, `BUILDKITE_AGENT_TIMESTAMP_LINES='${props.buildkiteAgentTimestampLines}' \\`, `BUILDKITE_AGENT_EXPERIMENTS='${props.buildkiteAgentExperiments}' \\`, `BUILDKITE_AGENT_TRACING_BACKEND='${props.buildkiteAgentTracingBackend}' \\`, `BUILDKITE_AGENT_RELEASE='${props.buildkiteAgentRelease}' \\`, `BUILDKITE_AGENT_CANCEL_GRACE_PERIOD='${props.buildkiteAgentCancelGracePeriod}' \\`, `BUILDKITE_AGENT_SIGNING_KMS_KEY='${props.pipelineSigningKMSKey}' \\`, `BUILDKITE_AGENT_SIGNING_FAILURE_BEHAVIOR='${props.pipelineSigningVerificationFailureBehavior}' \\`, `BUILDKITE_QUEUE='${props.buildkiteQueue}' \\`, `BUILDKITE_AGENT_ENABLE_GIT_MIRRORS='${props.buildkiteAgentEnableGitMirrors}' \\`, `BUILDKITE_ELASTIC_BOOTSTRAP_SCRIPT='${props.bootstrapScriptUrl}' \\`, `BUILDKITE_ENV_FILE_URL='${props.agentEnvFileUrl}' \\`, `BUILDKITE_ENABLE_INSTANCE_STORAGE='${props.enableInstanceStorage}' \\`, `BUILDKITE_AUTHORIZED_USERS_URL='${props.authorizedUsersUrl}' \\`, `BUILDKITE_ECR_POLICY='${props.ecrAccessPolicy}' \\`, `BUILDKITE_TERMINATE_INSTANCE_AFTER_JOB='${props.buildkiteTerminateInstanceAfterJob}' \\`, `BUILDKITE_ADDITIONAL_SUDO_PERMISSIONS='${props.buildkiteAdditionalSudoPermissions}' \\`, `AWS_DEFAULT_REGION='${props.env?.region}' \\`, `SECRETS_PLUGIN_ENABLED='${props.enableSecretsPlugin}' \\`, `ECR_PLUGIN_ENABLED='${props.enableEcrPlugin}' \\`, `DOCKER_LOGIN_PLUGIN_ENABLED='${props.enableDockerLoginPlugin}' \\`, `DOCKER_EXPERIMENTAL='${props.enableDockerExperimental}' \\`, `DOCKER_USERNS_REMAP='${props.enableDockerUserNamespaceRemap}' \\`, `AWS_REGION='${props.env?.region}' \\`, "/usr/local/bin/bk-install-elastic-stack.sh");
-        // Merge User Data
-        multipartUserData.addPart(MultipartBody.fromUserData(installElasticStackUserData, "text/x-shellscript; charset='us-ascii'"));
-        const ec2Instance = new Ec2Instance(this, `${id}Agent`, {
-            serviceName: `${id}Agent`,
-            vpc,
-            vpcSubnets: { subnetType: SubnetType.PUBLIC },
-            instanceType: props.agentInstanceType.toString(),
-            machineImage: MachineImage.lookup({
-                name: "buildkite-stack-linux-x86_64-*",
-                owners: ["172840064832"],
-                filters: {
-                    ["block-device-mapping.volume-type"]: ["gp3"]
-                }
-            }),
-            userData: multipartUserData,
-            role: agentRole,
-            blockDevices: [
-                {
-                    deviceName: "/dev/xvda",
-                    volume: safeEbs(props.agentVolumeSize)
-                }
-            ],
-            minCapacity: props.agentMinInstances,
-            maxCapacity: props.agentMaxInstances,
-            spotCapacityPercentage: props.spotCapacityPercentage
-        });
-        Tags.of(ec2Instance).add("Role", "buildkiteAgent");
-        Tags.of(ec2Instance).add("BuildkiteAgentRelease", props.buildkiteAgentRelease);
-        Tags.of(ec2Instance).add("BuildkiteQueue", props.buildkiteQueue);
-        const autoScalingGroup = ec2Instance.getAutoScalingGroup();
-        agentRole.attachInlinePolicy(new Policy(this, `${id}UpdateAutoScalingGroupPolicy`, {
-            statements: [
-                new PolicyStatement({
-                    actions: [
-                        "autoscaling:SetInstanceHealth",
-                        "autoscaling:TerminateInstanceInAutoScalingGroup"
-                    ],
-                    resources: [`${autoScalingGroup.autoScalingGroupArn}`]
-                })
-            ]
-        }));
-        new SamApplication(this, `${id}AgentScaler`, {
-            applicationId: "arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler",
-            semanticVersion: props.buildkiteAgentScalerVersion,
-            parameters: {
-                BuildkiteAgentTokenParameter: `${agentToken.name}`,
-                BuildkiteAgentTokenParameterStoreKMSKey: agentToken.cmk.key.keyId,
-                RolePermissionsBoundaryARN: "",
-                BuildkiteQueue: props.buildkiteQueue,
-                AgentsPerInstance: `${props.agentsPerInstance}`,
-                MinSize: `${props.agentMinInstances}`,
-                MaxSize: `${props.agentMaxInstances}`,
-                AgentAutoScaleGroup: autoScalingGroup.autoScalingGroupName,
-                ScaleOutFactor: props.scaleOutFactor,
-                ScaleOutForWaitingJobs: `${props.scaleOutWaitingForJobs}`,
-                EventSchedulePeriod: props.scalerEventSchedulePeriod,
-                MinPollInterval: props.scalerMinPollInterval,
-                LogRetentionDays: `${props.logRetentionDays}`
-            },
-            costAllocationService: "buildkite",
-            costAllocationDomain: "buildkite-agent-scaler"
-        });
-    }
-}
-export default Buildkite;
+/**
+ * Self-hosted Buildkite agent fleet — barrel for the `buildkite/` modules.
+ * The pre-2026-07 `Buildkite extends Stack` implementation is replaced by a
+ * Construct instantiated via `App.addBuildkite()`; design:
+ * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`.
+ */
+export { Buildkite, FJALL_ENV_HOOK_OBJECT_KEY, buildFjallApiKeyEnvHookScript } from "./buildkite/buildkite.js";
+export { BUILDKITE_AMI_OWNER_ACCOUNT_ID, BUILDKITE_CPU_ARCHITECTURES, BUILDKITE_STACK_PINS, resolvePinnedAmiId, resolveScalerSarApplicationArn } from "./buildkite/pins.js";
+export { BuildkitePropsSchema, validateBuildkiteProps } from "./buildkite/schema.js";
+export { BUILDKITE_AGENT_IAM_ACTION_ALLOWLIST, buildAgentRole } from "./buildkite/iam.js";
+export { BUILDKITE_DOCKER_PART_ENV_KEYS, BUILDKITE_MOUNT_PART_ENV_KEYS, BUILDKITE_USER_DATA_ENV_KEYS, buildBuildkiteDockerCommands, buildBuildkiteInstallCommands, buildBuildkiteMountCommands, buildBuildkiteUserData } from "./buildkite/userData.js";