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.

Base Configuration

Parameter	Description
`BuildkiteAgentToken` `(String)`	Buildkite agent registration token. Or, preload it into SSM Parameter Store and use BuildkiteAgentTokenParameterStorePath for secure environments.
`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)
`BuildkiteQueue` `(String)`	Queue name that agents will use, targeted in pipeline steps using "queue={value}" Default Value: `default` Minimum Length: 1

Signed Pipelines Configuration

Parameter	Description
`PipelineSigningKMSKeyId` `(String)`	Optional - Identifier of the KMS key used to sign and verify pipelines (Created if left blank and PipelineSigningKMSKeySpec is selected)
`PipelineSigningKMSKeySpec` `(String)`	The key spec for the KMS key used to sign and verify pipelines Allowed Values: `ECC_NIST_P256` `none` Default Value: `none`
`PipelineSigningKMSAccess` `(String)`	The access level for the KMS key used to sign and verify pipelines Allowed Values: `sign-and-verify` `verify` Default Value: `sign-and-verify`
`PipelineSigningVerificationFailureBehavior` `(String)`	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) Allowed Values: `block` `warn` Default Value: `block`

Advanced Configuration

Parameter	Description
`BuildkiteAgentRelease` `(String)`	Allowed Values: `stable` `beta` `edge` 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: `true` `false` Default Value: `false`
`BuildkiteAgentExperiments` `(String)`	Agent experiments to enable, comma delimited. See https://github.com/buildkite/agent/blob/-/EXPERIMENTS.md.
`BuildkiteAgentEnableGitMirrors` `(String)`	Enables git-mirrors in the agent Allowed Values: `true` `false` Default Value: `false`
`BuildkiteAgentTracingBackend` `(String)`	The tracing backend to use for CI tracing. See https://buildkite.com/docs/agent/v3/tracing Allowed Values: `datadog` `opentelemetry`
`BuildkiteAgentCancelGracePeriod` `(Number)`	The number of seconds a canceled or timed out job is given to gracefully terminate and upload its artifacts. Default Value: `60` Minimum Value: 1
`BuildkiteTerminateInstanceAfterJob` `(String)`	Set to "true" to terminate the instance after a job has completed. Allowed Values: `true` `false` 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: `true` `false` 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.8.0`
`LogRetentionDays` `(Number)`	The number of days to retain the Cloudwatch Logs of the lambda. Default Value: `1`

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)
`SecurityGroupIds` `(String)`	Optional - Comma separated list of security group ids to assign to instances
`AssociatePublicIpAddress` `(String)`	Associate instances with public IP addresses Allowed Values: `true` `false` 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: `linux` `windows` Default Value: `linux`
`InstanceTypes` `(String)`	Comma-separated list with 1-10 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,9}$` Minimum Length:* 1
`EnableInstanceStorage` `(String)`	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 Allowed Values: `true` `false` Default Value: `false`
`MountTmpfsAtTmp` `(String)`	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. Allowed Values: `true` `false` Default Value: `true`
`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
`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: `true` `false` 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: `true` `false` Default Value: `false`
`ManagedPolicyARNs` `(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: `optional` `required` Default Value: `optional`
`EnableDetailedMonitoring` `(String)`	Enable detailed EC2 monitoring Allowed Values: `true` `false` Default Value: `false`
`InstanceName` `(String)`	Optional - Customise the EC2 instance Name tag

Auto-scaling Configuration

Parameter	Description
`MinSize` `(Number)`	Minimum number of instances Default Value: `0` Minimum Value: 0
`MaxSize` `(Number)`	Maximum number of instances Default Value: `10` Minimum Value: 0
`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
`SpotAllocationStrategy` `(String)`	The strategy for allocating Spot Instances when launching or replacing instances. If choosing `capacity-optimized-prioritized`, the order you specify in InstanceTypes will be the priority. Allowed Values: `price-capacity-optimized` `capacity-optimized` `lowest-price` `capacity-optimized-prioritized` Default Value: `capacity-optimized`
`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: `true` `false` Default Value: `false`
`InstanceCreationTimeout` `(String)`	Timeout period for Autoscaling Group Creation Policy
`ScalerEventSchedulePeriod` `(String)`	How often the Event Schedule for buildkite-agent-scaler is triggered. Should be an expression with units, e.g. "30 seconds", "1 minute", "5 minutes". Default Value: `1 minute`
`ScalerMinPollInterval` `(String)`	Minimum interval at which the auto scaler should poll the AWS API Default Value: `10s`

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: `true` `false` 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: `true` `false` Default Value: `true`
`EnableDockerExperimental` `(String)`	Enables Docker experimental features Allowed Values: `true` `false` Default Value: `false`

Docker Registry Configuration

Parameter	Description
`ECRAccessPolicy` `(String)`	ECR access policy to give container instances Allowed Values: `none` `readonly` `poweruser` `full` Default Value: `none`

Plugin Configuration

Parameter	Description
`EnableSecretsPlugin` `(String)`	Enables s3-secrets plugin for all pipelines Allowed Values: `true` `false` Default Value: `true`
`EnableECRPlugin` `(String)`	Enables ecr plugin for all pipelines Allowed Values: `true` `false` Default Value: `true`
`EnableDockerLoginPlugin` `(String)`	Enables docker-login plugin for all pipelines Allowed Values: `true` `false` Default Value: `true`