Compreenda o estado do cliente do Cloud Service Mesh

Nota: este guia só suporta a Cloud Service Mesh com Google Cloud APIs e não suporta as APIs Istio. Para mais informações, consulte o artigo Vista geral do Cloud Service Mesh.

Quando usa o Cloud Service Mesh para processar a rede da sua aplicação, considere os dois componentes principais seguintes:

• A camada de infraestrutura. A camada de infraestrutura, como os proxies sidecar do Envoy ou as bibliotecas gRPC sem proxy, está configurada para processar a rede em nome das suas aplicações.
• O plano de controlo, o Cloud Service Mesh. O plano de controlo gera a configuração para a camada de infraestrutura e distribui a configuração para esta.

Quando um proxy Envoy ou a biblioteca gRPC é inicializada, usa APIs xDS para se ligar ao Cloud Service Mesh. O proxy ou a biblioteca atuam como um cliente para a Cloud Service Mesh. Depois de estabelecer uma ligação 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.

Por vezes, é útil compreender que clientes estão ligados ao Cloud Service Mesh ou inspecionar a configuração que o Cloud Service Mesh gera para os respetivos clientes. Por exemplo, pode querer depurar um problema ou compreender como as ações que realizou ao configurar o Cloud Service Mesh afetam a configuração que os seus clientes veem.

O Cloud Service Mesh suporta a API Client Status Discovery Service (CSDS). Usa um cliente CSDS para consultar esta API. Isto permite-lhe ver que clientes estão ligados à Cloud Service Mesh e inspecionar a configuração que a Cloud Service Mesh gera para os respetivos clientes.

O cliente CSDS é uma ferramenta de código aberto que pode obter no repositório do Envoy. O diagrama seguinte ilustra como o cliente CSDS consulta o Cloud Service Mesh para obter informações sobre a API CSDS do Cloud Service Mesh.

Usar a API CSDS para obter informações de configuração sobre clientes do Cloud Service Mesh (clique para aumentar)

O cliente CSDS liga-se à malha de serviços na nuvem e apresenta um número do projeto e um nome da rede, juntamente com um conjunto de credenciais. Em seguida, o Cloud Service Mesh pode responder com informações sobre os vários clientes do Cloud Service Mesh aos quais está ligado.

Para mais informações acerca do cliente CSDS, consulte o ficheiro README.

Pré-requisitos

Para estabelecer ligação à API CSDS, precisa de um cliente CSDS. Pode obter o cliente de duas formas:

1. Pode criar o cliente através do Cloud Shell.
2. Pode criar o cliente numa máquina de desenvolvimento local.

Crie o cliente CSDS através do Cloud Shell

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

1. Reponha o Cloud Shell seguindo as instruções em Desativar ou repor o Cloud Shell. Isto garante que as configurações existentes não interferem com a sua criação.
2. Na Google Cloud consola, abra uma nova sessão do Cloud Shell.

3. Execute o seguinte comando para obter o código fonte que usa para criar o cliente CSDS:

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

4. Navegue para 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 da compilação, teste-a com o seguinte comando:

   csds-client -help
   

Se a compilação for bem-sucedida, é apresentado o texto de ajuda para o cliente.

Crie o cliente CSDS numa máquina de desenvolvimento local

Pode transferir e criar um cliente CSDS numa máquina local seguindo as instruções no ficheiro README no repositório de código aberto. Para o fazer, também tem de ter o Go e a ferramenta make configurados no seu ambiente. Se preferir não o fazer, use as instruções anteriores para o Cloud Shell, no qual o Go e a ferramenta make são fornecidos.

Pré-requisitos adicionais

1. Certifique-se de que o ID do nó de cada cliente é exclusivo na malha de serviço. Se vários clientes partilharem o mesmo ID do nó, apenas é devolvida uma configuração: a configuração do cliente que se ligou mais recentemente ao Cloud Service Mesh.

   Se usar os pacotes de referência da Google, não precisa de definir manualmente o ID do nó nos ficheiros de arranque. É gerado um ID do nó automaticamente. Se não usar os pacotes de referência, tem de definir manualmente o ID do nó em cada um dos ficheiros de arranque.

