Résoudre les problèmes liés aux flags de fonctionnalité

Ce guide explique comment diagnostiquer et résoudre les problèmes courants liés aux flags de fonctionnalité App Lifecycle Manager.

Évaluation du SDK et de l'environnement d'exécution

L'API OpenFeature est conçue de sorte que les appels d'évaluation de flag ne génèrent pas d'exceptions non gérées et renvoient la valeur par défaut si une erreur d'évaluation se produit.

Symptôme : le flag renvoie une valeur par défaut sécurisée

Si le service de flag n'est pas accessible, si le fournisseur n'est pas disponible ou si le flag est mal configuré, le SDK renvoie la valeur par défaut requise fournie dans votre code.

Solution :

  1. Vérifiez la connexion entre votre fournisseur OpenFeature et le point de terminaison saasconfig.googleapis.com.
  2. Recherchez les erreurs d'authentification. Assurez-vous que le compte de service d'exécution de votre application dispose du rôle roles/saasconfig.viewer.
  3. Vérifiez que FLAGD_SOURCE_PROVIDER_ID est correct.

Symptôme : résultats d'évaluation inattendus

Si un flag ne renvoie pas la variante attendue :

Solution :

  1. Vérifiez vos conditions CEL et votre contexte d'évaluation.
  2. Si un attribut obligatoire est manquant dans le contexte lors d'une vérification de condition, le moteur d'évaluation ignore cette règle spécifique.
  3. Si un attribut est manquant lors d'une allocation basée sur un pourcentage, l'évaluation renvoie INVALID_CONTEXT.

Résoudre les problèmes de synchronisation des modèles App-Centric et de déploiement de la console

Si vous intégrez des flags de fonctionnalité à l'aide des modèles composites et de la console Google Cloud d'Application Design Center, suivez les étapes ci-dessous pour résoudre les problèmes de synchronisation et de déploiement des modèles.

Symptôme : Les genres d'unité ne sont pas créés après la connexion d'un modèle composite App Design Center

Si l'onglet Genres d'unités de votre offre SaaS reste vide après la connexion d'un modèle composite :

Solution :

  1. Vérifiez que chaque modèle d'application standard intégré et le modèle d'application composite parent ont été ajoutés au catalogue dans Application Design Center avant d'importer le modèle composite dans votre offre SaaS.
  2. Vérifiez que l'agent de service App Lifecycle Manager (service-PROJECT_NUMBER@gcp-sa-saasservicemgmt.) dispose du rôle roles/saasservicemgmt.serviceAgent dans votre projet.
  3. Consultez la page d'informations de l'offre SaaS dans la console Google Cloud ou exécutez gcloud beta app-lifecycle-manager saas describe SAAS_OFFERING_ID --location=global pour inspecter l'état de synchronisation du modèle.

Remplacez les éléments suivants :

  • PROJECT_NUMBER : numéro de votre projet Google Cloud .
  • SAAS_OFFERING_ID : ID de votre offre SaaS.

Symptôme : Le déploiement d'un flag dans la console ne met pas à jour un bloc créé à partir d'un modèle standard

Si le déploiement d'un flag se termine dans la console Google Cloud , mais qu'une unité créée à partir d'un modèle standard ne reçoit pas la configuration de flag mise à jour :

Solution :

  1. Vérifiez que l'unité appartient au genre d'unité ciblé, qu'elle se trouve dans une région incluse dans le déploiement et qu'elle correspond à tout unitFilter configuré sur le genre de déploiement.
  2. Vérifiez que FLAGD_SOURCE_PROVIDER_ID dans votre application correspond au chemin d'accès complet de la ressource de configuration du flag de fonctionnalité de l'unité (projects/PROJECT_ID/locations/LOCATION/featureFlagsConfigs/UNIT_ID).

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : région de votre unité.
  • UNIT_ID : ID de votre unité.

Surveiller les déploiements

La surveillance du déploiement d'un flag de fonctionnalité implique de vérifier à la fois l'état de l'orchestration (le déploiement est-il terminé ?) et l'état de l'application (le binaire a-t-il récupéré le flag ?).

État de l'orchestration du déploiement

Le système surveille le taux de réussite des opérations en temps réel.

Mise en veille automatique

Pour éviter qu'une configuration défectueuse n'atteigne l'ensemble de votre parc, le système suspend automatiquement un déploiement si le taux d'échec dans un emplacement dépasse le budget d'erreur configuré sur le type de déploiement (errorBudget.allowedCount ou errorBudget.allowedPercentage, par exemple un seuil de 10 % par emplacement).

Consulter les statistiques récapitulatives

Utilisez la commande describe pour afficher le nombre total d'échecs et déterminer si le déploiement est PAUSED ou FAILED.

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

