Entender o status do cliente do Cloud Service Mesh

Observação: este guia é compatível apenas com o Cloud Service Mesh com APIs do Google Cloud e não com as APIs do Istio. Para mais informações, consulte Visão geral do Cloud Service Mesh.

Ao usar o Cloud Service Mesh para lidar com a rede de aplicativos, 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, Cloud Service Mesh. 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 Cloud Service Mesh. O proxy ou a biblioteca atua como um cliente do Cloud Service Mesh. Depois que uma conexão é estabelecida entre o cliente e o Cloud Service Mesh, ele envia as informações de configuração de volta ao cliente e atualiza a configuração conforme necessário.

Às vezes, é útil entender quais clientes estão conectados ao Cloud Service Mesh ou inspecionar a configuração que o Cloud Service Mesh gera para seus clientes. Por exemplo, talvez você queira depurar um problema ou entender como as ações realizadas ao configurar o Cloud Service Mesh afetam a configuração mostrada aos clientes.

O Cloud Service Mesh é compatível com a API Client Status Discovery Service (CSDS). Você usa um cliente CSDS para consultar essa API. Assim, é possível ver quais clientes estão conectados ao Cloud Service Mesh e inspecionar a configuração que o Cloud Service Mesh 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 Cloud Service Mesh para encontrar informações sobre a API CSDS do Cloud Service Mesh.

Como usar a API CSDS para acessar informações de configuração sobre os clientes do Cloud Service Mesh (clique para ampliar)

O cliente CSDS se conecta ao Cloud Service Mesh e apresenta um número de projeto e um nome de rede, com um conjunto de credenciais. O Cloud Service Mesh pode responder com informações sobre os vários clientes do Cloud Service Mesh 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 ID de nó de cada cliente é exclusivo na malha de serviço. Se vários clientes compartilharem o mesmo ID de nó, apenas uma configuração será retornada: a configuração do cliente que se conectou mais recentemente ao Cloud Service Mesh.

   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 com as permissões de Identity and Access Management (IAM) necessárias para configurar o Cloud Service Mesh. 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 Cloud Service Mesh no momento

É possível usar o cliente CSDS para determinar quais clientes estão conectados à sua configuração do Cloud Service Mesh.

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 especificada quando você configurou o Cloud Service Mesh. 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.

Observação: uma solicitação CSDS V3 requer node.id, que representa o nó que está fazendo a solicitação CSDS. Para o Cloud Service Mesh, o node.id precisa estar no formato projects/PROJECT_NUMBER/networks/MESH_OR_SCOPE/nodes/NODE_ID. O cliente do CSDS inclui automaticamente node.id na solicitação do CSDS V3 com uma parte <node_id> gerada aleatoriamente quando a opção -platform está definida como gcp.

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 saída 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 Cloud Service Mesh. Esses IDs do cliente são fornecidos usando o campo node_id no arquivo de inicialização usado pelo Envoy ou pelo gRPC sem proxy quando eles se conectam ao Cloud Service Mesh.

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 saída 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 Cloud Service Mesh. Esses IDs do cliente são fornecidos usando o campo node_id no arquivo de inicialização usado pelo Envoy ou pelo gRPC sem proxy quando eles se conectam ao Cloud Service Mesh.

Inspecionar a configuração de um cliente específico do Cloud Service Mesh

É possível inspecionar a configuração que o Cloud Service Mesh envia a um cliente específico usando o ID do cliente, que você recebeu 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 Cloud Service Mesh. 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 que é enviada ao cliente do Cloud Service Mesh.

   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 das configurações individuais do xDS enviadas pelo Cloud Service Mesh ao cliente usando um stream gRPC agregado (ADS).

APIs mais antigas

1. Atualize o arquivo YAML criado em Determinar quais clientes estão conectados ao Cloud Service Mesh. 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 que é enviada ao cliente do Cloud Service Mesh.

   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 das configurações individuais do xDS enviadas pelo Cloud Service Mesh ao cliente usando um stream 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 Cloud Service Mesh enviou a configuração ao cliente e recebeu um ACK dele.
ERROR	⁣O Cloud Service Mesh enviou a configuração ao cliente e recebeu um NACK dele.
STALE	O Cloud Service Mesh enviou a configuração ao cliente, mas não recebeu um ACK ou um NACK dele.
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 saber mais 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 ao ativar a API Cloud Service Mesh apenas no seu projeto:

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

Este é o comportamento esperado. A configuração do Cloud Service Mesh tem escopo 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 ID de nó de cada cliente precisa ser exclusivo na malha de serviço. Se vários clientes compartilharem o mesmo ID de nó, apenas uma configuração será retornada, ou seja, a configuração do cliente que se conectou mais recentemente ao Cloud Service Mesh.
• À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

• Consulte informações gerais sobre solução de problemas do Cloud Service Mesh em Solução de problemas em implantações que usam o Envoy.
• Para resolver problemas de configuração ao implantar serviços gRPC sem proxy, consulte Solução de problemas em implantações que usam gRPC sem proxy.