Admin API

Token-authenticated API do podglądu i sterowania backendami. Bearer token, fail-closed, endpointy i przykłady curl.

Uwierzytelnianie#

Admin API wymaga bearer tokenu z ADMIN_TOKEN:

bash

export ADMIN_TOKEN=super-secret-token

Porównanie tokenu jest constant-time (ochrona przed timing attack).
Bez ADMIN_TOKEN API nie jest serwowane wcale — fail-closed, nie fail-open.
Token żyje tylko w environment, nigdy w YAML.

Endpointy#

Metoda	Ścieżka	Opis
`GET`	`/admin/backends`	Lista backendów: health, admin status, in-flight
`POST`	`/admin/backends/{index}/down`	Wyłącz backend z rotacji
`POST`	`/admin/backends/{index}/up`	Przywróć backend do rotacji

Podgląd backendów#

bash

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8080/admin/backends

json

{
  "backends": [
    {
      "url": "http://localhost:8081",
      "healthy": true,
      "admin_down": false,
      "in_flight": 3
    },
    {
      "url": "http://localhost:8082",
      "healthy": false,
      "admin_down": false,
      "in_flight": 0
    }
  ]
}

Sterowanie rotacją#

bash

curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8080/admin/backends/0/down

curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://localhost:8080/admin/backends/0/up

admin_down jest niezależny od health checków — backend może być zdrowy, ale wyłączony ręcznie (np. na czas deployu).

Przykład: kontrolowany deploy backendu#

Wyłącz backend z rotacji: POST /admin/backends/0/down.
Poczekaj, aż in_flight spadnie do zera.
Zdeployuj nową wersję backendu.
Sprawdź health: GET /admin/backends → healthy: true.
Przywróć do rotacji: POST /admin/backends/0/up.

Błędy#

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid admin token"
  },
  "request_id": "a1b2c3d4e5f6"
}

Kod	HTTP	Kiedy
`unauthorized`	401	Zły lub brak tokenu
`invalid_backend_index`	400	Indeks poza zakresem

Bezpieczeństwo odpowiedzi#

Odpowiedzi Admin API mają security headers, a sam endpoint jest chroniony przed CSRF przez wymóg tokenu w nagłówku (nie w cookie).

Ogranicz dostęp sieciowy

Admin API powinno być dostępne tylko z sieci wewnętrznej lub przez VPN. Token to ostatnia warstwa obrony, nie jedyna — wystawienie /admin/* do internetu to zły pomysł nawet z silnym tokenem.

Skrypt operacyjny#

bash

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

PROXY=http://localhost:8080
TOKEN=${ADMIN_TOKEN:?ustaw ADMIN_TOKEN}

list_backends() {
  curl -sf -H "Authorization: Bearer $TOKEN" "$PROXY/admin/backends" | jq .
}

drain_backend() {
  local index=$1
  curl -sf -X POST -H "Authorization: Bearer $TOKEN" "$PROXY/admin/backends/$index/down"
  echo "Backend $index wyłączony z rotacji"
}

case ${1:-list} in
  list) list_backends ;;
  drain) drain_backend "${2:?podaj indeks}" ;;
  restore) curl -sf -X POST -H "Authorization: Bearer $TOKEN" "$PROXY/admin/backends/$2/up" ;;
esac