1. Einführung
In diesem Dokument finden Sie eine Referenzarchitektur für die Konfiguration einer benutzerdefinierten Domain für den Zugriff auf AgentSpace mit WIF. Anstelle der von Google verwalteten URL, die bei der Erstellung der Agentspace-App zugewiesen wird, können Nutzer eine benutzerdefinierte Domain verwenden. In diesem Codelab wird der Zugriff auf Kalender- und Drive-Anwendungen von Agentspace über die Domain nip.io demonstriert. nip.io ist ein kostenloser Open-Source-Dienst, der Platzhalter-DNS für jede IP-Adresse bereitstellt. Damit können Sie einen Hostnamen erstellen, der in eine bestimmte IP-Adresse aufgelöst wird, ohne dass Sie einen eigenen DNS-Server einrichten oder die Datei „/etc/hosts“ ändern müssen.
Die Verwendung einer eigenen Domain wird empfohlen. In der Anleitung wird jedoch aus Demonstrationszwecken nip.io verwendet.
Im unten dargestellten Bereitstellungsszenario (Abbildung 1) hat AgentSpace einen Datenspeicher veröffentlicht, der eine Kalenderanwendung enthält, auf die über eine öffentliche, von Google verwaltete URL zugegriffen wird.
Abbildung 1
Das stetige Wachstum von Datenspeicher und nachfolgenden Anwendungen führt zu einer weiteren Verwaltung von öffentlichen, von Google verwalteten URLs, wie im folgenden Bereitstellungsszenario (Abbildung 2) dargestellt. Dies führt zu einer 1:1-Zuordnung von Agentspace-Anwendungen und URLs.
Abbildung 2.
Mit einer benutzerdefinierten Domain können verschiedene AgentSpace-Anwendungen einer einzelnen, vom Nutzer angegebenen Kundendomain zugeordnet werden. Mit dieser Funktion kann jeder Agentspace-Anwendung ein bestimmter URL-Pfad zugewiesen werden. Das bietet mehr Flexibilität, wie im folgenden Bereitstellungsszenario (Abbildung 3) dargestellt. Ein Beispiel: Die vom Kunden verwaltete Domain agentspace.cosmopup.com ist in Pfadregeln unterteilt, die jeweils einer bestimmten Agentspace-Anwendung zugeordnet sind. Beispiele:
- agentspace.cosmopup.com/drive-app, die der Agentspace-Anwendung für Workspace Drive zugeordnet ist
- agentspace.cosmopup.com/sharepoint-app, die der Agentspace-Anwendung für SharePoint zugeordnet ist
Die Host- und Pfadregeln des externen Application Load Balancers, die über die URL-ZUORDNUNG konfiguriert werden, steuern die Logik, mit der die benutzerdefinierte Domain der von Google verwalteten URL zugeordnet wird. Sie führt die folgende Funktion mit dem Beispiel-Agentspace „agentspace.cosmopup.com/drive-app“ aus:
- Der Hostpfad der benutzerdefinierten Domain „agentspace.cosmopup.com/drive-app“ wird vom Load Balancer empfangen.
- Die URL-Zuordnung ist für den erweiterten Abgleich von Host- und Pfadregeln konfiguriert.
- Der Host agentspace.cosmopup.com kommt für den Pfadabgleich und die Weiterleitung infrage.
- Der benutzerdefinierte Domainhostpfad agentspace.cosmopup.com/drive-app unterliegt UrlRedirect
- pathRedirect ist der Agentspace-Pfad: /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
- hostRedirect ist der Agentspace-Host: vertexaisearch.cloud.google.com
- Der benutzerdefinierte Domain-Hostpfad agentspace.cosmopup.com/sharepoint-app unterliegt „UrlRedirect“.
- pathRedirect ist der Agentspace-Pfad: /signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6
- hostRedirect ist der Agentspace-Host: auth.cloud.google
- Die Weiterleitung erfolgt vor dem Routing zum Backend-Dienst.
Abbildung 3
Lerninhalte
- Globalen externen Application Load Balancer erstellen
- Routing erstellen, um eine benutzerdefinierte Domain zu einer Agentspace-Anwendung weiterzuleiten
- nip.io und Cloud DNS integrieren, um eine benutzerdefinierte Domain zu erstellen
- Zugriff auf eine benutzerdefinierte Agentspace-Domain bestätigen
Voraussetzungen
- Google Cloud-Projekt mit Inhaberberechtigungen
- Vorhandene Agentspace-Anwendungs-URLs
- Benutzerdefinierte Domain (optional)
- Zertifikate – selbstsigniert oder von Google verwaltet
2. Aufgaben
Sie richten einen globalen externen Application Load Balancer mit erweiterten Funktionen zur Traffic-Verwaltung ein, um den benutzerdefinierten Domainpfadabgleich für Agentspace-Anwendungen mithilfe von Host- und Pfadweiterleitung zu ermöglichen. Nach der Bereitstellung führen Sie die folgenden Aktionen aus, um den Zugriff auf die Agentspace-Anwendung zu validieren:
- Greifen Sie auf Ihre Agentspace-Anwendung zu, indem Sie einen Webbrowser öffnen und zu Ihrer benutzerdefinierten Domain und dem angegebenen Pfad wechseln.
3. Netzwerkanforderungen
Im Folgenden finden Sie eine Aufschlüsselung der Netzwerkanforderungen:
Komponenten | Beschreibung |
VPC (agentspace-vpc) | VPC im benutzerdefinierten Modus |
Internet-NEG | Eine Ressource, die verwendet wird, um ein externes Backend für den Load Balancer zu definieren, der als FQDN konfiguriert ist, der den von Google verwalteten FQDN für Agentspace (vertexaisearch.cloud.google.com) angibt. Für Internet-FQDN wird ein DNS-Lookup innerhalb der VPC zur Auflösung durchgeführt. |
Backend-Dienst | Ein Back-End-Dienst fungiert als Brücke zwischen Ihrem Load-Balancer und Ihren Back-End-Ressourcen. Im Tutorial ist der Back-End-Dienst mit der Internet-NEG verknüpft. |
Zertifikate | Wenn Sie Zertifikate für einen Application Load Balancer in Google Cloud konfigurieren möchten, verwenden Sie den Dienst Certificate Manager und entweder von Google verwaltete oder selbstverwaltete SSL-Zertifikate. |
Cloud DNS | Die öffentliche Cloud DNS-Zone wird verwendet, um die externe IP-Adresse des externen Application Load Balancers in nip.io (agentspace.externalip.nip.io) aufzulösen. Alternativ können Sie Ihre benutzerdefinierte Domain und einen A-Eintrag mit der IP-Adresse des Load-Balancers verwenden. |
4. Codelab-Topologie
5. Einrichtung und Anforderungen
Einrichtung der Umgebung im eigenen Tempo
- Melden Sie sich in der Google Cloud Console an und erstellen Sie ein neues Projekt oder verwenden Sie ein vorhandenes. Wenn Sie noch kein Gmail- oder Google Workspace-Konto haben, müssen Sie eins erstellen.
- Der Projektname ist der Anzeigename für die Teilnehmer dieses Projekts. Es handelt sich um einen String, der nicht von Google APIs verwendet wird. Sie können sie jederzeit aktualisieren.
- Die Projekt-ID ist für alle Google Cloud-Projekte eindeutig und kann nach dem Festlegen nicht mehr geändert werden. In der Cloud Console wird automatisch ein eindeutiger String generiert. Normalerweise ist es nicht wichtig, wie dieser String aussieht. In den meisten Codelabs müssen Sie auf Ihre Projekt-ID verweisen (in der Regel als
PROJECT_ID
angegeben). Wenn Ihnen die generierte ID nicht gefällt, können Sie eine andere zufällige ID generieren. Alternativ können Sie es mit einem eigenen Namen versuchen und sehen, ob er verfügbar ist. Sie kann nach diesem Schritt nicht mehr geändert werden und bleibt für die Dauer des Projekts bestehen. - Zur Information: Es gibt einen dritten Wert, die Projektnummer, die von einigen APIs verwendet wird. Weitere Informationen zu diesen drei Werten
- Als Nächstes müssen Sie die Abrechnung in der Cloud Console aktivieren, um Cloud-Ressourcen/-APIs zu verwenden. Die Durchführung dieses Codelabs kostet wenig oder gar nichts. Wenn Sie Ressourcen herunterfahren möchten, um weitere Kosten zu vermeiden, können Sie die erstellten Ressourcen oder das Projekt löschen. Neue Google Cloud-Nutzer können am Programm Kostenlose Testversion mit einem Guthaben von 300$ teilnehmen.
Cloud Shell starten
Während Sie Google Cloud von Ihrem Laptop aus per Fernzugriff nutzen können, wird in diesem Codelab Google Cloud Shell verwendet, eine Befehlszeilenumgebung, die in der Cloud ausgeführt wird.
Klicken Sie in der Google Cloud Console in der Symbolleiste oben rechts auf das Cloud Shell-Symbol:
Die Bereitstellung und Verbindung mit der Umgebung dauert nur einen Moment. Anschließend sehen Sie in etwa Folgendes:
Diese virtuelle Maschine verfügt über sämtliche Entwicklertools, die Sie benötigen. Sie bietet ein Basisverzeichnis mit 5 GB nichtflüchtigem Speicher und läuft in Google Cloud, was die Netzwerkleistung und Authentifizierung erheblich verbessert. Alle Aufgaben in diesem Codelab können in einem Browser ausgeführt werden. Sie müssen nichts installieren.
6. Hinweis
APIs aktivieren
Prüfen Sie in Cloud Shell, ob Ihre Projekt-ID eingerichtet ist:
gcloud config list project
gcloud config set project [YOUR-PROJECT-ID]
project=[YOUR-PROJECT-ID]
region=[YOUR-REGION]
echo $project
echo $region
Aktivieren Sie alle erforderlichen Dienste:
gcloud services enable compute.googleapis.com
gcloud services enable dns.googleapis.com
7. Load-Balancer-Komponenten einrichten
Externe IP-Adresse des Load-Balancers reservieren
Reservieren Sie in Cloud Shell eine externe IP-Adresse für den Load-Balancer:
gcloud compute addresses create external-ip \
--network-tier=PREMIUM \
--ip-version=IPV4 \
--global
Rufen Sie in Cloud Shell die reservierte IP-Adresse auf:
gcloud compute addresses describe external-ip \
--global | grep -i address:
Beispielausgabe:
user@cloudshell$ gcloud compute addresses describe external-ip \
--global | grep -i address:
address: 34.54.158.206
Internet-NEG einrichten
Erstellen Sie eine Internet-NEG und legen Sie „–network-endpoint-type“ auf „internet-fqdn-port“ fest (der Hostname und der Port, an dem Ihr externes Back-End erreicht werden kann). Zur Auflösung von Agentspace wird der FQDN vertexaisearch.cloud.google.com und PORT 443 verwendet.
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
Load-Balancer erstellen
Führen Sie in Cloud Shell folgende Schritte aus:
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
Zertifikat erstellen
Sie haben jetzt die Internet-NEG und den Back-End-Dienst erstellt. Im nächsten Abschnitt müssen Sie eine Zertifikatsressource erstellen, die im HTTPS-Zielproxy verwendet werden soll. Sie können eine SSL-Zertifikatsressource entweder mit einem von Google verwalteten SSL-Zertifikat oder mit einem selbst verwalteten SSL-Zertifikat erstellen. Es empfiehlt sich, von Google verwaltete Zertifikate zu verwenden, da Google Cloud diese Zertifikate automatisch abruft, verwaltet und verlängert.
Weitere Informationen zu den unterstützten Zertifikaten für den globalen externen Application Load Balancer, der in dieser Anleitung verwendet wird, finden Sie unter:
SSL-Zertifikate | Load Balancing | Google Cloud
Im folgenden Abschnitt erstellen Sie ein selbstsigniertes Zertifikat. Stattdessen kann aber auch ein von Google verwaltetes Zertifikat verwendet werden. Dazu muss der allgemeine Name dem vollständig qualifizierten Domainnamen (agentspace.YOUR-EXTERNAL-IP.nip.io) zugeordnet werden, der der externen IP-Adresse des Load-Balancers entspricht, die zuvor generiert wurde. Beispiel:
Allgemeiner Name: agentspace.34.54.158.206.nip.io
Privaten Schlüssel in Cloud Shell erstellen
openssl genrsa -out private-key-file.pem 2048
Erstellen Sie in Cloud Shell eine Datei „config.txt“, mit der die PEM-Datei generiert wird. Geben Sie den vollständig qualifizierten Domainnamen im DNS 1-Eintrag agentspace.YOUR-EXTERNAL-IP.nip.io an, z.B. agentspace.34.54.158.206.nip.io in der Konfiguration unten.
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
Prüfen Sie in Cloud Shell, ob die Dateien „config.txt“ und „private-key-file.pem“ generiert wurden.
user@cloudshell:$ ls
config.txt private-key-file.pem
Führen Sie in Cloud Shell die folgenden Schritte aus.
sudo openssl req -new -key private-key-file.pem \
-out csr.pem \
-config config.txt
Beispiel:
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 []:
Prüfen Sie in Cloud Shell, ob die für die Zertifikatsignierung erforderliche PEM-Datei erstellt wurde.
user@cloudshell:$ ls
config.txt csr.pem private-key-file.pem
Generieren Sie das Zertifikat in 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
Beispielausgabe:
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
Prüfen Sie in Cloud Shell, ob die Datei „cert.cert“ erstellt wurde.
user@cloudshell:$ ls
cert.cert config.txt csr.pem private-key-file.pem
Erstellen Sie eine Zertifikatsressource, die Sie Ihrem externen Load-Balancer zuordnen. Ersetzen Sie die Parameter für das Zertifikat und den privaten Schlüssel durch Ihre spezifischen Dateinamen.
Führen Sie in Cloud Shell folgende Schritte aus:
gcloud compute ssl-certificates create agentspace-self-signed-cert \
--certificate=cert.cert \
--private-key=private-key-file.pem \
--global
Führen Sie in Cloud Shell folgende Schritte aus:
gcloud compute url-maps create agentspace-lb \
--default-service=agentspace-ineg-bes \
--global
Führen Sie in Cloud Shell folgende Schritte aus:
gcloud compute target-https-proxies create https-proxy \
--ssl-certificates=agentspace-self-signed-cert \
--url-map=agentspace-lb \
--global
Führen Sie in Cloud Shell folgende Schritte aus:
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. Öffentliche DNS-Zone erstellen
Im folgenden Abschnitt erstellen Sie eine öffentliche DNS-Zone, die von nip.io verwendet wird, um die externe IP-Adresse des Load-Balancers aufzulösen.
Führen Sie in Cloud Shell die folgenden Schritte aus, um eine Variable für die externe IP-Adresse des Load-Balancers zu erstellen:
externalip=<YOUR-EXTERNAL-IP>
echo $externalip
Führen Sie in Cloud Shell folgende Schritte aus:
gcloud dns --project=$project managed-zones create agentspace-dns --description="Agentspace public dns" --dns-name="$externalip.nip.io." --visibility="public"
Führen Sie in Cloud Shell folgende Schritte aus:
gcloud dns --project=$project record-sets create agentspace.$externalip.nip.io. --zone="agentspace-dns" --type="A" --ttl="300" --rrdatas="$externalip"
9. Agentspace-Anwendungs-URLs ermitteln
Im folgenden Verfahren werden die von Google generierten öffentlichen Agentspace-URLs ermittelt, die jeder Anwendung zugeordnet sind. Die Ausgabe der URLs sind Beispiele, die auf der Referenzarchitektur basieren. Sie müssen daher darauf achten, dass Ihre URLs korrekt sind.
Speichern Sie den Link zu Ihrer Web-App pro Anwendung.
Drive-Anwendung
Agentspace-Web-URL:
https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
SharePoint-Anwendung
Agentspace-Web-URL: 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. Erweiterte Host- und Pfadregel erstellen
Im folgenden Abschnitt aktualisieren Sie die Routingregeln des Load Balancers, um die Option zum Definieren von Host- und Pfadregeln über die Cloud Console zu aktivieren. In der folgenden Tabelle sind die benutzerdefinierten Werte (von oben nach unten) aufgeführt, die Sie entsprechend Ihrer Umgebung aktualisieren müssen:
Benutzerdefinierter Wert | Beispiel basierend auf der Anleitung | |
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 | /<Agentspace-URL-Pfad von App 1> | /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd |
hostRedirect | vertexaisearch.cloud.google.com | vertexaisearch.cloud.google.com |
prefixMatch | /<name of Agentspace app#2> | /sharepoint-app |
pathRedirect | /<Agentspace-URL-Pfad von App 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 |
So greifen Sie auf Host- und Pfadregeln zu:
„Load Balancing“ → „agentspace-lb“ → „Bearbeiten“ auswählen
Wählen Sie „Routingregeln“ → „Erweiterte Host- und Pfadregeln“ aus.
„Host- und Pfadregel hinzufügen“ auswählen
Sie werden nun aufgefordert, eine neue Host- und Pfadregel zu erstellen. Fügen Sie im Abschnitt „Hosts“ agentspace.YOUR-EXTERNAL-IP.nip.io oder die benutzerdefinierte Domain ein.
Aktualisieren Sie im Feld „Tool zum Abgleich von Pfaden“ (Abgleich, Aktionen und Dienste) den Inhalt unten mit Ihrer Umgebungskonfiguration und wählen Sie dann „Aktualisieren“ aus.
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
Beispiel-Screenshot:
11. Validierung
Die Bereitstellung ist abgeschlossen. Sie können über einen Webbrowser oder ein Terminal über die benutzerdefinierte Domain auf die Agentspace-Anwendung zugreifen, indem Sie agentspace.YOUR-EXTERNAL-IP.nip.io/path angeben, z. B. agentspace.34.54.158.206.nip.io. Nachfolgend finden Sie Beispiele:
Agentspace-Anwendung: drive-app
Pfad: agentspace.34.54.158.206.nip.io/drive-app
Agentspace-Anwendung: sharepoint-app
Pfad: agentspace.34.54.158.206.nip.io/sharepoint-app
12. Bereinigen
So löschen Sie OAuth-Anmeldedaten:
Rufen Sie „APIs & Dienste“ → „Anmeldedaten“ auf.
Wählen Sie unter „OAuth 2.0-Client-IDs“ Ihre Anmeldedaten aus und löschen Sie sie.
Löschen Sie die Laborkomponenten über ein einzelnes Cloud Shell-Terminal:
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. Glückwunsch
Sie haben die Konnektivität zu einem Agentspace mit einer benutzerdefinierten Domain über einen externen Application Load Balancer mit erweiterter Trafficverwaltung erfolgreich konfiguriert und validiert.
Sie haben die Load-Balancer-Infrastruktur erstellt und gelernt, wie Sie ein Internet-NEG, Cloud DNS und eine erweiterte Traffic-Verwaltung erstellen, die Host- und Pfadweiterleitung ermöglicht und die Verbindung zu Agentspace über eine benutzerdefinierte Domain ermöglicht.
Cosmopup findet Codelabs toll!!