1. Introducción
En este documento, se proporciona una arquitectura de referencia para configurar un dominio personalizado para acceder a AgentSpace. En lugar de la URL administrada por Google que se asigna durante la creación de la app de Agentspace, los usuarios pueden usar un dominio personalizado. En este codelab, se muestra el acceso al calendario de Agentspace y la conducción de aplicaciones con el dominio nip.io. nip.io es un servicio de código abierto y gratuito que proporciona DNS comodín para cualquier dirección IP. En esencia, 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 el archivo /etc/hosts.
Se recomienda usar tu propio dominio. Sin embargo, para fines de demostración, se usa nip.io en el instructivo.
En la siguiente situación de implementació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 genera 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 la URL de Agentspace.
Figura 2:
Un dominio personalizado permite asignar varias aplicaciones de AgentSpace a un solo dominio de cliente especificado por el usuario. Esta función permite que se asocie una ruta de URL específica con cada aplicación de Agentspace, lo que ofrece una mayor flexibilidad, como se muestra en la siguiente situación de implementación (Figura 3). A modo de ejemplo, un 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. Por ejemplo:
- agentspace.cosmopup.com/drive-app que se asigna a la aplicación Agentspace para Drive de Workspace
- agentspace.cosmopup.com/calendar-app que se asigna a la aplicación Agentspace para el Calendario de Workspace
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 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 de ruta
- El host agentspace.cosmopup.com es apto para la coincidencia de rutas de acceso y la reescritura
- La ruta de acceso del host del dominio personalizado agentspace.cosmopup.com/drive-app está sujeta a UrlRewrite.
- PathPrefixRewrite es la ruta de Agentspace: /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
- hostRewrite es el host de Agentspace: vertexaisearch.cloud.google.com
- La operación de reescritura se realiza antes de enrutar al servicio de backend.
- El servicio de backend enruta el tráfico a la aplicación de la app de Drive según la URL de Agentspace.
Figura 3
Qué aprenderás
- Crea un balanceador de cargas de aplicaciones externo global
- Crea una reimpresión de servicio de backend con un dominio personalizado y una operación de reimpresión en 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 propio (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 de tráfico para habilitar la coincidencia de ruta de dominio personalizado para las aplicaciones de Agentspace con la reescritura 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 la ruta especificada.
3. Requisitos de red
A continuación, se muestra un desglose de 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 FQDN que denota el FQDN administrado por Google de Agentspace (vertexaisearch.cloud.google.com). El FQDN de Internet realiza la búsqueda de DNS dentro de la VPC para la resolución. |
Servicio de backend | Un servicio de backend actúa como un puente entre el 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. Crear red de VPC
Red de VPC
En Cloud Shell, haz lo siguiente:
gcloud compute networks create agentspace-vpc --subnet-mode custom
8. 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
En 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 el tipo de extremo de red en internet-fqdn-port (el nombre de host y el puerto en el que se encuentra el backend externo). Para resolver Agentspace, se usa 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 usarlo 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 usar 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 se puede usar un certificado administrado por Google) que requiere la asignación del nombre común al nombre de dominio completo (agentspace.YOUR-EXTERNAL-IP.nip.io) que corresponde a la dirección IP externa del balanceador de cargas que se generó antes. A continuación, se muestra un 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 use 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 configuración que aparece a continuació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 generen 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 PEM de firma de certificados requerido.
user@cloudshell:$ ls
config.txt csr.pem private-key-file.pem
En 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 archivo 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
9. Crea una zona del DNS pública
En la siguiente sección, crearás una zona de DNS pública que usará nip.io para resolver la dirección IP del balanceador de cargas externo.
En Cloud Shell, sigue estos 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"
10. Credenciales de OAuth
En la siguiente sección, crearás una credencial de OAuth para aplicaciones web que redirecciona la URL administrada por Google a oauth-redirect para la autenticación. Las credenciales generadas no son necesarias para el instructivo.
Para obtener más información sobre Oauth, consulta lo siguiente:
Cómo agregar acciones de Calendario de Google y Gmail | Google Agentspace
Crea una app de OAuth y agrega permisos
- Ve a APIs y servicios > Pantalla de consentimiento de OAuth: Ve a la pantalla de consentimiento de OAuth
- Selecciona Interno y, luego, haz clic en Crear.
- Ingresa un nombre para tu app de OAuth.
- Ingresa un correo electrónico de asistencia al usuario.
- Ingresa la información de contacto del desarrollador.
- Haga clic en Guardar y continuar.
Crea un ID de cliente de OAuth
En este procedimiento, se describe cómo crear un nuevo ID de cliente de OAuth para las acciones de Google Cloud. Este ID de cliente y secreto de OAuth también se pueden usar para otras acciones de Google Cloud. Si tienes un ID de cliente de OAuth de Google Cloud existente para las acciones de Google Cloud, puedes usar ese ID de cliente y secreto para las acciones de Calendario de Google en lugar de crear un ID de cliente nuevo.
- Ve a la página Credenciales y haz clic en Crear credenciales > ID de cliente de OAuth.
- Selecciona Aplicación web.
- Ingresa un nombre para tu ID de cliente.
- Haz clic en Agregar URI y, luego, ingresa el siguiente URI: https://vertexaisearch.cloud.google.com/oauth-redirect
- Haz clic en Crear y copia la siguiente información:
- ID de cliente
- Secreto del cliente
11. Identifica las URLs de la aplicación de Agentspace
En el siguiente procedimiento, se identifican las URLs públicas de Agentspace administradas por Google que genera Google y que se asignan a Agentspace en cada aplicación. El resultado de las URLs 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 Calendario
URL web de Agentspace: https://vertexaisearch.cloud.google.com/us/home/cid/bb6b8b27-939b-494d-9227-45903bb8afcf
Aplicación de Drive
URL web de Agentspace:
https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
12. 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 de arriba abajo) que se actualizan 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 | Ver captura de pantalla |
prefixMatch | /<nombre de la app de Agentspace#1> | /drive-app |
backendService | projects/<projectid>/global/backendServices/agentspace-ineg-bes | Ver captura de pantalla |
pathPrefixRewrite | /<Ruta de URL de Agentspace de app#1> | /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd |
hostRewrite | vertexaisearch.cloud.google.com | vertexaisearch.cloud.google.com |
prefixMatch | /<nombre de la app de Agentspace#2> | /calendar-app |
backendService | projects/<projectid>/global/backendServices/agentspace-ineg-bes | Ver captura de pantalla |
pathPrefixRewrite | /<Ruta de URL de Agentspace de app#2> | /us/home/cid/bb6b8b27-939b-494d-9227-45903bb8afcf |
hostRewrite | vertexaisearch.cloud.google.com | vertexaisearch.cloud.google.com |
Navega a la siguiente ubicación para acceder a las reglas de host y de ruta:
Balanceo de cargas → agentspace-lb → Seleccionar 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 presenta la opción de 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 del comparador de rutas de acceso (coincidencias, acciones y servicios), actualiza el contenido que aparece 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
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
Captura de pantalla de ejemplo:
13. 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. Para ello, especifica agentspace.TU-IP-EXTERNA.nip.io/ruta, p. ej., agentspace.34.54.158.206.nip.io. Consulta los siguientes ejemplos:
Aplicación de Agentspace: drive-app
Ruta de acceso: agentspace.34.54.158.206.nip.io/drive-app
Aplicación de Agentspace: drive-app
Ruta: agentspace.34.54.158.206.nip.io/calendar-app
14. Limpia
Borra las credenciales de OAuth y haz lo siguiente:
Navega a APIs y servicios → Credenciales.
En IDs de cliente de 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
15. Felicitaciones
Felicitaciones, configuraste y validaste correctamente la conectividad a un espacio de agentes con un dominio personalizado mediante 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 de tráfico avanzada que habilitó la reescritura de host y ruta de acceso que permitió la conectividad a Agentspace con un dominio personalizado.
Cosmopup piensa que los codelabs son geniales.
