Monitora, mantieni e risolvi i problemi dei deployment del Model Gateway, inclusi aggiornamenti della configurazione del modello, rotazione delle credenziali, monitoraggio della salute, raccolta dei log e risoluzione dei problemi comuni di connettività e autenticazione.

Dopo il deployment, la gestione operativa continua del Model Gateway aiuta a garantire un accesso affidabile ai modelli AI configurati e a ridurre al minimo le interruzioni del servizio. Gli amministratori possono esaminare le configurazioni dei modelli attive, aggiornare le credenziali del provider, ruotare i secret, monitorare la salute del gateway e raccogliere informazioni diagnostiche quando si verificano problemi.

Visualizzazione dei modelli configurati

Ci sono due livelli per visualizzare i modelli — quello che è nella configurazione e quello che bob-inference ha effettivamente caricato in fase di runtime.

Livello di configurazione — recupera la configurazione del model gateway attuale dalla ConfigMap di inference:

oc get cm bob-inference-config -n <bob-namespace> -o yaml | yq '.data."config.yaml"'

Livello di runtime — quello che bob-inference ha registrato e sta instradando attivamente: interroga direttamente l'endpoint /v1/models (vedere Valida la connettività ai modelli).

Nota:

L'endpoint di runtime /v1/models elenca solo i modelli con exposed: true. Il file di configurazione è l'unico modo per vedere il set completo dei modelli configurati.

Aggiornamento delle credenziali del provider

Le credenziali sono montate come variabili d'ambiente da bob.modelGateway.secrets. Il loro aggiornamento è un'operazione in due fasi — aggiorna il valore del secret, poi riavvia l'Inference Service per acquisire il nuovo mount.

Aggiorna il secret

Modifica la CR Bob e applica il nuovo valore:

oc edit bob <instance-name> -n <bob-namespace>
# Update the value under bob.modelGateway.secrets

Riavvia l'Inference Service

Riavvia l'Inference Service in modo che il nuovo secret venga montato:

oc rollout restart deploy/inference-service -n <bob-namespace>
oc rollout status deploy/inference-service -n <bob-namespace>

Attenzione:

Il pod dell'Inference Service deve essere riavviato dopo qualsiasi aggiornamento del secret. Le modifiche alla configurazione del modello (aggiunta o rimozione di modelli, cambio di base_url) e le modifiche ai secret possono essere raggruppate in un singolo aggiornamento della CR seguito da un solo riavvio.

Rotazione dei secret

La rotazione dei secret segue lo stesso pattern di un aggiornamento delle credenziali, con attenzione aggiuntiva ai tempi per evitare downtime.

Sequenza di rotazione consigliata a zero downtime:

Aggiorna bob.modelGateway.secrets con il nuovo valore della credenziale.

Riavvia l'Inference Service: oc rollout restart deploy/inference-service -n <bob-namespace>.

Conferma che la nuova credenziale funzioni usando il test di inference da Verifica post-installazione.

Revoca la vecchia credenziale lato provider solo dopo che il pod è confermato sano.

Note specifiche del provider:

openai_compatible / chiavi API — la nuova chiave è effettiva immediatamente al riavvio. È sicuro revocare la vecchia chiave una volta che il pod è sano.

bedrock — assicurati che la nuova chiave di accesso IAM sia attiva in AWS prima di riavviare. La propagazione IAM può richiedere alcuni secondi.

vertex — genera e codifica in base64 la nuova chiave dell'account di servizio, aggiorna il secret, riavvia e verifica, poi elimina la vecchia chiave in GCP.

ca_cert_pem — per il rinnovo del certificato, verifica che il nuovo certificato non sia scaduto prima di applicarlo. Vedere Validazione del certificato TLS.

Monitoraggio della salute del gateway

Conteggio dei riavvii del pod — un conteggio di riavvii in aumento è un segnale precoce di un guasto ricorrente all'avvio (mount del secret errato, errore di analisi della configurazione):

oc get pods -n <bob-namespace> -l app=bob-inference \
  -o custom-columns='NAME:.metadata.name,RESTARTS:.status.containerStatuses[0].restartCount'

Probe di liveness e readiness — controlla la configurazione e lo stato attuale della probe:

oc describe deploy/bob-inference -n <bob-namespace> | grep -A 10 "Liveness\|Readiness"

Controllo periodico della salute — l'endpoint /v1/models funge da semplice controllo di liveness. Se restituisce un elenco di modelli valido, il gateway è attivo. Può essere interrogato da uno strumento di monitoraggio o da un cron job all'interno del cluster.

Raccolta di log e diagnostica

Log per una finestra temporale specifica (più utile durante l'indagine di un incidente segnalato):

oc logs -n <bob-namespace> deploy/bob-inference \
  --since-time="2025-01-01T12:00:00Z" > bob-inference.log

Log da un'istanza precedente del pod (se il pod si è riavviato e i log del guasto sono scomparsi):

oc logs -n <bob-namespace> deploy/bob-inference --previous

Bundle diagnostico completo per il supporto:

oc describe pod -n <bob-namespace> -l app=bob-inference >> diagnostics.txt
oc get events -n <bob-namespace> --sort-by='.lastTimestamp' >> diagnostics.txt
oc logs -n <bob-namespace> deploy/bob-inference --since=1h >> diagnostics.txt

Nota:

Il bundle diagnostico contiene i nomi delle variabili d'ambiente del pod ma non i valori dei secret (i secret sono montati, non stampati nei log). Esamina i log per qualsiasi output accidentale di credenziali prima di inviarlo al supporto.

Risoluzione dei problemi di connettività e autenticazione

Modello non presente in /v1/models

Controlla se è impostato exposed: false — in tal caso, è il comportamento atteso.

Controlla i log di avvio per un errore di registrazione per quel model_name.

Verifica il blocco del provider — base_url, ID model e credenziali corretti.

401 Unauthorized nelle richieste di inference

Conferma che il valore del secret in bob.modelGateway.secrets sia corretto e aggiornato.

Conferma che il riferimento env.<VAR> nella configurazione del modello corrisponda esattamente al nome della chiave del secret (case-sensitive).

Riavvia l'Inference Service e riprova — il secret potrebbe essere stato aggiornato senza un riavvio.

Testa la credenziale out-of-band. Vedere Validazione dell'autenticazione.

502 Bad Gateway o connection refused

Conferma che l'endpoint del modello sia attivo e raggiungibile dal cluster. Vedere Test di connettività.

Controlla i problemi di base_url — barre finali, schema errato (http vs https), porta errata.

Controlla le modifiche alle network policy che potrebbero aver bloccato il traffico in uscita dall'installazione.

certificate signed by unknown authority

Conferma che ca_cert_pem sia impostato e faccia riferimento a una variabile d'ambiente valida.

Conferma che la variabile d'ambiente sia presente in bob.modelGateway.secrets.

Verifica che il certificato non sia scaduto: openssl x509 -noout -dates.

Conferma che il certificato copra il hostname dell'endpoint controllando i Subject Alternative Names.

Pod dell'Inference Service in CrashLoopBackOff

Controlla i log dell'istanza precedente: oc logs --previous.

Cerca errori di analisi della configurazione — YAML non valido nella configurazione del model gateway.

Cerca mount di secret mancanti nella sezione Events: oc describe pod.

Conferma che il YAML della configurazione del model gateway sia valido prima di riapplicarlo.

Operazioni e risoluzione dei problemi