Domínio personalizado do Agentspace

1. Introdução

OBSERVAÇÃO: este tutorial fornece instruções detalhadas para configurar um domínio personalizado para o Agentspace. A criação de aplicativos do Agentspace não é abordada neste guia.

Este documento fornece uma arquitetura de referência para configurar um domínio personalizado para acessar o AgentSpace. Em vez do URL gerenciado pelo Google atribuído durante a criação do app Agentspace, os usuários podem usar um domínio personalizado. Este codelab demonstra o acesso ao calendário e aos aplicativos do Agentspace usando o domínio nip.io. O nip.io é um serviço sem custo financeiro e de código aberto que fornece DNS curinga para qualquer endereço IP. Essencialmente, ele permite que você crie um nome de host que seja resolvido para um endereço IP específico sem precisar configurar seu próprio servidor DNS ou modificar o arquivo /etc/hosts.

É recomendável usar seu próprio domínio, mas, para fins de demonstração, o nip.io é usado no tutorial.

OBSERVAÇÃO: o domínio personalizado do Agentspace vai redirecionar para o URL gerenciado pelo Google.

No cenário de implantação mostrado abaixo (Figura 1), o AgentSpace publicou um repositório de dados com um aplicativo de calendário acessado por um URL público gerenciado pelo Google.

Figura 1.

O crescimento contínuo do repositório de dados e dos aplicativos subsequentes resulta em um gerenciamento adicional de URLs públicos gerenciados pelo Google, conforme mostrado no cenário de implantação abaixo (Figura 2), resultando em um mapeamento 1:1 dos aplicativos e URLs do Agentspace.

Figura 2.

Um domínio personalizado permite o mapeamento de vários aplicativos do AgentSpace para um único domínio do cliente especificado pelo usuário. Esse recurso permite que um caminho de URL específico seja associado a cada aplicativo do Agentspace, oferecendo maior flexibilidade, conforme mostrado no cenário de implantação abaixo (Figura 3). Por exemplo, um domínio gerenciado pelo cliente, agentspace.cosmopup.com, é dividido em regras de caminho, cada uma mapeada para um aplicativo específico do Agentspace. Por exemplo:

• agentspace.cosmopup.com/drive-app, que é associado ao app Agentspace para o Drive do Workspace
• agentspace.cosmopup.com/calendar-app, que é associado ao aplicativo Agentspace para a Agenda do Workspace

As regras de host e de caminho do balanceador de carga de aplicativo externo,configuradas pelo mapa de URL, controlam a lógica que mapeia o domínio personalizado para o URL gerenciado pelo Google. Ele executa a função a seguir usando o exemplo agentspace.cosmopup.com/drive-app

• O caminho do host do domínio personalizado agentspace.cosmopup.com/drive-app é recebido pelo balanceador de carga.
• O mapa de URL está configurado para correspondência avançada de regras de host e caminho
• Os hosts agentspace.cosmopup.com estão qualificados para correspondência e substituição de caminho
• O caminho do host de domínio personalizado agentspace.cosmopup.com/drive-app está sujeito a UrlRewrite
• PathPrefixRewrite é o caminho do Agentspace: /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
• hostRewrite é o host do Agentspace: vertexaisearch.cloud.google.com
• A operação de regravação é realizada antes do roteamento para o serviço de back-end
• O serviço de back-end encaminha o tráfego para o aplicativo drive-app com base no URL do Agentspace

Figura 3.

O que você vai aprender

• Criar um balanceador de carga de aplicativo externo global
• Criar uma substituição de serviço de back-end usando um domínio personalizado e uma operação de substituição em um aplicativo do Agentspace
• Como integrar o nip.io e o Cloud DNS para criar um domínio personalizado
• Como validar o acesso a um domínio personalizado do Agentspace

O que é necessário

• Projeto do Google Cloud com permissões de proprietário
• URL(s) do aplicativo do Agentspace
• Domínio personalizado do proprietário (opcional)
• Certificados: autoassinados ou gerenciados pelo Google

2. O que você vai criar

Você vai estabelecer um balanceador de carga de aplicativo externo global com recursos avançados de gerenciamento de tráfego para ativar a correspondência de caminho de domínio personalizado para aplicativos do Agentspace usando a regra de host e caminho. Após a implantação, você vai realizar as seguintes ações para validar o acesso ao aplicativo Agentspace:

• Para acessar o aplicativo da Agentspace, abra um navegador da Web e navegue até o domínio personalizado e o caminho especificado.

OBSERVAÇÃO: o tutorial não fornece orientações sobre o repositório de dados do Agentspace ou a implantação do aplicativo.

3. Requisitos de rede

Confira abaixo os requisitos de rede:

Componentes	Descrição
VPC (agentspace-vpc)	VPC de modo personalizado
NEG da Internet	Um recurso usado para definir um back-end externo para o balanceador de carga configurado como FQDN, que denota o FQDN gerenciado pelo Google do Agentspace (vertexaisearch.cloud.google.com). O FQDN da Internet realiza a pesquisa DNS na VPC para resolução.
Serviço de back-end	Um serviço de back-end funciona como uma ponte entre o balanceador de carga e os recursos de back-end. No tutorial, o serviço de back-end está associado ao NEG da Internet.
Certificados	Para configurar certificados para um Application Load Balancer no Google Cloud, use o serviço Gerenciador de certificados e certificados SSL autogerenciados ou gerenciados pelo Google.
Cloud DNS	A zona pública do Cloud DNS é usada para resolver o IP externo do balanceador de carga de aplicativo externo para nip.io (agentspace.externalip.nip.io). Como alternativa, use seu domínio personalizado e o registro A que consiste no endereço IP do balanceador de carga.

4. Topologia do codelab

5. Configuração e requisitos

Configuração de ambiente autoguiada

1. Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.

• O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
• O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como PROJECT_ID. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto.
• Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.

Atenção: o ID do projeto é globalmente exclusivo e não pode ser usado por outras pessoas após a seleção. Você é o único usuário com esse ID. Mesmo que um projeto seja excluído, o ID não poderá ser usado novamente.

Observação: se você usa uma conta do Gmail, defina o local padrão como Sem organização. Se você usa uma conta do Google Workspace, escolha um local adequado para a organização.

2. Em seguida, ative o faturamento no console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não vai ser muito cara, se tiver algum custo. Para encerrar os recursos e evitar cobranças além deste tutorial, exclua os recursos criados ou exclua o projeto. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.

Inicie o Cloud Shell

Embora o Google Cloud e o Spanner possam ser operados remotamente do seu laptop, neste codelab usaremos o Google Cloud Shell, um ambiente de linha de comando executado no Cloud.

No Console do Google Cloud, clique no ícone do Cloud Shell na barra de ferramentas superior à direita:

O provisionamento e a conexão com o ambiente levarão apenas alguns instantes para serem concluídos: Quando o processamento for concluído, você verá algo como:

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, todo o trabalho pode ser feito com um navegador. Você não precisa instalar nada.

6. Antes de começar

Ativar APIs

No Cloud Shell, verifique se o ID do projeto está configurado:

gcloud config list project
gcloud config set project [YOUR-PROJECT-ID]
project=[YOUR-PROJECT-ID]
region=[YOUR-REGION]
echo $project
echo $region

Ative todos os serviços necessários:

gcloud services enable compute.googleapis.com
gcloud services enable dns.googleapis.com

7. Criar rede VPC

Rede VPC

No Cloud Shell, faça o seguinte:

gcloud compute networks create agentspace-vpc --subnet-mode custom

8. Configurar os componentes do balanceador de carga

Reservar o endereço IP externo do balanceador de carga

No Cloud Shell, reserve um endereço IP externo para o balanceador de carga:

gcloud compute addresses create external-ip \
    --network-tier=PREMIUM \
    --ip-version=IPV4 \
    --global

No Cloud Shell, confira o endereço IP reservado:

gcloud compute addresses describe external-ip \
  --global | grep -i address:

Exemplo de saída:

user@cloudshell$ gcloud compute addresses describe external-ip \
  --global | grep -i address:
address: 34.54.158.206

Configurar o NEG da Internet

Crie uma NEG na Internet e defina o –network-endpoint-type como internet-fqdn-port (o nome do host e a porta em que seu back-end externo pode ser alcançado). Para resolver o Agentspace, o FQDN vertexaisearch.cloud.google.com e a PORTA 443 são usados.

gcloud compute network-endpoint-groups create agentspace-ineg \
    --network-endpoint-type="internet-fqdn-port" \
    --global

gcloud compute network-endpoint-groups update agentspace-ineg \
    --add-endpoint="fqdn=vertexaisearch.cloud.google.com,port=443" \
    --global

Criar o balanceador de carga

No Cloud Shell, faça o seguinte:

gcloud compute backend-services create agentspace-ineg-bes \
      --load-balancing-scheme=EXTERNAL_MANAGED \
      --protocol=HTTPS \
      --global

gcloud compute backend-services add-backend agentspace-ineg-bes \
      --network-endpoint-group=agentspace-ineg \
      --global-network-endpoint-group \
      --global  

Criar o certificado

Neste ponto, você criou a NEG na Internet e o serviço de back-end. Na próxima seção, será necessário criar um recurso de certificado para usar no proxy de destino HTTPs. É possível criar um recurso de certificado SSL usando um certificado SSL gerenciado pelo Google ou um certificado SSL autogerenciado. Recomendamos o uso de certificados gerenciados pelo Google porque o Google Cloud recebe, gerencia e renova esses certificados automaticamente.

Para saber mais sobre os certificados compatíveis com o balanceador de carga de aplicativo externo global usado neste tutorial, consulte:

Visão geral dos certificados SSL | Balanceamento de carga | Google Cloud

Na seção a seguir, você vai criar um certificado autoassinado (embora um certificado gerenciado pelo Google possa ser usado) que exige o mapeamento do nome comum para o nome de domínio totalmente qualificado (agentspace.YOUR-EXTERNAL-IP.nip.io) corresponde ao endereço IP externo do balanceador de carga gerado anteriormente. Exemplo abaixo:

Nome comum: agentspace.34.54.158.206.nip.io

No Cloud Shell, crie a chave privada

openssl genrsa -out private-key-file.pem 2048

No Cloud Shell, crie um arquivo config.txt usado para gerar o arquivo pem. Especifique o nome de domínio totalmente qualificado na entrada DNS 1 agentspace.YOUR-EXTERNAL-IP.nip.io, por exemplo, agentspace.34.54.158.206.nip.io na configuração abaixo.

cat <<'EOF' >config.txt
[req]
default_bits              = 2048
req_extensions            = extension_requirements
distinguished_name        = dn_requirements

[extension_requirements]
basicConstraints          = CA:FALSE
keyUsage                  = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName            = @sans_list

[dn_requirements]
countryName               = Country Name (2 letter code)
stateOrProvinceName       = State or Province Name (full name)
localityName              = Locality Name (eg, city)
organizationName          = Organization Name (eg, company)
organizationalUnitName    = Organizational Unit Name (eg, section)
commonName                = Common Name (e.g. server FQDN or YOUR name)
emailAddress              = Email Address

[sans_list]
DNS.1                     = agentspace.YOUR-EXTERNAL-IP.nip.io

EOF

No Cloud Shell, valide se o config.txt e o private-key-file.pem foram gerados.

user@cloudshell:$ ls
config.txt  private-key-file.pem

Crie o arquivo de solicitação de assinatura de certificado que vai invocar uma série de perguntas definidas no arquivo config.txt. Verifique se o nome comum inserido corresponde ao domínio personalizado qualificado agentspace.YOUR-EXTERNAL-IP.nip.io, por exemplo, agentspace.34.54.158.206.nip.io.

No Cloud Shell, faça o seguinte.

sudo openssl req -new -key private-key-file.pem \
    -out csr.pem \
    -config config.txt

Exemplo:

user@cloudshell:$ sudo openssl req -new -key private-key-file.pem \
    -out csr.pem \
    -config config.txt
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:
State or Province Name (full name) []:
Locality Name (eg, city) []:
Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name)[]:agentspace.34.54.158.206.nip.io
Email Address []:

No Cloud Shell, valide a criação da assinatura de certificado pem necessária.

user@cloudshell:$ ls
config.txt  csr.pem  private-key-file.pem

No Cloud Shell, gere o certificado.

sudo openssl x509 -req \
    -signkey private-key-file.pem \
    -in csr.pem \
    -out cert.cert \
    -extfile config.txt \
    -extensions extension_requirements \
    -days 365

Exemplo de resposta:

user@cloudshell:$ sudo openssl x509 -req \
    -signkey private-key-file.pem \
    -in csr.pem \
    -out cert.cert \
    -extfile config.txt \
    -extensions extension_requirements \
    -days 365
Certificate request self-signature ok
subject=CN = agentspace.34.54.158.206.nip.io

No Cloud Shell, valide a criação do arquivo cert.cert.

user@cloudshell:$ ls
cert.cert  config.txt  csr.pem  private-key-file.pem

Crie um recurso de certificado para associar ao balanceador de carga externo. Substitua os parâmetros de certificado e chave privada pelos nomes dos arquivos específicos.

No Cloud Shell, faça o seguinte:

gcloud compute ssl-certificates create agentspace-self-signed-cert \
    --certificate=cert.cert \
    --private-key=private-key-file.pem \
    --global

No Cloud Shell, faça o seguinte:

gcloud compute url-maps create agentspace-lb \
      --default-service=agentspace-ineg-bes \
      --global  

No Cloud Shell, faça o seguinte:

gcloud compute target-https-proxies create https-proxy \
      --ssl-certificates=agentspace-self-signed-cert \
      --url-map=agentspace-lb \
      --global 

No Cloud Shell, faça o seguinte:

gcloud compute forwarding-rules create agentspace-fr \
      --load-balancing-scheme=EXTERNAL_MANAGED \
      --network-tier=PREMIUM \
      --address=external-ip \
      --target-https-proxy=https-proxy \
      --global \
      --ports=443

9. Criar uma zona de DNS pública

Para fins de teste, vamos usar o nip.io, um serviço de DNS curinga que simplifica o desenvolvimento e o teste local, permitindo que qualquer endereço IP seja mapeado para um nome de host seguindo um formato específico. Isso elimina a necessidade de editar manualmente os arquivos de host para mapeamentos de domínios personalizados.

O URL público usa o endereço IP externo que você acabou de configurar. YOUR COMMON NAME MUST BE CONFIGURED WITH <agentspace.YOUR-EXTERNAL-IP.nip.io>, por exemplo, agentspace.34.54.158.206.nip.io

Na próxima seção, você vai criar uma zona de DNS pública usada pelo nip.io para resolver o endereço IP do balanceador de carga externo.

No Cloud Shell, faça o seguinte para criar uma variável para o endereço IP do balanceador de carga externo:

externalip=<YOUR-EXTERNAL-IP>
echo $externalip

No Cloud Shell, faça o seguinte:

gcloud dns --project=$project managed-zones create agentspace-dns --description="Agentspace public dns" --dns-name="$externalip.nip.io." --visibility="public"

No Cloud Shell, faça o seguinte:

gcloud dns --project=$project record-sets create agentspace.$externalip.nip.io. --zone="agentspace-dns" --type="A" --ttl="300" --rrdatas="$externalip"

10. Credenciais do OAuth

Na próxima seção, você vai criar uma credencial OAuth para aplicativos da Web que redireciona o URL gerenciado pelo Google para oauth-redirect para autenticação. As credenciais geradas não são necessárias para o tutorial.

Para saber mais sobre o Oauth, consulte:

Adicionar ações do Google Agenda e do Gmail | Google Agentspace

Criar um app OAuth e adicionar escopos

1. Acesse APIs e serviços > Tela de permissão OAuth: Acessar a tela de permissão OAuth
2. Selecione "Interno" e clique em "Criar".
3. Insira um nome para o app OAuth.
4. Insira um e-mail de suporte ao usuário.
5. Insira os dados de contato do desenvolvedor.
6. Clique em Salvar e continuar .

Criar um ID do cliente OAuth

Este procedimento descreve como criar um novo ID do cliente OAuth para ações do Google Cloud. Esse ID do cliente e chave secreta do OAuth também podem ser usados para outras ações do Google Cloud. Se você já tiver um ID de cliente OAuth do Google Cloud para ações do Google Cloud, poderá usar esse ID e a chave secreta para ações do Google Agenda em vez de criar um novo ID.

1. Acesse a página "Credenciais" e clique em "Criar credenciais" > "ID do cliente do OAuth".
2. Selecione "Aplicativo da Web".
3. Insira um nome para o ID de cliente.
4. Clique em "Adicionar URI" e insira o seguinte URI: https://vertexaisearch.cloud.google.com/oauth-redirect
5. Clique em "Criar" e copie as seguintes informações:

• ID do cliente
• Chave secreta do cliente

11. Identificar URLs de aplicativos do Agentspace

O procedimento a seguir identifica os URLs públicos do Agentspace gerenciados pelo Google que são mapeados para cada aplicativo do Agentspace. A saída dos URLs é um exemplo com base na arquitetura de referência. Portanto, é necessário garantir que seus URLs sejam precisos.

Armazene o link para o app da Web por aplicativo.

Aplicativo Agenda

URL da Web do Agentspace: https://vertexaisearch.cloud.google.com/us/home/cid/bb6b8b27-939b-494d-9227-45903bb8afcf

Aplicativo do Drive

URL da Web do Agentspace:

https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd

12. Criar regra avançada de host e caminho

Na seção a seguir, você vai atualizar as regras de roteamento do balanceador de carga para ativar a opção de definir regras de host e caminho usando o console do Cloud. A tabela abaixo descreve os valores personalizados (em ordem de cima para baixo) atualizados com base no seu ambiente:

	Valor personalizado	Exemplo com base no tutorial
Hosts	agentspace.YOUR-EXTERNAL-IP.nip.io	agentspace.34.54.158.206.nip.io
defaultService	projects/<projectid>/global/backendServices/agentspace-ineg-bes	Ver captura de tela
prefixMatch	/<name of Agentspace app#1>	/drive-app
backendService	projects/<projectid>/global/backendServices/agentspace-ineg-bes	Ver captura de tela
pathPrefixRewrite	/<Agentspace URL path of app#1>	/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
hostRewrite	vertexaisearch.cloud.google.com	vertexaisearch.cloud.google.com
prefixMatch	/<name of Agentspace app#2>	/calendar-app
backendService	projects/<projectid>/global/backendServices/agentspace-ineg-bes	Ver captura de tela
pathPrefixRewrite	/<Agentspace URL path of app#2>	/us/home/cid/bb6b8b27-939b-494d-9227-45903bb8afcf
hostRewrite	vertexaisearch.cloud.google.com	vertexaisearch.cloud.google.com

Acesse o seguinte para acessar as regras de host e caminho

Balanceamento de carga → agentspace-lb → Selecionar edição

Selecione "Regras de roteamento" → "Regras avançadas de host e caminho".

Selecione "Adicionar regra de host e caminho".

