@fjall/components-infrastructure 2.34.0 → 3.1.0

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

@@ -0,0 +1,233 @@
+import { CfnOutput, Duration, Stack, Token } from "aws-cdk-lib";
+import { InstanceArchitecture, InstanceType, MachineImage, SubnetType } from "aws-cdk-lib/aws-ec2";
+import { PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { Source } from "aws-cdk-lib/aws-s3-deployment";
+import { Construct } from "constructs";
+import { safeEbs } from "../../../resources/aws/compute/blockDeviceVolume.js";
+import { Ec2Instance } from "../../../resources/aws/compute/ec2.js";
+import { SamApplication } from "../../../resources/aws/compute/samApplication.js";
+import { Policy } from "../../../resources/aws/iam/index.js";
+import { BucketDeployment, S3Bucket } from "../../../resources/aws/storage/index.js";
+import { applyCostAllocationTags } from "../../../utils/costAllocationTags.js";
+import { addBuildkiteAlarms } from "./alarms.js";
+import { buildAgentRole } from "./iam.js";
+import { BUILDKITE_STACK_PINS, resolvePinnedAmiId, resolveScalerSarApplicationArn } from "./pins.js";
+import { validateBuildkiteProps } from "./schema.js";
+import { buildBuildkiteUserData } from "./userData.js";
+/**
+ * Self-hosted Buildkite agent fleet on the pinned Elastic CI Stack AMIs —
+ * scale-to-zero ASG + buildkite-agent-scaler, no secret ever transiting
+ * synth, allowlist-only instance IAM. Design:
+ * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`.
+ *
+ * A Construct, not a Stack: instantiate via `App.addBuildkite(props)`, which
+ * scopes it under the default compute stack so deploy-core's fixed
+ * six-category stack selection actually deploys it (the DevSubstrate
+ * placement precedent). Network posture is public-subnet + public-IP +
+ * zero-ingress (design § D5): `associatePublicIpAddress` MUST be explicit —
+ * the wrapper's `!!keyPair` default silently produced no-egress agents in
+ * public subnets pre-refactor.
+ */
+export class Buildkite extends Construct {
+    artifactBucketName;
+    secretsBucketName;
+    autoScalingGroupName;
+    constructor(scope, id, props) {
+        super(scope, id);
+        const { vpc, ...plainProps } = props;
+        const config = validateBuildkiteProps(plainProps);
+        const stack = Stack.of(this);
+        if (Token.isUnresolved(stack.region)) {
+            throw new Error("Buildkite requires a concrete env region at synth (the pinned AMI " +
+                "is region-specific). Pass env: { account, region } to the App.");
+        }
+        const region = stack.region;
+        const architecture = deriveCpuArchitecture(config.instanceType);
+        const amiId = resolvePinnedAmiId(region, architecture);
+        applyCostAllocationTags(this, {
+            service: "buildkite",
+            domain: "platform",
+            ...(config.costAllocationEnvironment !== undefined && {
+                environment: config.costAllocationEnvironment
+            }),
+            ...(config.costAllocationOwner !== undefined && {
+                owner: config.costAllocationOwner
+            })
+        });
+        const artifactBucket = new S3Bucket(this, `${id}ArtifactBucket`);
+        const managedSecretsBucket = new S3Bucket(this, `${id}ManagedSecretsBucket`);
+        if (config.fjallApiKeySsmParameterName !== undefined) {
+            this.addFjallApiKeyEnvHook(id, managedSecretsBucket, config.fjallApiKeySsmParameterName, region);
+        }
+        const parameterArn = (name) => `arn:${stack.partition}:ssm:${region}:${stack.account}:parameter${name}`;
+        const agentRole = buildAgentRole(this, `${id}AgentRole`, {
+            agentTokenParameterArn: parameterArn(config.agentTokenSsmParameterName),
+            ...(config.agentTokenKmsKeyArn !== undefined && {
+                agentTokenKmsKeyArn: config.agentTokenKmsKeyArn
+            }),
+            ...(config.fjallApiKeySsmParameterName !== undefined && {
+                fjallApiKeyParameterArn: parameterArn(config.fjallApiKeySsmParameterName)
+            }),
+            secretsBucketArn: managedSecretsBucket.bucketArn,
+            artifactBucketArn: artifactBucket.bucketArn,
+            stackArn: stack.stackId,
+            logGroupArnPattern: `arn:${stack.partition}:logs:${region}:${stack.account}:log-group:/buildkite/*`
+        });
+        const userData = buildBuildkiteUserData(config, {
+            stackName: stack.stackName,
+            region,
+            secretsBucketName: managedSecretsBucket.bucketName,
+            artifactBucketName: artifactBucket.bucketName
+        });
+        // Deliberate deviation from upstream's InstanceScaleInProtection
+        // (design § D7): the wrapper's `newInstancesProtectedFromScaleIn: false`
+        // invariant wins (scale-in-protected instances wedge CFN rollback). Safe
+        // because the scaler runs with `DisableScaleIn: "true"` (pinned below) so
+        // it never reduces DesiredCapacity — instances leave only by
+        // self-termination (scale-in idle / disconnect-after-uptime) or the ASG
+        // `maxInstanceLifetime` replacement.
+        //
+        // `ssmSessionPermissions: false`: the wrapper default attaches
+        // `AmazonSSMManagedInstanceCore`, whose account-wide `ssm:GetParameter`
+        // would let any build job read every SSM parameter in the account —
+        // breaking § D9's allowlist-only posture. The agent role's scoped
+        // `sessionManager` inline policy carries the Session Manager actions.
+        const ec2Instance = new Ec2Instance(this, `${id}Agent`, {
+            serviceName: `${id}Agent`,
+            vpc,
+            vpcSubnets: { subnetType: SubnetType.PUBLIC },
+            associatePublicIpAddress: true,
+            instanceType: config.instanceType,
+            machineImage: MachineImage.genericLinux({ [region]: amiId }),
+            userData,
+            role: agentRole,
+            ssmSessionPermissions: false,
+            blockDevices: [
+                {
+                    deviceName: "/dev/xvda",
+                    volume: safeEbs(config.agentVolumeSizeGib)
+                }
+            ],
+            minCapacity: config.agentMinInstances,
+            maxCapacity: config.agentMaxInstances,
+            spotCapacityPercentage: config.spotCapacityPercentage,
+            maxInstanceLifetime: Duration.days(config.maxInstanceLifetimeDays),
+            tags: {
+                Role: "buildkite-agent",
+                BuildkiteQueue: config.buildkiteQueue,
+                BuildkiteAgentRelease: config.buildkiteAgentRelease,
+                AgentsPerInstance: `${config.agentsPerInstance}`
+            }
+        });
+        const autoScalingGroup = ec2Instance.getAutoScalingGroup();
+        agentRole.attachInlinePolicy(new Policy(this, `${id}AgentScaleInPolicy`, {
+            statements: [
+                new PolicyStatement({
+                    actions: [
+                        "autoscaling:SetInstanceHealth",
+                        "autoscaling:TerminateInstanceInAutoScalingGroup"
+                    ],
+                    resources: [autoScalingGroup.autoScalingGroupArn]
+                })
+            ]
+        }));
+        new SamApplication(this, `${id}AgentScaler`, {
+            applicationId: resolveScalerSarApplicationArn(architecture),
+            semanticVersion: BUILDKITE_STACK_PINS.scalerVersion,
+            parameters: {
+                BuildkiteAgentTokenParameter: config.agentTokenSsmParameterName,
+                ...(config.agentTokenKmsKeyArn !== undefined && {
+                    BuildkiteAgentTokenParameterStoreKMSKey: config.agentTokenKmsKeyArn
+                }),
+                ...(config.rolePermissionsBoundaryArn !== undefined && {
+                    RolePermissionsBoundaryARN: config.rolePermissionsBoundaryArn
+                }),
+                BuildkiteQueue: config.buildkiteQueue,
+                AgentsPerInstance: `${config.agentsPerInstance}`,
+                MinSize: `${config.agentMinInstances}`,
+                MaxSize: `${config.agentMaxInstances}`,
+                AgentAutoScaleGroup: autoScalingGroup.autoScalingGroupName,
+                ScaleOutFactor: config.scaleOutFactor,
+                ScaleOutForWaitingJobs: `${config.scaleOutWaitingForJobs}`,
+                EventSchedulePeriod: config.scalerEventSchedulePeriod,
+                MinPollInterval: config.scalerMinPollInterval,
+                LogRetentionDays: `${config.logRetentionDays}`,
+                // Pinned, not defaulted: the D7 scale-in posture above is only sound
+                // while the scaler never reduces DesiredCapacity. A scaler-side
+                // default flip must not change our termination semantics silently.
+                DisableScaleIn: "true"
+            },
+            costAllocationService: "buildkite",
+            costAllocationDomain: "buildkite-agent-scaler",
+            ...(config.costAllocationEnvironment !== undefined && {
+                costAllocationEnvironment: config.costAllocationEnvironment
+            })
+        });
+        addBuildkiteAlarms(this, {
+            buildkiteOrgSlug: config.buildkiteOrgSlug,
+            buildkiteQueue: config.buildkiteQueue,
+            autoScalingGroupName: autoScalingGroup.autoScalingGroupName,
+            ...(config.alarmSnsTopicArn !== undefined && {
+                alarmSnsTopicArn: config.alarmSnsTopicArn
+            })
+        });
+        this.artifactBucketName = artifactBucket.bucketName;
+        this.secretsBucketName = managedSecretsBucket.bucketName;
+        this.autoScalingGroupName = autoScalingGroup.autoScalingGroupName;
+        new CfnOutput(this, "BuildkiteQueueName", {
+            value: config.buildkiteQueue
+        });
+        new CfnOutput(this, "BuildkiteAgentAsgName", {
+            value: autoScalingGroup.autoScalingGroupName
+        });
+        new CfnOutput(this, "BuildkiteSecretsBucketName", {
+            value: managedSecretsBucket.bucketName
+        });
+        new CfnOutput(this, "BuildkiteArtifactBucketName", {
+            value: artifactBucket.bucketName
+        });
+    }
+    /**
+     * Ship the per-job `env` hook into the managed secrets bucket. The
+     * s3-secrets-hooks plugin sources this file at the start of EVERY job, so
+     * FJALL_API_KEY is read fresh from SSM per job — rotation takes effect on
+     * the next job with no instance replacement (design § D4(iii)). The script
+     * is configuration, not a secret: shipping it through a CDK asset is fine;
+     * the secret VALUE only ever moves SSM → instance at job runtime.
+     */
+    addFjallApiKeyEnvHook(id, secretsBucket, parameterName, region) {
+        new BucketDeployment(this, `${id}EnvHookDeployment`, {
+            sources: [
+                Source.data(FJALL_ENV_HOOK_OBJECT_KEY, buildFjallApiKeyEnvHookScript(parameterName, region))
+            ],
+            destinationBucket: secretsBucket,
+            // The secrets bucket also holds out-of-band objects the deployment
+            // does not know about (the git deploy key, design § D4(ii)). The CDK
+            // default `prune: true` DELETES every bucket object missing from
+            // `sources` on each custom-resource execution — wiping those secrets.
+            prune: false,
+            retainOnDelete: true
+        });
+    }
+}
+/**
+ * Object key the s3-secrets-hooks plugin sources at the start of every job —
+ * upstream contract: `env` at the secrets-bucket root.
+ */
+export const FJALL_ENV_HOOK_OBJECT_KEY = "env";
+/**
+ * The per-job env hook's script content (design § D4(iii)): FJALL_API_KEY is
+ * read fresh from SSM per job, so rotation takes effect on the next job with
+ * no instance replacement. Pure — the unit test pins the exact content.
+ */
+export function buildFjallApiKeyEnvHookScript(parameterName, region) {
+    return [
+        `FJALL_API_KEY="$(aws ssm get-parameter --name '${parameterName}' --with-decryption --query Parameter.Value --output text --region '${region}')"`,
+        "export FJALL_API_KEY",
+        ""
+    ].join("\n");
+}
+function deriveCpuArchitecture(instanceTypeIdentifier) {
+    const architecture = new InstanceType(instanceTypeIdentifier).architecture;
+    return architecture === InstanceArchitecture.ARM_64 ? "arm64" : "amd64";
+}

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

@@ -0,0 +1,35 @@
+import type { Construct } from "constructs";
+import { Role } from "../../../resources/aws/iam/index.js";
+/**
+ * Every IAM action the agent instance profile is permitted to carry — the
+ * no-deploy-IAM invariant (design § D9). Deploy AWS credentials are
+ * server-minted (FJALL_API_KEY → Fjall OIDC → target-account role); the
+ * instance profile confers NO deploy capability. Explicitly absent: any
+ * `ecr:*` write, `sts:AssumeRole`, any CloudFormation mutation.
+ *
+ * The allowlist synth test asserts the synthesised role's actions are a
+ * subset of this list, so an upstream bump (or a future edit) that grows
+ * permissions fails loudly instead of shipping silently.
+ */
+export declare const BUILDKITE_AGENT_IAM_ACTION_ALLOWLIST: readonly ["ssm:GetParameter", "kms:Decrypt", "s3:GetObject", "s3:ListBucket", "s3:GetObjectVersion", "s3:PutObject", "s3:PutObjectAcl", "s3:PutObjectVersionAcl", "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:PutRetentionPolicy", "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", "autoscaling:DescribeAutoScalingInstances", "autoscaling:SetInstanceHealth", "autoscaling:TerminateInstanceInAutoScalingGroup", "cloudwatch:PutMetricData", "cloudformation:DescribeStackResource", "ec2:DescribeTags"];
+export interface BuildkiteAgentRoleParams {
+    readonly agentTokenParameterArn: string;
+    readonly agentTokenKmsKeyArn?: string;
+    readonly fjallApiKeyParameterArn?: string;
+    readonly secretsBucketArn: string;
+    readonly artifactBucketArn: string;
+    /** Own-stack ARN — `cloudformation:DescribeStackResource` scope. */
+    readonly stackArn: string;
+    /** `arn:...:log-group:/buildkite/*` — the elastic stack's group namespace. */
+    readonly logGroupArnPattern: string;
+}
+/**
+ * Build the agent instance role. Tighter than the upstream v6.68.1 template
+ * on three axes: logs actions are scoped to the `/buildkite/*` group
+ * namespace (upstream: `*`), `cloudformation:DescribeStackResource` is
+ * scoped to the own stack (upstream: `*`), and there is no ECR/docker-login
+ * grant surface at all. The remaining `resources: ["*"]` statements are
+ * describe-only or instance-inventory actions with no resource-level
+ * support.
+ */
+export declare function buildAgentRole(scope: Construct, id: string, params: BuildkiteAgentRoleParams): Role;

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

@@ -0,0 +1,176 @@
+import { CompositePrincipal, PolicyDocument, PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
+import { Role } from "../../../resources/aws/iam/index.js";
+/**
+ * Every IAM action the agent instance profile is permitted to carry — the
+ * no-deploy-IAM invariant (design § D9). Deploy AWS credentials are
+ * server-minted (FJALL_API_KEY → Fjall OIDC → target-account role); the
+ * instance profile confers NO deploy capability. Explicitly absent: any
+ * `ecr:*` write, `sts:AssumeRole`, any CloudFormation mutation.
+ *
+ * The allowlist synth test asserts the synthesised role's actions are a
+ * subset of this list, so an upstream bump (or a future edit) that grows
+ * permissions fails loudly instead of shipping silently.
+ */
+export const BUILDKITE_AGENT_IAM_ACTION_ALLOWLIST = [
+    "ssm:GetParameter",
+    "kms:Decrypt",
+    "s3:GetObject",
+    "s3:ListBucket",
+    "s3:GetObjectVersion",
+    "s3:PutObject",
+    "s3:PutObjectAcl",
+    "s3:PutObjectVersionAcl",
+    "logs:CreateLogGroup",
+    "logs:CreateLogStream",
+    "logs:PutLogEvents",
+    "logs:DescribeLogGroups",
+    "logs:DescribeLogStreams",
+    "logs:PutRetentionPolicy",
+    "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",
+    "autoscaling:DescribeAutoScalingInstances",
+    "autoscaling:SetInstanceHealth",
+    "autoscaling:TerminateInstanceInAutoScalingGroup",
+    "cloudwatch:PutMetricData",
+    "cloudformation:DescribeStackResource",
+    "ec2:DescribeTags"
+];
+/**
+ * Build the agent instance role. Tighter than the upstream v6.68.1 template
+ * on three axes: logs actions are scoped to the `/buildkite/*` group
+ * namespace (upstream: `*`), `cloudformation:DescribeStackResource` is
+ * scoped to the own stack (upstream: `*`), and there is no ECR/docker-login
+ * grant surface at all. The remaining `resources: ["*"]` statements are
+ * describe-only or instance-inventory actions with no resource-level
+ * support.
+ */
+export function buildAgentRole(scope, id, params) {
+    return new Role(scope, id, {
+        description: "Buildkite agent instance role — allowlist-only, no deploy capability",
+        inlinePolicies: buildAgentPolicyDocuments(params),
+        assumedBy: new CompositePrincipal(new ServicePrincipal("autoscaling.amazonaws.com"), new ServicePrincipal("ec2.amazonaws.com"))
+    });
+}
+function buildAgentPolicyDocuments(params) {
+    const documents = {
+        readAgentSecrets: new PolicyDocument({
+            statements: [
+                new PolicyStatement({
+                    actions: ["ssm:GetParameter"],
+                    resources: [
+                        params.agentTokenParameterArn,
+                        ...(params.fjallApiKeyParameterArn !== undefined
+                            ? [params.fjallApiKeyParameterArn]
+                            : [])
+                    ]
+                }),
+                ...(params.agentTokenKmsKeyArn !== undefined
+                    ? [
+                        new PolicyStatement({
+                            actions: ["kms:Decrypt"],
+                            resources: [params.agentTokenKmsKeyArn]
+                        })
+                    ]
+                    : [])
+            ]
+        }),
+        readManagedSecretsBucket: new PolicyDocument({
+            statements: [
+                new PolicyStatement({
+                    actions: ["s3:GetObject", "s3:ListBucket"],
+                    resources: [params.secretsBucketArn, `${params.secretsBucketArn}/*`]
+                })
+            ]
+        }),
+        artifactBucket: new PolicyDocument({
+            statements: [
+                new PolicyStatement({
+                    // The Acl grants pair with the pinned BUILDKITE_S3_ACL env value:
+                    // S3 evaluates s3:PutObjectAcl whenever a PutObject request carries
+                    // an x-amz-acl header, so uploads fail AccessDenied without them.
+                    actions: [
+                        "s3:GetObject",
+                        "s3:GetObjectVersion",
+                        "s3:ListBucket",
+                        "s3:PutObject",
+                        "s3:PutObjectAcl",
+                        "s3:PutObjectVersionAcl"
+                    ],
+                    resources: [params.artifactBucketArn, `${params.artifactBucketArn}/*`]
+                })
+            ]
+        }),
+        logging: new PolicyDocument({
+            statements: [
+                new PolicyStatement({
+                    actions: [
+                        "logs:CreateLogGroup",
+                        "logs:CreateLogStream",
+                        "logs:PutLogEvents",
+                        "logs:PutRetentionPolicy"
+                    ],
+                    resources: [
+                        params.logGroupArnPattern,
+                        `${params.logGroupArnPattern}:*`
+                    ]
+                }),
+                new PolicyStatement({
+                    actions: ["logs:DescribeLogGroups", "logs:DescribeLogStreams"],
+                    resources: ["*"]
+                })
+            ]
+        }),
+        describeInstance: new PolicyDocument({
+            statements: [
+                new PolicyStatement({
+                    actions: [
+                        "autoscaling:DescribeAutoScalingInstances",
+                        "cloudwatch:PutMetricData",
+                        "ec2:DescribeTags"
+                    ],
+                    resources: ["*"]
+                }),
+                new PolicyStatement({
+                    actions: ["cloudformation:DescribeStackResource"],
+                    resources: [params.stackArn]
+                })
+            ]
+        }),
+        sessionManager: 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: ["*"]
+                })
+            ]
+        })
+    };
+    return documents;
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Buildkite Elastic CI Stack version pins — the single moving-together
+ * contract for everything the `Buildkite` pattern derives from an upstream
+ * release. AMI ids, the elastic-stack version, the scaler version and the
+ * secrets-plugin floor MUST only change together, regenerated from the
+ * upstream template for the new version (runbook:
+ * `aiDocs/runbooks/buildkite-stack-bump-runbook.md`).
+ *
+ * AMI ids come from the `Mappings.AWSRegion2AMI` block of
+ * `https://s3.amazonaws.com/buildkite-aws-stack/<version>/aws-stack.yml` and
+ * are owner-verified against `ec2 describe-images` (owner MUST be
+ * `BUILDKITE_AMI_OWNER_ACCOUNT_ID`) before landing here. The vendored copy of
+ * the template lives at
+ * `lib/__tests__/fixtures/buildkite/upstream-aws-stack-<version>.yml` and
+ * backs the user-data parity test.
+ *
+ * Explicit ids rather than `MachineImage.lookup` — a name-pattern lookup
+ * floats the AMI underneath a pinned stack version, needs lookup credentials
+ * at synth time (unavailable in worker synth), and makes synth
+ * non-deterministic. Design:
+ * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md` § D2.
+ */
+export declare const BUILDKITE_AMI_OWNER_ACCOUNT_ID = "172840064832";
+export declare const BUILDKITE_CPU_ARCHITECTURES: readonly ["arm64", "amd64"];
+export type BuildkiteCpuArchitecture = (typeof BUILDKITE_CPU_ARCHITECTURES)[number];
+export declare const BUILDKITE_STACK_PINS: {
+    /** Upstream elastic-stack release the AMIs and user-data contract match. */
+    readonly elasticStackVersion: "v6.68.1";
+    /** buildkite-agent-scaler SAR semantic version. */
+    readonly scalerVersion: "1.12.0";
+    /**
+     * Minimum s3-secrets-hooks plugin version baked into the pinned AMIs.
+     * Versions bundled with elastic stack v6.41.0–6.41.3 leak secrets to the
+     * build log (GHSA fixed in 2.7.0); any bump below this floor must be
+     * rejected at review. v6.68.1 bundles >= 2.7.0.
+     */
+    readonly secretsPluginFloor: "2.7.0";
+    /**
+     * buildkite-agent-scaler SAR application ARNs per architecture, from the
+     * upstream template's `Mappings` block. The SAR publisher account is
+     * us-east-1-global; the ARN region does not constrain deploy region.
+     */
+    readonly scalerSarApplicationArns: {
+        readonly amd64: "arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler";
+        readonly arm64: "arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler-arm64";
+    };
+    /**
+     * Pinned AMI ids per region per architecture. Single-region today
+     * (us-east-1 — the fleet's home); add regions by regenerating from the
+     * upstream template, never by hand-picking an AMI. Owner-verified
+     * 2026-07-18: both ids owned by 172840064832, arm64 image
+     * `buildkite-stack-linux-arm64-2026-07-07T09-03-25Z`.
+     */
+    readonly amiIdsByRegion: {
+        readonly "us-east-1": {
+            readonly arm64: "ami-0ca21e2db030163c8";
+            readonly amd64: "ami-0a28a471ffade73ed";
+        };
+    };
+};
+export type BuildkiteSupportedRegion = keyof typeof BUILDKITE_STACK_PINS.amiIdsByRegion;
+/**
+ * Resolve the pinned AMI id for a concrete region + architecture. Throws a
+ * synth-time error with the remediation path when the region is not pinned —
+ * adding a region is a pins regeneration, not a call-site workaround.
+ */
+export declare function resolvePinnedAmiId(region: string, architecture: BuildkiteCpuArchitecture): string;
+/** Resolve the architecture-matched buildkite-agent-scaler SAR ARN. */
+export declare function resolveScalerSarApplicationArn(architecture: BuildkiteCpuArchitecture): string;

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

@@ -0,0 +1,80 @@
+/**
+ * Buildkite Elastic CI Stack version pins — the single moving-together
+ * contract for everything the `Buildkite` pattern derives from an upstream
+ * release. AMI ids, the elastic-stack version, the scaler version and the
+ * secrets-plugin floor MUST only change together, regenerated from the
+ * upstream template for the new version (runbook:
+ * `aiDocs/runbooks/buildkite-stack-bump-runbook.md`).
+ *
+ * AMI ids come from the `Mappings.AWSRegion2AMI` block of
+ * `https://s3.amazonaws.com/buildkite-aws-stack/<version>/aws-stack.yml` and
+ * are owner-verified against `ec2 describe-images` (owner MUST be
+ * `BUILDKITE_AMI_OWNER_ACCOUNT_ID`) before landing here. The vendored copy of
+ * the template lives at
+ * `lib/__tests__/fixtures/buildkite/upstream-aws-stack-<version>.yml` and
+ * backs the user-data parity test.
+ *
+ * Explicit ids rather than `MachineImage.lookup` — a name-pattern lookup
+ * floats the AMI underneath a pinned stack version, needs lookup credentials
+ * at synth time (unavailable in worker synth), and makes synth
+ * non-deterministic. Design:
+ * `aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md` § D2.
+ */
+export const BUILDKITE_AMI_OWNER_ACCOUNT_ID = "172840064832";
+export const BUILDKITE_CPU_ARCHITECTURES = ["arm64", "amd64"];
+export const BUILDKITE_STACK_PINS = {
+    /** Upstream elastic-stack release the AMIs and user-data contract match. */
+    elasticStackVersion: "v6.68.1",
+    /** buildkite-agent-scaler SAR semantic version. */
+    scalerVersion: "1.12.0",
+    /**
+     * Minimum s3-secrets-hooks plugin version baked into the pinned AMIs.
+     * Versions bundled with elastic stack v6.41.0–6.41.3 leak secrets to the
+     * build log (GHSA fixed in 2.7.0); any bump below this floor must be
+     * rejected at review. v6.68.1 bundles >= 2.7.0.
+     */
+    secretsPluginFloor: "2.7.0",
+    /**
+     * buildkite-agent-scaler SAR application ARNs per architecture, from the
+     * upstream template's `Mappings` block. The SAR publisher account is
+     * us-east-1-global; the ARN region does not constrain deploy region.
+     */
+    scalerSarApplicationArns: {
+        amd64: "arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler",
+        arm64: "arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler-arm64"
+    },
+    /**
+     * Pinned AMI ids per region per architecture. Single-region today
+     * (us-east-1 — the fleet's home); add regions by regenerating from the
+     * upstream template, never by hand-picking an AMI. Owner-verified
+     * 2026-07-18: both ids owned by 172840064832, arm64 image
+     * `buildkite-stack-linux-arm64-2026-07-07T09-03-25Z`.
+     */
+    amiIdsByRegion: {
+        "us-east-1": {
+            arm64: "ami-0ca21e2db030163c8",
+            amd64: "ami-0a28a471ffade73ed"
+        }
+    }
+};
+function isSupportedRegion(region) {
+    return region in BUILDKITE_STACK_PINS.amiIdsByRegion;
+}
+/**
+ * Resolve the pinned AMI id for a concrete region + architecture. Throws a
+ * synth-time error with the remediation path when the region is not pinned —
+ * adding a region is a pins regeneration, not a call-site workaround.
+ */
+export function resolvePinnedAmiId(region, architecture) {
+    if (!isSupportedRegion(region)) {
+        throw new Error(`Buildkite: no pinned AMI for region '${region}'. Supported: ` +
+            `${Object.keys(BUILDKITE_STACK_PINS.amiIdsByRegion).join(", ")}. ` +
+            `Add the region to BUILDKITE_STACK_PINS via the bump runbook ` +
+            `(aiDocs/runbooks/buildkite-stack-bump-runbook.md).`);
+    }
+    return BUILDKITE_STACK_PINS.amiIdsByRegion[region][architecture];
+}
+/** Resolve the architecture-matched buildkite-agent-scaler SAR ARN. */
+export function resolveScalerSarApplicationArn(architecture) {
+    return BUILDKITE_STACK_PINS.scalerSarApplicationArns[architecture];
+}