2. Certifique-se de que tem acesso a uma conta de utilizador com as autorizações de gestão de identidade e de acesso (IAM) necessárias para configurar a Cloud Service Mesh. As instruções seguintes usam a CLI do Google Cloud para gerar e fornecer automaticamente as credenciais necessárias ao cliente CSDS. Em alternativa, pode usar o cliente CSDS e fornecer as credenciais diretamente.

Determine que clientes estão atualmente ligados à Cloud Service Mesh

Pode usar o cliente CSDS para determinar que clientes estão ligados à sua configuração do Cloud Service Mesh.

Para obter estas informações, precisa dos seguintes detalhes:

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

• Se estiver a usar as APIs de encaminhamento de serviços, uma das seguintes opções, consoante o recurso que o cliente xDS obtém:

  • O nome do recurso Mesh
  • O parâmetro scope no recurso Gateway

• Se estiver a usar as APIs mais antigas, o nome da rede VPC que especificou quando configurou o Cloud Service Mesh. Esta rede é a especificada pela regra de encaminhamento do mapa de regras de encaminhamento.

APIs de encaminhamento de serviços

1. A partir de uma conta com as autorizações corretas, execute o seguinte comando:

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

2. Crie um novo ficheiro 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 obtiver um recurso de malha, use um prefixo de mesh: seguido do nome da malha real; se o cliente xDS obtiver um recurso de gateway, use um prefixo de scope: seguido do nome do parâmetro de âmbito

Nota: um pedido CSDS V3 requer node.id, que representa o nó que está a fazer o pedido CSDS. Para o Cloud Service Mesh, o node.id tem de estar no formato projects/PROJECT_NUMBER/networks/MESH_OR_SCOPE/nodes/NODE_ID. O cliente CSDS inclui automaticamente node.id no pedido 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 ficheiro YAML que criou no passo 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
   

   Deverá ver uma saída semelhante à seguinte:

   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 apresenta os IDs de cliente dos clientes que estão ligados ao Cloud Service Mesh. Estes IDs de cliente são fornecidos através do campo node_id no ficheiro de arranque usado pelo Envoy ou pelo gRPC sem proxy quando se ligam ao Cloud Service Mesh.

APIs mais antigas

1. A partir de uma conta com as autorizações corretas, execute o seguinte comando:

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

2. Crie um novo ficheiro 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 projetoGoogle Cloud
   • NETWORK_NAME: a rede VPC especificada pela regra de encaminhamento do mapa de regras de encaminhamento

3. Execute o cliente CSDS, que usa as credenciais geradas pela CLI gcloud. Substitua PATH_TO_CSDS_REQUEST_YAML_FILE pelo caminho para o ficheiro YAML que criou no passo 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
   

   Deverá ver uma saída semelhante à seguinte:

   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 apresenta os IDs de cliente dos clientes que estão ligados ao Cloud Service Mesh. Estes IDs de cliente são fornecidos através do campo node_id no ficheiro de arranque usado pelo Envoy ou pelo gRPC sem proxy quando se ligam ao Cloud Service Mesh.

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

Pode inspecionar a configuração que o Cloud Service Mesh envia a um cliente específico através do ID do cliente, que obteve na secção anterior.

Pode examinar a configuração detalhada do proto de recursos para determinar que versão da API xDS esse cliente específico está a usar. Por exemplo, se vir envoy.api.v2.Cluster na configuração, significa que o cliente está a usar a API v2. Se vir envoy.api.v3.Cluster na configuração, significa que o cliente está a usar a API v3. Apenas é suportado o xDS v3. Para obter informações sobre como migrar da v2 para a v3, consulte o artigo Migre da xDS v2 para a xDS v3.

APIs de encaminhamento de serviços

