Entender o status do cliente do Cloud Service Mesh

Ao usar o Cloud Service Mesh para gerenciar a rede de aplicativos, considere 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 conectar-se ao Cloud Service Mesh. 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 envia informações de configuração de volta para o 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 talvez queira entender como as ações que você executou ao configurar O Cloud Service Mesh afeta 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 receber informações de configuração sobre os clientes 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 ao Cloud Service Mesh e apresenta um número de projeto e nome da rede e 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 compartilham o mesmo ID de nó, somente uma configuração é retornada, a configuração do cliente que fez conectadas 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 o Permissões do Identity and Access Management (IAM) necessárias para configurar 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

Você pode 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 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.
  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 que estão 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 ao se conectarem do Cloud Service Mesh.

APIs mais antigas

  1. De uma conta com o 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 mostra os IDs dos clientes que estão 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 ao se conectarem do 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. 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 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 de xDS individuais enviadas por Cloud Service Mesh ao cliente usando um stream gRPC agregado (ANÚNCIOS).

APIs mais antigas

  1. Atualize o arquivo YAML que você criou Determine 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. Este 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 de xDS individuais enviadas por Cloud Service Mesh ao cliente usando um stream gRPC agregado (ANÚNCIOS).

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 ao 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 a 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. O escopo da configuração do Cloud Service Mesh é 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 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