Create terraform.tfvars for Buildkite Agents

The Terraform stack at terraform/buildkite-agents/ deploys Buildkite build agents to AWS. It requires a terraform.tfvars file containing the Buildkite agent registration token. This file is gitignored and must NEVER be committed.

Prerequisites

• AWS CLI installed and SSO session active (aws sso login --profile mockserver-build)
• Chrome DevTools MCP configured with --autoConnect (for Buildkite UI retrieval)
• Buildkite org admin access (to view agent tokens)

Token Retrieval

The Buildkite agent token can be retrieved from two sources. Always retrieve from both and compare to ensure consistency.

Source 1: AWS SSM Parameter Store (Authoritative)

The token is stored as a SecureString in the legacy us-east-1 region:

export DYLD_LIBRARY_PATH="/opt/homebrew/opt/expat/lib${DYLD_LIBRARY_PATH:+:$DYLD_LIBRARY_PATH}"
export AWS_CA_BUNDLE="${NODE_EXTRA_CA_CERTS:-}"

aws ssm get-parameter \
  --name /buildkite/buildkite/agent-token \
  --region us-east-1 \
  --profile mockserver-build \
  --with-decryption \
  --query 'Parameter.Value' \
  --output text

This is the authoritative source — it's the same token the legacy CloudFormation stack uses and has been validated in production.

Source 2: Buildkite UI (via Chrome DevTools MCP)

Navigate to the Buildkite agents page and extract the token:

1. Ensure the user is logged into Buildkite in Chrome
2. Navigate: navigate_page(url="https://buildkite.com/organizations/mockserver/agents")
3. Take a snapshot: take_snapshot()
4. Look for the "Agent Token" section
5. Click "Reveal Agent Token" if the token is hidden
6. Extract the token value from the snapshot or via evaluate_script()

See the browser-auth skill for detailed Chrome MCP patterns.

Token Validation

Compare both values:

• If they match: Use the token — it's verified correct
• If they differ: The SSM token is authoritative (it's what agents currently use in production). The Buildkite UI may show a different token if the org has multiple tokens. Verify which token is associated with the default queue.
• If SSM retrieval fails: Use the Buildkite UI token, but verify with the user that it's the correct one for the default queue.

Create terraform.tfvars

The file lives at terraform/buildkite-agents/terraform.tfvars. Create it from the example template:

cp terraform/buildkite-agents/terraform.tfvars.example \
   terraform/buildkite-agents/terraform.tfvars

Then set buildkite_agent_token in terraform/buildkite-agents/terraform.tfvars.

CRITICAL COST REQUIREMENT: Verify min_size = 0 (MUST always be zero):

grep min_size terraform/buildkite-agents/terraform.tfvars
# Should show: min_size = 0

If min_size is not 0, agents run 24/7 incurring unnecessary cost. The Lambda autoscaler handles all scaling based on queue depth — pre-created agents are never needed.

Minimal required change:

# NEVER commit this file — it is gitignored.
# Token retrieved from AWS SSM: /buildkite/buildkite/agent-token (us-east-1)

buildkite_agent_token = "<TOKEN_VALUE>"

Variable Reference

Read current defaults from terraform/buildkite-agents/variables.tf and current overrides from terraform/buildkite-agents/terraform.tfvars.example.

Deploy

After creating terraform.tfvars, deploy with:

cd terraform/buildkite-agents
./run.sh apply

The run.sh wrapper handles:

• AWS SSO authentication check (prompts to login if expired)
• Corporate TLS proxy (AWS_CA_BUNDLE from NODE_EXTRA_CA_CERTS)
• macOS pyexpat workaround (DYLD_LIBRARY_PATH)
• terraform init + terraform apply

Review the Terraform plan and type yes to confirm.

Verification

After deployment, verify agents are working:

1. Check the ASG was created:

   cd terraform/buildkite-agents
   terraform output auto_scaling_group_name

2. Trigger a Buildkite build and confirm an agent picks it up

3. Check the Buildkite agents page for registered agents

Security Reminders

• terraform.tfvars is gitignored via terraform/**/*.tfvars in .gitignore
• NEVER commit this file or include the token in commit messages
• NEVER log the token value in CI/CD output
• The token is marked sensitive = true in variables.tf — Terraform will redact it from plan/apply output
• If the token is compromised, regenerate it in Buildkite and update both SSM Parameter Store and terraform.tfvars