Soluciona problemas relacionados con las marcas de función

En esta guía, se proporcionan los pasos para diagnosticar y resolver problemas comunes con las marcas de funciones de App Lifecycle Manager.

Evaluación del SDK y del entorno de ejecución

La API de OpenFeature está diseñada para brindar la máxima seguridad y nunca mostrará un error que bloquee tu aplicación.

Síntoma: La marca muestra un valor predeterminado seguro

Si no se puede acceder al servicio de marcas, el proveedor no está disponible o la marca no está configurada correctamente, el SDK muestra el valor predeterminado requerido que se proporciona en tu código.

Resolución:

  1. Verifica la conexión entre tu proveedor de OpenFeature y el extremo saasconfig.googleapis.com.
  2. Busca errores de autenticación. Asegúrate de que la cuenta de servicio tenga roles/saasconfig.viewer.
  3. Verifica que FLAGD_SOURCE_PROVIDER_ID sea correcto.

Síntoma: Resultados de evaluación inesperados

Si una marca no muestra la variante esperada, haz lo siguiente:

Resolución:

  1. Verifica tus condiciones de CEL y el contexto de evaluación.
  2. Si falta un atributo obligatorio en el contexto durante una verificación de condición, el motor de evaluación omite esa regla específica.
  3. Si falta un atributo durante una asignación basada en porcentajes, la evaluación muestra INVALID_CONTEXT.

Supervisa los lanzamientos

La supervisión del lanzamiento de una marca de función implica verificar el estado de la organización (¿se completó el lanzamiento?) y el estado de la aplicación (¿el objeto binario seleccionó la marca?).

Estado de la organización del lanzamiento

El sistema supervisa la tasa de éxito de las operaciones en tiempo real.

Pausado automático

Para evitar que una configuración "rota" llegue a toda tu flota, el sistema pausa automáticamente un lanzamiento si la tasa de fallas supera el presupuesto de errores (10% predeterminado por ubicación).

Consulta las estadísticas de resumen

Usa el comando describe para ver el recuento total de fallas y determinar si el lanzamiento está PAUSED o FAILED.

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

Filtra las actualizaciones de unidades con errores

Una vez que confirmes que existen fallas, debes encontrar las unidades específicas que no recibieron la actualización. Usa este filtro para aislar solo las actualizaciones de marcas con errores en una región específica:

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

Diagnostica la causa raíz

Para cada operación con errores, puedes recuperar un mensaje de error detallado que proporciona el motor de activación. Lee el campo state_message.

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

Faltan configuraciones de unidades

Información sobre la fijación de unidades

La fijación congela una unidad en su versión actual, lo que impide que se actualice con lanzamientos automáticos o manuales. Una unidad fijada se excluye de forma explícita de las operaciones de lanzamiento hasta que venza su período de fijación o se deje de fijar de forma manual.

Falta configuración en las unidades fijadas

Se produce una situación crítica cuando se fija una unidad durante el lanzamiento de una marca de función. La fijación bloquea todas las actualizaciones, lo que significa que la unidad omite la operación FlagUpdate necesaria para recibir su configuración.

Síntoma: Después de que se deja de fijar la unidad y se actualiza a un objeto binario que requiere marcas de funciones, la aplicación no se inicializa o ingresa en un bucle de reintento infinito, lo que genera fallas en las sondas de preparación y reinicios continuos del contenedor.

Causa raíz: No se actualizaron los default_flag_revisions de UnitKind mientras la unidad estaba fijada, lo que dejó la unidad sin configuración activa.

Comandos de diagnóstico

1. Enumera las operaciones de marcas con errores

Para encontrar las unidades que no recibieron una actualización, filtra las operaciones de unidades para el estado UNIT_OPERATION_STATE_FAILED y el tipo flag_update.

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

2. Filtra específicamente los lanzamientos de marcas con errores

Para identificar las actualizaciones de marcas con errores en toda tu flota o para una unidad específica, agrega una condición para el 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. Inspecciona el motivo de la falla

Usa el comando describe para leer el state_message.

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

4. Verifica el estado de la unidad

También puedes verificar el estado actual de una unidad directamente. Si un lanzamiento de marca falla actualmente o la última operación generó un error, se reflejará en el estado. Condiciones con un tipo de operationError.

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

Mitigación manual

Aplica las revisiones de marcas predeterminadas de UnitKind

Si a una unidad le falta su configuración porque se fijó durante uno o más lanzamientos, puedes recuperarla restableciendo manualmente la unidad a la línea de base actual definida en su UnitKind.

  1. Deja de fijar la unidad (si está fijada).
  2. Recupera las revisiones predeterminadas de la UnitKind superior.
  3. Crea una FlagRelease nueva que contenga esas revisiones.
  4. Inicia manualmente una operación de unidad FlagUpdate para aplicar la versión de recuperación.
# 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"