Invocar um endpoint particular usando o registro de serviço do Diretório de serviços

É possível direcionar um endpoint particular para chamadas HTTP da execução do fluxo de trabalho usando o registro de serviço do Diretório de serviços com o Workflows. Isso permite que você forneça ao fluxo de trabalho um nome de serviço do Diretório de serviços. A execução do fluxo de trabalho usa as informações recuperadas do registro de serviço para enviar a solicitação HTTP apropriada, sem sair para uma rede pública.

Este documento mostra como registrar uma máquina virtual (VM) em uma rede de nuvem privada virtual (VPC) como um endpoint do Diretório de serviços:

  • Uma rede VPC fornece conectividade para suas instâncias de VM e permite criar endpoints particulares na rede VPC usando endereços IP internos. As chamadas HTTP para um recurso de rede VPC são enviadas por uma rede privada, aplicando o Identity and Access Management (IAM) e o VPC Service Controls.

  • O Diretório de serviços é um registro de serviço que armazena informações sobre serviços de rede registrados, incluindo nomes, locais e atributos. Independentemente da infraestrutura, é possível registrar serviços automaticamente e capturar os detalhes deles. Isso permite descobrir, publicar e conectar serviços em escala para todos os endpoints de serviço.

Este diagrama oferece uma visão geral:

Enviar uma solicitação HTTP para um número de porta em uma instância de VM usando informações do Diretório de serviços

Em geral, você precisa fazer o seguinte:

  1. Conceda permissões ao agente de serviço do Cloud Workflows para que ele possa visualizar os recursos do Diretório de serviços e acessar redes VPC usando o Diretório de serviços.
  2. Crie uma rede VPC para fornecer funcionalidade de rede.
  3. Crie uma regra de firewall da VPC para que você possa permitir ou negar tráfego de/para instâncias de VM na sua rede VPC.
  4. Crie uma instância de VM na rede VPC. Uma instância de VM do Compute Engine é uma máquina virtual hospedada na infraestrutura do Google. Os termos instância do Compute Engine, instância de VM e VM são sinônimos e usados de forma intercambiável.
  5. Implante um aplicativo na VM. É possível executar um app na instância de VM e confirmar se o tráfego está sendo veiculado conforme o esperado.

  6. Configure o Diretório de serviços para que a execução do fluxo de trabalho possa invocar um endpoint do Diretório de serviços.

  7. Crie e implante o fluxo de trabalho. O valor private_service_name no fluxo de trabalho especifica o endpoint do Diretório de serviços que você registrou na etapa anterior.

Conceder permissões ao agente de serviço do Cloud Workflows

Alguns Google Cloud serviços têm agentes de serviço que permitem que os serviços acessem seus recursos. Se uma API exigir um agente de serviço, o Google criará esse agente depois que você ativar e começar a usar a API.

  1. Ao implantar um fluxo de trabalho pela primeira vez, o agente de serviço do Cloud Workflows é criado automaticamente com o seguinte formato:

    service-PROJECT_NUMBER@gcp-sa-workflows.iam.gserviceaccount.com

    É possível criar manualmente a conta de serviço em um projeto sem fluxos de trabalho com este comando:

    gcloud beta services identity create \
    --service=workflows.googleapis.com \
    --project=PROJECT_ID

    Substitua PROJECT_ID pelo seu Google Cloud ID do projeto.

  2. Para visualizar os recursos do Diretório de serviços, conceda o papel de leitor do Diretório de serviços (servicedirectory.viewer) no projeto ao agente de serviço do Workflows:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-workflows.iam.gserviceaccount.com \
    --role=roles/servicedirectory.viewer

    Substitua PROJECT_NUMBER pelo seu Google Cloud número do projeto. Encontre o número do projeto na página de boas-vindas do Google Cloud console ou executando o seguinte comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

  3. Para acessar redes VPC usando o Diretório de serviços, conceda o papel de serviço autorizado do Private Service Connect (roles/servicedirectory.pscAuthorizedService) no projeto ao agente de serviço do Workflows:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-workflows.iam.gserviceaccount.com \
    --role=roles/servicedirectory.pscAuthorizedService

