Risolvere i problemi relativi ai flag funzionalità

Questa guida fornisce i passaggi per diagnosticare e risolvere i problemi comuni con i flag delle funzionalità di App Lifecycle Manager.

Valutazione di SDK e runtime

L'API OpenFeature è progettata per la massima sicurezza e non genererà mai un errore che blocca l'applicazione.

Sintomo: il flag restituisce il valore predefinito sicuro

Se il servizio di flag non è raggiungibile, il provider non è disponibile o il flag non è configurato correttamente, l'SDK restituisce il valore predefinito richiesto fornito nel codice.

Risoluzione:

  1. Verifica la connessione tra il provider OpenFeature e l'endpoint saasconfig.googleapis.com.
  2. Verifica la presenza di errori di autenticazione. Assicurati che il account di servizio abbia roles/saasconfig.viewer.
  3. Verifica che FLAGD_SOURCE_PROVIDER_ID sia corretto.

Sintomo: risultati di valutazione imprevisti

Se un flag non restituisce la variante prevista:

Risoluzione:

  1. Controlla le condizioni CEL e il contesto di valutazione.
  2. Se manca un attributo obbligatorio nel contesto durante un controllo delle condizioni, il motore di valutazione salta la regola specifica.
  3. Se manca un attributo durante un'allocazione basata sulla percentuale, la valutazione restituisce INVALID_CONTEXT.

Monitorare le implementazioni

Il monitoraggio dell'implementazione di un flag funzionalità comporta la verifica sia dello stato di orchestrazione (l'implementazione è stata completata?) sia dello stato di salute dell'applicazione (il file binario ha rilevato il flag?).

Stato di orchestrazione dell'implementazione

Il sistema monitora la percentuale di successo delle operazioni in tempo reale.

Messa in pausa automatica

Per evitare che una configurazione "interrotta" raggiunga l'intero parco risorse, il sistema mette automaticamente in pausa un'implementazione se la percentuale di errori supera il budget di errore (valore predefinito 10% per località).

Controllare le statistiche di riepilogo

Utilizza il comando describe per visualizzare il conteggio totale degli errori e determinare se l'implementazione è PAUSED o FAILED.

gcloud beta app-lifecycle-manager rollouts describe ROLLOUT_ID --location=global

Filtrare gli aggiornamenti delle unità non riusciti

Una volta confermata l'esistenza di errori, devi trovare le unità specifiche che non hanno ricevuto l'aggiornamento. Utilizza questo filtro per isolare solo gli aggiornamenti dei flag non riusciti in una regione specifica:

gcloud beta app-lifecycle-manager unit-operations list \
    --location=LOCATION \
    --filter="state:UNIT_OPERATION_STATE_FAILED AND flag_update:*"

Diagnosticare la causa principale

Per ogni operazione non riuscita, puoi recuperare un messaggio di errore dettagliato fornito dal motore di attuazione. Leggi il campo state_message.

gcloud beta app-lifecycle-manager unit-operations describe OPERATION_ID --location=LOCATION

Configurazioni mancanti dell'unità

Informazioni sul blocco delle unità

Il blocco blocca un'unità nella release corrente, impedendo che venga aggiornata da implementazioni automatiche o manuali. Un'unità bloccata viene esclusa esplicitamente dalle operazioni di implementazione fino alla scadenza del periodo di blocco o fino a quando non viene sbloccata manualmente.

Configurazione mancante dalle unità bloccate

Si verifica uno scenario critico quando un'unità viene bloccata durante l'implementazione di un flag funzionalità. Il blocco impedisce tutti gli aggiornamenti, il che significa che l'unità salta l'operazione FlagUpdate necessaria per ricevere la configurazione.

Sintomo: dopo che l'unità viene sbloccata e aggiornata a un file binario che richiede flag di funzionalità, l'applicazione non riesce a inizializzarsi o entra in un ciclo di tentativi infiniti, con conseguenti probe di idoneità non riuscite e riavvii continui dei container.

Causa principale: default_flag_revisions di UnitKind non sono stati aggiornati mentre l'unità era bloccata, quindi l'unità non ha una configurazione attiva.

Comandi di diagnostica

1. Elencare le operazioni dei flag non riuscite

Per trovare le unità che non hanno ricevuto un aggiornamento, filtra le operazioni delle unità per lo stato UNIT_OPERATION_STATE_FAILED e il tipo flag_update.

gcloud beta app-lifecycle-manager unit-operations list \
    --location="LOCATION" \
    --filter="state:UNIT_OPERATION_STATE_FAILED AND flag_update:*"

2. Filtrare in modo specifico le implementazioni dei flag non riuscite

Per individuare gli aggiornamenti dei flag non riusciti nel parco risorse o per un'unità specifica, aggiungi una condizione per lo stato UNIT_OPERATION_STATE_FAILED.

# Find all failed operations for a specific unit
gcloud beta app-lifecycle-manager unit-operations list \
    --location="LOCATION" \
    --filter="unit:UNIT_ID AND state:UNIT_OPERATION_STATE_FAILED"

3. Esaminare il motivo dell'errore

Utilizza il comando describe per leggere state_message.

gcloud beta app-lifecycle-manager unit-operations describe "OPERATION_ID" --location="LOCATION"

4. Controllare la condizione dell'unità

Puoi anche controllare direttamente lo stato attuale di un'unità. Se un'implementazione di un flag non riesce o l'ultima operazione ha generato un errore, lo stato lo rifletterà. Condizioni con un tipo di operationError.

gcloud beta app-lifecycle-manager units describe "UNIT_ID" --location="LOCATION"

Mitigazione manuale

Applicare le revisioni dei flag predefinite di UnitKind

Se a un'unità manca la configurazione perché è stata bloccata durante una o più implementazioni, puoi recuperarla reimpostando manualmente l'unità sulla baseline corrente definita in UnitKind.

  1. Sblocca l'unità (se bloccata).
  2. Recupera le revisioni predefinite da UnitKind principale.
  3. Crea una nuova FlagRelease contenente queste revisioni.
  4. Avvia manualmente un'operazione dell'unità FlagUpdate per applicare la release di ripristino.
# 1. Unpin
gcloud beta app-lifecycle-manager units update "UNIT_ID" \
    --location="LOCATION" \
    --maintenance-pinned-until-time=""

# 2. Retrieve default revisions
gcloud beta app-lifecycle-manager unit-kinds describe "UNIT_KIND_ID" \
    --location="global" \
    --format="value(defaultFlagRevisions)"

# 3. Create recovery release
gcloud beta app-lifecycle-manager flags releases create "recovery-release-1" \
    --location="global" \
    --unit-kind="UNIT_KIND_ID" \
    --revisions="REVISIONS"

# 4. Initiate manual update
gcloud beta app-lifecycle-manager unit-operations create "recovery-op" \
    --unit="UNIT_ID" \
    --flag-release="recovery-release-1" \
    --location="global"