a6-recipe-blue-green

Overview

Blue-green deployment runs two identical production environments (blue and green). At any time, only one serves live traffic. Deploy the new version to the idle environment, test it, then switch traffic instantly. If anything goes wrong, switch back.

This recipe implements blue-green deployment using APISIX routes and upstreams managed by the a6 CLI.

When to Use

• Zero-downtime deployments with instant rollback
• You have two identical environments that can be swapped
• You want to test the new version with internal traffic before switching
• You need an auditable, scriptable deployment process

Approach A: Upstream Swap (Simplest)

Switch traffic by updating the route's upstream_id to point at the other environment.

1. Create both upstreams

a6 upstream create -f - <<'EOF'
{
  "id": "blue",
  "type": "roundrobin",
  "nodes": {
    "blue-backend-1:8080": 1,
    "blue-backend-2:8080": 1
  }
}
EOF

a6 upstream create -f - <<'EOF'
{
  "id": "green",
  "type": "roundrobin",
  "nodes": {
    "green-backend-1:8080": 1,
    "green-backend-2:8080": 1
  }
}
EOF

2. Create route pointing to blue

a6 route create -f - <<'EOF'
{
  "id": "api",
  "uri": "/api/*",
  "upstream_id": "blue"
}
EOF

3. Deploy new version to green, test it

Deploy your new version to the green environment. Test internally.

4. Switch to green

a6 route update api -f - <<'EOF'
{
  "upstream_id": "green"
}
EOF

Traffic switches instantly. No downtime.

5. Rollback to blue (if needed)

a6 route update api -f - <<'EOF'
{
  "upstream_id": "blue"
}
EOF

Approach B: Traffic-Split Plugin (Header-Based Testing)

Use the traffic-split plugin to test the green environment with specific headers before full switch.

1. Create route with traffic-split

a6 route create -f - <<'EOF'
{
  "id": "api",
  "uri": "/api/*",
  "plugins": {
    "traffic-split": {
      "rules": [
        {
          "match": [
            {
              "vars": [["http_x-env", "==", "green"]]
            }
          ],
          "weighted_upstreams": [
            {
              "upstream_id": "green",
              "weight": 1
            }
          ]
        }
      ]
    }
  },
  "upstream_id": "blue"
}
EOF

2. Test green internally

curl -H "x-env: green" http://gateway:9080/api/health

3. Full switch — remove traffic-split, swap upstream

a6 route update api -f - <<'EOF'
{
  "plugins": {},
  "upstream_id": "green"
}
EOF

Approach C: Config Sync (Declarative)

config.yaml — Blue active

version: "1"
upstreams:
  - id: blue
    type: roundrobin
    nodes:
      "blue-backend-1:8080": 1
      "blue-backend-2:8080": 1
  - id: green
    type: roundrobin
    nodes:
      "green-backend-1:8080": 1
      "green-backend-2:8080": 1
routes:
  - id: api
    uri: /api/*
    upstream_id: blue  # ← change to "green" to switch

Preview changes before switching

# Edit config.yaml: change upstream_id to "green"
a6 config diff -f config.yaml

Apply the switch

a6 config sync -f config.yaml

Deployment Script Example

#!/bin/bash
set -euo pipefail

CURRENT=$(a6 route get api -o json | jq -r '.upstream_id')
TARGET=$([ "$CURRENT" = "blue" ] && echo "green" || echo "blue")

echo "Current: $CURRENT → Switching to: $TARGET"

# Switch
a6 route update api -f - <<EOF
{"upstream_id": "$TARGET"}
EOF

echo "Switched to $TARGET. Verifying..."

# Health check
if curl -sf http://gateway:9080/api/health > /dev/null; then
  echo "✅ $TARGET is healthy"
else
  echo "❌ $TARGET unhealthy, rolling back to $CURRENT"
  a6 route update api -f - <<EOF
{"upstream_id": "$CURRENT"}
EOF
  exit 1
fi

Troubleshooting

Symptom	Cause	Fix
502 after switch	New environment not ready	Test health endpoint before switching; rollback if needed
Traffic still going to old env	Route cache or DNS	APISIX routes update instantly via etcd — verify with a6 route get
Can't rollback	Lost track of previous upstream	Always record current state before switching
Connections drop during switch	Long-running requests on old upstream	APISIX handles in-flight requests gracefully; existing connections complete

---

This page is generated from a6-recipe-blue-green/SKILL.md in the api7/a6 repository. Browse all skills on the AI Agent Skills page.