Gubernator adalah distributed rate limiter berkinerja tinggi yang mengandalkan consistent hashing ring untuk mendistribusikan limit request antar node. Ketika topologi cluster atau format variabel lingkungan mengalami miskonfigurasi, hash ring pecah: request diarahkan ke node yang salah, hitungan limit menjadi tidak sinkron, dan latensi melonjak drastis. Artikel ini membahas cara membangun observability topologi stack Gubernator di Docker, mendeteksi kegagalan routing, mengeksekusi rollback cepat, dan memvalidasi schema konfigurasi sebelum proses deployment.

Anatomi Insiden: Miskonfigurasi Peer Discovery dan Routing Bottleneck

Gubernator menentukan kepemilikan token bucket menggunakan consistent hashing berbasis daftar anggota cluster (GUBER_PEERS). Masalah umum terjadi ketika format alamat advertise tidak cocok dengan resolusi DNS internal container.

Sebagai contoh, jika sebuah container mendaftarkan dirinya sebagai localhost:27000 bukan IP overlay network atau service name (misal: gubernator-1:27000), node lain tidak dapat mengirimkan RPC forwarding via gRPC. Akibatnya:

  • Request forwarding timeout, menyebabkan lonjakan latensi gRPC internal dari <2ms ke 5000ms.
  • Setiap node mengasumsikan dirinya berdiri sendiri, menyebabkan kuota rate limit terpecah menjadi lokal (rate limit leak atau over-throttling).
  • Bottleneck upstream API gateway saat antrean HTTP worker penuh menunggu respons Gubernator.

Setup Stack: Docker Compose dengan Health Check Resilient

Konfigurasi di bawah menerapkan 2 node Gubernator dengan persistent peer discovery dan Docker Compose health check. Health check menginspeksi endpoint status HTTP sebelum container ditandai sehat, mencegah deployment yang rusak mengambil alih traffic.

services:
  gubernator-1:
    image: ghcr.io/mailgun/gubernator:latest
    environment:
      - GUBER_HTTP_ADDRESS=0.0.0.0:8081
      - GUBER_GRPC_ADDRESS=0.0.0.0:27000
      - GUBER_PEERS=gubernator-1:27000,gubernator-2:27000
      - GUBER_METRICS_HTTP_ADDRESS=0.0.0.0:2112
    ports:
      - "8081:8081"
      - "2112:2112"
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8081/v1/HealthCheck | grep -q 'ok' || exit 1"]
      interval: 5s
      timeout: 2s
      retries: 3
      start_period: 3s

  gubernator-2:
    image: ghcr.io/mailgun/gubernator:latest
    environment:
      - GUBER_HTTP_ADDRESS=0.0.0.0:8082
      - GUBER_GRPC_ADDRESS=0.0.0.0:27000
      - GUBER_PEERS=gubernator-1:27000,gubernator-2:27000
      - GUBER_METRICS_HTTP_ADDRESS=0.0.0.0:2113
    ports:
      - "8082:8082"
      - "2113:2113"
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8082/v1/HealthCheck | grep -q 'ok' || exit 1"]
      interval: 5s
      timeout: 2s
      retries: 3
      start_period: 3s

Instrumentasi Observability Topologi Stack

Gubernator mengekspos metrik Prometheus secara default pada port terpisah. Untuk memvalidasi topologi stack secara visual dan real-time, pantau metrik berikut:

  • gubernator_peers_count: Menampilkan jumlah node yang terhubung dalam consistent hash ring. Angka ini harus konsisten di setiap node (misal: 2). Jika terbaca 1, split-brain terjadi.
  • gubernator_forward_requests_total: Counter request gRPC yang diteruskan ke peer lain. Jika nilai status="failed" meningkat, terjadi kegagalan routing overlay network.
  • gubernator_forward_request_duration_seconds: Latensi transit inter-node. Lonjakan menunjukkan socket exhaustion atau packet drop pada bridge network Docker.

Strategi Rollback Cepat via Docker Health Status

Mekanisme zero-downtime rolling update harus berhenti seketika saat container baru gagal melewati health check. Implementasikan script deployment berikut:

#!/usr/bin/env bash
set -euo pipefail

echo "Deploying updated stack..."
docker compose up -d --no-deps --build gubernator-2

echo "Validating health..."
TARGET_STATUS=""
for i in {1..10}; do
  TARGET_STATUS=$(docker inspect --format='{{.State.Health.Status}}' "$(docker compose ps -q gubernator-2)")
  if [ "$TARGET_STATUS" = "healthy" ]; then
    echo "gubernator-2 is healthy."
    break
  fi
  sleep 2
done

if [ "$TARGET_STATUS" != "healthy" ]; then
  echo "Health check failed (status: $TARGET_STATUS). Rolling back..."
  docker compose restart gubernator-2
  exit 1
fi

Validasi Schema Konfigurasi Pre-Deployment

Pencegahan paling efektif adalah memvalidasi format konfigurasi sebelum Docker Compose dijalankan di environment staging atau production. Gunakan script validasi statis ringan berbasis Python untuk memastikan tipe data dan format string GUBER_PEERS valid.

import os, sys, re

def validate_gubernator_env():
    peers = os.getenv("GUBER_PEERS", "")
    if not peers:
        sys.exit("ERROR: GUBER_PEERS must not be empty.")
    
    peer_list = [p.strip() for p in peers.split(",")]
    pattern = re.compile(r"^[a-zA-Z0-9.-]+:[0-9]{2,5}$")
    
    for peer in peer_list:
        if not pattern.match(peer):
            sys.exit(f"ERROR: Invalid peer syntax '{peer}'. Expected format 'host:port'.")
        if "localhost" in peer or "127.0.0.1" in peer:
            sys.exit(f"SECURITY/ARCH ERROR: Invalid loopback target '{peer}' in cluster mode.")
            
    print(f"Config schema valid: {len(peer_list)} peers registered.")

if __name__ == "__main__":
    validate_gubernator_env()
Validasi statis ini mengeksekusi aturan fail-fast di pipeline CI/CD: jika ada developer mendefinisikan 127.0.0.1 sebagai peer address, deployment langsung dibatalkan sebelum container dibangun.