Resolver problemas com flags de recursos

Este guia fornece etapas para diagnosticar e resolver problemas comuns com flags de recursos do App Lifecycle Manager.

Avaliação do SDK e do ambiente de execução

A API OpenFeature foi projetada para oferecer máxima segurança e nunca vai gerar um erro que cause falha no seu aplicativo.

Sintoma: flag retornando o valor padrão seguro

Se o serviço de flags estiver inacessível, o provedor não estiver disponível ou a flag estiver mal configurada, o SDK vai retornar o valor padrão obrigatório fornecido no seu código.

Resolução:

  1. Verifique a conexão entre o provedor do OpenFeature e o endpoint saasconfig.googleapis.com.
  2. Verifique se há erros de autenticação. Verifique se a conta de serviço tem roles/saasconfig.viewer.
  3. Verifique se FLAGD_SOURCE_PROVIDER_ID está correto.

Sintoma: resultados inesperados da avaliação

Se uma flag não estiver retornando a variante esperada:

Resolução:

  1. Verifique as condições da CEL e o contexto de avaliação.
  2. Se um atributo obrigatório estiver faltando no contexto durante uma verificação de condição, o mecanismo de avaliação vai ignorar essa regra específica.
  3. Se um atributo estiver ausente durante uma alocação baseada em porcentagem, a avaliação vai retornar INVALID_CONTEXT.

Monitorar lançamentos

Monitorar o lançamento de uma flag de recurso envolve verificar o estado da orquestração (o lançamento foi concluído?) e a integridade do aplicativo (o binário capturou a flag?).

Estado da orquestração do lançamento

O sistema monitora a taxa de sucesso das operações em tempo real.

Pausa automática

Para evitar que uma configuração "corrompida" atinja toda a frota, o sistema pausa automaticamente um lançamento se a taxa de falha exceder o orçamento de erros (padrão de 10% por local).

Verificar as estatísticas de resumo

Use o comando describe para conferir a contagem agregada de falhas e determinar se o lançamento é PAUSED ou FAILED.

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

Filtrar atualizações de unidades com falha

Depois de confirmar que há falhas, encontre as unidades específicas que não receberam a atualização. Use este filtro para isolar apenas as atualizações de flag com falha em uma região específica:

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

Diagnosticar a causa raiz

Para cada operação com falha, é possível recuperar uma mensagem de erro detalhada fornecida pelo mecanismo de ação. Leia o campo state_message.

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

Configurações ausentes da unidade

Noções básicas sobre a fixação de unidades

A fixação congela uma unidade na versão atual, impedindo que ela seja atualizada por qualquer lançamento automatizado ou manual. Uma unidade fixada é explicitamente excluída das operações de lançamento até que o período de fixação expire ou ela seja desafixada manualmente.

Configuração ausente das unidades fixadas

Um cenário crítico ocorre quando uma unidade é fixada durante o lançamento de uma flag de recurso. O fixação bloqueia todas as atualizações, o que significa que a unidade pula a operação FlagUpdate necessária para receber a configuração.

Sintoma:depois que a unidade é desfixada e atualizada para um binário que exige flags de recursos, o aplicativo não é inicializado ou entra em um loop infinito de novas tentativas, o que leva a falhas nas sondagens de preparo e reinicializações contínuas de contêineres.

Causa principal:os default_flag_revisions de UnitKind não foram atualizados enquanto a unidade estava fixada, deixando-a sem uma configuração ativa.

Comandos de diagnóstico

1. Listar operações de flag com falha

Para encontrar unidades que não receberam uma atualização, filtre as operações de unidade pelo estado UNIT_OPERATION_STATE_FAILED e o tipo flag_update.

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

2. Filtrar especificamente os lançamentos de flags com falha

Para identificar atualizações de flags com falha em toda a frota ou em uma unidade específica, adicione uma condição para o estado 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. Inspecionar o motivo da falha

Use o comando describe para ler o state_message.

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

4. Verificar condição da unidade

Você também pode verificar o estado atual de uma unidade diretamente. Se um lançamento de flag estiver falhando ou se a última operação tiver resultado em um erro, isso será refletido no status. Condições com um tipo de operationError.

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

Mitigação manual

Aplicando revisões de flag padrão UnitKind

Se uma unidade não tiver a configuração porque foi fixada durante um ou mais lançamentos, recupere-a redefinindo manualmente a unidade para o valor de referência atual definido no UnitKind.

  1. Libere a unidade (se estiver fixada).
  2. Recupere as revisões padrão do UnitKind pai.
  3. Crie um novo FlagRelease com essas revisões.
  4. Inicie manualmente uma operação de unidade FlagUpdate para aplicar a versão de recuperação.
# 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"