Crie uma rede VPC

Uma rede VPC é uma versão virtual de uma rede física, implementada dentro da rede de produção do Google Ela fornece conectividade para suas instâncias de VM do Compute Engine.

É possível criar uma rede VPC de modo automático ou personalizado Toda nova rede criada precisa ter um nome exclusivo dentro do mesmo projeto.

Por exemplo, o comando a seguir cria uma rede VPC de modo automático:

gcloud compute networks create NETWORK_NAME \
    --subnet-mode=auto

Substitua NETWORK_NAME por um nome para a rede VPC.

Para mais informações, consulte Criar e gerenciar redes VPC.

Criar uma regra de firewall da VPC

Com as regras de firewall da VPC, é possível permitir ou negar o tráfego de/para instâncias de VM em uma rede VPC com base em número de porta, tag ou protocolo.

As regras de firewall são identificadas no nível da rede e se aplicam apenas à rede em que são criadas. No entanto, o nome escolhido para cada regra precisa ser único no projeto.

Por exemplo, o comando a seguir cria uma regra de firewall para a rede VPC criada anteriormente.

gcloud compute firewall-rules create RULE_NAME \
    --network=projects/PROJECT_ID/global/networks/NETWORK_NAME \
    --direction=INGRESS \
    --action=ALLOW \
    --source-ranges=IP_ADDRESS_RANGE \
    --rules=all

Substitua:

  • RULE_NAME: um nome da regra de firewall.

  • IP_ADDRESS_RANGE: um ou mais intervalos de endereços IPv4 ou IPv6. Como prática recomendada, especifique os intervalos de endereços IP específicos necessários para permitir o acesso. Observe o seguinte:

    • O acesso à rede privada para o Diretório de serviços usa 35.199.192.0/19 como um intervalo somente interno com os próximos saltos totalmente na rede do Google. Para mais informações, consulte Caminhos para o Cloud DNS e o Diretório de serviços.

    • A inclusão de 35.235.240.0/20 nos intervalos de origem permitirá conexões SSH usando o encaminhamento de TCP do Identity-Aware Proxy (IAP) se todos os outros pré-requisitos forem atendidos. Para mais informações, consulte Como usar o IAP para encaminhamento de TCP.

    • Se você estiver usando a ferramenta SSH no navegador para se conectar à sua VM do Compute Engine no Google Cloud console, há requisitos específicos.

  • O valor da flag --rules de all torna a regra de firewall aplicável a todos os protocolos e todas as portas de destino. É possível restringir o escopo especificando protocolos e portas.

  • Opcionalmente, é possível usar as --target-tags e --target-service-accounts flags para definir destinos. Caso contrário, a regra será aplicada a todos os destinos na rede.

Para mais informações, consulte Usar regras de firewall da VPC.

Criar uma instância de VM na rede VPC

As instâncias de VM incluem clusters do Google Kubernetes Engine (GKE), instâncias de ambiente flexível do App Engine e outros Google Cloud produtos criados em VMs do Compute Engine. Para oferecer suporte ao acesso à rede privada, um recurso de rede VPC pode ser uma instância de VM ou outro destino compatível. Para mais informações, consulte Visão geral do acesso à rede privada.

Nas instâncias do Compute Engine, é possível executar tanto as imagens públicas para Linux e Windows Server fornecidas pelo Google quanto as imagens privadas personalizadas que você cria ou importa dos seus sistemas atuais. Também é possível implantar contêineres do Docker.

Escolha as propriedades de máquina das instâncias, como o número e a quantidade de memória das CPUs virtuais. Use um conjunto de tipos de máquina predefinidos ou crie os próprios tipos de máquina personalizados.

