La passerelle refuse de démarrer

La passerelle refuse de démarrer quand une variable indispensable est absente ou quand une configuration est incohérente ; elle ne démarre pas avec un repli. Le message de démarrage nomme ce qui manque. Commencez par le lire.

DATABASE_URL est absente

La passerelle lit sa configuration (endpoints, modèles, moteurs d’inférence) dans sa base. Sans adresse de base, elle n’a rien à servir.

export DATABASE_URL="postgresql://<utilisateur>:<mot-de-passe>@<hôte>:<port>/<base>"

N’ajoutez aucun paramètre de chiffrement à cette adresse : c’est une cause de refus à part entière, traitée à la section suivante.

Un paramètre de chiffrement dans l’adresse de la base

Cette cause vient souvent d’un réglage ajouté pour faire marcher la connexion. Cinq paramètres de l’adresse font refuser le démarrage :

sslmode, ssl, sslrootcert, sslcert, sslkey

La bibliothèque PostgreSQL donne la priorité à ce que porte l’adresse sur ce que le code a posé. Un seul de ces paramètres remplace toute la configuration de chiffrement, y compris l’autorité de certification que vous avez déclarée. La passerelle s’arrête et nomme le paramètre.

Le refus ne concerne que les bases distantes. Une base sur la machine elle-même (localhost, 127.0.0.1, une socket de fichier) se joint sans TLS, et rien n’y est refusé.

Ce qu’il faut faire

Retirez le paramètre de l’adresse. Puis, si la base présente un certificat signé par une autorité interne, déclarez cette autorité :

export DATABASE_URL="postgresql://<utilisateur>:<mot-de-passe>@<hôte>:<port>/<base>"
export DATABASE_CA_CERT_PATH="/etc/ssl/certs/<autorité-interne>.pem"

Là où la plateforme qui exécute la passerelle ne passe que des variables et ne monte aucun fichier, DATABASE_CA_CERT porte le contenu du certificat au lieu de son chemin. Posez l’une ou l’autre : les deux à la fois font refuser le démarrage.

Aucun réglage ne désactive la vérification du certificat. Une base dont le certificat n’est pas validable se traite en ajoutant son autorité.

L’hôte de l’adresse : un nom DNS

Écrivez l’hôte de DATABASE_URL en nom DNS, pas en adresse IP. Pour une adresse IP, le client PostgreSQL ne transmet aucun nom de serveur, et la vérification retombe sur « localhost », qu’aucun certificat de base ne porte. La connexion échoue alors sur un message qui parle du nom.

ADMIN_API_KEY est absente

C’est la clé d’API du compte administrateur, que la passerelle crée à son premier démarrage. En profil hébergé, la passerelle refuse de démarrer sans elle. En profil on-premise, cette variable n’est pas lue : les identités viennent de l’annuaire de l’entreprise.

export ADMIN_API_KEY="<la clé d'administration de cette installation>"

Elle démarre, mais chaque requête échoue

Le symptôme est différent : la passerelle est saine, c’est le relais vers le moteur d’inférence qui échoue. La passerelle n’a aucune destination hors de votre périmètre (livre blanc sécurité V3, section 3.3) : les causes sont à chercher sur le trajet interne qui la sépare du moteur. Trois causes fréquentes.

Le moteur exige une clé, et sa variable n’est pas définie. Le nom de la variable attendue n’est pas figé dans le code : il est inscrit en base, dans la colonne api_key_env du moteur déclaré. Une omission ne se voit qu’à la première requête, sous la forme d’une réponse 500 qui nomme la variable. Relevez le nom attendu dans la console d’administration, puis définissez la variable.

Le certificat du moteur est signé par une autorité interne que la passerelle ne connaît pas. NODE_EXTRA_CA_CERTS désigne cette autorité ; ce magasin s’ajoute aux racines du système, sur tous les chemins vers le moteur, y compris quand UPSTREAM_TLS_CA_FILE ou un certificat client est configuré. Aucun réglage ne désactive la vérification du certificat du moteur.

Le filtrage réseau ne laisse pas l’hôte de la passerelle joindre le moteur, ou un proxy interne est déclaré à tort pour ce trajet. La passerelle suit le proxy que son environnement déclare : HTTPS_PROXY pour une cible https, HTTP_PROXY pour une cible http et en repli des cibles https, NO_PROXY pour les hôtes joints en direct, ce qui permet au moteur d’inférence de ne pas passer par le proxy. Si aucune de ces variables n’est posée, la passerelle joint le moteur en direct. Le journal de démarrage annonce le proxy retenu pour chaque protocole, les hôtes exclus et le magasin de confiance en usage, ou bien qu’aucun proxy n’est configuré. Commencez par lire cette ligne.

Deux erreurs de configuration arrêtent la passerelle au démarrage, avec le nom de la variable en cause : une valeur de proxy qui n’est pas une URL complète, et un NODE_EXTRA_CA_CERTS qui désigne un fichier illisible. Le détail de chaque variable : Variables d’environnement de la passerelle.

Vérifier que la passerelle répond

Il n’existe pas de route de santé dédiée. Le contrôle consiste à appeler une route inexistante et à vérifier qu’elle répond 401, ce qui montre que le service écoute et que l’authentification s’applique :

curl -s -o /dev/null -w '%{http_code}\n' https://<hôte>:<port>/healthz/v1/models

Une réponse 401 est le résultat attendu. Une absence de réponse signifie que le service n’écoute pas.