Noções básicas sobre o status de cliente do Traffic Director

Ao usar o Traffic Director para processar a rede do aplicativo, considere os dois componentes principais a seguir:

  • A camada da infraestrutura. A camada de infraestrutura, como proxies sidecar do Envoy ou bibliotecas gRPC sem proxy, é configurada para processar a rede em nome dos seus aplicativos.
  • O plano de controle, Traffic Director. O plano de controle gera a configuração e a distribui para a camada da infraestrutura.

Quando um proxy Envoy ou a biblioteca gRPC é inicializado, ele usa APIs xDS para se conectar ao Traffic Director. O proxy ou a biblioteca atua como um cliente para o Traffic Director. Depois que uma conexão é estabelecida entre o cliente e o Traffic Director, o Traffic Director envia informações de configuração de volta para o cliente e atualiza a configuração conforme necessário.

Às vezes, é útil entender quais clientes estão conectados ao Traffic Director ou inspecionar a configuração que o Traffic Director gera para os clientes. Por exemplo, talvez você queira depurar um problema ou entender melhor como as ações tomadas ao configurar o Traffic Director afetam a configuração que seus clientes veem.

O Traffic Director é compatível com a API Client Status Discovery Service (CSDS). Você usa um cliente CSDS para consultar essa API. Isso permite ver quais clientes estão conectados ao Traffic Director e inspecionar a configuração que o Traffic Director gera para os clientes.

O cliente CSDS é uma ferramenta de código aberto disponível no repositório do Envoy (em inglês). O diagrama a seguir ilustra como o cliente CSDS consulta o Traffic Director para informações sobre a API CSDS do Traffic Director.

Como usar a API CSDS para acessar informações de configuração sobre clientes do Traffic Director.
Como usar a API CSDS para ver informações de configuração sobre os clientes do Traffic Director (clique para ampliar)

O cliente CSDS se conecta ao Traffic Director e apresenta um número de projeto, um nome de rede e um conjunto de credenciais. O Traffic Director pode responder com informações sobre os vários clientes do Traffic Director a que está conectado.

Para mais informações sobre o cliente CSDS, consulte o arquivo README.

Pré-requisitos

Para se conectar à API CSDS, você precisa de um cliente CSDS. É possível conseguir o cliente de duas maneiras:

  1. Crie o cliente usando o Cloud Shell.
  2. Crie o cliente em uma máquina de desenvolvimento local.

Criar o cliente CSDS usando o Cloud Shell

Para usar o Cloud Shell para criar o cliente CSDS, faça o seguinte:

  1. Redefina o Cloud Shell seguindo as instruções em Como desativar ou redefinir o Cloud Shell. Isso garante que as configurações atuais não interfiram na compilação.
  2. No Console do Google Cloud, abra uma nova sessão do Cloud Shell.
  3. Execute o seguinte comando para acessar o código-fonte usado para criar o cliente CSDS:

    git clone https://github.com/envoyproxy/envoy-tools.git
    
  4. Acesse o diretório do cliente CSDS e execute os seguintes comandos:

    cd envoy-tools/csds-client/
    make init
    make build
    
  5. Após a conclusão do build, teste-o com o seguinte comando:

    csds-client -help
    

Se a versão for bem-sucedida, você verá o texto de ajuda do cliente.

Criar o cliente CSDS em uma máquina de desenvolvimento local

É possível fazer o download e criar um cliente CSDS em uma máquina local seguindo as instruções no arquivo README no repositório de código aberto. Para isso, você também precisa ter o Go e a ferramenta make configurados no seu ambiente. Se preferir não fazer isso, use as instruções acima para o Cloud Shell, em que o Go e a ferramenta make são fornecidos.

Pré-requisitos adicionais

  1. Verifique se o código do nó de cada cliente é único dentro da malha de serviço. Se vários clientes compartilharem o mesmo ID do nó, somente uma configuração será retornada: a configuração do cliente que se conectou mais recentemente ao Traffic Director.

    Se você usa pacotes de referência do Google, não precisa definir manualmente o código do nó nos arquivos de inicialização. Um ID de nó será gerado para você. Se você não usar os pacotes de referência, precisará definir manualmente o ID do nó em cada um dos arquivos de inicialização.

  2. Verifique se você tem acesso a uma conta de usuário que tenha as permissões de gerenciamento de identidade e acesso (IAM, na sigla em inglês) necessárias para configurar o Traffic Director. As instruções a seguir usam a CLI do Google Cloud para gerar e fornecer automaticamente as credenciais necessárias para o cliente CSDS. Se preferir, use o cliente CSDS e forneça as credenciais diretamente.

