@fjall/components-infrastructure 2.34.0 → 3.1.0

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

@@ -0,0 +1,80 @@
+import { z } from "zod";
+/**
+ * Plain-data props for the `Buildkite` pattern, validated at construct time.
+ * Deliberately CDK-free so the same schema can later back the customer
+ * scaffold surface if the pattern is ever promoted to `PATTERN_TYPE_VALUES`
+ * (design § D3 — promotion must be additive).
+ *
+ * Defaults encode the design's deploy-fleet posture
+ * (`aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`):
+ * on-demand-only (`spotCapacityPercentage` 0 — ASG mixed-instances has no
+ * spot→on-demand fallback, and a spot reclaim mid-deploy is a rollback
+ * incident, § D7), scale-to-zero, whole-instance agents, bounded instance
+ * staleness, and no ECR / docker-login instance-level credentials (§ D9 —
+ * deploy AWS access stays server-minted; the instance profile confers none).
+ */
+export declare const BuildkitePropsSchema: z.ZodObject<{
+    buildkiteQueue: z.ZodString;
+    buildkiteOrgSlug: z.ZodString;
+    agentTokenSsmParameterName: z.ZodString;
+    agentTokenKmsKeyArn: z.ZodOptional<z.ZodString>;
+    fjallApiKeySsmParameterName: z.ZodOptional<z.ZodString>;
+    instanceType: z.ZodDefault<z.ZodString>;
+    agentVolumeSizeGib: z.ZodDefault<z.ZodNumber>;
+    agentMinInstances: z.ZodDefault<z.ZodNumber>;
+    agentMaxInstances: z.ZodDefault<z.ZodNumber>;
+    agentsPerInstance: z.ZodDefault<z.ZodNumber>;
+    spotCapacityPercentage: z.ZodDefault<z.ZodNumber>;
+    scaleInIdlePeriodSeconds: z.ZodDefault<z.ZodNumber>;
+    disconnectAfterUptimeSeconds: z.ZodDefault<z.ZodNumber>;
+    maxInstanceLifetimeDays: z.ZodDefault<z.ZodNumber>;
+    terminateInstanceAfterJob: z.ZodDefault<z.ZodBoolean>;
+    purgeBuildsOnDiskFull: z.ZodDefault<z.ZodBoolean>;
+    terminateInstanceOnDiskFull: z.ZodDefault<z.ZodBoolean>;
+    logRetentionDays: z.ZodDefault<z.ZodNumber>;
+    buildkiteAgentRelease: z.ZodDefault<z.ZodEnum<{
+        stable: "stable";
+        beta: "beta";
+        edge: "edge";
+    }>>;
+    buildkiteAgentTags: z.ZodDefault<z.ZodString>;
+    buildkiteAgentTimestampLines: z.ZodDefault<z.ZodBoolean>;
+    buildkiteAgentExperiments: z.ZodDefault<z.ZodString>;
+    buildkiteAgentTracingBackend: z.ZodDefault<z.ZodEnum<{
+        "": "";
+        datadog: "datadog";
+        opentelemetry: "opentelemetry";
+    }>>;
+    buildkiteAgentCancelGracePeriodSeconds: z.ZodDefault<z.ZodNumber>;
+    enableSecretsPlugin: z.ZodDefault<z.ZodBoolean>;
+    enableEcrPlugin: z.ZodDefault<z.ZodBoolean>;
+    enableDockerLoginPlugin: z.ZodDefault<z.ZodBoolean>;
+    enableDockerUserNamespaceRemap: z.ZodDefault<z.ZodBoolean>;
+    enableDockerExperimental: z.ZodDefault<z.ZodBoolean>;
+    dockerNetworkingProtocol: z.ZodDefault<z.ZodEnum<{
+        ipv4: "ipv4";
+        dualstack: "dualstack";
+    }>>;
+    enableInstanceStorage: z.ZodDefault<z.ZodBoolean>;
+    mountTmpfsAtTmp: z.ZodDefault<z.ZodBoolean>;
+    buildkiteAgentEnableGitMirrors: z.ZodDefault<z.ZodBoolean>;
+    bootstrapScriptUrl: z.ZodDefault<z.ZodString>;
+    agentEnvFileUrl: z.ZodDefault<z.ZodString>;
+    scalerEventSchedulePeriod: z.ZodDefault<z.ZodString>;
+    scalerMinPollInterval: z.ZodDefault<z.ZodString>;
+    scaleOutFactor: z.ZodDefault<z.ZodString>;
+    scaleOutWaitingForJobs: z.ZodDefault<z.ZodBoolean>;
+    rolePermissionsBoundaryArn: z.ZodOptional<z.ZodString>;
+    alarmSnsTopicArn: z.ZodOptional<z.ZodString>;
+    costAllocationEnvironment: z.ZodOptional<z.ZodString>;
+    costAllocationOwner: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type BuildkiteProps = z.infer<typeof BuildkitePropsSchema>;
+/** Caller-facing shape: fields with defaults are optional at the call site. */
+export type BuildkitePropsInput = z.input<typeof BuildkitePropsSchema>;
+/**
+ * Validate + default the plain-data props at construct time. Throws a
+ * synth-time error listing every violation — the pattern's constructor is the
+ * validation boundary, mirroring `ClickHouseDatabase`'s Stage-1 shape.
+ */
+export declare function validateBuildkiteProps(props: BuildkitePropsInput): BuildkiteProps;

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

@@ -0,0 +1,148 @@
+import { z } from "zod";
+/**
+ * Plain-data props for the `Buildkite` pattern, validated at construct time.
+ * Deliberately CDK-free so the same schema can later back the customer
+ * scaffold surface if the pattern is ever promoted to `PATTERN_TYPE_VALUES`
+ * (design § D3 — promotion must be additive).
+ *
+ * Defaults encode the design's deploy-fleet posture
+ * (`aiDocs/designs/2026-07-18-buildkite-selfhosted-agents.md`):
+ * on-demand-only (`spotCapacityPercentage` 0 — ASG mixed-instances has no
+ * spot→on-demand fallback, and a spot reclaim mid-deploy is a rollback
+ * incident, § D7), scale-to-zero, whole-instance agents, bounded instance
+ * staleness, and no ECR / docker-login instance-level credentials (§ D9 —
+ * deploy AWS access stays server-minted; the instance profile confers none).
+ */
+export const BuildkitePropsSchema = z
+    .object({
+    /** Buildkite queue this fleet serves (cluster-scoped via the token). */
+    buildkiteQueue: z
+        .string()
+        .min(1, "buildkiteQueue cannot be empty")
+        .max(100)
+        .regex(/^[a-zA-Z0-9-_]+$/, "buildkiteQueue must be alphanumeric with hyphens/underscores"),
+    /**
+     * Buildkite organisation slug (e.g. `fjall-tech`). The
+     * buildkite-agent-scaler publishes its CloudWatch metrics dimensioned by
+     * {Org, Queue} — the fleet's alarms must query the same pair or they read
+     * no data at all (heartbeat permanently ALARM, queued-with-zero-capacity
+     * permanently inert).
+     */
+    buildkiteOrgSlug: z
+        .string()
+        .min(1, "buildkiteOrgSlug cannot be empty")
+        .max(100)
+        .regex(/^[a-z0-9-]+$/, "buildkiteOrgSlug must be a lowercase Buildkite organisation slug"),
+    /**
+     * Name of the pre-provisioned SSM SecureString holding the cluster-scoped
+     * agent token (e.g. `/Buildkite/agents/agent-token`). Provisioned
+     * out-of-band via `fjall secrets` tooling — the construct receives the
+     * identifier only; no secret value ever transits synth (design § D4).
+     */
+    agentTokenSsmParameterName: z
+        .string()
+        .min(2)
+        .regex(/^\//, "agentTokenSsmParameterName must be a full path (leading /)"),
+    /**
+     * KMS key ARN encrypting the agent-token parameter, when a customer
+     * managed key is used. Omit for the AWS-managed `aws/ssm` key.
+     */
+    agentTokenKmsKeyArn: z.string().min(1).optional(),
+    /**
+     * Name of the SSM SecureString holding FJALL_API_KEY. When set, the
+     * construct ships a per-job `env` hook into the managed secrets bucket
+     * that reads the parameter at job start (rotation takes effect on the
+     * next job, no instance replacement — design § D4(iii)) and grants the
+     * instance profile read on exactly this parameter.
+     */
+    fjallApiKeySsmParameterName: z
+        .string()
+        .min(2)
+        .regex(/^\//, "fjallApiKeySsmParameterName must be a full path (leading /)")
+        .optional(),
+    /** EC2 instance type. Graviton default per design § D7. */
+    instanceType: z.string().min(1).default("c8g.xlarge"),
+    agentVolumeSizeGib: z.number().int().min(20).max(1000).default(250),
+    agentMinInstances: z.number().int().min(0).default(0),
+    agentMaxInstances: z.number().int().min(1).default(2),
+    agentsPerInstance: z.number().int().min(1).default(1),
+    /**
+     * Percentage of capacity on spot. Deploy fleets MUST stay 0 (on-demand
+     * only): no spot→on-demand fallback mechanism exists, and a reclaim
+     * mid-deploy lands in the rollback-wedge class (design § D7). Non-zero is
+     * for Phase-2 CI fleets running idempotent, auto-retried jobs.
+     */
+    spotCapacityPercentage: z.number().int().min(0).max(100).default(0),
+    /** Agent-driven scale-in: idle seconds before an instance self-terminates. */
+    scaleInIdlePeriodSeconds: z.number().int().min(60).default(600),
+    /** Bounded instance staleness; also caps stale-token propagation (§ D5). */
+    disconnectAfterUptimeSeconds: z.number().int().min(3600).default(86_400),
+    maxInstanceLifetimeDays: z.number().int().min(1).max(365).default(7),
+    terminateInstanceAfterJob: z.boolean().default(false),
+    purgeBuildsOnDiskFull: z.boolean().default(true),
+    terminateInstanceOnDiskFull: z.boolean().default(false),
+    /** CloudWatch retention for the scaler's log group (days). */
+    logRetentionDays: z.number().int().min(1).default(30),
+    buildkiteAgentRelease: z.enum(["stable", "beta", "edge"]).default("stable"),
+    buildkiteAgentTags: z.string().default(""),
+    buildkiteAgentTimestampLines: z.boolean().default(false),
+    buildkiteAgentExperiments: z.string().default(""),
+    buildkiteAgentTracingBackend: z
+        .enum(["", "datadog", "opentelemetry"])
+        .default(""),
+    buildkiteAgentCancelGracePeriodSeconds: z
+        .number()
+        .int()
+        .min(10)
+        .default(60),
+    /** S3 secrets-hooks plugin — required for the FJALL_API_KEY env hook. */
+    enableSecretsPlugin: z.boolean().default(true),
+    /**
+     * ECR + docker-login plugins default OFF: the instance profile carries no
+     * registry credentials (design § D9); deploy jobs authenticate through
+     * server-minted credentials exactly as on hosted agents.
+     */
+    enableEcrPlugin: z.boolean().default(false),
+    enableDockerLoginPlugin: z.boolean().default(false),
+    enableDockerUserNamespaceRemap: z.boolean().default(true),
+    enableDockerExperimental: z.boolean().default(false),
+    dockerNetworkingProtocol: z.enum(["ipv4", "dualstack"]).default("ipv4"),
+    enableInstanceStorage: z.boolean().default(false),
+    mountTmpfsAtTmp: z.boolean().default(true),
+    buildkiteAgentEnableGitMirrors: z.boolean().default(false),
+    bootstrapScriptUrl: z.string().default(""),
+    agentEnvFileUrl: z.string().default(""),
+    scalerEventSchedulePeriod: z.string().min(1).default("1 minute"),
+    scalerMinPollInterval: z.string().min(1).default("10s"),
+    scaleOutFactor: z.string().min(1).default("1.0"),
+    scaleOutWaitingForJobs: z.boolean().default(false),
+    /** IAM permissions boundary for the scaler's roles; emitted only when set. */
+    rolePermissionsBoundaryArn: z.string().min(1).optional(),
+    /**
+     * SNS topic receiving the fleet's two alarms (scaler heartbeat + queued
+     * with zero capacity — design § D14). Omit to create the alarms without
+     * actions (visible on the console, silent).
+     */
+    alarmSnsTopicArn: z.string().min(1).optional(),
+    costAllocationEnvironment: z.string().min(1).optional(),
+    costAllocationOwner: z.string().min(1).optional()
+})
+    .strict()
+    .refine((props) => props.agentMinInstances <= props.agentMaxInstances, {
+    message: "agentMinInstances must be <= agentMaxInstances"
+});
+/**
+ * Validate + default the plain-data props at construct time. Throws a
+ * synth-time error listing every violation — the pattern's constructor is the
+ * validation boundary, mirroring `ClickHouseDatabase`'s Stage-1 shape.
+ */
+export function validateBuildkiteProps(props) {
+    const result = BuildkitePropsSchema.safeParse(props);
+    if (!result.success) {
+        const details = result.error.issues
+            .map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`)
+            .join("\n");
+        throw new Error(`Buildkite: invalid props:\n${details}`);
+    }
+    return result.data;
+}

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

@@ -0,0 +1,58 @@
+import { MultipartUserData } from "aws-cdk-lib/aws-ec2";
+import type { BuildkiteProps } from "./schema.js";
+/**
+ * Resolved synth-time values the user data needs beyond the plain props —
+ * supplied by the construct (region from `Stack.of(this)`, never
+ * `props.env?.region`, which rendered the literal string "undefined" in the
+ * pre-refactor stack).
+ */
+export interface BuildkiteUserDataContext {
+    readonly stackName: string;
+    readonly region: string;
+    readonly secretsBucketName: string;
+    readonly artifactBucketName: string;
+}
+/**
+ * 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 declare const BUILDKITE_MOUNT_PART_ENV_KEYS: readonly ["BUILDKITE_ENABLE_INSTANCE_STORAGE", "BUILDKITE_MOUNT_TMPFS_AT_TMP"];
+export declare const BUILDKITE_DOCKER_PART_ENV_KEYS: readonly ["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 declare const BUILDKITE_USER_DATA_ENV_KEYS: readonly ["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"];
+/**
+ * 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 declare function buildBuildkiteUserData(props: BuildkiteProps, context: BuildkiteUserDataContext): MultipartUserData;
+/** Storage-mount part — `bk-mount-instance-storage.sh` env assignments. */
+export declare function buildBuildkiteMountCommands(props: BuildkiteProps): string[];
+/** Docker-configure part — `bk-configure-docker.sh` env assignments. */
+export declare function buildBuildkiteDockerCommands(props: BuildkiteProps): string[];
+/**
+ * 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 declare function buildBuildkiteInstallCommands(props: BuildkiteProps, context: BuildkiteUserDataContext): string[];

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,12 @@
-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";
+export { addBuildkiteAlarms, type BuildkiteAlarmParams } from "./buildkite/alarms.js";