1. Atualize o ficheiro YAML que criou em Determine que clientes estão atualmente ligados ao Cloud Service Mesh. Adicione um campo node-id que use o ID de 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 cuja configuração está a inspecionar. Por exemplo, projects/000000/networks/mesh:mesh1/nodes/00000000-0000-0000-0000-00000000~127.0.0.1
   • PROJECT_NUMBER: o ID exclusivo do projetoGoogle Cloud
   • MESH_OR_SCOPE: se o cliente xDS obtiver um recurso de malha, use um prefixo de mesh: seguido do nome da malha real; se o cliente xDS obtiver um recurso de gateway, use um prefixo de scope: seguido do nome do parâmetro de âmbito

2. Execute o cliente CSDS. A execução do cliente gera um ficheiro JSON. Este ficheiro contém a configuração que é enviada para o 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 seu ficheiro YAML
   • FILENAME.JSON: um nome para o ficheiro que contém o resultado do cliente CSDS

   Deverá ver uma saída semelhante à seguinte:

   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
   

   Pode inspecionar uma configuração xDS detalhada consultando o ficheiro JSON. Este resultado contém o estado das configurações xDS individuais enviadas pelo Cloud Service Mesh para o cliente através de um fluxo gRPC agregado (ADS).

APIs mais antigas

1. Atualize o ficheiro YAML que criou em Determine que clientes estão atualmente ligados ao Cloud Service Mesh. Adicione um campo node-id que use o ID de 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 cuja configuração está a inspecionar. Por exemplo, f38a59c1-4428-42f1-be81-e02eb994f9dd~10.128.0.6
   • PROJECT_NUMBER: o ID exclusivo do projetoGoogle Cloud
   • NETWORK_NAME: A rede de VPC especificada pela regra de encaminhamento do mapa de regras de encaminhamento

2. Execute o cliente CSDS. A execução do cliente gera um ficheiro JSON. Este ficheiro contém a configuração que é enviada para o 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 seu ficheiro YAML
   • FILENAME.JSON: um nome para o ficheiro que contém o resultado do cliente CSDS

   Deverá ver uma saída semelhante à seguinte:

   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
   

   Pode inspecionar uma configuração xDS detalhada consultando o ficheiro JSON. Este resultado contém o estado das configurações xDS individuais enviadas pelo Cloud Service Mesh para o cliente através de um fluxo gRPC agregado (ADS).

Valores de estado

A tabela seguinte apresenta os valores de estado da configuração xDS que pode ver.

Valor	Descrição
UNKNOWN	(Predefinição) ⁣As informações de estado 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 um NACK do cliente.
STALE	O Cloud Service Mesh enviou a configuração para o cliente, mas não recebeu um ACK nem 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ó. Todas as streams associadas são devolvidas, mas o estado da configuração não está disponível.

Visualização e monitorização

A ferramenta de código aberto do cliente CSDS tem funcionalidades adicionais que pode querer usar, como a visualização e a monitorização contínua. Para mais informações acerca destas funcionalidades, consulte o ficheiro README no repositório de código aberto.

Mensagem de erro

Pode ver a seguinte mensagem de erro do cliente CSDS quando ativa a API Cloud Service Mesh apenas no seu projeto:

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

Este comportamento é o esperado. A configuração do Cloud Service Mesh tem âmbito por rede. Se ainda não tiver criado uma rede e executar o cliente CSDS, é apresentada esta mensagem de erro.

Limitações

• As informações dos pontos finais não estão incluídas na resposta CSDS porque estas informações não estão disponíveis na API CSDS v3.
• O ID do nó de cada cliente tem de ser exclusivo na malha de serviços. Se vários clientes partilharem o mesmo ID do nó, é devolvida apenas uma configuração, ou seja, a configuração do cliente que se ligou mais recentemente ao Cloud Service Mesh.
• Por vezes, pode ver uma barra invertida (\) no campo do ID do nó no ficheiro YAML. Se isto acontecer, escape a barra invertida usando uma barra invertida adicional quando consultar a API CSDS para obter informações de configuração. Este é um problema conhecido.

O que se segue?

• Para encontrar informações gerais de resolução de problemas do Cloud Service Mesh, consulte o artigo Resolva problemas de implementações que usam o Envoy.
• Para resolver problemas de configuração quando implementa serviços gRPC sem proxy, consulte o artigo Resolução de problemas de implementações que usam gRPC sem proxy.