Buildkite : agents self-hosted pour scale

À la fin de ce tutoriel, vous saurez installer un agent Buildkite Linux (systemd), router les jobs avec queues et tags (docker, deploy, heavy), esquisser des elastic agents EC2 en ca-central-1, sécuriser le Agent Token (hooks, hors Git), et publier un pipeline YAML lint/test/build. Angle DevOps Elastic Hayway (DEH) : control plane SaaS + compute self-hosted, coût bas, cleanup obligatoire.

Niveau : Intermédiaire · Temps estimé : 60–80 min · Versions cibles : Buildkite Agent 3.x · Buildkite Cloud 2026 · systemd · AWS CLI v2 · EC2 / ASG · Dernière vérification : 2026-09-11 · Region : ca-central-1

Slug : wow-buildkite-agents · Série : WOW (38/50) · Mot-clé SEO : buildkite agents · Publish : LIVE

← Précédent : GitHub Actions reusable · → Suivant : Dagger CI · Aussi : Jenkins · Azure Pipelines agents · GHA OIDC AWS

Prérequis

Coût estimé : 0–2 € (agent local = 0 € ; EC2 t3.micro/t3.small quelques heures en ca-central-1 puis terminate). Pas de NAT, RDS, EBS > 8 Go, EIP oubliée.

export AWS_PROFILE=lab
export AWS_DEFAULT_REGION=ca-central-1
aws sts get-caller-identity

Ce que nous allons construire

Buildkite agents self-hosted (WOW 38/50) — ca-central-1
  ├── Pourquoi Buildkite (SaaS + agents chez vous)
  ├── Architecture : Cloud, Token, Agent, Pipelines, Queues/Tags
  ├── Install agent Linux + systemd
  ├── Tags / queues : docker, deploy, heavy
  ├── Elastic agents : sketch ASG EC2 t3.small
  ├── Secrets : hooks ; OIDC/AWS si pertinent
  ├── Pipeline .buildkite/pipeline.yml
  └── Anti-patterns + comparatif + quiz + FAQ

(Schéma — alt : « Buildkite Cloud orchestre ; agents self-hosted en ca-central-1 exécutent les steps via queues/tags ».)

Étape 1 — Pourquoi Buildkite vs runners GitHub / GitLab

Buildkite sépare control plane (Buildkite Cloud : UI, API, scheduling, logs) et data plane (vos agents qui clonent et exécutent). Vous gardez compute, caches et accès VPC.

Critère Buildkite GHA self-hosted GitLab runners
Control plane SaaS Buildkite GitHub GitLab SaaS/self
Agents Self-hosted / Elastic Self-hosted Shared / self-hosted
Isolation Queues / tags Labels Tags / runners
Accès VPC Chez vous Chez vous Chez vous
Coût scale Votre EC2 Minutes + infra Minutes + infra

DEH : CI vers ressources privées en ca-central-1, ou scale compute sans minutes SaaS au pic — Buildkite (ou GHA/GitLab self-hosted). Buildkite : routing fin (queues) + elasticité agents.

Étape 2 — Architecture : Cloud, Token, Agent, Pipelines

[ Git push ]
     |
     v
[ Buildkite Cloud : Pipelines, Token, Queues/Tags ]
     |
     v
[ Agents self-hosted — ca-central-1 ]
  ├── queue=docker
  ├── queue=deploy
  └── queue=heavy (ASG elastic)
Composant Rôle
Buildkite Cloud Orchestre builds, UI, API
Agent Token Auth agent — jamais dans Git
Agent Poll les jobs, exécute les steps
Pipeline Steps (souvent .buildkite/pipeline.yml)
Queues / Tags Routage agent ↔ step

Un agent déclare queue=docker,os=linux. Un step agents: { queue: docker } n’est pris que par un agent compatible.

Étape 3 — Installer un agent Linux + systemd

Ubuntu 22.04/24.04 (2026). Token via SSM — pas de fichier commité.