Por exemplo, o comando a seguir cria uma instância de VM do Linux a partir de uma imagem pública com uma interface de rede anexada à rede VPC criada anteriormente.

  1. Criar e iniciar uma instância de VM:

    gcloud compute instances create VM_NAME \
    --image-family=debian-11 \
    --image-project=debian-cloud \
    --machine-type=e2-micro \
    --network-interface network=projects/PROJECT_ID/global/networks/NETWORK_NAME

    Substitua VM_NAME por um nome para a VM.

  2. Se você receber uma solicitação para confirmar a zona da instância, digite y.

    Depois de criar a instância de VM, anote o endereço INTERNAL_IP retornado.

  3. No Google Cloud console do, acesse a página Instâncias de VM.

    Acessar instâncias de VM

  4. Na coluna Nome, clique no nome da instância de VM apropriada.

  5. Se a VM estiver em execução, clique em Parar para interrompê-la.

  6. Para editar a VM, clique em Editar.

  7. Na seção Rede > Firewalls, para permitir tráfego HTTP ou HTTPS na VM, selecione Permitir tráfego HTTP ou Permitir tráfego HTTPS.

    Para este exemplo, marque a caixa de seleção Permitir tráfego HTTP.

    O Compute Engine adiciona uma tag de rede à VM que associa a regra de firewall à VM. Em seguida, ele cria a regra de firewall de entrada correspondente que permite todo o tráfego de entrada em tcp:80 (HTTP) ou tcp:443 (HTTPS).

  8. Para salvar as alterações, clique em Salvar.

  9. Para reiniciar a VM, clique em Iniciar/Retomar.

Para mais informações, consulte Criar e iniciar uma instância de VM.

Implantar um aplicativo na VM

Para testar a configuração de rede e confirmar se o tráfego está sendo veiculado conforme o esperado, é possível implantar um app básico na VM que detecta uma porta.

Por exemplo, os comandos a seguir criam um serviço da Web do Node.js que detecta a porta 3000.

  1. Estabeleça uma conexão SSH com a instância de VM.

  2. Atualize os repositórios de pacotes:

    sudo apt update

  3. Instale o NVM, Node.js, e o npm.

    Para mais informações, consulte Como configurar um ambiente de desenvolvimento em Node.js.

  4. Crie um arquivo package.json de forma interativa:

    npm init

    Exemplo:

    {
"name": "test",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "hello"
},
"author": "",
"license": "ISC"
}

  5. Instale Express, um framework de aplicativos da Web para Node.js:

    npm install express

  6. Escreva o código do app de teste:

    vim app.js

    O exemplo a seguir cria um app que responde a GET solicitações para o caminho raiz (/) com o texto "Hello, world!"

    const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.status(200).send('Hello, world!').end();
});

app.listen(3000, () => {
  console.log('Sample app listening on port 3000.');
});

    Anote a porta em que o app está detectando. O mesmo número de porta precisa ser usado ao configurar o endpoint para o serviço do Diretório de serviços.

  7. Confirme se o app está detectando a porta 3000:

    node app.js

O Compute Engine oferece uma variedade de opções de implantação. Para mais informações, consulte Escolher uma estratégia de implantação do Compute Engine para sua carga de trabalho.

Configurar o diretório de serviços

Para oferecer suporte à invocação de um endpoint particular de uma execução de fluxo de trabalho, é necessário configurar um namespace do Diretório de serviços, registrar um serviço no namespace e adicionar um endpoint ao serviço.

