Comprendre l'état du client Traffic Director

Lorsque vous utilisez Traffic Director pour gérer la mise en réseau de vos applications, tenez compte des deux composants principaux suivants :

  • La couche d'infrastructure. La couche d'infrastructure, qui inclut les proxys side-car Envoy ou les bibliothèques gRPC sans proxy, est configurée pour gérer la mise en réseau pour le compte de vos applications.
  • Le plan de contrôle, Traffic Director. Le plan de contrôle génère une configuration pour la couche d'infrastructure et la lui distribue.

Lorsqu'un proxy Envoy ou la bibliothèque gRPC est initialisée, il utilise les API xDS pour se connecter à Traffic Director. Le proxy ou la bibliothèque agit en tant que client auprès de Traffic Director. Une fois la connexion établie entre le client et Traffic Director, celui-ci renvoie les informations de configuration au client et met à jour la configuration si nécessaire.

Il est parfois utile de comprendre quels clients sont connectés à Traffic Director ou d'inspecter la configuration générée par Traffic Director pour ses clients. Par exemple, vous pouvez vouloir déboguer un problème ou comprendre l'impact des actions que vous avez effectuées lors de la configuration de Traffic Director sur la configuration visible de vos clients.

Traffic Director est compatible avec l'API Client Status Discovery Service (CSDS). Vous devez utiliser un client CSDS pour interroger cette API. Cela vous permet de voir quels clients sont connectés à Traffic Director et d'inspecter la configuration générée par Traffic Director pour ses clients.

Le client CSDS est un outil Open Source que vous pouvez obtenir à partir du dépôt Envoy. Le schéma suivant montre comment le client CSDS interroge Traffic Director pour en savoir plus sur son API CSDS.

Utiliser l'API CSDS pour obtenir des informations de configuration sur les clients Traffic Director.
Utiliser l'API CSDS pour obtenir des informations de configuration sur les clients Traffic Director (cliquez pour agrandir)

Le client CSDS se connecte à Traffic Director et présente un numéro de projet et un nom de réseau ainsi qu'un ensemble d'identifiants. Traffic Director peut ensuite répondre avec des informations sur les différents clients Traffic Director auxquels il est connecté.

Pour plus d'informations sur le client CSDS, consultez le fichier README.

Prérequis

Pour vous connecter à l'API CSDS, vous aurez besoin d'un client CSDS. Vous pouvez obtenir le client de l'une des deux manières suivantes :

  1. Vous pouvez créer ce client à l'aide de Cloud Shell.
  2. Vous pouvez créer le client sur un ordinateur de développement local.

Créer le client CSDS à l'aide de Cloud Shell

Pour utiliser Cloud Shell afin de créer le client CSDS, procédez comme suit :

  1. Réinitialisez Cloud Shell en suivant les instructions de la section Désactiver ou réinitialiser Cloud Shell. Cela garantit que les configurations existantes n'interfèrent pas avec votre build.
  2. Dans Google Cloud Console, ouvrez une nouvelle session Cloud Shell.

  3. Exécutez la commande suivante pour obtenir le code source que vous utiliserez pour créer le client CSDS :

    git clone https://github.com/envoyproxy/envoy-tools.git

  4. Accédez au répertoire client CSDS et exécutez les commandes suivantes :

    cd envoy-tools/csds-client/
make init
make build

  5. Une fois la compilation terminée, testez-la avec la commande suivante :

    csds-client -help

Si la compilation réussit, le texte d'aide du client s'affiche.

Créer le client CSDS sur un ordinateur de développement local

Vous pouvez télécharger et créer un client CSDS sur un ordinateur local en suivant les instructions du fichier README dans le dépôt Open Source. Pour ce faire, vous devez également avoir installé Go et l'outil make doit être configuré dans votre environnement. Si vous préférez ne pas le faire, suivez plutôt les instructions précédentes pour Cloud Shell (qui inclut Go et l'outil make).

Conditions préalables supplémentaires

  1. Assurez-vous que l'ID de nœud de chaque client est unique dans le maillage de services. Si plusieurs clients partagent le même ID de nœud, une seule configuration est renvoyée. Il s'agit de la configuration du dernier client connecté à Traffic Director.

    Si vous utilisez les packages de référence Google, vous n'avez pas besoin de définir manuellement l'ID du nœud dans vos fichiers d'amorçage car un ID de nœud est généré pour vous. Si vous n'utilisez pas les packages de référence, vous devez définir manuellement l'ID de nœud dans chacun de vos fichiers d'amorçage.

  2. Vérifiez que vous avez accès à un compte utilisateur disposant des autorisations IAM (Identity and Access Management) requises pour configurer Traffic Director. Les instructions suivantes font appel à Google Cloud CLI pour générer et fournir automatiquement les identifiants requis par le client CSDS. Vous pouvez également utiliser le client CSDS et fournir les identifiants directement.

