Configurar express links

Pré-lançamento — Express links

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Os links expressos na rede de ambiente permitem conectar um serviço de origem do Cloud Run a um serviço de destino do Cloud Run no mesmo projeto e região sem escrever código de autenticação no aplicativo ou configurar uma malha de serviço.

Quando um serviço do Cloud Run chama outro serviço do Cloud Run protegido pelo Identity and Access Management (IAM), a solicitação precisa incluir um token de ID do OpenID Connect (OIDC) para que o destino possa verificar a identidade e as permissões do autor da chamada. Sem um express link, você precisa escrever um código de autenticação de serviço para serviço no aplicativo para buscar e anexar tokens do servidor de metadados ou configurar recursos do Cloud Service Mesh, como uma rede de nuvem privada virtual (VPC), serviços de back-end e regras de roteamento. Um express link transfere esse trabalho de autenticação e roteamento para o contêiner secundário de ambiente totalmente gerenciado, mantendo o código do aplicativo portátil e focado na lógica de negócios.

Casos de uso

É possível usar express links nos seguintes cenários:

• Transferir a autenticação de serviço a serviço do código do aplicativo: conecte um serviço de chamada do Cloud Run a um serviço de destino do Cloud Run protegido pelo IAM por HTTP simples. O sidecar ambiente busca e injeta automaticamente o token de ID do OIDC do serviço de origem e criptografa a solicitação por HTTPS.
• Abstrair URLs de destino com nomes de host personalizados: configure um nome de host personalizado no express link usando a flag --matches-hostname para que o aplicativo de origem envie solicitações para um endereço lógico, como http://my-backend, em vez de codificar o URL determinista do destino. Se o serviço de destino mudar, será possível recriar o express link para apontar para o novo destino sem modificar ou reimplantar o código do aplicativo de origem.
• Simplifique as chamadas de serviço ponto a ponto sem uma malha de serviço: receba injeção automática de credenciais entre serviços do Cloud Run sem provisionar uma rede VPC, grupos de endpoints de rede, serviços de back-end ou registros do Cloud DNS exigidos pelo Cloud Service Mesh.

A tabela a seguir compara as etapas para configurar a comunicação autenticada entre serviços com e sem um express link:

Etapa	Sem um express link	Com um express link
1. Implantar o serviço de destino	Implante o serviço de destino do Cloud Run com a autenticação do IAM necessária (--no-allow-unauthenticated).	Igual.
2. Conceder permissão de invocador	Conceda o papel de Invocador do Cloud Run (roles/run.invoker) no serviço de destino à conta de serviço do serviço de origem.	Igual.
3. Configurar a solicitação de saída	Escreva um código no aplicativo de origem para buscar um token de ID do OIDC para o URL de destino e anexá-lo ao cabeçalho Authorization: Bearer por HTTPS.	Envie uma solicitação http:// simples para o URL de destino ou o nome do host personalizado sem código de autenticação no aplicativo de origem.
4. Implantar o serviço de origem	Implante o serviço de origem do Cloud Run.	Implante o serviço de origem do Cloud Run com a rede de ambiente ativada e crie um express link entre os serviços de origem e destino implantados.

Arquitetura

Quando você ativa a rede de ambiente em um serviço de origem do Cloud Run e cria um express link, o Cloud Run configura o contêiner secundário do Envoy totalmente gerenciado que é executado ao lado do contêiner do aplicativo em cada instância de contêiner.

Quando o aplicativo envia uma solicitação HTTP simples para o URL determinista do serviço de destino ou para um nome de host personalizado que você configura no link expresso, o contêiner secundário de ambiente faz o seguinte automaticamente:

1. Intercepta solicitações HTTP de saída destinadas ao serviço de destino.
2. Busca um token de ID do OIDC para a conta de serviço do serviço de origem e o injeta no cabeçalho Authorization.
3. Criptografa e encaminha a solicitação por HTTPS (TLS unidirecional) para o serviço de destino do Cloud Run, que verifica as permissões do IAM do autor da chamada.

Figura 1. O contêiner secundário intercepta as solicitações de saída do serviço de origem, injeta um token de ID do OIDC e encaminha a solicitação por HTTPS (TLS unidirecional) para o serviço de destino.

Conectividade de rede e plano de dados

Um express link configura a interceptação de solicitações de saída e a injeção de credenciais no sidecar de ambiente, mas não substitui o caminho de rede subjacente entre os serviços. Ainda é necessário garantir que o serviço de origem possa alcançar o caminho de entrada do serviço de destino:

• Entrada de destino definida como Tudo: nenhuma rede VPC ou configuração de saída é necessária no serviço de origem.
• Entrada de destino definida como Interna ou Interna e balanceadores de carga do Cloud: é preciso rotear o tráfego de saída do serviço de origem por uma rede VPC autorizada usando a saída de VPC direta ou um conector de acesso VPC sem servidor com o Acesso privado do Google ativado. Para mais informações, consulte Receber solicitações de outros serviços do Cloud Run.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Ative as APIs Cloud Run, Network Services e Traffic Director, se ainda não estiverem ativadas.

   Funções necessárias para ativar APIs

   Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar as APIs