sudo apt-get update
sudo apt-get install -y curl apt-transport-https gnupg
curl -fsSL https://keys.openpgp.org/vks/v1/by-fingerprint/32A9757BC9EB1E6C7ACF0AC56F54A178B5796D3B 
  | sudo gpg --dearmor -o /usr/share/keyrings/buildkite-agent-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/buildkite-agent-archive-keyring.gpg] 
  https://apt.buildkite.com/buildkite-agent stable main" 
  | sudo tee /etc/apt/sources.list.d/buildkite-agent.list
sudo apt-get update && sudo apt-get install -y buildkite-agent

TOKEN=$(aws ssm get-parameter --name /deh/lab/buildkite-agent-token 
  --with-decryption --query Parameter.Value --output text 
  --region ca-central-1)

sudo tee /etc/buildkite-agent/buildkite-agent.cfg >/dev/null <<EOF
token="${TOKEN}"
name="%hostname-%spawn"
tags="queue=default,os=linux,arch=amd64,env=lab"
tags-from-ec2-meta-data=true
build-path="/var/lib/buildkite-agent/builds"
hooks-path="/etc/buildkite-agent/hooks"
EOF
sudo chown buildkite-agent:buildkite-agent /etc/buildkite-agent/buildkite-agent.cfg
sudo chmod 0600 /etc/buildkite-agent/buildkite-agent.cfg
sudo systemctl enable --now buildkite-agent
sudo systemctl status buildkite-agent --no-pager

UI Buildkite (Agents) : machine Connected avec les tags attendus.

Étape 4 — Tags et queues pour router les jobs

Sans routage, un agent léger prend un job Docker lourd. DEH : une intention = une queue.

Queue Workload Machine
queue=default Lint, unit tests t3.micro / laptop
queue=docker Images, Compose Docker + disque
queue=deploy Terraform / kubectl IAM restreint
queue=heavy e2e, matrix t3.small+ / ASG 
steps:
  - label: ":docker: build"
    command: "docker build -t app:ci ."
    agents:
      queue: docker
  - label: ":rocket: deploy lab"
    command: "kubectl apply -f k8s/"
    agents:
      queue: deploy

Séparez deploy (credentials AWS) de docker (IAM distinct).

Étape 5 — Elastic agents : scale EC2 en ca-central-1

Lab : Launch Template + ASG (t3.small), user-data installe l’agent, destroy après. Subnet publique + SSM = pas de NAT.

export AWS_PROFILE=lab
export AWS_DEFAULT_REGION=ca-central-1
AMI_ID=$(aws ssm get-parameters 
  --names /aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64 
  --query 'Parameters[0].Value' --output text)

cat > /tmp/deh-wow38-userdata.sh << 'UD'
#!/bin/bash
set -eux
dnf install -y docker || yum install -y docker
systemctl enable --now docker
# Installer buildkite-agent (doc rpm/apt 2026)
# TOKEN=$(aws ssm get-parameter --name /deh/lab/buildkite-agent-token --with-decryption ...)
# cfg tags="queue=heavy,os=linux,env=lab" ; systemctl enable --now buildkite-agent
UD

aws ec2 create-launch-template 
  --launch-template-name deh-wow38-bk-agent-lt 
  --version-description "WOW38 Buildkite elastic lab" 
  --launch-template-data "{
    "ImageId": "${AMI_ID}",
    "InstanceType": "t3.small",
    "IamInstanceProfile": {"Name": "deh-lab-ssm-ssmparam"},
    "SecurityGroupIds": ["sg-REPLACE"],
    "UserData": "$(base64 -w0 /tmp/deh-wow38-userdata.sh)"
  }"

aws autoscaling create-auto-scaling-group 
  --auto-scaling-group-name deh-wow38-bk-asg 
  --launch-template LaunchTemplateName=deh-wow38-bk-agent-lt,Version='$Latest' 
  --min-size 0 --max-size 2 --desired-capacity 1 
  --vpc-zone-identifier "subnet-AAA,subnet-BBB" 
  --tags ResourceId=deh-wow38-bk-asg,ResourceType=auto-scaling-group,Key=Project,Value=deh-wow38,PropagateAtLaunch=true

Cleanup obligatoire :

