1. Введение
В этом документе представлена эталонная архитектура для настройки пользовательского домена для доступа к AgentSpace. Вместо URL-адреса, управляемого Google, назначенного во время создания приложения Agentspace, пользователи могут использовать пользовательский домен. Эта кодовая лабораторная работа демонстрирует доступ к календарю и приложениям Drive от Agentspace с использованием домена nip.io. nip.io — это бесплатная служба с открытым исходным кодом, которая предоставляет подстановочный DNS для любого IP-адреса. По сути, она позволяет вам создать имя хоста, которое разрешается в определенный IP-адрес без необходимости настраивать собственный DNS-сервер или изменять файл /etc/hosts.
Рекомендуется использовать собственный домен, однако в демонстрационных целях в руководстве используется nip.io.
В представленном ниже сценарии развертывания (рисунок 1) AgentSpace опубликовал хранилище данных, содержащее приложение «Календарь», доступ к которому осуществляется через общедоступный URL-адрес, управляемый Google.
Рисунок 1

Продолжающийся рост хранилища данных и последующих приложений приводит к дальнейшему управлению общедоступными URL-адресами, управляемыми Google, как показано в сценарии развертывания ниже (рисунок 2), что приводит к сопоставлению приложений Agentspace и URL-адресов 1:1.
Рисунок 2.

Пользовательский домен позволяет сопоставлять различные приложения AgentSpace с одним, указанным пользователем доменом клиента. Эта функция позволяет связать определенный путь URL с каждым приложением Agentspace, предлагая большую гибкость, как показано в сценарии развертывания ниже (рисунок 3). В качестве примера, управляемый клиентом домен agentspace.cosmopup.com сегментирован на правила пути, каждое из которых сопоставляется с определенным приложением Agentspace, например:
- agentspace.cosmopup.com/drive-app, который сопоставляется с приложением Agentspace для Workspace Drive
 - agentspace.cosmopup.com/calendar-app, который сопоставляется с приложением Agentspace для Workspace Calendar
 
Правила хоста и пути внешнего балансировщика нагрузки приложений, настроенные через URL MAP, управляют логикой, которая сопоставляет пользовательский домен с управляемым Google URL. Он выполняет следующую функцию, используя пример agentspace.cosmopup.com/drive-app
- Балансировщик нагрузки получает путь к хосту пользовательского домена agentspace.cosmopup.com/drive-app
 - Карта URL настроена для расширенного сопоставления правил хоста и пути
 - Хосты agentspace.cosmopup.com имеют право на сопоставление и перезапись путей
 - Пользовательский путь к хосту домена agentspace.cosmopup.com/drive-app подлежит UrlRewrite
 - PathPrefixRewrite — это путь к Agentspace: /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
 - hostRewrite — это хост Agentspace: vertexaisearch.cloud.google.com
 - Операция перезаписи выполняется перед маршрутизацией на внутреннюю службу.
 - Внутренний сервис направляет трафик в приложение Drive-App на основе URL-адреса Agentspace.
 
Рисунок 3

Чему вы научитесь
- Создать глобальный внешний балансировщик нагрузки приложений
 - Создайте переписанную внутреннюю службу с использованием пользовательского домена и перепишите операцию в приложение Agentspace
 - Как интегрировать nip.io и Cloud DNS для создания собственного домена
 - Как проверить доступ к пользовательскому домену Agentspace
 
Что вам понадобится
- Проект Google Cloud с разрешениями владельца
 - Существующие URL-адреса приложений Agentspace
 - Собственный пользовательский домен (необязательно)
 - Сертификаты — самоподписанные или управляемые Google
 
2. Что вы будете строить
Вы создадите Global External Application Load Balancer с расширенными возможностями управления трафиком, чтобы включить сопоставление пути пользовательского домена для приложений Agentspace с использованием перезаписи хоста и пути. После развертывания вы выполните следующие действия для проверки доступа к приложению Agentspace:
- Чтобы получить доступ к приложению Agentspace, откройте веб-браузер и перейдите в свой пользовательский домен по указанному пути.
 

