Resolver problemas com flags de recursos

Neste guia, mostramos as etapas para diagnosticar e resolver problemas comuns com as flags de recurso do App Lifecycle Manager.

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

A API OpenFeature foi projetada para que as chamadas de avaliação de flag não gerem exceções não processadas e, em vez disso, retornem o valor padrão se ocorrer um erro de avaliação.

Sintoma: a flag retorna um valor padrão seguro

Se o serviço de flag estiver inacessível, o provedor estiver indisponível ou a flag estiver configurada incorretamente, o SDK vai retornar o valor padrão obrigatório fornecido no 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 do ambiente de execução do aplicativo tem o papel roles/saasconfig.viewer.
  3. Verifique se FLAGD_SOURCE_PROVIDER_ID está correto.

Sintoma: resultados de avaliação inesperados

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 ausente do contexto durante uma verificação de condição, o mecanismo de avaliação vai pular essa regra específica.
  3. Se um atributo estiver ausente durante uma alocação baseada em porcentagem, a avaliação vai retornar INVALID_CONTEXT.

Resolver problemas de sincronização de modelos centrados em apps e lançamentos do console

Se você integrar as flags de recurso usando os modelos compostos do Application Design Center e o console do Google Cloud , siga as etapas abaixo para resolver problemas de sincronização e lançamento de modelos.

Sintoma: os tipos de unidade não são criados após a conexão de um modelo composto do App Design Center

Se a guia Tipos de unidade na sua oferta de SaaS permanecer vazia depois que você conectar um modelo composto:

Resolução:

  1. Verifique se cada modelo de aplicativo padrão incorporado e o modelo de aplicativo composto pai foram adicionados ao catálogo no Application Design Center antes de importar o modelo composto para sua oferta de SaaS.
  2. Verifique se o agente de serviço do App Lifecycle Manager (service-PROJECT_NUMBER@gcp-sa-saasservicemgmt.) tem o papel roles/saasservicemgmt.serviceAgent no seu projeto.
  3. Verifique a página de detalhes da oferta de SaaS no console do Google Cloud ou execute gcloud beta app-lifecycle-manager saas describe SAAS_OFFERING_ID --location=global para inspecionar o status de sincronização do modelo.

Substitua:

  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • SAAS_OFFERING_ID: o ID da sua oferta de SaaS.

Sintoma: o lançamento da flag no console não atualiza uma unidade criada com base em um modelo padrão

Se o lançamento de uma flag for concluído no console do Google Cloud , mas uma unidade criada com base em um modelo padrão não receber a configuração atualizada da flag:

Resolução:

  1. Verifique se a unidade pertence ao tipo de unidade segmentado, se está em uma região incluída no lançamento e se corresponde a qualquer unitFilter configurado no tipo de lançamento.
  2. Confirme se FLAGD_SOURCE_PROVIDER_ID no aplicativo corresponde ao caminho completo do recurso de configuração da flag de recurso da unidade (projects/PROJECT_ID/locations/LOCATION/featureFlagsConfigs/UNIT_ID).

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • LOCATION: a região da unidade.
  • UNIT_ID: o ID da unidade.

Monitorar lançamentos

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

Estado de 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 com falha chegue a toda a frota, o sistema pausa automaticamente um lançamento se a taxa de falha em um local exceder a margem de erro configurada no tipo de lançamento (errorBudget.allowedCount ou errorBudget.allowedPercentage, como um limite de 10% por local).

Verificar as estatísticas resumidas

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

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

Filtrar atualizações de unidade com falha

Depois de confirmar que há falhas, você precisa encontrar as unidades específicas que não receberam a atualização. Use este filtro para isolar apenas as atualizações de sinalização 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 atuação no campo conditions (message e reason) e errorCategory (ou inspecionar stateMessage no recurso de lançamento).

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

Substitua:

  • ROLLOUT_ID: o ID do lançamento.
  • LOCATION: a região da operação de unidade.
  • OPERATION_ID: o ID da operação de unidade.

Unidade sem configurações

Nesta seção, descrevemos como a fixação de unidade pode impedir que uma unidade receba configurações de flag de recurso e como recuperar a 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 lançamentos automatizados ou manuais. 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. A fixação bloqueia todas as atualizações, o que significa que a unidade ignora 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 recurso, o aplicativo não é inicializado ou entra em um loop de repetição infinito, o que leva a falhas nas sondagens de prontidão e reinicializações contínuas do contêiner.

Causa raiz: enquanto a unidade estava fixada, os lançamentos atualizaram o campo defaultFlagRevisions do recurso de tipo de unidade pai, mas a unidade fixada pulou a operação FlagUpdate e não recebeu nenhuma configuração ativa.

Comandos de diagnóstico

Use os comandos a seguir para inspecionar as operações de atualização de flag com falha e o status da unidade.

1. Listar operações de sinalização com falha

Para encontrar unidades que não foram atualizadas, filtre as operações de unidade pelo estado UNIT_OPERATION_STATE_FAILED e pelo 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 por lançamentos de sinalizações com falha

Para identificar atualizações de sinalização com falha em toda a frota ou em uma unidade específica, adicione uma condição para o estado UNIT_OPERATION_STATE_FAILED.

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

3. Inspecionar o motivo da falha

Use o comando describe para inspecionar o campo conditions (message e reason) e errorCategory.

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

4. Verificar as condições da unidade

Também é possível verificar o estado atual de uma unidade diretamente. Se um lançamento de flag estiver falhando ou a última operação tiver resultado em um erro, a lista conditions da unidade vai conter uma entrada com type: TYPE_OPERATION_ERROR.

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

Substitua:

  • LOCATION: a região da unidade ou operação de unidade.
  • UNIT_ID: o ID da unidade.
  • OPERATION_ID: o ID da operação de unidade.

Mitigação manual

Para recuperar uma unidade fixada que não recebeu as atualizações de flag, aplique as revisões de flag padrão do tipo de unidade mãe.

Aplicar revisões de flag padrão do tipo de unidade

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

  1. Liberar a unidade (se estiver fixada):

    gcloud beta app-lifecycle-manager units update "UNIT_ID" \
    --location="LOCATION" \
    --maintenance-pinned-until-time=""

  2. Recupere as revisões padrão do tipo de unidade pai:

    gcloud beta app-lifecycle-manager unit-kinds describe "UNIT_KIND_ID" \
    --location="LOCATION" \
    --format="value(defaultFlagRevisions.join(','))"

  3. Crie um novo FlagRelease contendo essas revisões:

    gcloud beta app-lifecycle-manager flags releases create "recovery-release-1" \
    --location="LOCATION" \
    --unit-kind="UNIT_KIND_ID" \
    --revisions="REVISIONS"

  4. Inicie manualmente uma operação de unidade FlagUpdate para aplicar a versão de recuperação:

    gcloud beta app-lifecycle-manager unit-operations create "recovery-op" \
    --unit="UNIT_ID" \
    --flag-update="projects/PROJECT_ID/locations/LOCATION/flagReleases/recovery-release-1" \
    --location="LOCATION"

Substitua:

  • UNIT_ID: o ID da unidade a ser recuperada.
  • LOCATION: a região da unidade.
  • UNIT_KIND_ID: o ID do tipo de unidade pai.
  • REVISIONS: a lista separada por vírgulas de nomes de recursos de revisão de flag padrão retornados na etapa 2.
  • PROJECT_ID: o ID do projeto Google Cloud .