aws autoscaling update-auto-scaling-group 
  --auto-scaling-group-name deh-wow38-bk-asg --min-size 0 --desired-capacity 0
aws autoscaling delete-auto-scaling-group 
  --auto-scaling-group-name deh-wow38-bk-asg --force-delete
aws ec2 delete-launch-template --launch-template-name deh-wow38-bk-agent-lt

Prod : metrics / Elastic CI Stack Buildkite / scale-to-zero. Lab DEH : desired 1, Connected, puis destroy.

Étape 6 — Secrets : hooks, pas de token en clair

Anti-pattern n°1 : token dans repo, gist ou user-data Git. Correctifs DEH :

  1. SSM / Secrets Manager + rôle instance (ca-central-1)
  2. Agent hooks (environment, pre-command) au runtime
  3. OIDC / AWS pour steps deploy (pas de clés longue durée) — esprit GHA OIDC AWS
  4. buildkite-agent.cfg en 0600, user buildkite-agent
#!/bin/bash
# /etc/buildkite-agent/hooks/environment
set -euo pipefail
if [[ "${BUILDKITE_AGENT_META_DATA_QUEUE:-}" == "deploy" ]]; then
  export DEPLOY_ROLE_ARN="arn:aws:iam::ACCOUNT:role/deh-lab-deploy"
fi

Ne logguez jamais le token. Rotatez dans Org Settings.

Étape 7 — Pipeline YAML (lint / test / build)

Fichier .buildkite/pipeline.yml :

steps:
  - label: ":mag: lint"
    command: "make lint"
    agents:
      queue: default
  - label: ":hammer: test"
    command: "make test"
    agents:
      queue: default
    artifact_paths:
      - "coverage/**/*"
  - wait
  - label: ":package: build"
    command: "make build && docker build -t app:${BUILDKITE_COMMIT} ."
    agents:
      queue: docker
  - block: ":rocket: deploy lab ?"
    prompt: "Déployer en lab ca-central-1 ?"
  - label: ":rocket: deploy"
    command: "make deploy-lab"
    agents:
      queue: deploy

Step initial : buildkite-agent pipeline upload. Variables : BUILDKITE_COMMIT, BUILDKITE_BRANCH, BUILDKITE_BUILD_NUMBER.

Étape 8 — Lab concrète

  1. Agent Token en SSM /deh/lab/buildkite-agent-token (ca-central-1, SecureString).
  2. VM Ubuntu ou EC2 t3.micro : install étape 3, tags queue=default.
  3. Repo minimal + .buildkite/pipeline.yml + Makefile (lint/test/build = echo OK).
  4. Build : Connected + step vert sur default.
  5. Option : agent queue=docker ; ASG étape 5 (desired=1) puis cleanup.
  6. Cleanup : stop agent, terminate EC2, delete ASG/LT, pas d’EIP.

Étape 9 — Anti-patterns et comparatif

Anti-patterns : agents partagés sans isolation ; root partout ; tokens long-lived dans Git ; une queue pour lint et prod-deploy ; ASG oublié ; region us-east-1 au lieu de ca-central-1.

Outil Force Attention
Buildkite Queues/tags, elastic, VPC Ops agents chez vous
GHA self-hosted Intégré GitHub Labels + hardening
GitLab runners Tags, shared/group Executor Docker/K8s

Suite : Dagger CI.

Erreurs fréquentes

Erreur Impact Correction
Token dans le repo Fuite SSM + cfg 0600 ; rotate
Connected mais idle Steps en attente Aligner agents.queue et tags
Docker sans Docker Engine Build rouge Queue docker dédiée
ASG desired > 0 oublié Facture Destroy (étape 5)
Region us-east-1 Drift DEH Forcer ca-central-1
Root partout Blast radius User buildkite-agent
Un agent multi-tenants Contamination Isolation queues / comptes

Check-list DEH

  • [ ] Agent systemd Connected + tags explicites
  • [ ] Token hors Git ; cfg 0600
  • [ ] Queues default / docker / deploy (/ heavy)
  • [ ] .buildkite/pipeline.yml lint, test, build
  • [ ] Lab EC2/ASG en ca-central-1 + cleanup
  • [ ] Pas de root pour les jobs applicatifs
  • [ ] Hooks secrets + rotation token
  • [ ] AWS_PROFILE=lab + aws sts get-caller-identity OK

