Aller au contenu principal

Connecter une passerelle tierce avec stoa-connect

stoa-connect est un agent Go léger qui s'exécute aux côtés de votre passerelle API existante (Kong, Gravitee ou webMethods) et la connecte au Plan de Contrôle STOA — aucun remplacement de passerelle requis.

Ce que vous allez accomplir​

À la fin de ce guide, votre passerelle tierce sera en mesure de :

  • Apparaître dans la Console STOA sous Gateways
  • Exposer ses API dans l'inventaire du Plan de Contrôle (découverte automatique toutes les 60 secondes)
  • Recevoir les politiques poussées depuis STOA automatiquement
  • Envoyer des heartbeats toutes les 30 secondes pour que la Console affiche l'état de santé en temps réel

Architecture​

VPS / On-Premise
┌─────────────────────────────────────────┐
│  Third-Party Gateway (Kong/Gravitee/wM) │
│  ← admin API ─────────────────────┐     │
│                                    │     │
│  stoa-connect agent ──────────────┘     │
│  (Go binary, port 8090)                 │
│     ├── register with CP                │
│     ├── heartbeat 30s                   │
│     ├── discover APIs 60s               │
│     └── sync policies 60s              │
└──────────────────┬──────────────────────┘
                   │ HTTPS (X-Gateway-Key)
                   ▼
         STOA Control Plane
         (${STOA_API_URL})

Prérequis​

  • Une passerelle Kong, Gravitee ou webMethods en cours d'exécution avec son API d'administration accessible localement
  • Un compte STOA sur console.gostoa.dev
  • Une clé API de passerelle obtenue depuis la Console STOA (Paramètres → Gateways → Nouvelle clé)

Étape 1 — Installer stoa-connect​

curl -sSL https://get.gostoa.dev/connect | sh

Vérifiez l'installation :

stoa-connect --version

Étape 2 — Configurer​

Créez un fichier .env (ou exportez les variables dans votre shell ou votre unité systemd) :

# Connexion au Plan de Contrôle
export STOA_CONTROL_PLANE_URL="${STOA_API_URL}"
export STOA_GATEWAY_API_KEY="gw_your_key_here"
export STOA_INSTANCE_NAME="kong-prod-01"    # détecté automatiquement depuis le hostname si omis
export STOA_ENVIRONMENT="production"

# API d'administration de la passerelle
export STOA_GATEWAY_TYPE="kong"
export STOA_GATEWAY_ADMIN_URL="http://localhost:8001"
export STOA_GATEWAY_ADMIN_TOKEN="your-kong-admin-token"
VariableObligatoireDéfautDescription
STOA_CONTROL_PLANE_URLOui—URL de base de l'API du Plan de Contrôle
STOA_GATEWAY_API_KEYOui—X-Gateway-Key pour l'authentification au Plan de Contrôle
STOA_GATEWAY_TYPEOuiautokong, gravitee ou webmethods
STOA_GATEWAY_ADMIN_URLOui—URL locale de l'API d'administration de la passerelle
STOA_INSTANCE_NAMENonhostnameIdentifiant affiché dans la Console
STOA_ENVIRONMENTNonproductionLibellé d'environnement
STOA_HEARTBEAT_INTERVALNon30sFréquence des heartbeats
STOA_CONNECT_PORTNon8090Port HTTP local de l'agent

Étape 3 — Démarrer​

stoa-connect

Au démarrage, stoa-connect va :

  1. Enregistrer la passerelle auprès du Plan de Contrôle (POST /v1/internal/gateways/register)
  2. Découvrir les API depuis l'API d'administration locale de la passerelle
  3. Démarrer la boucle de heartbeat (toutes les 30 secondes)
  4. Lancer la synchronisation des politiques (toutes les 60 secondes)

Étape 4 — Vérifier​

Vérifiez que l'agent est opérationnel :

# Vérifier l'état de l'agent (remplacez l'URL par l'adresse de votre agent)
curl -s http://localhost:8090/health | jq

Résultat attendu :

{
  "status": "ok",
  "version": "0.3.0",
  "gateway_id": "a1b2c3d4-...",
  "discovered_apis": 12
}

Ou via la CLI :

stoactl connect status --url http://localhost:8090

Confirmez que la passerelle apparaît dans la Console sur console.gostoa.dev sous Gateways. L'indicateur d'état doit devenir vert en moins de 30 secondes.

Référence CLI​

stoactl connect propose trois sous-commandes pour les opérations courantes :

# Afficher l'état de l'agent et la connectivité
stoactl connect status --url http://localhost:8090

# Déclencher une découverte d'API immédiate (sans attendre les 60s)
stoactl connect discover --admin-url http://localhost:8001

# Forcer une synchronisation des politiques depuis le Plan de Contrôle
stoactl connect sync --url http://localhost:8090

Dépannage​

SymptômeCause probableSolution
UNAUTHORIZED au démarrageSTOA_GATEWAY_API_KEY invalide ou expiréeRégénérez la clé dans Console → Paramètres → Gateways
La passerelle reste OFFLINE dans la ConsoleLe heartbeat n'atteint pas le Plan de ContrôleVérifiez que les règles du pare-feu autorisent le trafic HTTPS sortant vers ${STOA_API_URL}
0 API découverteSTOA_GATEWAY_ADMIN_URL incorrecteVérifiez avec curl ${STOA_GATEWAY_ADMIN_URL}/health
La synchronisation des politiques échoueIdentifiants d'administration rejetésVérifiez STOA_GATEWAY_ADMIN_TOKEN / USER / PASSWORD

Pour des logs structurés, définissez LOG_LEVEL=debug avant de démarrer l'agent.

Compagnon et stoa-connect​

stoa-connect est le chemin GitOps pour une passerelle tierce. Il synchronise l'état souhaité vers l'API d'administration (adaptateurs webMethods, Kong, Gravitee et Envoy dans le dépôt stoa) et reste hors du chemin de requête client.

Le compagnon est une autre intégration. Le même binaire Rust, avec STOA_GATEWAY_MODE=sidecar, répond à POST /authz pour un hôte dans le même pod ou pour un appel depuis une application. L'hôte conserve l'authentification, le routage et l'application du verdict. Ce chemin n'est pas une démo Kong ou webMethods enregistrée en conditions réelles. Les adaptateurs mesh sont des notes de conception. Voir Usage du compagnon.

Étapes suivantes​

  • Configuration multi-passerelles — gérez plusieurs passerelles depuis un seul Plan de Contrôle (bientôt disponible)
  • Enregistrement automatique de passerelle — enregistrement natif STOA sans agent (bientôt disponible)
  • Politiques OPA — rédigez des politiques que stoa-connect synchronisera avec votre passerelle (bientôt disponible)