terraform-tfvars - SKILL.md Agent Skill

name: terraform-tfvars description: > Creates the terraform.tfvars file for the Buildkite build agent Terraform stack. Documents how to retrieve the Buildkite agent token from Buildkite UI (via Chrome DevTools MCP) and AWS SSM Parameter Store, validate tokens, and populate the tfvars file. Use when users say "create tfvars", "set up terraform variables", "deploy buildkite agents", "configure buildkite token", or need to recreate the terraform.tfvars after a fresh checkout.

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:

Ensure the user is logged into Buildkite in Chrome
Navigate: navigate_page(url="https://buildkite.com/organizations/mockserver/agents")
Take a snapshot: take_snapshot()
Look for the "Agent Token" section
Click "Reveal Agent Token" if the token is hidden
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

Variable	Source of truth	Description
`buildkite_agent_token`	`terraform.tfvars`	Buildkite agent registration token (sensitive)
`region`	`variables.tf` / `terraform.tfvars`	AWS region for the agent stack
`instance_types`	`variables.tf` / `terraform.tfvars`	EC2 instance types (comma-separated)
`min_size`	`variables.tf` / `terraform.tfvars`	CRITICAL: MUST be `0` for scale-to-zero cost control — NEVER set to non-zero
`max_size`	`variables.tf` / `terraform.tfvars`	Maximum ASG size
`on_demand_percentage`	`variables.tf` / `terraform.tfvars`	Spot/On-Demand mix

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:

Check the ASG was created:

cd terraform/buildkite-agents
terraform output auto_scaling_group_name

Trigger a Buildkite build and confirm an agent picks it up
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