2. Verifique se você tem um serviço de origem do Cloud Run e um serviço de destino do Cloud Run no mesmo projeto e região.
3. Verifique se a rede de ambiente está ativada com o escopo global no serviço de origem do Cloud Run. Por exemplo, execute gcloud beta run services update SOURCE_SERVICE --ambient-networking --ambient-scope=global --region=REGION, lembrando-se de primeiro aumentar os limites de CPU e memória do serviço.

4. Leia a página de preços do Cloud Run para saber mais sobre o uso do sidecar de rede ambiente. O faturamento dos recursos de ambiente não é aplicado durante o pré-lançamento.

Funções exigidas

Para receber as permissões necessárias para configurar express links, peça ao administrador que conceda a você os seguintes papéis do IAM:

• Configurar o express link: Desenvolvedor do Cloud Run (roles/run.developer) e Usuário da conta de serviço (roles/iam.serviceAccountUser) no projeto
• Gerenciar recursos de express link: Administrador de serviços de rede (roles/networkservices.admin) no projeto

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

A identidade de serviço do serviço de origem do Cloud Run também precisa ter os seguintes papéis no projeto:

• Cliente do Traffic Director (roles/trafficdirector.client)
• Agente do Cloud Trace (roles/cloudtrace.agent)

Para conceder esses papéis à identidade de serviço, use a gcloud:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:RUN_CLIENT_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/trafficdirector.client"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:RUN_CLIENT_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/cloudtrace.agent"

Substitua:

• PROJECT_ID: o ID do projeto Google Cloud .
• RUN_CLIENT_SA: o nome da conta de serviço anexada ao serviço de origem do Cloud Run.

Se a identidade de serviço do Cloud Run não tiver esses papéis, o serviço do Cloud Run ainda será implantado, mas os recursos que dependem da rede ambiente não vão funcionar. Esse comportamento é diferente do Cloud Service Mesh, em que o serviço do Cloud Run não é implantado quando não tem os papéis necessários.

Limitações

As seguintes limitações se aplicam aos links expressos:

• Somente os serviços do Cloud Run são compatíveis como recursos de origem e destino. Jobs, pools de workers e instâncias do Cloud Run não são compatíveis.
• Não há suporte para configurações entre projetos e entre regiões. Os serviços de origem e destino do Cloud Run precisam estar no mesmo projeto e região.
• Os express links exigem Rede Ambiente com o escopo global no serviço de origem. Se o serviço de origem usar o escopo regional, a express link será criada, mas o tráfego não será roteado.
• É necessário criar os serviços de origem e destino do Cloud Run antes de criar o express link. Não é possível criar fora de ordem. Se você excluir um serviço de destino, o express link poderá continuar mostrando e exibindo a configuração desatualizada até que você exclua ou recrie o express link.
• Não é possível atualizar o serviço de origem, o serviço de destino ou o nome do host personalizado de um express link atual. O comando gcloud beta network-services express-links update atualiza apenas a descrição do express link. Para mudar a configuração de roteamento, exclua e recrie o express link.
• Os serviços de destino do Cloud Run precisam ter o URL padrão run.app ativado, mesmo que você use URLs personalizados, domínios personalizados ou configure um nome de host personalizado com a flag --matches-hostname.
• As solicitações enviadas ao URL não determinista do destino não são interceptadas e falham com um erro 403 Forbidden. Se o serviço de destino não tiver um URL determinista porque o nome do serviço e o número do projeto combinados excedem 63 caracteres, especifique --matches-hostname. Caso contrário, a criação do express link vai falhar com um erro Cloud Run Service name is too long.
• Quando você visualiza o status completo de um express link, apenas as informações do serviço de destino são retornadas. Os detalhes sobre as revisões de origem do Cloud Run e a autenticação negociada podem estar ausentes ou mostrar dados desatualizados. Isso não afeta como o express link roteia ou autentica o tráfego.
• Os serviços de origem do Cloud Run configurados com identidade do agente e tokens vinculados a mTLS não são compatíveis.
• Os serviços de origem do Cloud Run configurados para rotear o tráfego de saída pelo Gateway de Agente no Cloud Run e pelo Secure Web Proxy não são compatíveis. Os express links exigem o escopo de rede global do ambiente, enquanto o Gateway de Agente exige o escopo regional.
• Se uma solicitação de saída do serviço de origem já incluir um cabeçalho Authorization, o express link vai encaminhar a solicitação com esse cabeçalho inalterado e não vai injetar um token. A injeção automática de token no cabeçalho X-Serverless-Authorization não é compatível.
• O tráfego gerado por contêineres de sandbox do Cloud Run não é compatível.
• Não é possível usar express links para encaminhar tráfego para serviços de destino do Cloud Run protegidos pelo Identity-Aware Proxy.
• Cada express link é compatível com um serviço de destino do Cloud Run, e é possível criar até 5.000 express links por projeto.

Configurar um link expresso

