1. Introducción
En este documento, se proporciona una arquitectura de referencia para configurar un dominio personalizado y acceder a AgentSpace con WIF. En lugar de la URL administrada por Google que se asigna durante la creación de la app de Agentspace, los usuarios pueden utilizar un dominio personalizado. En este codelab, se demuestra el acceso a las aplicaciones de calendario y Drive de Agentspace con el dominio nip.io. nip.io es un servicio gratuito de código abierto que proporciona DNS comodín para cualquier dirección IP. Básicamente, te permite crear un nombre de host que se resuelve en una dirección IP específica sin necesidad de configurar tu propio servidor DNS ni modificar tu archivo /etc/hosts.
Se recomienda usar tu propio dominio, pero, para fines de demostración, se usa nip.io en el instructivo.
En la situación de implementación que se muestra a continuación (figura 1), AgentSpace publicó un almacén de datos que contiene una aplicación de calendario a la que se accede a través de una URL pública administrada por Google.
Figura 1
El crecimiento continuo del almacén de datos y las aplicaciones posteriores generan una mayor administración de las URLs públicas administradas por Google, como se muestra en la siguiente situación de implementación (Figura 2), lo que genera una asignación 1:1 de las aplicaciones y las URLs de Agentspace.
Figura 2:
Un dominio personalizado permite asignar varias aplicaciones de AgentSpace a un solo dominio del cliente especificado por el usuario. Esta función permite asociar una ruta de URL específica con cada aplicación de Agentspace, lo que ofrece mayor flexibilidad, como se muestra en la siguiente situación de implementación (figura 3). Por ejemplo, un espacio de agentes de dominio administrado por el cliente agentspace.cosmopup.com se segmenta en reglas de ruta, cada una asignada a una aplicación de Agentspace específica. Algunos ejemplos son los siguientes:
- agentspace.cosmopup.com/drive-app que se asigna a la aplicación Agentspace para Drive de Workspace
- agentspace.cosmopup.com/sharepoint-app que se asigna a la aplicación de Agentspace para SharePoint
Las reglas de host y de ruta de acceso del balanceador de cargas de aplicaciones externo,configuradas a través del MAPA DE URL, controlan la lógica que asigna el dominio personalizado a la URL administrada por Google. Realiza la siguiente función con el espacio de agentes de ejemplo agentspace.cosmopup.com/drive-app
- El balanceador de cargas recibe la ruta de host del dominio personalizado agentspace.cosmopup.com/drive-app
- El mapa de URL está configurado para la coincidencia avanzada de reglas de host y ruta de acceso
- El host agentspace.cosmopup.com es apto para la redirección y la coincidencia de rutas de acceso
- El espacio de agentes de la ruta de host del dominio personalizado agentspace.cosmopup.com/drive-app está sujeto a UrlRedirect
- pathRedirect es la ruta de Agentspace: /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
- hostRedirect es el host de Agentspace: vertexaisearch.cloud.google.com
- El espacio de agentes de la ruta de host del dominio personalizado agentspace.cosmopup.com/sharepoint-app está sujeto a UrlRedirect
- pathRedirect es la ruta de 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 es el host de Agentspace: auth.cloud.google
- La operación de redireccionamiento se realiza antes del enrutamiento al servicio de backend
Figura 3
Qué aprenderás
- Crea un balanceador de cargas de aplicaciones externo global
- Crea un enrutamiento para redireccionar un dominio personalizado a una aplicación de Agentspace
- Cómo integrar nip.io y Cloud DNS para crear un dominio personalizado
- Cómo validar el acceso a un dominio personalizado de Agentspace
Requisitos
- Proyecto de Google Cloud con permisos de propietario
- URLs de aplicaciones de Agentspace existentes
- Dominio personalizado del propietario (opcional)
- Certificados autofirmados o administrados por Google
2. Qué compilarás
Establecerás un balanceador de cargas de aplicaciones externo global con capacidades avanzadas de administración del tráfico para habilitar la coincidencia de rutas de dominio personalizado para las aplicaciones de Agentspace con redireccionamiento de host y ruta. Una vez que se implemente, realizarás las siguientes acciones para validar el acceso a la aplicación de Agentspace:
- Para acceder a tu aplicación de Agentspace, abre un navegador web y navega a tu dominio personalizado y a la ruta especificada.
3. Requisitos de red
A continuación, se desglosan los requisitos de red:
Componentes | Descripción |
VPC (agentspace-vpc) | VPC en modo personalizado |
NEG de Internet | Es un recurso que se usa para definir un backend externo para el balanceador de cargas configurado como un FQDN que denota el FQDN administrado por Google de Agentspace (vertexaisearch.cloud.google.com). El FQDN de Internet realiza una búsqueda de DNS dentro de la VPC para la resolución. |
Servicio de backend | Un servicio de backend actúa como puente entre tu balanceador de cargas y tus recursos de backend. En el instructivo, el servicio de backend está asociado con el NEG de Internet. |
Certificados | Para configurar certificados para un balanceador de cargas de aplicaciones en Google Cloud, usarás el servicio Administrador de certificados y certificados SSL administrados por Google o autoadministrados. |
Cloud DNS | La zona pública de Cloud DNS se usa para resolver la IP externa del balanceador de cargas de aplicaciones externo en nip.io (agentspace.externalip.nip.io). Como alternativa, usa tu dominio personalizado y el registro A que consta de la dirección IP del balanceador de cargas. |
4. Topología del codelab
5. Configuración y requisitos
Configuración del entorno de autoaprendizaje
- Accede a Google Cloud Console y crea un proyecto nuevo o reutiliza uno existente. Si aún no tienes una cuenta de Gmail o de Google Workspace, debes crear una.
- El Nombre del proyecto es el nombre visible de los participantes de este proyecto. Es una cadena de caracteres que no se utiliza en las APIs de Google. Puedes actualizarla cuando quieras.
- El ID del proyecto es único en todos los proyectos de Google Cloud y es inmutable (no se puede cambiar después de configurarlo). La consola de Cloud genera automáticamente una cadena única. Por lo general, no importa cuál sea. En la mayoría de los codelabs, deberás hacer referencia al ID de tu proyecto (suele identificarse como
PROJECT_ID). Si no te gusta el ID que se generó, podrías generar otro aleatorio. También puedes probar uno propio y ver si está disponible. No se puede cambiar después de este paso y se usa el mismo durante todo el proyecto. - Recuerda que hay un tercer valor, un número de proyecto, que usan algunas APIs. Obtén más información sobre estos tres valores en la documentación.
- A continuación, deberás habilitar la facturación en la consola de Cloud para usar las APIs o los recursos de Cloud. Ejecutar este codelab no costará mucho, tal vez nada. Para cerrar recursos y evitar que se generen cobros más allá de este instructivo, puedes borrar los recursos que creaste o borrar el proyecto. Los usuarios nuevos de Google Cloud son aptos para participar en el programa Prueba gratuita de $300.
Inicia Cloud Shell
Si bien Google Cloud y Spanner se pueden operar de manera remota desde tu laptop, en este codelab usarás Google Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube.
En Google Cloud Console, haz clic en el ícono de Cloud Shell en la barra de herramientas en la parte superior derecha:
El aprovisionamiento y la conexión al entorno deberían tomar solo unos minutos. Cuando termine el proceso, debería ver algo como lo siguiente:
Esta máquina virtual está cargada con todas las herramientas de desarrollo que necesitarás. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud, lo que permite mejorar considerablemente el rendimiento de la red y la autenticación. Todo tu trabajo en este codelab se puede hacer en un navegador. No es necesario que instales nada.
6. Antes de comenzar
Habilita las APIs
En Cloud Shell, asegúrate de que tu ID del proyecto esté configurado:
gcloud config list project
gcloud config set project [YOUR-PROJECT-ID]
project=[YOUR-PROJECT-ID]
region=[YOUR-REGION]
echo $project
echo $region
Habilita todos los servicios necesarios con el siguiente comando:
gcloud services enable compute.googleapis.com
gcloud services enable dns.googleapis.com
7. Configura los componentes del balanceador de cargas
Reserva la dirección IP externa del balanceador de cargas
En Cloud Shell, reserva una dirección IP externa para el balanceador de cargas:
gcloud compute addresses create external-ip \
--network-tier=PREMIUM \
--ip-version=IPV4 \
--global
Dentro de Cloud Shell, consulta la dirección IP reservada:
gcloud compute addresses describe external-ip \
--global | grep -i address:
Resultado de ejemplo:
user@cloudshell$ gcloud compute addresses describe external-ip \
--global | grep -i address:
address: 34.54.158.206
Configura el NEG de Internet
Crea un NEG de Internet y establece –network-endpoint-type en internet-fqdn-port (el nombre de host y el puerto en el que se encuentra el backend externo). Para resolver Agentspace, se usan el FQDN vertexaisearch.cloud.google.com y el puerto 443.
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
Crea el balanceador de cargas
En Cloud Shell, haz lo siguiente:
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
Crea el certificado
En este punto, creaste el NEG de Internet y el servicio de backend. En la siguiente sección, deberás crear un recurso de certificado para usar en el proxy de destino HTTPS. Puedes crear un recurso de certificado SSL mediante un certificado SSL administrado por Google o un certificado SSL autoadministrado. Te recomendamos que uses certificados administrados por Google, ya que Google Cloud obtiene, administra y renueva estos certificados de manera automática.
Para obtener más información sobre los certificados admitidos para el balanceador de cargas de aplicaciones externo global que se usa en este instructivo, consulta lo siguiente:
Descripción general de los certificados SSL | Balanceo de cargas | Google Cloud
En la siguiente sección, crearás un certificado autofirmado (aunque también se puede usar un certificado administrado por Google) que requiere que la asignación del nombre común al nombre de dominio completamente calificado (agentspace.YOUR-EXTERNAL-IP.nip.io) corresponda a la dirección IP externa del balanceador de cargas que se generó anteriormente, como se muestra en el siguiente ejemplo:
Nombre común: agentspace.34.54.158.206.nip.io
Dentro de Cloud Shell, crea la clave privada.
openssl genrsa -out private-key-file.pem 2048
Dentro de Cloud Shell, crea un archivo config.txt que se usa para generar el archivo pem. Especifica el nombre de dominio completamente calificado en la entrada DNS 1 agentspace.TU-IP-EXTERNA.nip.io, p.ej., agentspace.34.54.158.206.nip.io en la siguiente configuración.
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
Dentro de Cloud Shell, valida que se hayan generado los archivos config.txt y private-key-file.pem.
user@cloudshell:$ ls
config.txt private-key-file.pem
En Cloud Shell, haz lo siguiente.
sudo openssl req -new -key private-key-file.pem \
-out csr.pem \
-config config.txt
Ejemplo:
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 []:
Dentro de Cloud Shell, valida la creación del archivo .pem requerido para la firma del certificado.
user@cloudshell:$ ls
config.txt csr.pem private-key-file.pem
Dentro de Cloud Shell, genera el certificado.
sudo openssl x509 -req \
-signkey private-key-file.pem \
-in csr.pem \
-out cert.cert \
-extfile config.txt \
-extensions extension_requirements \
-days 365
Resultado de ejemplo:
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
En Cloud Shell, valida la creación del archivo cert.cert.
user@cloudshell:$ ls
cert.cert config.txt csr.pem private-key-file.pem
Crea un recurso de certificado para asociarlo con tu balanceador de cargas externo. Reemplaza los parámetros de certificado y clave privada por los nombres de tus archivos específicos.
En Cloud Shell, haz lo siguiente:
gcloud compute ssl-certificates create agentspace-self-signed-cert \
--certificate=cert.cert \
--private-key=private-key-file.pem \
--global
En Cloud Shell, haz lo siguiente:
gcloud compute url-maps create agentspace-lb \
--default-service=agentspace-ineg-bes \
--global
En Cloud Shell, haz lo siguiente:
gcloud compute target-https-proxies create https-proxy \
--ssl-certificates=agentspace-self-signed-cert \
--url-map=agentspace-lb \
--global
En Cloud Shell, haz lo siguiente:
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. Crea una zona de DNS pública
En la siguiente sección, crearás una zona de DNS pública que usa nip.io para resolver la dirección IP del balanceador de cargas externo.
En Cloud Shell, realiza los siguientes pasos para crear una variable para la dirección IP de tu balanceador de cargas externo:
externalip=<YOUR-EXTERNAL-IP>
echo $externalip
En Cloud Shell, haz lo siguiente:
gcloud dns --project=$project managed-zones create agentspace-dns --description="Agentspace public dns" --dns-name="$externalip.nip.io." --visibility="public"
En Cloud Shell, haz lo siguiente:
gcloud dns --project=$project record-sets create agentspace.$externalip.nip.io. --zone="agentspace-dns" --type="A" --ttl="300" --rrdatas="$externalip"
9. Identifica URLs de aplicaciones de Agentspace
En el siguiente procedimiento, se identifican las URLs públicas de Agentspace administradas por Google y generadas por Google que se asignan a Agentspace para cada aplicación. Las URLs de salida son ejemplos basados en la arquitectura de referencia, por lo que debes asegurarte de que tus URLs sean precisas.
Asegúrate de almacenar el vínculo a tu app web por aplicación.
Aplicación de Drive
URL web de Agentspace:
https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
Aplicación de SharePoint
URL web de 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. Crea una regla avanzada de host y ruta de acceso
En la siguiente sección, actualizarás las reglas de enrutamiento de los balanceadores de cargas para habilitar la opción de definir reglas de host y ruta de acceso con la consola de Cloud. En la siguiente tabla, se describen los valores personalizados (en orden descendente) que debes actualizar según tu entorno:
Valor personalizado | Ejemplo basado en el instructivo | |
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 | /<nombre de la app de Agentspace#1> | /drive-app |
pathRedirect | /<ruta de URL de Agentspace de la app núm. 1> | /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd |
hostRedirect | vertexaisearch.cloud.google.com | vertexaisearch.cloud.google.com |
prefixMatch | /<nombre de la app de Agentspace núm. 2> | /sharepoint-app |
pathRedirect | /<ruta de URL de Agentspace de la app núm. 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 |
Navega a la siguiente ubicación para acceder a las reglas de host y ruta de acceso
Balanceo de cargas → agentspace-lb → Selecciona Editar
Selecciona Reglas de enrutamiento → Reglas avanzadas de host y ruta de acceso.
Selecciona Agregar regla de host y ruta de acceso.
Ahora se te presentará la opción para crear una nueva regla de host y ruta de acceso. En la sección de hosts, inserta agentspace.TU-IP-EXTERNA.nip.io o el dominio personalizado.
En el campo Comparador de rutas de acceso (coincidencias, acciones y servicios), actualiza el contenido que se muestra a continuación con la configuración de tu entorno y, luego, selecciona Actualizar.
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
Captura de pantalla de ejemplo:
11. Validación
Se completó la implementación. Puedes acceder a la aplicación de Agentspace con el dominio personalizado a través de un navegador web o una terminal especificando agentspace.TU-IP-EXTERNA.nip.io/ruta, p. ej., agentspace.34.54.158.206.nip.io. A continuación, se incluyen algunos ejemplos:
Aplicación de Agentspace: drive-app
Ruta de acceso: agentspace.34.54.158.206.nip.io/drive-app
Aplicación de Agentspace: sharepoint-app
Ruta de acceso: agentspace.34.54.158.206.nip.io/sharepoint-app
12. Limpia
Para borrar las credenciales de OAuth, haz lo siguiente:
Navega a APIs y servicios → Credenciales.
En ID de clientes OAuth 2.0, selecciona tus credenciales y, luego, bórralas.
Desde una sola terminal de Cloud Shell, borra los componentes del lab:
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. Felicitaciones
Felicitaciones. Configuraste y validaste correctamente la conectividad a un Agentspace con un dominio personalizado a través de un balanceador de cargas de aplicaciones externo con administración avanzada del tráfico.
Creaste la infraestructura del balanceador de cargas, aprendiste a crear un NEG de Internet, Cloud DNS y una administración avanzada del tráfico que habilitó el redireccionamiento de host y ruta que permitió la conectividad a Agentspace con un dominio personalizado.
Cosmopup cree que los codelabs son increíbles.
