Warning
This release has been tested, but is still in beta. If any issues are encountered, please raise an issue or feel free to draft a Pull Request.
Note
Prefer Cloudformation? See elastic-ci-stack-for-aws
Buildkite provides a platform for running fast, secure, and scalable continuous integration pipelines on your own infrastructure.
The Buildkite Elastic CI Stack for AWS gives you a private, autoscaling Buildkite Agent cluster. Use it to parallelize large test suites across thousands of nodes, run tests and deployments for Linux or Windows based services and apps, or run AWS ops tasks.
Learn more about the Elastic CI Stack for AWS and how to get started with it from the Buildkite Docs:
- Elastic CI Stack for AWS overview page, for a summary of the stack's architecture and supported features.
- Linux and Windows setup for the Elastic CI Stack for AWS page for a step-by-step guide on how to set up the Elastic CI Stack in AWS for these operating systems.
A list of recommended resources provides links to other pages in the Buildkite Docs for more detailed information.
Alternatively, jump straight in:
module "buildkite_stack" {
source = "github.com/buildkite/terraform-buildkite-elastic-ci-stack-for-aws#0.1.0"
stack_name = "my-buildkite-stack"
buildkite_queue = "default"
buildkite_agent_token = "your-agent-token-here"
# Scaling configuration
min_size = 0
max_size = 10
# Instance configuration
instance_types = "t3.large,t3.xlarge"
# Network (creates VPC by default)
associate_public_ip_address = true
}The current release is 
Although the stack creates its own VPC by default, Buildkite highly recommends following best practices by setting up a separate development AWS account and using role switching and consolidated billing — see the Delegate Access Across AWS Accounts tutorial for more information.
This repository hasn't been reviewed by security researchers. Therefore, exercise caution and careful thought with what credentials you make available to your builds.
Anyone with commit access to your codebase (including third-party pull-requests if you've enabled them in Buildkite) will have access to your secrets bucket files.
Also, keep in mind the EC2 HTTP metadata server is available from within builds, which means builds act with the same IAM permissions as the instance.
The Elastic CI Stack includes configurable systemd resource limits to prevent resource exhaustion. These limits can be configured using Terraform variables:
| Variable | Description | Default |
|---|---|---|
experimental_enable_resource_limits |
Enable systemd resource limits for the Buildkite agent | false |
resource_limits_memory_high |
MemoryHigh limit (e.g., '90%' or '4G') | "90%" |
resource_limits_memory_max |
MemoryMax limit (e.g., '90%' or '4G') | "90%" |
resource_limits_memory_swap_max |
MemorySwapMax limit (e.g., '90%' or '4G') | "90%" |
resource_limits_cpu_weight |
CPU weight (1-10000) | 100 |
resource_limits_cpu_quota |
CPU quota (e.g., '90%') | "90%" |
resource_limits_io_weight |
I/O weight (1-10000) | 80 |
See the examples/ directory for more use cases.
- Resource limits are disabled by default
- Values can be specified as percentages or absolute values (for memory-related parameters)
The Elastic CI Stack supports time-based scaling to automatically adjust the minimum number of instances based on your team's working hours. This feature helps optimize costs by scaling down during off-hours while allowing users the ability to proactively scale up capacity ahead of expected increasing capacity requirements.
| Variable | Description | Default |
|---|---|---|
enable_scheduled_scaling |
Enable scheduled scaling actions | false |
schedule_timezone |
Timezone for scheduled actions | "UTC" |
scale_up_schedule |
Cron expression for scaling up | "0 8 * * MON-FRI" |
scale_up_min_size |
MinSize when scaling up | 1 |
scale_down_schedule |
Cron expression for scaling down | "0 18 * * MON-FRI" |
scale_down_min_size |
MinSize when scaling down | 0 |
Example usage can be found in the Scheduled Scaling directory.
Scheduled scaling uses AWS Auto Scaling cron expressions with the format:
minute hour day-of-month month day-of-week
Common examples:
0 8 * * MON-FRI- 8:00 AM on weekdays0 18 * * MON-FRI- 6:00 PM on weekdays0 9 * * SAT- 9:00 AM on Saturdays30 7 * * 1-5- 7:30 AM Monday through Friday (using numbers)
The ScheduleTimezone parameter supports IANA timezone names such as:
America/New_York(Eastern Time)America/Los_Angeles(Pacific Time)Europe/London(Greenwich Mean Time)Asia/Tokyo(Japan Standard Time)UTC(Coordinated Universal Time)
When developing changes, please ensure you refer to our Code of Conduct.
We welcome pull requests for improvements that benefit the broader community. Changes specific to individual use cases should be maintained in forked repositories.
If you need to build your own AMIs take a look at the elastic-ci-stack-for-aws repository and the Custom images section of the Buildkite Docs.
We provide support for security and bug fixes on the current major release only.
If there are any changes in the main branch since the last tagged release, we aim to publish a new tagged release of this template at the end of each month.
Buildkite builds and deploys the following AMIs to all our supported regions:
- Amazon Linux 2023 (64-bit x86)
- Amazon Linux 2023 (64-bit Arm)
- Windows Server 2022 (64-bit x86)
Following on from the Getting started pages above, to gain a better understanding of how Elastic CI Stack works and how to use it most effectively and securely, see the following resources:
- Buildkite Agents in AWS overview
- Configuration parameters
- Using AWS Secrets Manager
- VPC design
- Terraform Get Started - AWS
Feel free to drop an email to [email protected] with questions. It'll also help us if you can provide the following details:
# List your tfvars
cat YOUR_VARS_NAME.tfvarsProvide Buildkite with logs from CloudWatch Logs:
/buildkite/elastic-stack/{instance-id}
/buildkite/system/{instance-id}See Licence.md (MIT)
| Name | Version |
|---|---|
| terraform | >= 1.0 |
| archive | ~> 2.0 |
| aws | >= 5.0 |
| random | ~> 3.0 |
| Name | Version |
|---|---|
| archive | ~> 2.0 |
| aws | >= 5.0 |
| random | ~> 3.0 |
| terraform | n/a |
No modules.
| Name | Description | Type | Default | Required |
|---|---|---|---|---|
| agent_endpoint | API endpoint URL for Buildkite agent communication. Most customers shouldn't need to change this unless using a custom endpoint agreed with the Buildkite team. | string |
"https://agent.buildkite.com/v3" |
no |
| agent_env_file_url | Optional - HTTPS or S3 URL containing environment variables for the Buildkite agent process itself (not for builds). These variables configure agent behavior like proxy settings or debugging options. For build environment variables, use pipeline 'env' configuration instead. | string |
"" |
no |
| agents_per_instance | Number of Buildkite agents to start on each EC2 instance. NOTE: If an agent crashes or is terminated, it won't be automatically restarted, leaving fewer active agents on that instance. The scale_in_idle_period parameter controls when the entire instance terminates (when all agents are idle), not individual agent restarts. Consider enabling scaler_enable_elastic_ci_mode for better agent management, or use fewer agents per instance with more instances for high availability. | number |
1 |
no |
| artifacts_bucket | Optional - Name of an existing S3 bucket for build artifact storage. | string |
"" |
no |
| artifacts_bucket_region | Optional - Region for the artifacts_bucket. If blank the bucket's region is dynamically discovered. | string |
"" |
no |
| artifacts_s3_acl | Optional - ACL to use for S3 artifact uploads. | string |
"private" |
no |
| associate_public_ip_address | Give instances public IP addresses for direct internet access. Set to false for a more isolated environment if the VPC has alternative outbound internet access configured. | bool |
true |
no |
| authorized_users_url | Optional - HTTPS or S3 URL to periodically download SSH authorized_keys from, setting this will enable SSH ingress. authorized_keys are applied to ec2-user. | string |
"" |
no |
| availability_zones | Optional - Comma separated list of AZs that subnets are created in (if subnets parameter is not specified). | string |
"" |
no |
| bootstrap_script_url | Optional - HTTPS or S3 URL for a script to run on each instance during boot. | string |
"" |
no |
| buildkite_additional_sudo_permissions | Optional - Comma-separated list of specific commands (full paths) that build jobs can run with sudo privileges. Include only commands essential for builds. Leave blank unless builds require specific system-level operations. | string |
"" |
no |
| buildkite_agent_cancel_grace_period | The number of seconds a canceled or timed out job is given to gracefully terminate and upload its artifacts. | number |
60 |
no |
| buildkite_agent_disconnect_after_uptime | The maximum uptime in seconds before the Buildkite agent stops accepting new jobs and shuts down after any running jobs complete. Set to 0 to disable uptime-based termination. This helps regularly cycle out machines and prevent resource accumulation issues. | number |
0 |
no |
| buildkite_agent_enable_git_mirrors | Enables Git mirrors in the agent. | bool |
false |
no |
| buildkite_agent_enable_graceful_shutdown | Set to true to enable graceful shutdown of Buildkite agents when the ASG is updated with replacement. This allows ASGs to be removed in a timely manner during an in-place update of the Elastic CI Stack for AWS, and allows remaining Buildkite agents to finish jobs without interruptions. | bool |
false |
no |
| buildkite_agent_experiments | Optional - Agent experiments to enable, comma delimited. See https://github.com/buildkite/agent/blob/-/EXPERIMENTS.md. | string |
"" |
no |
| buildkite_agent_release | Buildkite agent release channel to install. 'stable' = production-ready (recommended), 'beta' = pre-release with latest features, 'edge' = bleeding-edge development builds. Use 'stable' unless specific new features are required. | string |
"stable" |
no |
| buildkite_agent_scaler_serverless_arn | ARN of the Serverless Application Repository that hosts the buildkite-agent-scaler Lambda function. The scaler automatically manages Buildkite agent instances based on job queue demand. Repository must be public or shared with your AWS account. See https://aws.amazon.com/serverless/serverlessrepo/. | string |
"arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler" |
no |
| buildkite_agent_scaler_version | Version of the buildkite-agent-scaler to use. | string |
"1.9.6" |
no |
| buildkite_agent_signal_grace_period | The number of seconds given to a subprocess to handle being sent cancel-signal. After this period has elapsed, SIGKILL will be sent. | number |
-1 |
no |
| buildkite_agent_tags | Additional tags to help target specific Buildkite agents in pipeline steps (comma-separated). Example: 'environment=production,docker=enabled,size=large'. Use these tags in pipeline steps with 'agents: { environment: production }'. | string |
"" |
no |
| buildkite_agent_timestamp_lines | Set to true to prepend timestamps to every line of output. | bool |
false |
no |
| buildkite_agent_token | Buildkite agent registration token. Or, preload it into SSM Parameter Store and use buildkite_agent_token_parameter_store_path for secure environments. | string |
"" |
no |
| buildkite_agent_token_parameter_store_kms_key | Optional - AWS KMS key ID used to encrypt the SSM parameter. | string |
"" |
no |
| buildkite_agent_token_parameter_store_path | Optional - Path to Buildkite agent token stored in AWS Systems Manager Parameter Store (e.g., '/buildkite/agent-token'). If provided, this overrides the buildkite_agent_token field. Recommended for better security instead of hardcoding tokens. | string |
"" |
no |
| buildkite_agent_tracing_backend | Optional - The tracing backend to use for CI tracing. See https://buildkite.com/docs/agent/v3/tracing. | string |
"" |
no |
| buildkite_purge_builds_on_disk_full | Set to true to purge build directories as a last resort when disk space is critically low. | bool |
false |
no |
| buildkite_queue | Queue name that agents will use, targeted in pipeline steps using 'queue={value}'. | string |
"default" |
no |
| buildkite_terminate_instance_after_job | Set to true to terminate the instance after a job has completed. | bool |
false |
no |
| buildkite_terminate_instance_on_disk_full | Set to true to terminate the instance when disk space is critically low (default is to exit job with code 1). | bool |
false |
no |
| buildkite_windows_administrator | Add buildkite-agent user to Windows Administrators group. This provides full system access for build jobs. Set to false if builds don't require administrator privileges for additional security isolation. | bool |
true |
no |
| cost_allocation_tag_name | The name of the Cost Allocation Tag used for billing purposes. | string |
"CreatedBy" |
no |
| cost_allocation_tag_value | The value of the Cost Allocation Tag used for billing purposes. | string |
"buildkite-elastic-ci-stack-for-aws" |
no |
| cpu_credits | Credit option for CPU usage of burstable instances. Sets the CreditSpecification.CpuCredits property in the LaunchTemplate for T-class instance types (t2, t3, t3a, t4g). | string |
"unlimited" |
no |
| disable_scale_in | Whether the desired count should ever be decreased on the Auto Scaling group. When set to true (default), the scaler will not reduce the Auto Scaling group's desired capacity, and instances are expected to self-terminate when idle. | bool |
true |
no |
| docker_fixed_cidr_v4 | Optional IPv4 CIDR block for Docker's fixed-cidr option. Restricts the IP range Docker uses for container networking on the default bridge. Must be a subset of docker_ipv4_address_pool_1. Leave empty to disable. Only applies to Linux instances, not Windows. | string |
"" |
no |
| docker_fixed_cidr_v6 | IPv6 CIDR block for Docker's fixed-cidr-v6 option in dualstack mode. Restricts the IP range Docker uses for IPv6 container networking. Only applies to Linux instances in dualstack mode, not Windows. | string |
"2001:db8:1::/64" |
no |
| docker_ipv4_address_pool_1 | Primary IPv4 CIDR block for Docker default address pools. Must not conflict with host network or VPC CIDR. Only applies to Linux instances, not Windows. | string |
"172.17.0.0/12" |
no |
| docker_ipv4_address_pool_2 | Secondary IPv4 CIDR block for Docker default address pools. Only applies to Linux instances, not Windows. | string |
"192.168.0.0/16" |
no |
| docker_ipv6_address_pool | IPv6 CIDR block for Docker default address pools in dualstack mode. Only applies to Linux instances, not Windows. | string |
"2001:db8:2::/104" |
no |
| docker_networking_protocol | Which IP version to enable for docker containers and building docker images. Only applies to Linux instances, not Windows. | string |
"ipv4" |
no |
| ec2_log_retention_days | The number of days to retain CloudWatch Logs for EC2 instances managed by the CloudWatch agent (Buildkite agents, system logs, etc). | number |
7 |
no |
| ecr_access_policy | Docker image registry permissions for agents. 'none' = no access, 'readonly' = pull images only, 'poweruser' = pull/push images, 'full' = complete ECR access. The '-pullthrough' variants (e.g., 'readonly-pullthrough') add permissions to enable automatic caching of public Docker images, reducing pull times and bandwidth costs. | string |
"none" |
no |
| enable_cost_allocation_tags | Enables AWS Cost Allocation tags for all resources in the stack. See https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html. | bool |
false |
no |
| enable_detailed_monitoring | Enable detailed EC2 monitoring. | bool |
false |
no |
| enable_docker_experimental | Enables Docker experimental features. | bool |
false |
no |
| enable_docker_login_plugin | Enables docker-login plugin for all pipelines. | bool |
true |
no |
| enable_docker_user_namespace_remap | Enables Docker user namespace remapping so docker runs as buildkite-agent. | bool |
true |
no |
| enable_ec2_log_retention_policy | Enable automatic deletion of old EC2 logs to reduce CloudWatch storage costs. Disabled by default to preserve all logs. When enabled, EC2 logs older than ec2_log_retention_days will be automatically deleted. This only affects EC2 instance logs (agents, system logs), not Lambda logs. WARNING: Enabling this on existing stacks will delete historical logs older than the retention period - this cannot be undone. | bool |
false |
no |
| enable_ecr_credential_helper | Enable Amazon ECR Credential Helper in ECR plugin for Docker authentication. Provides an alternative authentication method for ECR. | bool |
false |
no |
| enable_ecr_plugin | Enables ECR plugin for all pipelines. | bool |
true |
no |
| enable_instance_storage | Mount available NVMe Instance Storage at /mnt/ephemeral, and use it to store docker images and containers, and the build working directory. You must ensure that the instance types have instance storage available for this to have any effect. See https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-store-volumes.html | bool |
false |
no |
| enable_scheduled_scaling | Enable scheduled scaling to automatically adjust min_size based on time-based schedules | bool |
false |
no |
| enable_secrets_plugin | Enables S3 Secrets plugin for all pipelines. | bool |
true |
no |
| experimental_enable_resource_limits | Experimental - If true, enables systemd resource limits for the Buildkite agent. This helps prevent resource exhaustion by limiting CPU, memory, and I/O usage. Useful for shared instances running multiple agents or resource-intensive builds. | bool |
false |
no |
| image_id | Optional - Custom AMI to use for instances (must be based on the stack's AMI). | string |
"" |
no |
| image_id_parameter | Optional - Custom AMI SSM Parameter to use for instances (must be based on the stack's AMI). | string |
"" |
no |
| imdsv2_tokens | Security setting for EC2 instance metadata access. 'required' enforces secure token-based access (recommended for security), 'optional' allows both secure and legacy access methods. Use 'required' unless legacy applications require the older metadata service. | string |
"optional" |
no |
| instance_buffer | Number of idle instances to keep running. Lower values save costs, higher values reduce wait times for new jobs. | number |
0 |
no |
| instance_creation_timeout | Optional - Timeout period for Auto Scaling Group Creation Policy. | string |
"" |
no |
| instance_name | Optional - Customize the EC2 instance Name tag. | string |
"" |
no |
| instance_operating_system | The operating system to run on the instances. | string |
"linux" |
no |
| instance_role_name | Optional - A name for the IAM Role attached to the Instance Profile. | string |
"" |
no |
| instance_role_permissions_boundary_arn | Optional - The ARN of the policy used to set the permissions boundary for the role. | string |
"" |
no |
| instance_role_tags | Optional - Comma-separated key=value pairs for instance IAM role tags (up to 5 tags). Example: 'Environment=production,Team=platform,Purpose=ci'. Note: Keys and values cannot contain '=' characters. | string |
"" |
no |
| instance_types | EC2 instance types to use (comma-separated, up to 25). The first type listed is preferred for OnDemand instances. Additional types improve Spot instance availability but make costs less predictable. Examples: 't3.large' for light workloads, 'm5.xlarge,m5a.xlarge' for CPU-intensive builds, 'c5.2xlarge,c5.4xlarge' for compute-heavy tasks. | string |
"t3.large" |
no |
| key_name | Optional - SSH keypair used to access the Buildkite instances via ec2-user, setting this will enable SSH ingress. | string |
"" |
no |
| lambda_architecture | CPU architecture for Lambda functions (x86_64 or arm64). arm64 provides better price-performance but requires compatible dependencies. | string |
"x86_64" |
no |
| lambda_log_retention_days | The number of days to retain CloudWatch Logs for Lambda functions in the stack. | number |
1 |
no |
| managed_policy_arns | Optional - List of managed IAM policy ARNs to attach to the instance role. | list(string) |
[] |
no |
| max_size | Maximum number of instances. Controls cost ceiling and prevents runaway scaling. | number |
10 |
no |
| min_size | Minimum number of instances. Ensures baseline capacity for immediate job execution. | number |
0 |
no |
| mount_tmpfs_at_tmp | Controls the filesystem mounted at /tmp. By default, /tmp is a tmpfs (memory-backed filesystem). Disabling this causes /tmp to be stored in the root filesystem. | bool |
true |
no |
| on_demand_base_capacity | Specify how much On-Demand capacity the Auto Scaling group should have for its base portion before scaling by percentages. The maximum group size will be increased (but not decreased) to this value. | number |
0 |
no |
| on_demand_percentage | Percentage of instances to launch as OnDemand vs Spot instances. OnDemand instances provide guaranteed availability at higher cost. Spot instances offer 60-90% cost savings but may be interrupted by AWS. Use 100% for critical workloads, lower values when jobs can handle unexpected instance interruptions. | number |
100 |
no |
| pipeline_signing_jwks_key_id | The ID of the key in the JWKS to use for signing jobs. If not specified, and the JWKS contains only one key, that key will be used. Only relevant when pipeline_signing_jwks_parameter_store_path is set. | string |
"" |
no |
| pipeline_signing_jwks_parameter_store_path | Existing SSM Parameter Store path to a JSON Web Key Set (JWKS) containing a key to sign jobs with. Alternative to pipeline_signing_kms_key_id for JWKS-based signing. Leave blank to use KMS signing instead. | string |
"" |
no |
| pipeline_signing_kms_access | Access permissions for pipeline signing. 'sign-and-verify' allows both operations, 'verify' restricts to verification only. | string |
"sign-and-verify" |
no |
| pipeline_signing_kms_key_id | Optional - Identifier or ARN of existing KMS key for pipeline signing. Leave blank to create a new key when pipeline_signing_kms_key_spec is specified. | string |
"" |
no |
| pipeline_signing_kms_key_spec | Key specification for pipeline signing KMS key. Set to 'none' to disable pipeline signing, or 'ECC_NIST_P256' to enable with automatic key creation. | string |
"none" |
no |
| pipeline_signing_verification_failure_behavior | The behavior when a job is received without a valid verifiable signature (without a signature, with an invalid signature, or with a signature that fails verification). | string |
"block" |
no |
| pipeline_verification_jwks_parameter_store_path | Existing SSM Parameter Store path to a JSON Web Key Set (JWKS) containing keys with which to verify jobs. Used for pipeline signature verification. | string |
"" |
no |
| resource_limits_cpu_quota | Experimental - Sets the CPU quota for the Buildkite agent slice. Takes a percentage value, suffixed with '%'. | string |
"90%" |
no |
| resource_limits_cpu_weight | Experimental - Sets the CPU weight for the Buildkite agent slice (1-10000, default 100). Higher values give more CPU time to the agent. | number |
100 |
no |
| resource_limits_io_weight | Experimental - Sets the I/O weight for the Buildkite agent slice (1-10000, default 80). Higher values give more I/O bandwidth to the agent. | number |
80 |
no |
| resource_limits_memory_high | Experimental - Sets the MemoryHigh limit for the Buildkite agent slice. The value can be a percentage (e.g., '90%') or an absolute value (e.g., '4G'). | string |
"90%" |
no |
| resource_limits_memory_max | Experimental - Sets the MemoryMax limit for the Buildkite agent slice. The value can be a percentage (e.g., '90%') or an absolute value (e.g., '4G'). | string |
"90%" |
no |
| resource_limits_memory_swap_max | Experimental - Sets the MemorySwapMax limit for the Buildkite agent slice. The value can be a percentage (e.g., '90%') or an absolute value (e.g., '4G'). | string |
"90%" |
no |
| root_volume_encrypted | Indicates whether the EBS volume is encrypted. | bool |
false |
no |
| root_volume_iops | If the root_volume_type is gp3, io1, or io2, the number of IOPS to provision for the root volume. | number |
1000 |
no |
| root_volume_name | Optional - Name of the root block device for the AMI. | string |
"" |
no |
| root_volume_size | Size of each instance's root EBS volume (in GB). | number |
250 |
no |
| root_volume_throughput | If the root_volume_type is gp3, the throughput (MB/s data transfer rate) to provision for the root volume. | number |
125 |
no |
| root_volume_type | Type of root volume to use. If specifying io1 or io2, specify root_volume_iops as well for optimal performance. See https://docs.aws.amazon.com/ebs/latest/userguide/provisioned-iops.html for more details. | string |
"gp3" |
no |
| scale_down_min_size | min_size to set when the scale_down_schedule is triggered (applied at the time specified in scale_down_schedule, only used when enable_scheduled_scaling is true) | number |
0 |
no |
| scale_down_schedule | Cron expression for when to scale down (only used when enable_scheduled_scaling is true). See AWS documentation for format details: https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-scheduled-scaling.html#scheduled-scaling-cron ('0 18 * * MON-FRI' for 6 PM weekdays) | string |
"0 18 * * MON-FRI" |
no |
| scale_in_cooldown_period | Cooldown period in seconds before allowing another scale-in event. Longer periods prevent premature termination when job queues fluctuate. | number |
3600 |
no |
| scale_in_idle_period | Number of seconds ALL agents on an instance must be idle before the instance is terminated. When all agents_per_instance agents are idle for this duration, the entire instance is terminated, not individual agents. This parameter controls instance-level scaling behavior. | number |
600 |
no |
| scale_out_cooldown_period | Cooldown period in seconds before allowing another scale-out event. Prevents rapid scaling and reduces costs from frequent instance launches. | number |
300 |
no |
| scale_out_factor | Multiplier for scale-out speed. Values higher than 1.0 create instances more aggressively, values lower than 1.0 more conservatively. Use higher values for time-sensitive workloads, lower values to control costs. | number |
1 |
no |
| scale_out_for_waiting_jobs | Scale up instances for pipeline steps queued behind manual approval or wait steps. When enabled, the scaler will provision instances even when jobs can't start immediately due to pipeline waits. Ensure scale_in_idle_period is long enough to keep instances running during wait periods. | bool |
false |
no |
| scale_up_min_size | min_size to set when the scale_up_schedule is triggered (applied at the time specified in scale_up_schedule, only used when enable_scheduled_scaling is true). Cannot exceed max_size. | number |
1 |
no |
| scale_up_schedule | Cron expression for when to scale up (only used when enable_scheduled_scaling is true). See AWS documentation for format details: https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-scheduled-scaling.html#scheduled-scaling-cron ('0 8 * * MON-FRI' for 8 AM weekdays) | string |
"0 8 * * MON-FRI" |
no |
| scaler_enable_elastic_ci_mode | Experimental - Enable the Elastic CI Mode with enhanced features like graceful termination and dangling instance detection. Available since buildkite_agent_scaler_version 1.9.3 | bool |
false |
no |
| scaler_event_schedule_period | How often the Event Schedule for buildkite-agent-scaler is triggered. Should be an expression with units. Example: '30 seconds', '1 minute', '5 minutes'. See https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html#eb-rate-expressions | string |
"1 minute" |
no |
| scaler_min_poll_interval | Minimum time between auto-scaler checks for new build jobs (e.g., '30s', '1m'). | string |
"10s" |
no |
| schedule_timezone | Timezone for scheduled scaling actions (only used when enable_scheduled_scaling is true). See AWS documentation for supported formats: https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-scheduled-scaling.html#scheduled-scaling-timezone (America/New_York, UTC, Europe/London, etc.) | string |
"UTC" |
no |
| secrets_bucket | Optional - Name of an existing S3 bucket containing pipeline secrets (Created if left blank). | string |
"" |
no |
| secrets_bucket_encryption | Indicates whether the secrets_bucket should enforce encryption at rest and in transit. | bool |
false |
no |
| secrets_bucket_region | Optional - Region for the secrets_bucket. If blank the bucket's region is dynamically discovered. | string |
"" |
no |
| security_group_ids | Optional - List of security group ids to assign to instances. | list(string) |
[] |
no |
| spot_allocation_strategy | Strategy for selecting Spot instance types to minimize interruptions and costs. 'capacity-optimized' (recommended) chooses types with the most available capacity. 'price-capacity-optimized' balances low prices with availability. 'lowest-price' prioritizes cost savings. 'capacity-optimized-prioritized' follows instance_types order while optimizing for capacity. | string |
"capacity-optimized" |
no |
| stack_name | Unique name for this Buildkite stack. Used as a prefix for all resource names to enable multiple stack deployments. | string |
"buildkite-stack" |
no |
| subnets | Optional - List of two existing VPC subnet ids where EC2 instances will run. Required if setting vpc_id. | list(string) |
[] |
no |
| vpc_id | Optional - Id of an existing VPC to launch instances into. Leave blank to have a new VPC created. | string |
"" |
no |
| Name | Description |
|---|---|
| auto_scaling_group_arn | ARN of the agent Auto Scaling Group |
| auto_scaling_group_name | Name of the agent Auto Scaling Group |
| image_id | AMI ID used by agent instances |
| instance_role_arn | ARN of the IAM role attached to agent instances |
| instance_role_name | Name of the IAM role attached to agent instances |
| launch_template_id | ID of the launch template used by the Auto Scaling Group |
| launch_template_version | Latest version of the launch template |
| lifecycle_hook_name | Name of the lifecycle hook for graceful termination |
| managed_secrets_bucket | S3 bucket for secrets storage |
| managed_secrets_logging_bucket | S3 bucket for secrets bucket logging |
| pipeline_signing_kms_key | KMS key ARN for pipeline signing |
| scaler_lambda_function_arn | ARN of the Buildkite agent scaler Lambda function |
| scaler_lambda_function_name | Name of the Buildkite agent scaler Lambda function |
| scaler_log_group | CloudWatch Log Group for the scaler Lambda |
| vpc_id | VPC ID (either created or provided) |