Déterminer quels clients sont actuellement connectés à Traffic Director

Le client CSDS vous permet de déterminer les clients connectés à votre configuration Traffic Director.

Pour obtenir ces informations, vous avez besoin des informations suivantes :

  • ID du projet à partir duquel les identifiants ont été générés.

  • Si vous utilisez les API de routage de services, l'une des options suivantes, selon la ressource que le client xDS récupère :

    • Nom de la ressource Mesh
    • Le paramètre scope sur la ressource de passerelle

  • Si vous utilisez les anciennes API, indiquez le nom du réseau VPC que vous avez spécifié lors de la configuration de Traffic Director. Ce réseau est celui spécifié par la règle de transfert de la carte des règles de routage.

API de routage de services

  1. En utilisant un compte disposant des autorisations appropriées, exécutez la commande suivante :

    gcloud auth application-default login \
 --billing-project=BILLING_PROJECT_ID

  2. Créez un fichier au format YAML avec le contenu suivant.

    node_matchers:
  - node_metadatas:
      - path:
          - key: TRAFFICDIRECTOR_GCP_PROJECT_NUMBER
        value:
          string_match:
            exact: "PROJECT_NUMBER"
      - path:
          - key: TRAFFICDIRECTOR_MESH_SCOPE_NAME
        value:
          string_match:
            exact: "MESH_OR_SCOPE"

    Remplacez les valeurs suivantes :

    • PROJECT_NUMBER : ID du projet
    • MESH_OR_SCOPE : si le client xDS récupère une ressource Mesh, utilisez un préfixe mesh: suivi du nom réel du maillage. Si le client xDS récupère une ressource de passerelle, utilisez un préfixe scope: suivi du nom du paramètre de champ d'application.

  1. Exécutez le client CSDS, qui utilise les identifiants générés par gcloud CLI. Remplacez PATH_TO_CSDS_REQUEST_YAML_FILE par le chemin d'accès au fichier YAML que vous avez créé à l'étape précédente.

    csds-client \
  -service_uri trafficdirector.googleapis.com:443 \
  -platform gcp \
  -authn_mode auto \
  -api_version v3 \
  -request_file PATH_TO_CSDS_REQUEST_YAML_FILE

    La sortie obtenue doit ressembler à ceci :

    Client ID                                          xDS stream type    Config status
603e3524-d1d6-4a9e-9b26-39bcd633a7cb~10.128.0.5    ADS                N/A
603e3524-d1d6-4a9e-9b26-39bcd633a7cb~10.128.0.5    LRS                N/A
8576d4bf-8f10-40b2-920b-bb6a7cf9f34a~10.168.0.3    ADS                N/A
8576d4bf-8f10-40b2-920b-bb6a7cf9f34a~10.168.0.3    LRS                N/A
d9577b61-fa3a-41d6-90bd-11c4fdd2f8c0~10.128.0.4    ADS                N/A
d9577b61-fa3a-41d6-90bd-11c4fdd2f8c0~10.128.0.4    LRS                N/A
f38a59c1-4428-42f1-be81-e02eb994f9dd~10.128.0.6    ADS                N/A
f38a59c1-4428-42f1-be81-e02eb994f9dd~10.128.0.6    LRS                N/A

    La colonne Client ID affiche les ID des clients connectés à Traffic Director. Ces ID clients sont fournis à l'aide du champ node_id du fichier d'amorçage utilisé par Envoy ou gRPC sans proxy lorsqu'ils se connectent à Traffic Director.

Anciennes API

  1. En utilisant un compte disposant des autorisations appropriées, exécutez la commande suivante :

    gcloud auth application-default login \
 --billing-project=BILLING_PROJECT_ID

  2. Créez un fichier au format YAML avec le contenu suivant.

    node_matchers:
  - node_metadatas:
      - path:
          - key: TRAFFICDIRECTOR_GCP_PROJECT_NUMBER
        value:
          string_match:
            exact: "PROJECT_NUMBER"
      - path:
          - key: TRAFFICDIRECTOR_NETWORK_NAME
        value:
          string_match:
            exact: "NETWORK_NAME"

    Remplacez les valeurs suivantes :

    • PROJECT_NUMBER : ID unique du projet Google Cloud.
    • NETWORK_NAME : réseau VPC spécifié par la règle de transfert de la carte des règles de routage

  3. Exécutez le client CSDS, qui utilise les identifiants générés par gcloud CLI. Remplacez PATH_TO_CSDS_REQUEST_YAML_FILE par le chemin d'accès au fichier YAML que vous avez créé à l'étape précédente.

    csds-client \
  -service_uri trafficdirector.googleapis.com:443 \
  -platform gcp \
  -authn_mode auto \
  -api_version v3 \
  -request_file PATH_TO_CSDS_REQUEST_YAML_FILE

    La sortie obtenue doit ressembler à ceci :

    Client ID                                          xDS stream type    Config status