Determinar quais clientes estão conectados ao Traffic Director

É possível usar o cliente do CSDS para determinar quais clientes estão conectados à configuração do Traffic Director.

Para receber essas informações, você precisa dos seguintes detalhes:

  • O ID do projeto a partir do qual as credenciais foram geradas.

  • Se você estiver usando as APIs de roteamento de serviço, uma das seguintes opções, dependendo de qual recurso o cliente xDS busca:

    • O nome do recurso da Malha.
    • O parâmetro scope no recurso Gateway
  • Se você estiver usando as APIs mais antigas, o nome da rede VPC que você especificou ao configurar o Traffic Director. Essa rede é a especificada pela regra de encaminhamento do mapa de regras de roteamento.

APIs de roteamento de serviço

  1. Em uma conta com as permissões corretas, execute o seguinte comando:

    gcloud auth application-default login \
     --billing-project=BILLING_PROJECT_ID
    
  2. Crie um novo arquivo no formato YAML com o conteúdo a seguir.

    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"
    

    Substitua os seguintes valores:

    • PROJECT_NUMBER: o ID do projeto
    • MESH_OR_SCOPE: se o cliente xDS buscar um recurso da Malha, use um prefixo de mesh: seguido pelo nome da malha real. Se o cliente xDS buscar um recurso de Gateway, use um prefixo de scope: seguido pelo nome do parâmetro de escopo.
  1. Execute o cliente CSDS, que usa as credenciais geradas pela CLI gcloud. Substitua PATH_TO_CSDS_REQUEST_YAML_FILE pelo caminho para o arquivo YAML que você criou na etapa anterior.

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

    A resposta será semelhante a esta:

    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
    

    A coluna Client ID exibe os IDs dos clientes que estão conectados ao Traffic Director. Esses IDs de cliente são fornecidos usando o campo node_id no arquivo de inicialização usado pelo Envoy ou pelo gRPC sem proxy quando se conectam ao Traffic Director.

APIs mais antigas

  1. Em uma conta com as permissões corretas, execute o seguinte comando:

    gcloud auth application-default login \
     --billing-project=BILLING_PROJECT_ID
    
  2. Crie um novo arquivo no formato YAML com o conteúdo a seguir.

    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"
    

    Substitua os seguintes valores:

    • PROJECT_NUMBER: o ID exclusivo do projeto do Google Cloud.
    • NETWORK_NAME: a rede VPC especificada pela regra de encaminhamento do mapa de regras de roteamento.
  3. Execute o cliente CSDS, que usa as credenciais geradas pela CLI gcloud. Substitua PATH_TO_CSDS_REQUEST_YAML_FILE pelo caminho para o arquivo YAML que você criou na etapa anterior.

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

    A resposta será semelhante a esta:

    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
    

    A coluna Client ID exibe os IDs dos clientes que estão conectados ao Traffic Director. Esses IDs de cliente são fornecidos usando o campo node_id no arquivo de inicialização usado pelo Envoy ou pelo gRPC sem proxy quando se conectam ao Traffic Director.

Inspecionar a configuração de um cliente específico do Traffic Director

Para inspecionar a configuração que o Traffic Director envia a um cliente específico, use o ID do cliente recebido na seção anterior.

Você pode examinar a configuração detalhada do proto de recursos para determinar qual versão da API xDS esse cliente específico está usando. Por exemplo, se você vir envoy.api.v2.Cluster na configuração, significa que o cliente está usando a API v2. Se você vir envoy.api.v3.Cluster na configuração, significa que o cliente está usando a API v3.

