diff --git a/templates/aws-stack.yml b/templates/aws-stack.yml index 06467f0a0..74ea137a3 100644 --- a/templates/aws-stack.yml +++ b/templates/aws-stack.yml @@ -3,19 +3,19 @@ AWSTemplateFormatVersion: "2010-09-09" Description: "Buildkite stack %v" # The Buildkite Elastic CI Stack for AWS gives you a private, -# autoscaling Buildkite Agent cluster. Use it to parallelize +# 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. # -# To gain a better understanding of how Elastic CI Stack works +# To gain a better understanding of how Elastic CI Stack for AWS works # and how to use it most effectively and securely, check out # the following resources: # # * Elastic CI Stack for AWS Overview: https://buildkite.com/docs/agent/v3/elastic_ci_aws # * Elastic CI Stack for AWS Tutorial: https://buildkite.com/docs/tutorials/elastic-ci-stack-aws -# * Running Buildkite Agent on AWS: https://buildkite.com/docs/agent/v3/aws -# * GitHub Repo for Elastic CI Stack: https://github.com/buildkite/elastic-ci-stack-for-aws +# * Running Buildkite agent on AWS: https://buildkite.com/docs/agent/v3/aws +# * GitHub Repo for Elastic CI Stack for AWS: https://github.com/buildkite/elastic-ci-stack-for-aws # * Template Parameters for Elastic CI Stack for AWS: https://buildkite.com/docs/agent/v3/elastic-ci-aws/parameters # * Using AWS Secrets Manager: https://buildkite.com/docs/agent/v3/aws/secrets-manager # * VPC Design: https://buildkite.com/docs/agent/v3/aws/vpc @@ -164,11 +164,15 @@ Metadata: Parameters: KeyName: - Description: Optional - SSH keypair used to access the buildkite instances via ec2-user, setting this will enable SSH ingress + Description: Optional - SSH keypair used to access the Buildkite instances via ec2-user, setting this will enable SSH ingress. Type: String Default: "" BuildkiteAgentRelease: + Description: > + 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. Type: String AllowedValues: - stable @@ -177,35 +181,45 @@ Parameters: Default: "stable" BuildkiteAgentToken: - Description: Buildkite agent registration token. Or, preload it into SSM Parameter Store and use BuildkiteAgentTokenParameterStorePath for secure environments. + Description: > + Buildkite agent registration token. + Or, preload it into SSM Parameter Store and use BuildkiteAgentTokenParameterStorePath for secure environments. Type: String NoEcho: true Default: "" BuildkiteAgentTokenParameterStorePath: - Description: Existing SSM Parameter Store path to the Buildkite agent registration token (takes precedence over BuildkiteAgentToken). Expects a leading slash ('/'). + Description: > + Optional - Path to Buildkite agent token stored in AWS Systems Manager Parameter Store (e.g., '/buildkite/agent-token'). + If provided, this overrides the BuildkiteAgentToken field. + Recommended for better security instead of hardcoding tokens in the template. Type: String Default: "" AllowedPattern: "^$|^/[a-zA-Z0-9_.\\-/]+$" ConstraintDescription: "Expects a leading forward slash" BuildkiteAgentTokenParameterStoreKMSKey: - Description: AWS KMS key ID used to encrypt the SSM parameter (if encrypted) + Description: Optional - AWS KMS key ID used to encrypt the SSM parameter. Type: String Default: "" AgentEndpoint: - Description: Override API endpoint the Buildkite Agent connects to. + Description: > + 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. Type: String Default: "https://agent.buildkite.com/v3" BuildkiteAgentTags: - Description: Additional tags separated by commas to provide to the agent. E.g os=linux,llamas=always + Description: > + 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 }'. Type: String Default: "" BuildkiteAgentTimestampLines: - Description: Set to true to prepend timestamps to every line of output + Description: Set to true to prepend timestamps to every line of output. Type: String AllowedValues: - "true" @@ -213,24 +227,28 @@ Parameters: Default: "false" BuildkiteAgentExperiments: - Description: Agent experiments to enable, comma delimited. See https://github.com/buildkite/agent/blob/-/EXPERIMENTS.md. + Description: > + Optional - Agent experiments to enable, comma delimited. + See https://github.com/buildkite/agent/blob/-/EXPERIMENTS.md. Type: String Default: "" BuildkiteAgentScalerServerlessARN: - Description: 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/. + Description: 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/. Type: String - Default: arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler + Default: "arn:aws:serverlessrepo:us-east-1:172840064832:applications/buildkite-agent-scaler" BuildkiteAgentScalerVersion: - Description: "Version of the buildkite-agent-scaler to use." + Description: Version of the buildkite-agent-scaler to use. Type: String AllowedPattern: '^(?:(?:[2-9]|[1-9]\d+)\.\d+\.\d+|1\.(?:[1-9]\d+\.\d+|9\.(?:[5-9]|[1-9]\d+)))$' ConstraintDescription: "The agent scaler release must be 1.9.5 or newer." Default: "1.9.5" ScalerEnableExperimentalElasticCIMode: - Description: "[EXPERIMENTAL] Enable the Elastic CI Mode with enhanced features like safety checks, agent sorting, dangling instance detection, and graceful termination. Available since BuildkiteAgentScalerVersion 1.9.3" + Description: > + Experimental - Enable the Elastic CI Mode with enhanced features like graceful termination and dangling instance detection. + Available since BuildkiteAgentScalerVersion 1.9.3 Type: String AllowedValues: - "true" @@ -277,12 +295,12 @@ Parameters: MinValue: 0 ScaleOutCooldownPeriod: - Description: Cooldown period in seconds before allowing another scale-out event + Description: Cooldown period in seconds before allowing another scale-out event. Prevents rapid scaling and reduces costs from frequent instance launches. Type: Number Default: 300 ScaleInCooldownPeriod: - Description: Cooldown period in seconds before allowing another scale-in event + Description: Cooldown period in seconds before allowing another scale-in event. Longer periods prevent premature termination when job queues fluctuate. Type: Number Default: 3600 @@ -291,10 +309,10 @@ Parameters: Default: "false" AllowedValues: ["true", "false"] Description: > - Enable CloudWatch log retention policy for EC2 instance logs managed by the CloudWatch agent. - When enabled, EC2 logs older than EC2LogRetentionDays will be automatically deleted to reduce storage costs. - This only affects logs from Buildkite agents, system logs, and other EC2-generated logs - not Lambda or other AWS service logs. - WARNING: For existing stacks, this will delete historical EC2 logs older than the retention period. This action cannot be undone. + 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 EC2LogRetentionDays 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. EC2LogRetentionDays: Type: Number @@ -310,8 +328,8 @@ Parameters: BuildkiteAgentEnableGracefulShutdown: Description: > - Set to true to enable graceful shutdown of agents when the ASG is updated with replacement. - This allows ASGs to be removed in a timely manner during an in-place update of th Elastic Stack, and allows remaining agents to finish jobs without interruptions. + 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. Type: String AllowedValues: - "true" @@ -319,7 +337,7 @@ Parameters: Default: "false" BuildkiteAgentTracingBackend: - Description: The tracing backend to use for CI tracing. See https://buildkite.com/docs/agent/v3/tracing + Description: Optional - The tracing backend to use for CI tracing. See https://buildkite.com/docs/agent/v3/tracing. Type: String AllowedValues: - "" @@ -334,13 +352,15 @@ Parameters: MinValue: 1 BuildkiteAgentSignalGracePeriod: - Description: The number of seconds given to a subprocess to handle being sent `cancel-signal`. After this period has elapsed, SIGKILL will be sent. + Description: > + The number of seconds given to a subprocess to handle being sent `cancel-signal`. + After this period has elapsed, SIGKILL will be sent. Type: Number Default: -1 MinValue: -1 BuildkiteTerminateInstanceAfterJob: - Description: Set to "true" to terminate the instance after a job has completed. + Description: Set to 'true' to terminate the instance after a job has completed. Type: String AllowedValues: - "true" @@ -348,7 +368,7 @@ Parameters: Default: "false" BuildkiteTerminateInstanceOnDiskFull: - Description: Set to "true" to terminate the instance when disk space is critically low (default is to exit job with code 1). + Description: Set to 'true' to terminate the instance when disk space is critically low (default is to exit job with code 1). Type: String AllowedValues: - "true" @@ -356,7 +376,7 @@ Parameters: Default: "false" BuildkitePurgeBuildsOnDiskFull: - Description: Set to "true" to purge build directories as a last resort when disk space is critically low. + Description: Set to 'true' to purge build directories as a last resort when disk space is critically low. Type: String AllowedValues: - "true" @@ -365,7 +385,7 @@ Parameters: BuildkiteAgentDisconnectAfterUptime: Description: > - The maximum uptime in seconds before the agent stops accepting new jobs and shuts down + 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. Type: Number @@ -374,8 +394,8 @@ Parameters: ExperimentalEnableResourceLimits: Description: > - (Experimental) If true, enables systemd resource limits for the Buildkite agent. - This helps prevent resource exhaustion by limiting CPU, memory, and I/O usage. + 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. Type: String AllowedValues: - "true" @@ -384,7 +404,7 @@ Parameters: ResourceLimitsMemoryHigh: Description: > - (Experimental) Sets the MemoryHigh limit for the Buildkite agent slice. + 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'). Type: String Default: '90%' @@ -393,7 +413,7 @@ Parameters: ResourceLimitsMemoryMax: Description: > - (Experimental) Sets the MemoryMax limit for the Buildkite agent slice. + 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'). Type: String Default: '90%' @@ -402,7 +422,7 @@ Parameters: ResourceLimitsMemorySwapMax: Description: > - (Experimental) Sets the MemorySwapMax limit for the Buildkite agent slice. + 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'). Type: String Default: '90%' @@ -411,7 +431,7 @@ Parameters: ResourceLimitsCPUWeight: Description: > - (Experimental) Sets the CPU weight for the Buildkite agent slice (1-10000, default 100). + Experimental - Sets the CPU weight for the Buildkite agent slice (1-10000, default 100). Higher values give more CPU time to the agent. Type: Number Default: 100 @@ -420,8 +440,8 @@ Parameters: ResourceLimitsCPUQuota: Description: > - (Experimental) Sets the CPU quota for the Buildkite agent slice. - Takes a percentage value, suffixed with "%" . + Experimental - Sets the CPU quota for the Buildkite agent slice. + Takes a percentage value, suffixed with "%". Type: String Default: '90%' AllowedPattern: '^\d+%$' @@ -429,7 +449,7 @@ Parameters: ResourceLimitsIOWeight: Description: > - (Experimental) Sets the I/O weight for the Buildkite agent slice (1-10000, default 80). + 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. Type: Number Default: 80 @@ -437,12 +457,17 @@ Parameters: MaxValue: 10000 BuildkiteAdditionalSudoPermissions: - Description: 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. + Description: > + 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. Type: String Default: "" BuildkiteWindowsAdministrator: - Description: Set to "true" to add the local "buildkite-agent" user account to the local Windows Administrator group. + Description: > + 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. Type: String AllowedValues: - "true" @@ -450,21 +475,23 @@ Parameters: Default: "true" BuildkiteQueue: - Description: Queue name that agents will use, targeted in pipeline steps using "queue={value}" + Description: Queue name that agents will use, targeted in pipeline steps using 'queue={value}'. Type: String - Default: default + Default: "default" MinLength: 1 AgentsPerInstance: Description: > - Number of Buildkite agents to run on each instance. This determines the initial count of agents launched when an instance starts. - If an individual agent is terminated (e.g., due to a job failure or manual shutdown), it will not be automatically restarted, resulting in fewer agents on that instance (N-1). The ScaleInIdlePeriod parameter does not affect this agent count. + 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 ScaleInIdlePeriod parameter controls when the entire instance terminates (when all agents are idle), not individual agent restarts. + Consider enabling ScalerEnableExperimentalElasticCIMode for better agent management, or use fewer agents per instance with more instances for high availability. Type: Number Default: 1 MinValue: 1 SecretsBucket: - Description: Optional - Name of an existing S3 bucket containing pipeline secrets (Created if left blank) + Description: Optional - Name of an existing S3 bucket containing pipeline secrets (Created if left blank). Type: String Default: "" @@ -474,7 +501,7 @@ Parameters: Default: "" SecretsBucketEncryption: - Description: Indicates whether the SecretsBucket should enforce encryption at rest and in transit + Description: Indicates whether the SecretsBucket should enforce encryption at rest and in transit. Type: String AllowedValues: - "true" @@ -482,7 +509,7 @@ Parameters: Default: "false" ArtifactsBucket: - Description: Optional - Name of an existing S3 bucket for build artifact storage + Description: Optional - Name of an existing S3 bucket for build artifact storage. Type: String Default: "" @@ -492,7 +519,7 @@ Parameters: Default: "" ArtifactsS3ACL: - Description: Optional - ACL to use for S3 artifact uploads + Description: Optional - ACL to use for S3 artifact uploads. Type: String AllowedValues: - "private" @@ -505,23 +532,26 @@ Parameters: Default: "private" BootstrapScriptUrl: - Description: Optional - HTTPS or S3 URL for a script to run on each instance during boot + Description: Optional - HTTPS or S3 URL for a script to run on each instance during boot. Type: String Default: "" AgentEnvFileUrl: - Description: 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. + Description: > + 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. Type: String Default: "" AuthorizedUsersUrl: - Description: 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 + Description: 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. Type: String Default: "" VpcId: Type: String - Description: Optional - Id of an existing VPC to launch instances into. Leave blank to have a new VPC created + Description: Optional - Id of an existing VPC to launch instances into. Leave blank to have a new VPC created. Default: "" Subnets: @@ -531,13 +561,17 @@ Parameters: AvailabilityZones: Type: CommaDelimitedList - Description: Optional - Comma separated list of AZs that subnets are created in (if Subnets parameter is not specified) + Description: Optional - Comma separated list of AZs that subnets are created in (if Subnets parameter is not specified). Default: "" InstanceTypes: - Description: Comma-separated list with 1-25 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). + Description: > + 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. Type: String - Default: t3.large + Default: "t3.large" MinLength: 1 AllowedPattern: "^[\\w-\\.]+(,[\\w-\\.]*){0,24}$" ConstraintDescription: "must contain 1-25 instance types separated by commas. No space before/after the comma." @@ -551,49 +585,63 @@ Parameters: Default: "unlimited" MaxSize: - Description: Maximum number of instances + Description: Maximum number of instances. Controls cost ceiling and prevents runaway scaling. Type: Number Default: 10 MinValue: 0 MinSize: - Description: Minimum number of instances + Description: Minimum number of instances. Ensures baseline capacity for immediate job execution. Type: Number Default: 0 MinValue: 0 InstanceBuffer: - Description: How many free instances to maintain + Description: Number of idle instances to keep running. Lower values save costs, higher values reduce wait times for new jobs. Type: Number - Default: "0" + Default: 0 ScalerEventSchedulePeriod: - Description: 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". + Description: > + How often the Event Schedule for buildkite-agent-scaler is triggered. + Should be an expression with units. Example: '30 seconds', '1 minute', '5 minutes'. Type: String Default: "1 minute" ScalerMinPollInterval: - Description: Minimum interval at which the auto scaler should poll the AWS API + Description: > + Minimum time between auto-scaler checks for new build jobs (e.g., '30s', '1m'). Type: String Default: "10s" OnDemandBaseCapacity: - Description: 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. + Description: > + 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. Type: Number Default: 0 MinValue: 0 OnDemandPercentage: - Description: 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. + Description: > + 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. Type: Number Default: 100 MinValue: 0 MaxValue: 100 SpotAllocationStrategy: - Description: 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. + Description: > + 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 InstanceTypes order while optimizing for capacity. Type: String - Default: capacity-optimized + Default: "capacity-optimized" AllowedValues: - price-capacity-optimized - capacity-optimized @@ -601,7 +649,10 @@ Parameters: - capacity-optimized-prioritized ScaleOutFactor: - Description: A decimal factor to apply to scale out changes to speed up or slow down scale-out + Description: > + 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. Type: Number Default: 1.0 @@ -614,46 +665,51 @@ Parameters: Default: 600 ScaleOutForWaitingJobs: + Description: > + 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 ScaleInIdlePeriod is long enough to keep instances running during wait periods. Type: String - Description: Whether to scale-out for steps behind wait steps. Make sure you have a long enough idle period! AllowedValues: - "true" - "false" Default: "false" InstanceCreationTimeout: - Description: Timeout period for Autoscaling Group Creation Policy + Description: Optional - Timeout period for Auto Scaling Group Creation Policy. Type: String Default: "" RootVolumeSize: - Description: Size of each instance's root EBS volume (in GB) + Description: Size of each instance's root EBS volume (in GB). Type: Number Default: 250 MinValue: 10 RootVolumeName: - Description: Name of the root block device for your AMI + Description: Optional - Name of the root block device for the AMI. Type: String Default: "" RootVolumeType: - Description: Type of root volume to use. If you are specifying `io1` or `io2`, you will most likely want to specify `RootVolumeIOPS` as well. + Description: > + Type of root volume to use. If specifying `io1` or `io2`, specify `RootVolumeIOPS` as well for optimal performance. + See https://docs.aws.amazon.com/ebs/latest/userguide/provisioned-iops.html for more details. Type: String Default: "gp3" RootVolumeThroughput: - Description: If the `RootVolumeType` is gp3, the throughput to provision for the root volume + Description: If the `RootVolumeType` is gp3, the throughput (MB/s data transfer rate) to provision for the root volume. Type: Number Default: 125 RootVolumeIops: - Description: If the `RootVolumeType` is gp3, io1, or io2, the number of IOPS to provision for the root volume + Description: If the `RootVolumeType` is gp3, io1, or io2, the number of IOPS to provision for the root volume. Type: Number Default: 1000 RootVolumeEncrypted: - Description: Indicates whether the EBS volume is encrypted + Description: Indicates whether the EBS volume is encrypted. Type: String AllowedValues: - "true" @@ -662,51 +718,57 @@ Parameters: SecurityGroupIds: Type: String - Description: Optional - Comma separated list of security group ids to assign to instances + Description: Optional - Comma separated list of security group ids to assign to instances. Default: "" ImageId: Type: String - Description: Optional - Custom AMI to use for instances (must be based on the stack's AMI) + Description: Optional - Custom AMI to use for instances (must be based on the stack's AMI). Default: "" ImageIdParameter: Type: String - Description: Optional - Custom AMI SSM Parameter to use for instances (must be based on the stack's AMI) + Description: Optional - Custom AMI SSM Parameter to use for instances (must be based on the stack's AMI). Default: "" ManagedPolicyARNs: Type: CommaDelimitedList - Description: Optional - Comma separated list of managed IAM policy ARNs to attach to the instance role + Description: Optional - Comma separated list of managed IAM policy ARNs to attach to the instance role. Default: "" IMDSv2Tokens: Type: String - Description: Whether IMDSv2 tokens must be used for the Instance Metadata Service. + Description: > + 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. AllowedValues: - optional - required - Default: optional + Default: "optional" InstanceRoleName: Type: String - Description: Optional - A name for the IAM Role attached to the Instance Profile + Description: Optional - A name for the IAM Role attached to the Instance Profile. Default: "" InstanceRolePermissionsBoundaryARN: Type: String - Description: The ARN of the policy used to set the permissions boundary for the role. + Description: Optional - The ARN of the policy used to set the permissions boundary for the role. Default: "" InstanceRoleTags: - Description: "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." + Description: > + 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. Type: String Default: "" AllowedPattern: "^$|^[\\w\\s_.:/+\\-@]+=[\\w\\s_.:/+\\-@]*(,[\\w\\s_.:/+\\-@]+=[\\w\\s_.:/+\\-@]*){0,4}$" InstanceOperatingSystem: Type: String - Description: The operating system to run on the instances + Description: The operating system to run on the instances. AllowedValues: - linux - windows @@ -714,7 +776,10 @@ Parameters: ECRAccessPolicy: Type: String - Description: ECR access policy to give instances. The `-pullthrough` variants add ECR pull-through cache permissions (including `ecr:CreateRepository`, `ecr:BatchImportUpstreamImage`, `ecr:GetImageCopyStatus`, and upload permissions) to enable transparent upstream registry caching. + Description: > + 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. AllowedValues: - none - readonly @@ -726,7 +791,9 @@ Parameters: AssociatePublicIpAddress: Type: String - Description: Associate instances with public IP addresses + Description: > + 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. AllowedValues: - "true" - "false" @@ -734,7 +801,9 @@ Parameters: DockerNetworkingProtocol: Type: String - Description: Which IP version to enable for docker containers and building docker images. Only applies to Linux instances, not Windows. + Description: > + Which IP version to enable for docker containers and building docker images. + Only applies to Linux instances, not Windows. AllowedValues: - "ipv4" - "dualstack" @@ -757,7 +826,7 @@ Parameters: EnableSecretsPlugin: Type: String - Description: Enables s3-secrets plugin for all pipelines + Description: Enables S3 Secrets plugin for all pipelines. AllowedValues: - "true" - "false" @@ -765,7 +834,7 @@ Parameters: EnableECRPlugin: Type: String - Description: Enables ecr plugin for all pipelines + Description: Enables ECR plugin for all pipelines. AllowedValues: - "true" - "false" @@ -773,7 +842,7 @@ Parameters: EnableDockerLoginPlugin: Type: String - Description: Enables docker-login plugin for all pipelines + Description: Enables docker-login plugin for all pipelines. AllowedValues: - "true" - "false" @@ -781,7 +850,7 @@ Parameters: EnableDockerUserNamespaceRemap: Type: String - Description: Enables Docker user namespace remapping so docker runs as buildkite-agent + Description: Enables Docker user namespace remapping so docker runs as buildkite-agent. AllowedValues: - "true" - "false" @@ -789,7 +858,7 @@ Parameters: EnableDockerExperimental: Type: String - Description: Enables Docker experimental features + Description: Enables Docker experimental features. AllowedValues: - "true" - "false" @@ -808,7 +877,10 @@ Parameters: MountTmpfsAtTmp: Type: String - Description: 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. + Description: > + 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. AllowedValues: - "true" - "false" @@ -816,7 +888,7 @@ Parameters: EnableCostAllocationTags: Type: String - Description: Enables AWS Cost Allocation tags for all resources in the stack. See https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html + Description: Enables AWS Cost Allocation tags for all resources in the stack. See https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html. AllowedValues: - "true" - "false" @@ -824,17 +896,17 @@ Parameters: CostAllocationTagName: Type: String - Description: The name of the Cost Allocation Tag used for billing purposes + Description: The name of the Cost Allocation Tag used for billing purposes. Default: "CreatedBy" CostAllocationTagValue: Type: String - Description: The value of the Cost Allocation Tag used for billing purposes + Description: The value of the Cost Allocation Tag used for billing purposes. Default: "buildkite-elastic-ci-stack-for-aws" BuildkiteAgentEnableGitMirrors: Type: String - Description: Enables git-mirrors in the agent + Description: Enables Git mirrors in the agent. AllowedValues: - "true" - "false" @@ -842,7 +914,7 @@ Parameters: EnableDetailedMonitoring: Type: String - Description: Enable detailed EC2 monitoring + Description: Enable detailed EC2 monitoring. AllowedValues: - "true" - "false" @@ -850,17 +922,17 @@ Parameters: InstanceName: Type: String - Description: Optional - Customise the EC2 instance Name tag + Description: Optional - Customize the EC2 instance Name tag. Default: "" PipelineSigningKMSKeyId: Type: String - Description: Optional - Identifier or ARN of the KMS key used to sign and verify pipelines (created if both PipelineSigningKMSKeyId and PipelineSigningKMSKeyARN are left blank and PipelineSigningKMSKeySpec is selected) + Description: Optional - Identifier or ARN of existing KMS key for pipeline signing. Leave blank to create a new key when PipelineSigningKMSKeySpec is specified. Default: "" PipelineSigningKMSKeySpec: Type: String - Description: The key spec for the KMS key used to sign and verify pipelines + Description: Key specification for pipeline signing KMS key. Set to 'none' to disable pipeline signing, or 'ECC_NIST_P256' to enable with automatic key creation. AllowedValues: - "ECC_NIST_P256" - "none" @@ -868,7 +940,7 @@ Parameters: PipelineSigningKMSAccess: Type: String - Description: The access level for the KMS key used to sign and verify pipelines + Description: Access permissions for pipeline signing. 'sign-and-verify' allows both operations, 'verify' restricts to verification only. AllowedValues: - "sign-and-verify" - "verify" @@ -876,7 +948,7 @@ Parameters: PipelineSigningVerificationFailureBehavior: Type: String - Description: 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) + Description: 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). AllowedValues: - "block" - "warn" @@ -1327,7 +1399,7 @@ Resources: UpdateReplacePolicy: Retain DeletionPolicy: Retain Properties: - Description: Key used to sign and verify pipelines + Description: Key used to sign and verify pipelines. KeySpec: !Ref PipelineSigningKMSKeySpec KeyUsage: SIGN_VERIFY Tags: @@ -2108,7 +2180,7 @@ Resources: AzRebalancingSuspenderFunction: Type: AWS::Lambda::Function Properties: - Description: 'Disables AZ Rebalancing on the agent ASG' + Description: Disables AZ Rebalancing on the agent ASG. Code: ZipFile: | import cfnresponse @@ -2200,7 +2272,7 @@ Resources: Type: AWS::Lambda::Function Condition: EnableBuildkiteAgentGracefulShutdown Properties: - Description: "Gracefully stops all Buildkite agents in a given Auto Scaling group." + Description: Gracefully stops all Buildkite agents in a given Auto Scaling group. Code: ZipFile: | import boto3