Terraform deployment for the Elastic CI Stack for AWS

The Elastic CI Stack for AWS can be deployed using Terraform instead of AWS CloudFormation.

Prefer AWS CloudFormation?

This guide uses Terraform. For AWS CloudFormation instructions, see the AWS CloudFormation setup guide.

Before you start

Deploying the Elastic CI Stack for AWS with Terraform requires Terraform version 1.0 or later and a Buildkite Agent token.

For the information on getting started with Terraform, see HashiCorp's Get Started with Terraform tutorial and the AWS Provider documentation for configuring AWS credentials.

The module creates its own VPC by default. To deploy into an existing VPC, set the vpc_id and subnets variables.

Deploying the stack

Create a main.tf file with the following configuration:

terraform {
  required_version = ">= 1.0"
}

module "buildkite_stack" {
  source  = "buildkite/elastic-ci-stack/aws"
  version = "~> 0.1.0"

  stack_name            = "buildkite"
  buildkite_agent_token = "your-agent-token-here"

  min_size = 0
  max_size = 10
}

Next, run the following commands to deploy the stack:

terraform init
terraform plan
terraform apply

Configuration

The only required variable is buildkite_agent_token. For information on creating and managing agent tokens, see Agent tokens.

For the complete list of variables and their descriptions, see the module documentation on the Terraform Registry or the configuration parameters reference.

Example configurations

The Terraform module repository includes several example configurations. You can check out the following examples in the examples directory:

Updating the stack

To update to a newer version of the module, update the version constraint in your main.tf:

module "buildkite_stack" {
  source  = "buildkite/elastic-ci-stack/aws"
  version = "0.1.0"

  # ... your configuration
}

Then run the following commands:

terraform init -upgrade
terraform plan
terraform apply

The Auto Scaling group will replace instances gradually during the update. Existing builds will complete before instances are terminated using the Buildkite Agent Scaler.