Template parameters in the Elastic CI Stack for AWS
To create an Auto Scaling group and the launch template for the Elastic CI Stack for AWS deployment, you can either use the default YAML config file, or you can copy it, and substitute that YAML config file with your own configuration file when you create new instances.
The following tables list all the available parameters for the aws-stack.yml
template which creates an Auto Scaling group and the launch template for the Elastic CI Stack for AWS deployment.
You can use these parameters to configure the EC2 instances to suit your needs.
Note that you must provide a value for one of BuildkiteAgentTokenParameterStorePath
or BuildkiteAgentToken
to be able to use aws-stack.yml
template, all other parameters are optional.
Buildkite Configuration
Parameter | Description |
---|---|
BuildkiteAgentTokenParameterStorePath
(String)
|
Existing SSM Parameter Store path to the Buildkite agent registration token (takes precedence over BuildkiteAgentToken). Expects a leading slash ('/').
Allowed Pattern: ^$|^/[a-zA-Z0-9_.\-/]+$
|
BuildkiteAgentTokenParameterStoreKMSKey
(String)
|
AWS KMS key ID used to encrypt the SSM parameter (if encrypted) |
BuildkiteAgentToken
(String)
|
Buildkite agent registration token. Or, preload it into SSM Parameter Store and use BuildkiteAgentTokenParameterStorePath for secure environments. |
BuildkiteQueue
(String)
|
Queue name that agents will use, targeted in pipeline steps using "queue={value}"
Default Value: default
Minimum Length: 1 |
Advanced Buildkite Configuration
Parameter | Description |
---|---|
BuildkiteAgentRelease
(String)
|
Allowed Values:
Default Value: stable
|
BuildkiteAgentTags
(String)
|
Additional tags separated by commas to provide to the agent. E.g os=linux,llamas=always |
BuildkiteAgentTimestampLines
(String)
|
Set to true to prepend timestamps to every line of output
Allowed Values:
Default Value: false
|
BuildkiteAgentExperiments
(String)
|
Agent experiments to enable, comma delimited. See https://github.com/buildkite/agent/blob/master/EXPERIMENTS.md. |
EnableAgentGitMirrorsExperiment
(String)
|
Enables the git-mirrors experiment in the agent
Allowed Values:
Default Value: false
|
BuildkiteAgentTracingBackend
(String)
|
The tracing backend to use for CI tracing. See https://buildkite.com/docs/agent/v3/tracing
Allowed Values:
|
BuildkiteTerminateInstanceAfterJob
(String)
|
Set to "true" to terminate the instance after a job has completed.
Allowed Values:
Default Value: false
|
BuildkiteAdditionalSudoPermissions
(String)
|
Optional - Comma separated list of commands to allow the buildkite-agent user to run using sudo. Note that the commands should be fully qualified paths to executables. |
BuildkiteWindowsAdministrator
(String)
|
Set to "true" to add the local "buildkite-agent" user account to the local Windows Administrator group.
Allowed Values:
Default Value: true
|
BuildkiteAgentScalerServerlessARN
(String)
|
ARN of the Serverless Application Repository that hosts the version of buildkite-agent-scaler to run. This needs to be public or shared with your AWS account. See https://aws.amazon.com/serverless/serverlessrepo/.
Default Value: arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler
|
BuildkiteAgentScalerVersion
(String)
|
Version of the buildkite-agent-scaler to use
Default Value: 1.3.2
|
Network Configuration
Parameter | Description |
---|---|
VpcId
(String)
|
Optional - Id of an existing VPC to launch instances into. Leave blank to have a new VPC created |
Subnets
(CommaDelimitedList)
|
Optional - Comma separated list of two existing VPC subnet ids where EC2 instances will run. Required if setting VpcId. |
AvailabilityZones
(CommaDelimitedList)
|
Optional - Comma separated list of AZs that subnets are created in (if Subnets parameter is not specified) |
SecurityGroupId
(String)
|
Optional - Comma separated list of security group ids to assign to instances |
AssociatePublicIpAddress
(String)
|
Associate instances with public IP addresses
Allowed Values:
Default Value: true
|
Instance Configuration
Parameter | Description |
---|---|
ImageId
(String)
|
Optional - Custom AMI to use for instances (must be based on the stack's AMI) |
ImageIdParameter
(String)
|
Optional - Custom AMI SSM Parameter to use for instances (must be based on the stack's AMI) |
InstanceOperatingSystem
(String)
|
The operating system to run on the instances
Allowed Values:
Default Value: linux
|
InstanceType
(String)
|
Instance type. Comma-separated list with 1-4 instance types. The order is a prioritized preference for launching OnDemand instances, and a non-prioritized list of types to consider for Spot Instances (where used).
Default Value: t3.large
Allowed Pattern: ^[\w\.]+(,[\w\.]*){0,3}$
Minimum Length: 1 |
EnableInstanceStorage
(String)
|
Mount available NVMe Instance Storage at /mnt/ephemeral
Allowed Values:
Default Value: false
|
AgentsPerInstance
(Number)
|
Number of Buildkite agents to run on each instance
Default Value: 1
Minimum Value: 1 |
KeyName
(String)
|
Optional - SSH keypair used to access the buildkite instances via ec2_user, setting this will enable SSH ingress |
SpotPrice
(String)
|
Maximum spot price to use for the instances, in instance cost per hour. Values >0 will result in 100% of instances being spot. 0 means only use normal (non-spot) instances. This parameter is deprecated - we recommend setting to 0 and using OnDemandPercentage to opt into spot instances.
Default Value: 0
|
SecretsBucket
(String)
|
Optional - Name of an existing S3 bucket containing pipeline secrets (Created if left blank) |
SecretsBucketRegion
(String)
|
Optional - Region for the SecretsBucket. If blank the bucket's region is dynamically discovered. |
SecretsBucketEncryption
(String)
|
Indicates whether the SecretsBucket should enforce encryption at rest and in transit
Allowed Values:
Default Value: false
|
ArtifactsBucket
(String)
|
Optional - Name of an existing S3 bucket for build artifact storage |
AuthorizedUsersUrl
(String)
|
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 |
BootstrapScriptUrl
(String)
|
Optional - HTTPS or S3 URL for a script to run on each instance during boot |
AgentEnvFileUrl
(String)
|
Optional - HTTPS or S3 URL for a list of environment variables to propagate into the agent's execution environment. Note that these environment variables **will not** be passed into builds running on the agent, only to the agent process itself. |
RootVolumeSize
(Number)
|
Size of each instance's root EBS volume (in GB)
Default Value: 250
Minimum Value: 10 |
RootVolumeName
(String)
|
Name of the root block device for your AMI |
RootVolumeType
(String)
|
Type of root volume to use
Default Value: gp3
|
RootVolumeEncrypted
(String)
|
Indicates whether the EBS volume is encrypted
Allowed Values:
Default Value: false
|
ManagedPolicyARN
(CommaDelimitedList)
|
Optional - Comma separated list of managed IAM policy ARNs to attach to the instance role |
InstanceRoleName
(String)
|
Optional - A name for the IAM Role attached to the Instance Profile |
InstanceRolePermissionsBoundaryARN
(String)
|
The ARN of the policy used to set the permissions boundary for the role. |
IMDSv2Tokens
(String)
|
Whether IMDSv2 tokens must be used for the Instance Metadata Service.
Allowed Values:
Default Value: optional
|
EnableDetailedMonitoring
(String)
|
Enable detailed EC2 monitoring
Allowed Values:
Default Value: false
|
InstanceName
(String)
|
Optional - Customise the EC2 instance Name tag
Default Value: buildkite-agent
|
Auto-scaling Configuration
Parameter | Description |
---|---|
MinSize
(Number)
|
Minimum number of instances
Default Value: 0
|
MaxSize
(Number)
|
Maximum number of instances
Default Value: 10
Minimum Value: 1 |
OnDemandPercentage
(Number)
|
Percentage of total instances that should launch as OnDemand. Default is 100% OnDemand - reduce this to use some Spot Instances when they're available and cheaper than the OnDemand price. A value of 70 means 70% OnDemand and 30% Spot Instances.
Default Value: 100
Minimum Value: 0 Maximum Value: 100 |
ScaleOutFactor
(Number)
|
A decimal factor to apply to scale out changes to speed up or slow down scale-out
Default Value: 1.0
|
ScaleInIdlePeriod
(Number)
|
Number of seconds an agent must be idle before terminating
Default Value: 600
|
ScaleOutForWaitingJobs
(String)
|
Whether to scale-out for steps behind wait steps. Make sure you have a long enough idle period!
Allowed Values:
Default Value: false
|
InstanceCreationTimeout
(String)
|
Timeout period for Autoscaling Group Creation Policy |
Cost Allocation Configuration
Parameter | Description |
---|---|
EnableCostAllocationTags
(String)
|
Enables AWS Cost Allocation tags for all resources in the stack. See https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html
Allowed Values:
Default Value: false
|
CostAllocationTagName
(String)
|
The name of the Cost Allocation Tag used for billing purposes
Default Value: CreatedBy
|
CostAllocationTagValue
(String)
|
The value of the Cost Allocation Tag used for billing purposes
Default Value: buildkite-elastic-ci-stack-for-aws
|
Docker Daemon Configuration
Parameter | Description |
---|---|
EnableDockerUserNamespaceRemap
(String)
|
Enables Docker user namespace remapping so docker runs as buildkite-agent
Allowed Values:
Default Value: true
|
EnableDockerExperimental
(String)
|
Enables Docker experimental features
Allowed Values:
Default Value: false
|
Docker Registry Configuration
Parameter | Description |
---|---|
ECRAccessPolicy
(String)
|
ECR access policy to give container instances
Allowed Values:
Default Value: none
|
Plugin Configuration
Parameter | Description |
---|---|
EnableSecretsPlugin
(String)
|
Enables s3-secrets plugin for all pipelines
Allowed Values:
Default Value: true
|
EnableECRPlugin
(String)
|
Enables ecr plugin for all pipelines
Allowed Values:
Default Value: true
|
EnableDockerLoginPlugin
(String)
|
Enables docker-login plugin for all pipelines
Allowed Values:
Default Value: true
|