Entender o status do cliente do Cloud Service Mesh

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

Ao usar o Cloud Service Mesh para gerenciar 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, o Cloud Service Mesh envia 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 os 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 exibida para seus clientes.

O Cloud Service Mesh oferece suporte à API Client Status Discovery Service (CSDS). Você usa um cliente CSDS para consultar essa API. Isso permite que você veja quais clientes estão conectados ao Cloud Service Mesh e inspecione 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 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, além de 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 do arquivo README (em inglês) 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 do 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 gerenciamento de identidade e acesso (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

É possível usar o cliente CSDS para determinar quais clientes estão conectados à 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 que você especificou ao configurar 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 que tenha 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. No Cloud Service Mesh, o node.id precisa estar no formato projects/PROJECT_NUMBER/networks/MESH_OR_SCOPE/nodes/NODE_ID. O cliente CSDS inclui automaticamente node.id na solicitação CSDS V3 com uma parte de <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 o gRPC sem proxy quando eles se conectam ao Cloud Service Mesh.

APIs mais antigas

1. Em uma conta que tenha 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 o 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 para um determinado cliente 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. Somente xDS v3 é compatível. Para informações sobre como migrar da v2 para a v3, consulte Migrar do xDS v2 para o xDS 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 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 de configurações individuais de xDS enviadas pelo Cloud Service Mesh 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 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 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 de configurações individuais de xDS enviadas pelo Cloud Service Mesh 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 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 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 (em inglês) 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 CSDS porque elas não estão disponíveis na API CSDS v3.
• O ID do 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: 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

• Para encontrar informações gerais sobre solução de problemas do Cloud Service Mesh, consulte Como solucionar problemas de 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.