3. Требования к сети
Ниже приведена разбивка сетевых требований:
Компоненты  | Описание  | 
VPC (агентское пространство-vpc)  | Пользовательский режим VPC  | 
Интернет НЕГ  | Ресурс, используемый для определения внешнего бэкэнда для балансировщика нагрузки , настроенного как FQDN, обозначающий Agentspace Google-Manged FQDN (vertexaisearch.cloud.google.com). Internet FQDN выполняет поиск DNS в VPC для разрешения.  | 
Бэкэнд-сервис  | Служба бэкенда действует как мост между вашим балансировщиком нагрузки и ресурсами бэкенда. В руководстве служба бэкенда связана с Интернет-NEG.  | 
Сертификаты  | Чтобы настроить сертификаты для Application Load Balancer в Google Cloud, вам понадобится служба Certificate Manager и SSL-сертификаты , управляемые Google или самостоятельно управляемые.  | 
Облачный DNS  | Зона публичной части Cloud DNS используется для разрешения внешнего IP-адреса балансировщика нагрузки внешнего приложения в nip.io (agentspace.externalip.nip.io). В качестве альтернативы используйте свой пользовательский домен и запись A, состоящую из IP-адреса балансировщика нагрузки.  | 
4. Топология кодовой лаборатории


5. Настройка и требования
Самостоятельная настройка среды
- Войдите в Google Cloud Console и создайте новый проект или повторно используйте существующий. Если у вас еще нет учетной записи Gmail или Google Workspace, вам необходимо ее создать .
 



- Имя проекта — это отображаемое имя для участников этого проекта. Это строка символов, не используемая API Google. Вы всегда можете ее обновить.
 -  Идентификатор проекта уникален для всех проектов Google Cloud и неизменяем (его нельзя изменить после установки). Cloud Console автоматически генерирует уникальную строку; обычно вам все равно, что это такое. В большинстве кодовых лабораторий вам нужно будет ссылаться на свой идентификатор проекта (обычно идентифицируемый как 
PROJECT_ID). Если вам не нравится сгенерированный идентификатор, вы можете сгенерировать другой случайный идентификатор. В качестве альтернативы вы можете попробовать свой собственный и посмотреть, доступен ли он. Его нельзя изменить после этого шага, и он остается на протяжении всего проекта. - Для вашего сведения, есть третье значение, Project Number , которое используют некоторые API. Узнайте больше обо всех трех этих значениях в документации .
 
- Далее вам нужно будет включить биллинг в Cloud Console для использования ресурсов/API Cloud. Прохождение этой кодовой лаборатории не будет стоить много, если вообще будет стоить. Чтобы отключить ресурсы и избежать выставления счетов за пределами этого руководства, вы можете удалить созданные вами ресурсы или удалить проект. Новые пользователи Google Cloud имеют право на бесплатную пробную программу стоимостью 300 долларов США .
 
Запустить Cloud Shell
Хотя Google Cloud можно управлять удаленно с вашего ноутбука, в этой лабораторной работе вы будете использовать Google Cloud Shell — среду командной строки, работающую в облаке.
В Google Cloud Console щелкните значок Cloud Shell на верхней правой панели инструментов:

Подготовка и подключение к среде займет всего несколько минут. Когда все будет готово, вы увидите что-то вроде этого:

Эта виртуальная машина загружена всеми необходимыми вам инструментами разработки. Она предлагает постоянный домашний каталог на 5 ГБ и работает на Google Cloud, что значительно повышает производительность сети и аутентификацию. Вся ваша работа в этой кодовой лаборатории может быть выполнена в браузере. Вам не нужно ничего устанавливать.
6. Прежде чем начать
Включить API
Внутри Cloud Shell убедитесь, что настроен идентификатор вашего проекта:
gcloud config list project
gcloud config set project [YOUR-PROJECT-ID]
project=[YOUR-PROJECT-ID]
region=[YOUR-REGION]
echo $project
echo $region
Включите все необходимые службы:
gcloud services enable compute.googleapis.com
gcloud services enable dns.googleapis.com
7. Создание сети VPC
Сеть VPC
Внутри Cloud Shell выполните следующие действия:
gcloud compute networks create agentspace-vpc --subnet-mode custom
8. Настройте компоненты балансировщика нагрузки
Зарезервируйте внешний IP-адрес балансировщика нагрузки
Внутри Cloud Shell зарезервируйте внешний IP-адрес для балансировщика нагрузки:
gcloud compute addresses create external-ip \
    --network-tier=PREMIUM \
    --ip-version=IPV4 \
    --global
Внутри Cloud Shell просмотрите зарезервированный IP-адрес:
gcloud compute addresses describe external-ip \
  --global | grep -i address:
Пример вывода:
user@cloudshell$ gcloud compute addresses describe external-ip \
  --global | grep -i address:
address: 34.54.158.206
Настройте Интернет NEG
Создайте Internet NEG и установите –network-endpoint-type на internet-fqdn-port (имя хоста и порт, по которому может быть достигнут ваш внешний бэкэнд). Для разрешения Agentspace используется FQDN vertexaisearch.cloud.google.com и PORT 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
Создать балансировщик нагрузки
Внутри Cloud Shell выполните следующие действия:
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  
Создать сертификат
На этом этапе вы создали интернет-neg и бэкэнд-сервис, в следующем разделе вам нужно будет создать ресурс сертификата для использования в целевом прокси-сервере HTTPs. Вы можете создать ресурс сертификата SSL, используя либо управляемый Google SSL-сертификат, либо самоуправляемый SSL-сертификат. Мы рекомендуем использовать управляемые Google сертификаты, поскольку Google Cloud получает, управляет и обновляет эти сертификаты автоматически.
Дополнительную информацию о поддерживаемых сертификатах для глобального внешнего балансировщика нагрузки приложений, используемого в этом руководстве, см. по следующим ссылкам:
Обзор SSL-сертификатов | Балансировка нагрузки | Google Cloud
В следующем разделе вы создадите самоподписанный сертификат (хотя вместо него можно использовать управляемый сертификат Google), который требует сопоставления общего имени с полным доменным именем ( agentspace.YOUR-EXTERNAL-IP.nip.io) , соответствующим внешнему IP-адресу балансировщика нагрузки, сгенерированному ранее, пример ниже:
Общее имя: agentspace.34.54.158.206.nip.io
Внутри Cloud Shell создайте закрытый ключ
openssl genrsa -out private-key-file.pem 2048
Внутри Cloud Shell создайте файл config.txt, который будет использоваться для генерации файла pem. Укажите полное доменное имя в записи DNS 1 agentspace.YOUR-EXTERNAL-IP.nip.io , например, agentspace.34.54.158.206.nip.io в конфигурации ниже.
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
Внутри Cloud Shell проверьте, созданы ли файлы config.txt и private-key-file.pem.
user@cloudshell:$ ls
config.txt  private-key-file.pem
Внутри Cloud Shell выполните следующие действия.
sudo openssl req -new -key private-key-file.pem \
    -out csr.pem \
    -config config.txt
Пример:
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 []:
Внутри Cloud Shell проверьте создание необходимого pem-файла подписи сертификата.
user@cloudshell:$ ls
config.txt  csr.pem  private-key-file.pem
Внутри Cloud Shell сгенерируйте сертификат.
sudo openssl x509 -req \
    -signkey private-key-file.pem \
    -in csr.pem \
    -out cert.cert \
    -extfile config.txt \
    -extensions extension_requirements \
    -days 365