603e3524-d1d6-4a9e-9b26-39bcd633a7cb~10.128.0.5    ADS                N/A
603e3524-d1d6-4a9e-9b26-39bcd633a7cb~10.128.0.5    LRS                N/A
8576d4bf-8f10-40b2-920b-bb6a7cf9f34a~10.168.0.3    ADS                N/A
8576d4bf-8f10-40b2-920b-bb6a7cf9f34a~10.168.0.3    LRS                N/A
d9577b61-fa3a-41d6-90bd-11c4fdd2f8c0~10.128.0.4    ADS                N/A
d9577b61-fa3a-41d6-90bd-11c4fdd2f8c0~10.128.0.4    LRS                N/A
f38a59c1-4428-42f1-be81-e02eb994f9dd~10.128.0.6    ADS                N/A
f38a59c1-4428-42f1-be81-e02eb994f9dd~10.128.0.6    LRS                N/A

    La colonne Client ID affiche les ID des clients connectés à Traffic Director. Ces ID clients sont fournis à l'aide du champ node_id du fichier d'amorçage utilisé par Envoy ou gRPC sans proxy lorsqu'ils se connectent à Traffic Director.

Inspecter la configuration d'un client Traffic Director spécifique

Vous pouvez inspecter la configuration envoyée par Traffic Director à un client particulier en utilisant l'ID client que vous avez obtenu dans la section précédente.

Vous pouvez examiner la configuration détaillée du fichier proto de la ressource pour déterminer la version de l'API xDS que ce client spécifique utilise. Par exemple, si envoy.api.v2.Cluster figure dans la configuration, cela signifie que le client utilise la version 2 de l'API. Si envoy.api.v3.Cluster apparaît dans la configuration, cela signifie que le client utilise la version 3 de l'API.

API de routage de services

  1. Mettez à jour le fichier YAML que vous avez créé dans la section Déterminer les clients actuellement connectés à Traffic Director. Ajoutez un champ node-id en utilisant l'ID client comme valeur.

    node_matchers:
  - node_id:
      exact: "CLIENT_ID"
    node_metadatas:
      - path:
          - key: TRAFFICDIRECTOR_GCP_PROJECT_NUMBER
        value:
          string_match:
            exact: "PROJECT_NUMBER"
      - path:
          - key: TRAFFICDIRECTOR_MESH_SCOPE_NAME
        value:
          string_match:
            exact: "MESH_OR_SCOPE_NAME"

    Remplacez les valeurs suivantes :

    • CLIENT_ID : ID du client dont vous inspectez la configuration, par exemple projects/000000/networks/mesh:mesh1/nodes/00000000-0000-0000-0000-00000000~127.0.0.1
    • PROJECT_NUMBER : ID unique du projet Google Cloud.
    • MESH_OR_SCOPE : si le client xDS récupère une ressource Mesh, utilisez un préfixe mesh: suivi du nom réel du maillage. Si le client xDS récupère une ressource de passerelle, utilisez un préfixe scope: suivi du nom du paramètre de champ d'application.

  2. Exécutez le client CSDS. L'exécution du client génère un fichier JSON. Ce fichier contient la configuration envoyée au client Traffic Director.

    csds-client \
 -service_uri trafficdirector.googleapis.com:443 \
 -platform gcp \
 -authn_mode auto \
 -api_version v3 \
 -request_file PATH_TO_CSDS_REQUEST_YAML_FILE \
 -output_file FILENAME.JSON

    Remplacez les valeurs suivantes :

    • PATH_TO_CSDS_REQUEST_YAML_FILE : chemin d'accès à votre fichier YAML.
    • FILENAME.JSON : nom du fichier contenant la sortie du client CSDS.

    La sortie obtenue doit ressembler à ceci :

    Client ID                                          xDS stream type    Config status
8576d4bf-8f10-40b2-920b-bb6a7cf9f34a~10.168.0.3    ADS                LDS  SYNCED
                                                                      RDS  SYNCED
                                                                      CDS  STALE
Config has been saved to FILENAME.JSON

    Vous pouvez inspecter une configuration xDS détaillée en consultant le fichier JSON. Ce résultat contient l'état des configurations xDS individuelles envoyées par Traffic Director au client à l'aide d'un flux gRPC agrégé (ADS).