APIs de roteamento de serviço

  1. Atualize o arquivo YAML criado em Determinar quais clientes estão conectados ao Traffic Director. Adicione um campo node-id que use o ID do cliente como valor.

    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"
    

    Substitua os seguintes valores:

    • CLIENT_ID: o ID do cliente onde a configuração está sendo inspecionada. Por exemplo, projects/000000/networks/mesh:mesh1/nodes/00000000-0000-0000-0000-00000000~127.0.0.1.
    • PROJECT_NUMBER: o ID exclusivo do projeto do Google Cloud.
    • MESH_OR_SCOPE: se o cliente xDS buscar um recurso da Malha, use um prefixo de mesh: seguido pelo nome da malha real. Se o cliente xDS buscar um recurso de Gateway, use um prefixo de scope: seguido pelo nome do parâmetro de escopo.
  2. Execute o cliente CSDS. Executar o cliente gera um arquivo JSON. Esse arquivo contém a configuração enviada ao cliente do 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
    

    Substitua os seguintes valores:

    • PATH_TO_CSDS_REQUEST_YAML_FILE: o caminho para o arquivo YAML.
    • FILENAME.JSON: um nome para o arquivo que contém a saída do cliente CSDS

    A saída será semelhante a esta:

    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
    

    É possível inspecionar uma configuração xDS detalhada observando o arquivo JSON. Essa saída contém o status de configurações xDS individuais enviadas pelo Traffic Director ao cliente usando um fluxo gRPC agregado (ADS).

APIs mais antigas

  1. Atualize o arquivo YAML criado em Determinar quais clientes estão conectados ao Traffic Director. Adicione um campo node-id que use o ID do cliente como valor.

    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"
    

    Substitua os seguintes valores:

    • CLIENT_ID: o ID do cliente onde a configuração está sendo inspecionada. Por exemplo, f38a59c1-4428-42f1-be81-e02eb994f9dd~10.128.0.6.
    • PROJECT_NUMBER: o ID exclusivo do projeto do Google Cloud.
    • NETWORK_NAME: a rede VPC especificada pela regra de encaminhamento do mapa de regras de roteamento.
  2. Execute o cliente CSDS. Executar o cliente gera um arquivo JSON. Esse arquivo contém a configuração enviada ao cliente do 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
    

    Substitua os seguintes valores:

    • PATH_TO_CSDS_REQUEST_YAML_FILE: o caminho para o arquivo YAML.
    • FILENAME.JSON: um nome para o arquivo que contém a saída do cliente CSDS

    A saída será semelhante a esta:

    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
    

    É possível inspecionar uma configuração xDS detalhada observando o arquivo JSON. Essa saída contém o status de configurações xDS individuais enviadas pelo Traffic Director ao cliente usando um fluxo gRPC agregado (ADS).

Valores de status

A tabela a seguir lista os valores de status de configuração do xDS que podem ser exibidos.

Valor Descrição
UNKNOWN (Padrão) ⁣As informações de status não estão disponíveis ou são desconhecidas.
SYNCED O Traffic Director enviou a configuração para o cliente e recebeu um ACK do cliente.
ERROR O Traffic Director enviou a configuração para o cliente e recebeu uma NACK do cliente.
STALE O Traffic Director enviou a configuração para o cliente, mas não recebeu um ACK ou um NACK do cliente.
NOT_SENT A configuração não foi enviada.
N/A O cliente CSDS não incluiu o ID do nó. Todos os streams conectados são retornados, mas o status da configuração não está disponível.

Visualização e monitoramento

A ferramenta de código aberto do cliente CSDS tem outros recursos que você pode usar, como visualização e monitoramento contínuo. Para mais informações sobre esses recursos, consulte o arquivo README no repositório de código aberto.

Mensagem de erro

Talvez você veja a seguinte mensagem de erro do cliente CSDS quando só ativar a API Traffic Director no projeto:

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

Este comportamento é esperado. O escopo da configuração do Traffic Director é definido por rede. Se você ainda não tiver criado uma rede e executar o cliente CSDS, verá esta mensagem de erro.

Limitações

  • As informações do endpoint não estão incluídas na resposta da CSDS porque não estão disponíveis na API CSDS v3.
  • O código do nó de cada cliente precisa ser exclusivo na malha de serviço. Se vários clientes compartilharem o mesmo ID do nó, somente uma configuração será retornada: a configuração do cliente que se conectou mais recentemente ao Traffic Director.
  • Às vezes, pode ser exibida uma barra invertida (\) no campo de ID do nó no arquivo YAML. Se isso acontecer, faça o escape da barra invertida usando uma barra invertida extra quando consultar a API CSDS para mais informações sobre a configuração. Esse é um problema conhecido.

A seguir