Quiz (5 questions)

1. Buildkite se distingue surtout par :
– A. Des runners uniquement managés Buildkite Cloud
– B. Un control plane SaaS + des agents self-hosted chez vous
– C. L’absence de tokens d’agent

2. Pour router un job Docker :
– A. Un commit message magique
– B. Des tags / queues (queue=docker)
– C. Uniquement le nom de branche

3. Où stocker le Agent Token en lab DEH ?
– A. Dans .buildkite/pipeline.yml
– B. SSM / Secrets Manager (hors Git)
– C. Dans un README public

4. Region lab de ce tutoriel :
– A. us-east-1
– B. ca-central-1
– C. eu-west-3

5. Anti-pattern critique :
– A. Séparer queue deploy et docker
– B. Agents root partagés + token long-lived dans le dépôt
– C. ASG desired=0 après le lab

Réponses : 1‑B · 2‑B · 3‑B · 4‑B · 5‑B

FAQ

Pourquoi Buildkite plutôt que GitHub Actions hosted ?

Exécution dans votre VPC (ca-central-1), caches disque lourds, scale compute sans minutes SaaS au pic. GHA hosted reste excellent pour beaucoup de repos ; self-hosted pour le data plane privé.

Queues vs tags ?

Buildkite route via les tags ; queue=... est la convention de routage principale. Autres tags : os, arch, env=lab.

Combien d’agents pour démarrer ?

Un queue=default pour lint/test. Ajoutez docker puis deploy quand IAM/Docker divergent. ASG pour le burst heavy.

Elastic CI Stack vs ASG maison ?

Buildkite propose des stacks Elastic (CloudFormation). Ce WOW = ASG minimal pédagogique en ca-central-1. Prod : stack officielle + FinOps.

Éviter les secrets dans les logs ?

Hooks environment / pre-command ; redaction Buildkite ; pas de set -x ni echo $TOKEN.

OIDC avec Buildkite ?

Oui pour assumer des rôles AWS depuis les steps deploy — même esprit que github-actions-oidc-aws. L’agent s’authentifie toujours avec son Agent Token.

Mélanger agents locaux et EC2 ?

Oui : laptop pour default, ASG pour heavy. Alignez tags ; isolez credentials.

Coût lab viser ?

0 € local ; moins de 2 € pour quelques heures t3.micro/t3.small puis terminate. Surveillez ASG et volumes.

Pour aller plus loin

Maillage série WOW
← Précédent GitHub Actions reusable
→ Suivant Dagger CI
Aussi Jenkins · Azure Pipelines agents · GHA OIDC AWS · DevSecOps pipeline · Démarrer avec AWS · EC2 + SSM · ASG Launch Template

Meta publication (SEO)

  • Title SEO : Buildkite agents self-hosted pour scale : queues, tags, EC2 (guide FR)
  • Meta description : Buildkite agents self-hosted pour scale : install systemd, queues/tags, elastic agents EC2 ca-central-1, secrets, pipeline YAML, FAQ, quiz et check-list DEH.
  • Focus keyword : buildkite agents
  • Secondary : Buildkite self-hosted, Buildkite queues tags, elastic agents EC2, pipeline.yml Buildkite, agents CI ca-central-1
  • Image : assets/web/devopelastichayway/cover-wow-buildkite-agents-1200x630.webp (à générer)
  • Catégorie : WOW / CI-CD · Niveau : Intermédiaire
  • URL cible : https://devopelastichayway.com/tutoriels/wow-buildkite-agents/
  • Post live : N/A (nouveau) · slug wow-buildkite-agents · Publish : LIVE (feu vert Maître — prêt WP-CLI parent)

← Catalogue Tutoriels

Pour aller plus loin — hubs live

Retour parcours Catalogue Tutoriels — hub de la série et leçons sœurs.

© 2023 devopelastichayway.com All rights reserved.