Anciennes API

  1. Mettez à jour le fichier YAML que vous avez créé dans la section Déterminer les clients actuellement connectés à Traffic Director. Ajoutez un champ node-id en utilisant l'ID client comme valeur.

    node_matchers:
  - node_id:
      exact: "CLIENT_ID"
    node_metadatas:
      - path:
          - key: TRAFFICDIRECTOR_GCP_PROJECT_NUMBER
        value:
          string_match:
            exact: "PROJECT_NUMBER"
      - path:
          - key: TRAFFICDIRECTOR_NETWORK_NAME
        value:
          string_match:
            exact: "NETWORK_NAME"

    Remplacez les valeurs suivantes :

    • CLIENT_ID : ID du client dont vous inspectez la configuration, par exemple f38a59c1-4428-42f1-be81-e02eb994f9dd~10.128.0.6
    • PROJECT_NUMBER : ID unique du projet Google Cloud.
    • NETWORK_NAME : réseau VPC spécifié par la règle de transfert de la carte des règles de routage.

  2. Exécutez le client CSDS. L'exécution du client génère un fichier JSON. Ce fichier contient la configuration envoyée au client Traffic Director.

    csds-client \
 -service_uri trafficdirector.googleapis.com:443 \
 -platform gcp \
 -authn_mode auto \
 -api_version v3 \
 -request_file PATH_TO_CSDS_REQUEST_YAML_FILE \
 -output_file FILENAME.JSON

    Remplacez les valeurs suivantes :

    • PATH_TO_CSDS_REQUEST_YAML_FILE : chemin d'accès à votre fichier YAML.
    • FILENAME.JSON : nom du fichier contenant la sortie du client CSDS.

    La sortie obtenue doit ressembler à ceci :

    Client ID                                          xDS stream type    Config status
8576d4bf-8f10-40b2-920b-bb6a7cf9f34a~10.168.0.3    ADS                LDS  SYNCED
                                                                      RDS  SYNCED
                                                                      CDS  STALE
Config has been saved to FILENAME.JSON

    Vous pouvez inspecter une configuration xDS détaillée en consultant le fichier JSON. Ce résultat contient l'état des configurations xDS individuelles envoyées par Traffic Director au client à l'aide d'un flux gRPC agrégé (ADS).

Valeurs d'état

Le tableau suivant répertorie les valeurs d'état de configuration xDS que vous pouvez rencontrez.

Value (Valeur) Description
UNKNOWN (Par défaut) Les informations sur l'état ne sont pas disponibles ou sont inconnues.
SYNCED Traffic Director a envoyé la configuration au client et a reçu un ACK du client.
ERROR ⁣Traffic Director a envoyé la configuration au client et a reçu un NACK du client.
STALE Traffic Director a envoyé la configuration au client, mais n'a pas reçu de ACK ni de NACK de la part du client.
NOT_SENT La configuration n'a pas été envoyée.
N/A Le client CSDS n'a pas inclus l'ID du nœud. Tous les flux connectés sont renvoyés, mais l'état de la configuration n'est pas disponible.

Visualisation et surveillance

L'outil Open Source du client CSDS offre des fonctionnalités supplémentaires que vous pouvez utiliser, telles que la visualisation et la surveillance continue. Pour en savoir plus sur ces fonctionnalités, consultez le fichier README dans le dépôt Open Source.

Message d'erreur

Vous pouvez voir le message d'erreur suivant du client CSDS si vous activez l'API Traffic Director uniquement dans votre projet :

rpc error: code = NotFound desc = Requested entity was not found.

Ce comportement est normal. La configuration de Traffic Director est limitée par réseau. Si vous n'avez pas encore créé de réseau et que vous exécutez le client CSDS, ce message d'erreur s'affiche.

Limites

  • Les informations sur le point de terminaison ne sont pas incluses dans la réponse CSDS, car elles ne sont pas disponibles dans l'API CSDS v3.
  • L'ID de nœud de chaque client doit être unique dans le maillage de services. Si plusieurs clients partagent le même ID de nœud, une seule configuration est renvoyée. Il s'agit de la configuration du client qui s'est connecté le plus récemment à Traffic Director.
  • Une barre oblique inverse (\) peut parfois apparaître dans le champ d'ID de nœud du fichier YAML. Dans ce cas, échappez la barre oblique inverse en utilisant une barre oblique inverse supplémentaire lorsque vous interrogez l'API CSDS pour obtenir des informations de configuration. Il s'agit d'un problème connu.

Étapes suivantes