Пример вывода:
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
Внутри Cloud Shell проверьте создание файла cert.cert
user@cloudshell:$ ls
cert.cert  config.txt  csr.pem  private-key-file.pem
Создайте ресурс сертификата для связи с вашим внешним балансировщиком нагрузки. Замените параметры сертификата и закрытого ключа на ваши конкретные имена файлов.
В Cloud Shell выполните следующие действия:
gcloud compute ssl-certificates create agentspace-self-signed-cert \
    --certificate=cert.cert \
    --private-key=private-key-file.pem \
    --global
В Cloud Shell выполните следующие действия:
gcloud compute url-maps create agentspace-lb \
      --default-service=agentspace-ineg-bes \
      --global  
В Cloud Shell выполните следующие действия:
gcloud compute target-https-proxies create https-proxy \
      --ssl-certificates=agentspace-self-signed-cert \
      --url-map=agentspace-lb \
      --global 
В Cloud Shell выполните следующие действия:
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. Создать публичную DNS-зону
В следующем разделе вы создадите публичную DNS-зону, используемую nip.io для разрешения IP-адреса внешнего балансировщика нагрузки.
В Cloud Shell выполните следующие действия, чтобы создать переменную для IP-адреса внешнего балансировщика нагрузки:
externalip=<YOUR-EXTERNAL-IP>
echo $externalip
В Cloud Shell выполните следующие действия:
gcloud dns --project=$project managed-zones create agentspace-dns --description="Agentspace public dns" --dns-name="$externalip.nip.io." --visibility="public"
В Cloud Shell выполните следующие действия:
gcloud dns --project=$project record-sets create agentspace.$externalip.nip.io. --zone="agentspace-dns" --type="A" --ttl="300" --rrdatas="$externalip"
10. Учетные данные OAuth
В следующем разделе вы создадите учетные данные Oauth для веб-приложений, которые перенаправляют управляемый Google URL на oauth-redirect для аутентификации. Сгенерированные учетные данные не требуются для руководства.
Чтобы узнать больше об OAuth, ознакомьтесь со следующими источниками:
Добавьте действия Google Calendar и Gmail | Google Agentspace
Создайте приложение OAuth и добавьте области действия
- Перейдите в раздел API и службы > Экран согласия OAuth: Перейдите на экран согласия OAuth
 - Выберите Внутренний и нажмите Создать.
 - Введите имя для вашего приложения OAuth.
 - Введите адрес электронной почты службы поддержки пользователей.
 - Введите контактную информацию разработчика.
 - Нажмите «Сохранить» и продолжите.
 
Создайте идентификатор клиента OAuth
Эта процедура описывает, как создать новый идентификатор клиента OAuth для действий Google Cloud. Этот идентификатор клиента OAuth и секрет также можно использовать для других действий Google Cloud. Если у вас есть существующий идентификатор клиента Google Cloud OAuth для действий Google Cloud, вы можете использовать этот идентификатор клиента и секрет для действий Google Calendar вместо создания нового идентификатора клиента.
- Перейдите на страницу «Учетные данные» и нажмите «Создать учетные данные» > «Идентификатор клиента OAuth».
 - Выберите Веб-приложение.
 - Введите имя для вашего идентификатора клиента.
 - Нажмите «Добавить URI» и введите следующий URI: https://vertexaisearch.cloud.google.com/oauth-redirect
 - Нажмите «Создать» и скопируйте следующую информацию:
 
- Идентификатор клиента
 - Секрет клиента
 
11. Определите URL-адреса приложений Agentspace
Следующая процедура определяет общедоступные URL-адреса Agentspace, управляемые Google и сгенерированные Google, которые сопоставляются с Agentspace для каждого приложения. Вывод URL-адресов является примерами, основанными на эталонной архитектуре, поэтому вы должны убедиться, что ваши URL-адреса точны.
Обязательно сохраните ссылку на ваше веб-приложение для каждого приложения.
Календарь приложений
URL-адрес Agentspace Web: https://vertexaisearch.cloud.google.com/us/home/cid/bb6b8b27-939b-494d-9227-45903bb8afcf

