Soluciona problemas relacionados con las marcas de función

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

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

La API de OpenFeature está diseñada para que las llamadas de evaluación de marcas no arrojen excepciones no controladas y, en su lugar, devuelvan el valor predeterminado si se produce un error de evaluación.

Síntoma: El parámetro de configuración devuelve un valor predeterminado seguro

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

Resolución:

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

Síntoma: Resultados de evaluación inesperados

Si un parámetro no devuelve la variante esperada, haz lo siguiente:

Resolución:

  1. Verifica las 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 devuelve INVALID_CONTEXT.

Soluciona problemas de sincronización de plantillas centradas en apps y de lanzamientos de la consola

Si te incorporas a las marcas de funciones con las plantillas compuestas de Application Design Center y la consola de Google Cloud , sigue estos pasos para resolver los problemas de sincronización y lanzamiento de plantillas.

Síntoma: No se crean tipos de unidades después de conectar una plantilla compuesta de App Design Center

Si la pestaña Tipos de unidades de tu oferta de SaaS permanece vacía después de conectar una plantilla compuesta, haz lo siguiente:

Resolución:

  1. Verifica que cada plantilla de aplicación estándar incorporada y la plantilla de aplicación compuesta superior se hayan agregado al catálogo en Application Design Center antes de importar la plantilla compuesta a tu oferta de SaaS.
  2. Verifica que el agente de servicio de App Lifecycle Manager (service-PROJECT_NUMBER@gcp-sa-saasservicemgmt.) tenga el rol roles/saasservicemgmt.serviceAgent en tu proyecto.
  3. Consulta la página de detalles de la oferta de SaaS en la consola de Google Cloud o ejecuta gcloud beta app-lifecycle-manager saas describe SAAS_OFFERING_ID --location=global para inspeccionar el estado de sincronización de la plantilla.

Reemplaza lo siguiente:

  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
  • SAAS_OFFERING_ID: Es el ID de tu oferta de SaaS.

Síntoma: El lanzamiento de la marca en la consola no actualiza una unidad creada a partir de una plantilla estándar

Si el lanzamiento de una marca se completa en la consola de Google Cloud , pero una unidad creada a partir de una plantilla estándar no recibe la configuración de marca actualizada, haz lo siguiente:

Resolución:

  1. Verifica que la unidad pertenezca al tipo de unidad de destino, esté en una región incluida en el lanzamiento y coincida con cualquier unitFilter configurado en el tipo de lanzamiento.
  2. Confirma que FLAGD_SOURCE_PROVIDER_ID en tu aplicación coincida con la ruta de acceso completa del recurso de configuración de la marca de función de la unidad (projects/PROJECT_ID/locations/LOCATION/featureFlagsConfigs/UNIT_ID).

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la región de tu unidad.
  • UNIT_ID: Es el ID de tu unidad.

Supervisa los lanzamientos

La supervisión del lanzamiento de un indicador 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 detectó el indicador?).

Estado de la organización del lanzamiento

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

Pausa automática

Para evitar que una configuración defectuosa llegue a toda tu flota, el sistema pausa automáticamente un lanzamiento si la tasa de fallas en una ubicación supera el porcentaje de error aceptable configurado en el tipo de lanzamiento (errorBudget.allowedCount o errorBudget.allowedPercentage, como un umbral del 10% por ubicación).

Cómo consultar las estadísticas de resumen

Usa el comando describe para ver el recuento de fallas agregadas y determinar si el lanzamiento es PAUSED o FAILED.

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

Filtrar actualizaciones de unidades con errores

Después de confirmar 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 ejecución de acciones en el campo conditions (message y reason) y errorCategory (o inspeccionar stateMessage en el recurso de lanzamiento).

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

Reemplaza lo siguiente:

  • ROLLOUT_ID: Es el ID del lanzamiento.
  • LOCATION: Es la región de la operación de la unidad.
  • OPERATION_ID: Es el ID de la operación de la unidad.

Faltan parámetros de configuración de la unidad

En esta sección, se describe cómo la fijación de unidades puede evitar que una unidad reciba parámetros de configuración de marcas de funciones y cómo recuperar la unidad.

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 la configuración de 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 desvincula la unidad y se actualiza a un objeto binario que requiere marcas de funciones, la aplicación no se inicializa o entra en un bucle de reintentos infinito, lo que genera fallas en los sondeos de preparación y reinicios continuos del contenedor.

Causa raíz: Mientras la unidad estaba fijada, los lanzamientos actualizaron el campo defaultFlagRevisions del recurso de tipo de unidad superior, pero la unidad fijada omitió la operación FlagUpdate y no recibió ninguna configuración activa.

Comandos de diagnóstico

Usa los siguientes comandos para inspeccionar las operaciones de actualización de marcas con errores y el estado de la unidad.

1. Enumera las operaciones de marcas con errores

Para encontrar las unidades que no se actualizaron, filtra las operaciones de la unidad por 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. Filtrar específicamente los lanzamientos de marcas con errores

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

Usa el comando describe para inspeccionar el campo conditions (message y reason) y errorCategory.

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 el lanzamiento de un parámetro de configuración falla o la última operación generó un error, la lista conditions de la unidad contiene una entrada con type: TYPE_OPERATION_ERROR.

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

Reemplaza lo siguiente:

  • LOCATION: Es la región de la unidad o de la operación de la unidad.
  • UNIT_ID: Es el ID de la unidad.
  • OPERATION_ID: Es el ID de la operación de la unidad.

Mitigación manual

Para recuperar una unidad fijada que no recibió las actualizaciones de marcas, aplica las revisiones de marcas predeterminadas de su tipo de unidad superior.

Aplicar las revisiones de marcas predeterminadas del tipo de unidad

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 base actual definida en su tipo de unidad.

  1. Deja de fijar la unidad (si está fijada):

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

  2. Recupera las revisiones predeterminadas del tipo de unidad superior:

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

  3. Crea un FlagRelease nuevo que contenga esas revisiones:

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

  4. Inicia de forma manual una operación de unidad FlagUpdate para aplicar la versión de recuperación:

    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"

Reemplaza lo siguiente:

  • UNIT_ID: Es el ID de la unidad que se recuperará.
  • LOCATION: Es la región de la unidad.
  • UNIT_KIND_ID: Es el ID del tipo de unidad superior.
  • REVISIONS: Es la lista separada por comas de los nombres de recursos de revisión de marcas predeterminados que se devolvieron en el paso 2.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .