1. Introdução
Este documento fornece uma arquitetura de referência para configurar um domínio personalizado e acessar o AgentSpace usando o WIF. 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 aos aplicativos de agenda e Drive do Agentspace usando o domínio nip.io. O nip.io é um serviço sem custo financeiro de código aberto que fornece DNS curinga para qualquer endereço IP. Basicamente, ele permite criar um nome de host que é resolvido para um endereço IP específico sem precisar configurar seu próprio servidor DNS ou modificar o arquivo /etc/hosts.
Recomendamos usar seu próprio domínio, mas, para fins de demonstração, o tutorial usa nip.io.
No cenário de implantação mostrado abaixo (Figura 1), o AgentSpace publicou um repositório de dados que contém um aplicativo de agenda acessado por um URL público gerenciado pelo Google.
Figura 1.
O crescimento contínuo do armazenamento de dados e dos aplicativos subsequentes resulta em mais gerenciamento de URLs públicos gerenciados pelo Google, conforme mostrado no cenário de implantação abaixo (Figura 2), resultando em um mapeamento de 1:1 de aplicativos e URLs do Agentspace.
Figura 2.
Com um domínio personalizado, é possível mapear vários aplicativos do AgentSpace para um único domínio do cliente especificado pelo usuário. Com esse recurso, um caminho de URL específico pode ser associado a cada aplicativo do Agentspace, oferecendo mais flexibilidade, conforme mostrado no cenário de implantação abaixo (Figura 3). Por exemplo, um domínio gerenciado pelo cliente agentspace.cosmopup.com é segmentado em regras de caminho, cada uma mapeada para um aplicativo Agentspace específico. Por exemplo:
- agentspace.cosmopup.com/drive-app, que mapeia o aplicativo Agentspace para o Drive do Workspace
- agentspace.cosmopup.com/sharepoint-app, que mapeia para o aplicativo Agentspace para SharePoint
As regras de host e 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 seguinte função usando o exemplo agentspace.cosmopup.com/drive-app
- O balanceador de carga recebe o caminho do host do domínio personalizado agentspace.cosmopup.com/drive-app
- O mapa de URL está configurado para correspondência avançada de regras de host e caminho
- O host agentspace.cosmopup.com está qualificado para correspondência de caminho e redirecionamento
- O caminho do host do domínio personalizado agentspace.cosmopup.com/drive-app está sujeito a UrlRedirect
- pathRedirect é o caminho do Agentspace: /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
- hostRedirect é o host do Agentspace: vertexaisearch.cloud.google.com
- O caminho do host do domínio personalizado agentspace.cosmopup.com/sharepoint-app está sujeito a UrlRedirect
- pathRedirect é o caminho do Agentspace: /signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6
- hostRedirect é o host do Agentspace: auth.cloud.google
- A operação de redirecionamento é realizada antes do roteamento para o serviço de back-end.
Figura 3.
O que você vai aprender
- Criar um balanceador de carga de aplicativo externo global
- Criar um roteamento para redirecionar um domínio personalizado a 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
- URLs dos aplicativos 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 redirecionamento de host e caminho. Depois da implantação, faça as seguintes ações para validar o acesso ao aplicativo Agentspace:
- Acesse o aplicativo Agentspace abrindo um navegador da Web e navegando até seu domínio personalizado e o caminho especificado.
3. Requisitos de rede
Confira abaixo o detalhamento dos 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, indicando o FQDN gerenciado pelo Google do Agentspace (vertexaisearch.cloud.google.com). O FQDN da Internet realiza uma pesquisa de DNS na VPC para resolução. |
Serviço de back-end | Um serviço de back-end atua 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 balanceador de carga de aplicativo no Google Cloud, use o serviço Certificate Manager e certificados SSL gerenciados pelo Google ou autogerenciados. |
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). Ou use seu domínio personalizado e o registro A com o endereço IP do balanceador de carga. |
4. Topologia do codelab
5. Configuração e requisitos
Configuração de ambiente autoguiada
- 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.
- 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. Configurar os componentes do balanceador de carga
Reserve 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, veja 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 da 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 da Internet e o serviço de back-end. Na seção a seguir, 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 | Load Balancing | Google Cloud
Na seção a seguir, você vai criar um certificado autoassinado (embora um certificado gerenciado pelo Google possa ser usado). Ele exige o mapeamento do nome comum para o nome de domínio totalmente qualificado (agentspace.YOUR-EXTERNAL-IP.nip.io), que corresponde ao endereço IP externo do balanceador de carga gerado anteriormente. Confira o 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 os arquivos config.txt e private-key-file.pem foram gerados.
user@cloudshell:$ ls
config.txt private-key-file.pem
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 do arquivo PEM necessário para a assinatura do certificado.
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 de arquivo 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
8. Criar zona de DNS pública
Na seção a seguir, você vai criar uma zona de DNS público 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"
9. Identificar URLs de aplicativos do Agentspace
O procedimento a seguir identifica os URLs públicos do Agentspace gerenciados pelo Google que são gerados pelo Google e mapeados para cada aplicativo do Agentspace. A saída dos URLs são exemplos baseados na arquitetura de referência. Portanto, verifique se os URLs estão corretos.
Armazene o link para seu app da Web por aplicativo.
Aplicativo do Drive
URL da Web do Agentspace:
https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
Aplicativo do SharePoint
URL da Web do Agentspace: https://auth.cloud.google/signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6
10. Criar uma regra avançada de host e caminho
Na seção a seguir, você vai atualizar as regras de roteamento dos balanceadores 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). Atualize 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 | projects/your-project-id/global/backendServices/agentspace-ineg-bes |
prefixMatch | /<name of Agentspace app#1> | /drive-app |
pathRedirect | /<Caminho do URL do Agentspace do app nº 1> | /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd |
hostRedirect | vertexaisearch.cloud.google.com | vertexaisearch.cloud.google.com |
prefixMatch | /<nome do app do Agentspace nº 2> | /sharepoint-app |
pathRedirect | /<caminho do URL do Agentspace do app nº 2> | //signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6 |
hostRedirect | auth.cloud.google | vertexaisearch.cloud.google.com |
Navegue até o seguinte para acessar as regras de host e caminho:
Balanceamento de carga → agentspace-lb → Selecione "Editar"
Selecione "Regras de roteamento" → "Regras avançadas de host e caminho".
Selecione "Adicionar regra de host e caminho".
Agora você pode criar uma 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 sua configuração de ambiente e selecione "Atualizar".
defaultService: projects/<projectid>/global/backendServices/agentspace-ineg-bes
name: matcher1
routeRules:
- matchRules:
- prefixMatch: /<name of Agentspace app#1>
priority: 1
urlRedirect:
pathRedirect: /<Agentspace URL path of app#1>
hostRedirect: vertexaisearch.cloud.google.com
redirectResponseCode: FOUND
- matchRules:
- prefixMatch: /<name of Agentspace app#2>
priority: 2
urlRedirect:
pathRedirect: /<Agentspace URL path of app#2>
hostRedirect: auth.cloud.google
redirectResponseCode: FOUND
Exemplo de captura de tela:
11. 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.Confira alguns exemplos abaixo:
Aplicativo do Agentspace: drive-app
Caminho: agentspace.34.54.158.206.nip.io/drive-app
Aplicativo do Agentspace: sharepoint-app
Caminho: agentspace.34.54.158.206.nip.io/sharepoint-app
12. Limpar
Exclua as credenciais do OAuth fazendo o seguinte:
Acesse APIs e serviços → Credenciais.
Em "IDs do cliente 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
13. Parabéns
Parabéns! Você configurou e validou a conectividade com um Agentspace usando um domínio personalizado com um balanceador de carga de aplicativo externo e gerenciamento avançado de tráfego.
Você criou a infraestrutura do balanceador de carga, aprendeu a criar um NEG da Internet, o Cloud DNS e o gerenciamento avançado de tráfego que permitiu o redirecionamento de host e caminho, possibilitando a conectividade com o Agentspace usando um domínio personalizado.
O Cosmopup acha que os codelabs são incríveis!