Приложение Drive
URL-адрес веб-сайта Agentspace:
https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd

12. Создайте расширенное правило хоста и пути
В следующем разделе вы обновите правила маршрутизации балансировщиков нагрузки, чтобы включить возможность определения правил хоста и пути с помощью облачной консоли. В таблице ниже приведены пользовательские значения (в порядке сверху вниз), обновление на основе вашей среды:
Пользовательское значение  | Пример на основе учебника  | |
Хозяева  | agentspace.ВАШ-ВНЕШНИЙ-IP.nip.io  | agentspace.34.54.158.206.nip.io  | 
defaultService  | проекты/<projectid>/global/backendServices/agentspace-ineg-bes  | Смотреть скриншот  | 
префиксСовпадение  | /<имя приложения Agentspace#1>  | /drive-приложение  | 
бэкэндСервис  | проекты/<projectid>/global/backendServices/agentspace-ineg-bes  | Смотреть скриншот  | 
pathPrefixRewrite  | /<URL-путь Agentspace приложения №1>  | /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd  | 
hostRewrite  | vertexaisearch.cloud.google.com  | vertexaisearch.cloud.google.com  | 
префиксСовпадение  | /<имя приложения Agentspace#2>  | /календарь-приложение  | 
бэкэндСервис  | проекты/<projectid>/global/backendServices/agentspace-ineg-bes  | Смотреть скриншот  | 
pathPrefixRewrite  | /<URL-путь Agentspace приложения №2>  | /нас/home/cid/bb6b8b27-939b-494d-9227-45903bb8afcf  | 
hostRewrite  | vertexaisearch.cloud.google.com  | vertexaisearch.cloud.google.com  | 
Перейдите по ссылке ниже, чтобы получить доступ к правилам хоста и пути.
Балансировка нагрузки → agentspace-lb → Выбрать редактирование
Выберите Правила маршрутизации → Расширенные правила хоста и пути.
Выберите Добавить правило хоста и пути.

Теперь вам предлагается создать новое правило хоста и пути. В разделе хостов введите agentspace.YOUR-EXTERNAL-IP.nip.io или пользовательский домен.

В поле «Сопоставление путей» (совпадения, действия и службы) обновите содержимое ниже, указав конфигурацию вашей среды, затем выберите «Обновить».
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
Пример скриншота:


13. Проверка
Развертывание завершено! Вы можете получить доступ к приложению Agentspace, используя пользовательский домен через веб-браузер или терминал, указав agentspace.YOUR-EXTERNAL-IP.nip.io/path, например, agentspace.34.54.158.206.nip.io, примеры ниже:
Приложение Agentspace: drive-app
Путь: agentspace.34.54.158.206.nip.io/drive-app
Приложение Agentspace: drive-app
Путь: agentspace.34.54.158.206.nip.io/calendar-app
14. Уборка
Удалите учетные данные OAuth, выполните следующие действия:
Перейдите в раздел APIS и службы → Учетные данные.
В разделе «Идентификаторы клиентов OAuth 2.0» выберите свои учетные данные, а затем удалите их.
Из одного терминала Cloud Shell удалите компоненты лаборатории:
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. Поздравления
Поздравляем, вы успешно настроили и проверили подключение к Agentspace с использованием пользовательского домена с использованием внешнего балансировщика нагрузки приложений с расширенным управлением трафиком.
Вы создали инфраструктуру балансировщика нагрузки, узнали, как создать Интернет-NEG, облачный DNS и расширенное управление трафиком, которое позволило перезаписать хост и путь, что позволило подключиться к Agentspace с использованием настраиваемого домена.
Cosmopup считает, что лабораторные работы — это здорово!!