Filtrer les mises à jour d'unités ayant échoué

Après avoir confirmé l'existence d'échecs, vous devez identifier les unités spécifiques qui n'ont pas reçu la mise à jour. Utilisez ce filtre pour n'isoler que les mises à jour de flag ayant échoué dans une région spécifique :

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

Diagnostiquer la cause principale

Pour chaque opération ayant échoué, vous pouvez récupérer un message d'erreur détaillé fourni par le moteur d'actionnement dans le champ conditions (message et reason) et errorCategory (ou inspecter stateMessage sur la ressource de déploiement).

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

Remplacez les éléments suivants :

  • ROLLOUT_ID : ID du déploiement.
  • LOCATION : région de l'opération unitaire.
  • OPERATION_ID : ID de l'opération unitaire.

Configurations manquantes de l'unité

Cette section explique comment l'épinglage d'une unité peut l'empêcher de recevoir des configurations de flag de fonctionnalité et comment récupérer l'unité.

Comprendre l'épinglage d'unités

Le blocage fige une unité à sa version actuelle, ce qui l'empêche d'être mise à jour par des déploiements automatiques ou manuels. Une unité épinglée est explicitement exclue des opérations de déploiement jusqu'à l'expiration de sa période d'épinglage ou jusqu'à ce qu'elle soit désépinglée manuellement.

Configuration manquante pour les unités épinglées

Un scénario critique se produit lorsqu'une unité est épinglée lors du déploiement d'un flag de fonctionnalité. L'épinglage bloque toutes les mises à jour, ce qui signifie que l'appareil ignore l'opération FlagUpdate requise pour recevoir sa configuration.

Symptôme : Une fois l'unité désépinglée et mise à niveau vers un binaire qui nécessite des flags de fonctionnalité, l'application ne parvient pas à s'initialiser ou entre dans une boucle de nouvelles tentatives infinie, ce qui entraîne l'échec des vérifications d'aptitude et des redémarrages continus du conteneur.

Cause principale : Lorsque l'unité était épinglée, les déploiements ont mis à jour le champ defaultFlagRevisions de la ressource de type d'unité parente, mais l'unité épinglée a ignoré l'opération FlagUpdate et n'a reçu aucune configuration active.

Commandes de diagnostic

Utilisez les commandes suivantes pour inspecter les opérations de mise à jour des options ayant échoué et l'état de l'unité.

1. Répertorier les opérations de signalement ayant échoué

Pour trouver les unités qui n'ont pas été mises à jour, filtrez les opérations des unités sur l'état UNIT_OPERATION_STATE_FAILED et le type flag_update.

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

2. Filtrer spécifiquement les déploiements de flags ayant échoué

Pour identifier les mises à jour de flag ayant échoué dans votre parc ou pour une unité spécifique, ajoutez une condition pour l'état 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. Examiner le motif de l'échec

Utilisez la commande describe pour inspecter le champ conditions (message et reason) et errorCategory.

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

4. Vérifier l'état de l'appareil

Vous pouvez également vérifier directement l'état actuel d'une unité. Si le déploiement d'un flag échoue ou si la dernière opération a entraîné une erreur, la liste conditions de l'unité contient une entrée avec type: TYPE_OPERATION_ERROR.

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

Remplacez les éléments suivants :

  • LOCATION : région de l'unité ou de l'opération d'unité.
  • UNIT_ID : ID de l'unité.
  • OPERATION_ID : ID de l'opération unitaire.

Correction manuelle

Pour récupérer une unité épinglée qui n'a pas reçu les mises à jour des flags, appliquez les révisions de flags par défaut de son genre d'unité parent.

Appliquer les révisions de flag par défaut du genre d'unité

Si une unité ne dispose pas de sa configuration, car elle a été épinglée lors d'un ou de plusieurs déploiements, vous pouvez la récupérer en réinitialisant manuellement l'unité sur la référence actuelle définie dans son type d'unité.

  1. Désépinglez l'unité (si elle est épinglée) :

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

  2. Récupérez les révisions par défaut à partir du genre d'unité parent :

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

  3. Créez un fichier FlagRelease contenant ces révisions :

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

  4. Lancez manuellement une opération d'unité FlagUpdate pour appliquer la version de récupération :

    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"

Remplacez les éléments suivants :

  • UNIT_ID : ID de l'unité à récupérer.
  • LOCATION : région de l'unité.
  • UNIT_KIND_ID : ID du type d'unité parent.
  • REVISIONS : liste des noms de ressources de révision de flag par défaut renvoyés à l'étape 2, séparés par une virgule.
  • PROJECT_ID : ID de votre projet Google Cloud .