Agora você vai poder criar uma nova regra de host e caminho. Na seção de hosts, insira agentspace.YOUR-EXTERNAL-IP.nip.io ou um domínio personalizado.

No campo "Correspondência de caminho" (correspondências, ações e serviços), atualize o conteúdo abaixo com a configuração do ambiente e selecione "Atualizar".

Erros podem aparecer no console após a aplicação da configuração. Portanto, formate a configuração para corresponder à captura de tela de exemplo fornecida ou copie e cole a configuração necessária da página do Balanceamento de carga do Cloud.

defaultService: projects/<projectid>/global/backendServices/agentspace-ineg-bes
name: matcher1
routeRules:
- matchRules:
 - prefixMatch: /<name of Agentspace app#1>
 priority: 1
 routeAction:
   weightedBackendServices:
   - backendService: projects/<projectid>/global/backendServices/agentspace-ineg-bes
     weight: 100
   urlRewrite:
     pathPrefixRewrite: /<Agentspace URL path of app#1>
     hostRewrite: vertexaisearch.cloud.google.com
- matchRules:
 - prefixMatch: /<name of Agentspace app#2>
 priority: 2
 routeAction:
   weightedBackendServices:
   - backendService: projects/<projectid>/global/backendServices/agentspace-ineg-bes
     weight: 101
   urlRewrite:
     pathPrefixRewrite: /<Agentspace URL path of app#2>
     hostRewrite: vertexaisearch.cloud.google.com

Exemplo de captura de tela:

13. Validação

A implantação foi concluída. É possível acessar o aplicativo Agentspace usando o domínio personalizado em um navegador da Web ou terminal, especificando agentspace.YOUR-EXTERNAL-IP.nip.io/path, por exemplo, agentspace.34.54.158.206.nip.io, como nos exemplos abaixo:

Aplicativo Agentspace: drive-app

Caminho: agentspace.34.54.158.206.nip.io/drive-app

Aplicativo Agentspace: drive-app

Caminho: agentspace.34.54.158.206.nip.io/calendar-app

Se você estiver usando um certificado autoassinado, um erro de certificado é esperado. Aceite o aviso.

14. Limpar

Excluir credenciais do OAuth:

Navegue até APIs e serviços → Credenciais.

Em "IDs do cliente do OAuth 2.0", selecione suas credenciais e exclua.

Em um único terminal do Cloud Shell, exclua os componentes do laboratório:

gcloud compute forwarding-rules delete agentspace-fr --global -q

gcloud compute target-https-proxies delete https-proxy --global -q

gcloud compute url-maps delete agentspace-lb --global -q

cloud compute ssl-certificates delete agentspace-self-signed-cert --global -q

gcloud compute backend-services delete agentspace-ineg-bes --global -q

gcloud compute network-endpoint-groups delete agentspace-ineg --global -q

gcloud dns --project=$projectid record-sets delete agentspace.$externalip.nip.io --zone="agentspace-dns" --type="A"

gcloud dns --project=$projectid managed-zones delete agentspace-dns

gcloud compute addresses delete external-ip --global -q

gcloud compute networks delete agentspace-vpc -q

15. Parabéns

Parabéns! Você configurou e validou a conectividade a um Agentspace usando um domínio personalizado com um balanceador de carga de aplicativo externo com gerenciamento de tráfego avançado.

Você criou a infraestrutura do balanceador de carga e aprendeu a criar um NEG da Internet, o Cloud DNS e o gerenciamento de tráfego avançado que ativaram a substituição de host e caminho, permitindo a conectividade ao Agentspace usando um domínio personalizado.

Cosmopup acha que os codelabs são incríveis.

Documentos de referência

• Configurar o gerenciamento de tráfego para balanceadores de carga de aplicativo externos globais
• Adicionar ações do Google Agenda e do Gmail | Google Agentspace
• Como usar o OAuth 2.0 para acessar as APIs do Google | Autorização
• nip.io