Por exemplo, os comandos a seguir criam um namespace, um serviço e um endpoint que especifica a rede VPC e o endereço IP interno da instância de VM.

  1. Para criar um namespace:

    gcloud service-directory namespaces create NAMESPACE \
    --location=REGION

    Substitua:

    • NAMESPACE: o ID do namespace ou o identificador totalmente qualificado do namespace.
    • REGION: a Google Cloud região que contém o namespace, por exemplo, us-central1.

  2. Criar um serviço:

    gcloud service-directory services create SERVICE \
    --namespace=NAMESPACE \
    --location=REGION

    Substitua SERVICE pelo nome do serviço que você está criando.

  3. Configure um endpoint.

    gcloud service-directory endpoints create ENDPOINT \
    --namespace=NAMESPACE \
    --service=SERVICE \
    --network=projects/PROJECT_NUMBER/locations/global/networks/NETWORK_NAME \
    --port=PORT_NUMBER \
    --address=IP_ADDRESS \
    --location=REGION

    Substitua:

    • ENDPOINT: o nome do endpoint que você está criando.
    • PORT_NUMBER: a porta em que o endpoint está em execução, por exemplo, 3000.
    • IP_ADDRESS: o endereço IPv6 ou IPv4 do endpoint. Esse é o endereço IP interno que você anotou anteriormente.

Para mais informações, consulte Configurar o Diretório de serviços e Configurar o acesso à rede privada.

Criar e implantar o fluxo de trabalho

A chamada ou invocação de um endpoint particular do Workflows é feita por uma solicitação HTTP. Os métodos de solicitação HTTP mais comuns têm um atalho de chamada (como http.get e http.post), mas é possível fazer qualquer tipo de solicitação HTTP definindo o campo call como http.request e especificando o tipo de solicitação usando o campo method. Para mais informações, consulte Fazer uma solicitação HTTP.

  1. Crie um arquivo de código-fonte para o fluxo de trabalho:

    touch call-private-endpoint.JSON_OR_YAML

    Substitua JSON_OR_YAML por yaml ou json, dependendo do formato do fluxo de trabalho.

  2. Em um editor de texto, copie o fluxo de trabalho a seguir (que, neste caso, usa um protocolo HTTP para o valor url) para o arquivo de código-fonte:

    YAML

    main:
  steps:
    - checkHttp:
        call: http.get
        args:
          url: http://IP_ADDRESS
          private_service_name: "projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE"
        result: res
    - ret:
        return: ${res}

    JSON

    {
  "main": {
    "steps": [
      {
        "checkHttp": {
          "call": "http.get",
          "args": {
            "url": "http://IP_ADDRESS",
            "private_service_name": "projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE"
          },
          "result": "res"
        }
      },
      {
        "ret": {
          "return": "${res}"
        }
      }
    ]
  }
}

    O valor private_service_name precisa ser uma string que especifica um nome de serviço registrado do Diretório de serviços com o seguinte formato:

    projects/PROJECT_ID/locations/LOCATION/namespaces/NAMESPACE_NAME/services/SERVICE_NAME

  3. Implante o fluxo de trabalho. Para fins de teste, é possível anexar a conta de serviço padrão do Compute Engine ao fluxo de trabalho para representar a identidade dele:

    gcloud workflows deploy call-private-endpoint \
    --source=call-private-endpoint.JSON_OR_YAML \
    --location=REGION \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

  4. Execute o fluxo de trabalho:

    gcloud workflows run call-private-endpoint \
    --location=REGION

    Uma resposta semelhante a esta será exibida:

    argument: 'null'
duration: 0.650784403s
endTime: '2023-06-09T18:19:52.570690079Z'
name: projects/968807934019/locations/us-central1/workflows/call-private-endpoint/executions/4aac88d3-0b54-419b-b364-b6eb973cc932
result: '{"body":"Hello, world!","code":200,"headers":{"Connection":"keep-alive","Content-Length":"21","Content-Type":"text/html;
charset=utf-8","Date":"Fri, 09 Jun 2023 18:19:52 GMT","Etag":"W/\"15-NFaeBgdti+9S7zm5kAdSuGJQm6Q\"","Keep-Alive":"timeout=5","X-Powered-By":"Express"}}'
startTime: '2023-06-09T18:19:51.919905676Z'
state: SUCCEEDED

A seguir