Para conectar os serviços do Cloud Run, crie um express link especificando o serviço de origem e o de destino e conceda o papel de invocador do Cloud Run no serviço de destino.

Conectar-se a outro serviço do Cloud Run

Para conectar um serviço de origem do Cloud Run a um serviço de destino do Cloud Run, crie um express link usando gcloud ou YAML.

gcloud

Use o comando gcloud beta network-services express-links create para criar um express link:

gcloud beta network-services express-links create EXPRESS_LINK_NAME \
    --location=global \
    --source-services=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SOURCE_SERVICE \
    --destination-services=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/DESTINATION_SERVICE

Substitua:

• EXPRESS_LINK_NAME: um nome para o link expresso.
• PROJECT_ID: o ID do projeto Google Cloud .
• REGION: a região em que os serviços do Cloud Run estão implantados.
• SOURCE_SERVICE: o nome do serviço de origem do Cloud Run.
• DESTINATION_SERVICE: o nome do serviço de destino do Cloud Run.

Depois que o comando for concluído, pode levar até 2 minutos para que a configuração de roteamento seja propagada para as instâncias do serviço de origem em execução.

Por padrão, o express link intercepta apenas as solicitações enviadas ao URL determinístico do serviço de destino, não ao URL não determinístico. Para usar um nome de host personalizado, transmita o nome do host sem um esquema na flag --matches-hostname="HOSTNAME", como --matches-hostname="DESTINATION_SERVICE", e envie solicitações do aplicativo de origem para http://HOSTNAME. Especificar --matches-hostname substitui o URL determinista em vez de adicionar a ele.

YAML

1. Crie um arquivo de configuração, por exemplo, express-link.yaml:

   name: "projects/PROJECT_ID/locations/global/expressLinks/EXPRESS_LINK_NAME"
   source:
     services:
       - "//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SOURCE_SERVICE"
   destination:
     services:
       - "//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/DESTINATION_SERVICE"

   Substitua:

   • PROJECT_ID: o ID do projeto Google Cloud .
   • REGION: a região em que os serviços estão implantados.
   • EXPRESS_LINK_NAME: um nome para o link expresso.
   • SOURCE_SERVICE: o nome do serviço de origem do Cloud Run.
   • DESTINATION_SERVICE: o nome do serviço de destino do Cloud Run.

2. Importe o arquivo YAML usando o comando gcloud beta network-services express-links import:

   gcloud beta network-services express-links import EXPRESS_LINK_NAME \
       --location=global \
       --source=YAML_FILENAME.yaml

   Substitua:

   • EXPRESS_LINK_NAME: um nome para o link expresso.
   • YAML_FILENAME: o nome do arquivo YAML.

Conceder permissões de invocador no serviço de destino

Para permitir que o serviço de origem invoque um serviço de destino protegido pelo IAM, conceda o papel Invocador do Cloud Run (roles/run.invoker) à conta de serviço do serviço de origem no serviço de destino do Cloud Run. Isso é necessário para que a autenticação funcione no plano de dados.

gcloud run services add-iam-policy-binding DESTINATION_SERVICE \
    --member="serviceAccount:SOURCE_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/run.invoker" \
    --region=REGION

Substitua:

• DESTINATION_SERVICE: o nome do serviço de destino do Cloud Run.
• SOURCE_SA: o nome da conta de serviço anexada ao serviço de origem do Cloud Run.
• PROJECT_ID: o ID do projeto Google Cloud .
• REGION: a região em que o serviço de destino está implantado.

Verificar o status do express link

Para conferir a configuração básica do express link, use o comando gcloud beta network-services express-links describe:

gcloud beta network-services express-links describe EXPRESS_LINK_NAME \
    --location=global

Para conferir o status completo do express link, incluindo connectionStatus (tipo de rota ativa, nomes de host correspondentes e URI de revisão de origem) e cloudRunSourceInfo (métodos de autenticação configurados e rede VPC), inclua ?view=EXPRESS_LINK_VIEW_FULL# no nome do recurso:

gcloud beta network-services express-links describe 'EXPRESS_LINK_NAME?view=EXPRESS_LINK_VIEW_FULL#' \
    --location=global

Substitua EXPRESS_LINK_NAME pelo nome do express link. Mantenha as aspas simples e o caractere # final ao consultar a visualização completa.

Excluir ou recriar um express link

Para remover um express link e interromper a injeção automática de credenciais e a interceptação de tráfego do serviço de origem, use o comando gcloud beta network-services express-links delete:

gcloud beta network-services express-links delete EXPRESS_LINK_NAME \
    --location=global

Substitua EXPRESS_LINK_NAME pelo nome do express link.

Para apontar um express link atual para um serviço de destino diferente ou alterar a configuração --matches-hostname, exclua o express link com o comando anterior e crie um novo express link com a configuração atualizada.

A seguir

• Saiba como configurar a rede ambiente para serviços do Cloud Run.
• Saiba mais sobre o Gateway de Agente no Cloud Run.
• Saiba mais sobre a autenticação entre serviços no Cloud Run.
• Saiba como restringir a entrada de endpoints de rede para serviços do Cloud Run.