Entender o status do cliente do Cloud Service Mesh

Observação: este guia só oferece suporte ao Cloud Service Mesh com APIs do Google Cloud e não às APIs do Istio. Para mais informações, consulte Visão geral do Cloud Service Mesh.

Ao usar o Cloud Service Mesh 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, o 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 à malha de serviço do Cloud. O proxy ou a biblioteca atua como um cliente para o 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 para o 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 tomadas ao configurar o Cloud Service Mesh afetam a configuração que seus clientes veem.

O Cloud Service Mesh é 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 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 informações sobre a API CSDS do Cloud Service Mesh.

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

O cliente CSDS se conecta à 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 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 do nó de cada cliente é único 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 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 que tenha as permissões de gerenciamento de identidade e acesso (IAM) necessárias para configurar a 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 do 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 seguinte conteúdo.

   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 <node_id> gerada aleatoriamente quando a opção -platform é 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 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 mostra os IDs dos clientes conectados ao Cloud Service Mesh. 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 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 seguinte conteúdo.

   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 mostra os IDs dos clientes conectados ao Cloud Service Mesh. 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 Cloud Service Mesh.

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

Para inspecionar a configuração que o Cloud Service Mesh 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. Há suporte apenas para xDS v3. 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 que você criou 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 resposta 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 Cloud Service Mesh ao cliente usando um fluxo gRPC agregado (ADS).

APIs mais antigas

1. Atualize o arquivo YAML que você criou 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 resposta 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 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 para o cliente e recebeu um ACK do cliente.
ERROR	⁣O Cloud Service Mesh enviou a configuração para o cliente e recebeu uma NACK do cliente.
STALE	O Cloud Service Mesh 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 ativar a API Cloud Service Mesh apenas no seu projeto:

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

Esse comportamento é esperado. A configuração do Cloud Service Mesh é definida 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 do CSDS, porque essas informações 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 do nó, somente 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 de solução de problemas do Cloud Service Mesh, consulte Solução de 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.