1. מבוא
במסמך הזה מפורטת ארכיטקטורת הפניה להגדרת דומיין מותאם אישית לגישה ל-AgentSpace באמצעות WIF. במקום כתובת ה-URL שמנוהלת על ידי Google ומוקצית במהלך יצירת אפליקציית Agentspace, המשתמשים יכולים להשתמש בדומיין מותאם אישית. ב-codelab הזה מוצגת גישה לאפליקציות של יומן ו-Drive ב-Agentspace באמצעות הדומיין nip.io. nip.io הוא שירות חינמי בקוד פתוח שמספק DNS עם תווים כלליים לכל כתובת IP. היא מאפשרת לכם ליצור שם מארח שמתורגם לכתובת IP ספציפית בלי שתצטרכו להגדיר שרת DNS משלכם או לשנות את הקובץ /etc/hosts.
מומלץ להשתמש בדומיין משלכם, אבל לצורך ההדגמה נעשה שימוש ב-nip.io במדריך.
בתרחיש הפריסה שמתואר בהמשך (איור 1), AgentSpace פרסמה מאגר נתונים שמכיל אפליקציית יומן, שאפשר לגשת אליה דרך כתובת URL ציבורית שמנוהלת על ידי Google.
איור 1
המשך הצמיחה של מאגר הנתונים והאפליקציות הבאות מוביל לניהול נוסף של כתובות URL ציבוריות שמנוהלות על ידי Google, כפי שמתואר בתרחיש הפריסה שלמטה (איור 2), וכתוצאה מכך מתקבל מיפוי של 1:1 בין אפליקציות של Agentspace לבין כתובת URL.
איור 2.
דומיין מותאם אישית מאפשר מיפוי של אפליקציות שונות ב-AgentSpace לדומיין לקוח יחיד שמוגדר על ידי המשתמש. התכונה הזו מאפשרת לשייך נתיב ספציפי של כתובת URL לכל אפליקציית Agentspace, וכך מציעה גמישות רבה יותר, כפי שמוצג בתרחיש הפריסה שלמטה (איור 3). לדוגמה, דומיין שמנוהל על ידי הלקוח agentspace.cosmopup.com מפולח לכללי נתיב, שכל אחד מהם ממופה לאפליקציית Agentspace ספציפית. דוגמאות:
- agentspace.cosmopup.com/drive-app שמופנה לאפליקציית Agentspace ל-Drive
- agentspace.cosmopup.com/sharepoint-app שמופה לאפליקציית Agentspace ל-Sharepoint
כללי המארח והנתיב של מאזן העומסים החיצוני של האפליקציות (ALB), שמוגדרים באמצעות מפת כתובות ה-URL, שולטים בלוגיקה שממפה את הדומיין המותאם אישית לכתובת ה-URL שמנוהלת על ידי Google. הוא מבצע את הפונקציה הבאה באמצעות סביבת הסוכן לדוגמה agentspace.cosmopup.com/drive-app
- נתיב המארח של הדומיין המותאם אישית agentspace.cosmopup.com/drive-app מתקבל על ידי מאזן העומסים
- מיפוי כתובות URL מוגדר להתאמה מתקדמת של כללי מארח ונתיב
- המארחים agentspace.cosmopup.com עומדים בדרישות להתאמת נתיבים ולהפניה אוטומטית
- הנתיב המארח של הדומיין המותאם אישית agentspace.cosmopup.com/drive-app כפוף ל-UrlRedirect
- pathRedirect הוא הנתיב של Agentspace: /us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
- hostRedirect הוא המארח של Agentspace: vertexaisearch.cloud.google.com
- הנתיב של מארח הדומיין המותאם אישית agentspace.cosmopup.com/sharepoint-app כפוף ל-UrlRedirect
- pathRedirect הוא הנתיב של 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 הוא המארח של Agentspace: auth.cloud.google
- פעולת ההפניה האוטומטית מתבצעת לפני הניתוב לשירות העורפי
איור 3
מה תלמדו
- יצירת מאזן עומסים גלובלי חיצוני לאפליקציות
- יצירת ניתוב להפניה אוטומטית של דומיין מותאם אישית לאפליקציית Agentspace
- איך משלבים בין nip.io ו-Cloud DNS כדי ליצור דומיין מותאם אישית
- איך מאמתים את הגישה לדומיין מותאם אישית של מרחב סוכנים
מה צריך להכין
- פרויקט ב-Google Cloud עם הרשאות בעלים
- כתובות URL קיימות של אפליקציות Agentspace
- דומיין מותאם אישית בבעלות עצמית (אופציונלי)
- אישורים – חתימה עצמית או ניהול על ידי Google
2. מה תפַתחו
תגדירו מאזן עומסים חיצוני גלובלי של אפליקציות עם יכולות מתקדמות לניהול תנועת גולשים, כדי לאפשר התאמה של נתיב דומיין מותאם אישית לאפליקציות של Agentspace באמצעות הפניה אוטומטית של מארח ונתיב. אחרי הפריסה, תבצעו את הפעולות הבאות כדי לאמת את הגישה לאפליקציית Agentspace:
- כדי לגשת לאפליקציית Agentspace, פותחים דפדפן אינטרנט ועוברים לדומיין המותאם אישית ולנתיב שצוין.
3. דרישות הרשת
בהמשך מפורטות דרישות הרשת:
רכיבים | תיאור |
VPC (agentspace-vpc) | מצב מותאם אישית של VPC |
NEG באינטרנט | משאב שמשמש להגדרת קצה עורפי חיצוני למאזן העומסים, שמוגדר כ-FQDN שמציין את ה-FQDN שמנוהל על ידי Google של Agentspace (vertexaisearch.cloud.google.com). שם דומיין מלא (FQDN) באינטרנט מבצע חיפוש DNS בתוך ה-VPC לצורך רזולוציה. |
שירות לקצה העורפי | שירות לקצה העורפי משמש כגשר בין מאזן העומסים לבין משאבי הקצה העורפי. במדריך, שירות הקצה העורפי משויך ל-NEG של האינטרנט. |
אישורים | כדי להגדיר אישורים למאזן עומסים של אפליקציות ב-Google Cloud, צריך להשתמש בשירות Certificate Manager ובאחד מהאפשרויות הבאות: אישורי SSL בניהול Google או אישורי SSL בניהול עצמי. |
Cloud DNS | אזור ציבורי של Cloud DNS משמש לפתרון כתובת ה-IP החיצונית של מאזן העומסים החיצוני של האפליקציה אל nip.io (agentspace.externalip.nip.io). אפשרות אחרת היא להשתמש בדומיין המותאם אישית וברשומת A שכוללת את כתובת ה-IP של מאזן העומסים. |
4. טופולוגיית Codelab
5. הגדרה ודרישות
הגדרת סביבה בקצב אישי
- נכנסים ל-Google Cloud Console ויוצרים פרויקט חדש או משתמשים בפרויקט קיים. אם עדיין אין לכם חשבון Gmail או חשבון Google Workspace, אתם צריכים ליצור חשבון.
- שם הפרויקט הוא השם המוצג למשתתפים בפרויקט. זו מחרוזת תווים שלא נמצאת בשימוש ב-Google APIs. תמיד אפשר לעדכן את המיקום.
- מזהה הפרויקט הוא ייחודי לכל הפרויקטים ב-Google Cloud, והוא קבוע (אי אפשר לשנות אותו אחרי שהוא מוגדר). מסוף Cloud יוצר באופן אוטומטי מחרוזת ייחודית. בדרך כלל לא צריך לדעת מה היא. ברוב המדריכים ללימוד תכנות, תצטרכו להפנות למזהה הפרויקט (בדרך כלל מסומן כ-
PROJECT_ID). אם לא אהבתם את המזהה שנוצר, תוכלו ליצור מזהה אקראי אחר. אפשר גם לנסות שם משתמש משלכם ולבדוק אם הוא זמין. אי אפשר לשנות את ההגדרה הזו אחרי השלב הזה, והיא נשארת לאורך הפרויקט. - לידיעתכם, יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. במאמרי העזרה מפורט מידע נוסף על שלושת הערכים האלה.
- בשלב הבא, תצטרכו להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבי Cloud או בממשקי API של Cloud. השלמת ה-codelab הזה לא תעלה לכם הרבה, אם בכלל. כדי להשבית את המשאבים ולוודא שלא תחויבו על שימוש בהם אחרי שתסיימו את המדריך הזה, תוכלו למחוק את המשאבים שיצרתם או למחוק את הפרויקט. משתמשים חדשים ב-Google Cloud זכאים לתוכנית תקופת ניסיון בחינם בשווי 300$.
הפעלת Cloud Shell
אפשר להפעיל את Google Cloud מרחוק מהמחשב הנייד, אבל ב-codelab הזה תשתמשו ב-Google Cloud Shell, סביבת שורת פקודה שפועלת בענן.
ב-Google Cloud Console, לוחצים על סמל Cloud Shell בסרגל הכלים שבפינה הימנית העליונה:
יחלפו כמה רגעים עד שההקצאה והחיבור לסביבת העבודה יושלמו. בסיום התהליך, אמור להופיע משהו כזה:
המכונה הווירטואלית הזו כוללת את כל הכלים הדרושים למפתחים. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר מאוד את הביצועים והאימות ברשת. אפשר לבצע את כל העבודה ב-codelab הזה בדפדפן. לא צריך להתקין שום דבר.
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. הגדרת רכיבי מאזן העומסים
שמירת כתובת ה-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 באינטרנט
יוצרים NEG לאינטרנט ומגדירים את –network-endpoint-type ל-internet-fqdn-port (שם המארח והיציאה שדרכם אפשר להגיע לקצה העורפי החיצוני). כדי לפתור את Agentspace, נעשה שימוש ב-FQDN vertexaisearch.cloud.google.com וביציאה 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 ואת שירות ה-Backend באינטרנט. בקטע הבא תצטרכו ליצור משאב אישור לשימוש ב-proxy היעד של HTTPs. אפשר ליצור משאב של אישור SSL באמצעות אישור SSL בניהול Google או אישור 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
8. יצירת תחום 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"
9. זיהוי כתובות URL של אפליקציות ב-Agentspace
בתהליך הבא מפורטות כתובות ה-URL הציבוריות של Agentspace שמנוהלות על ידי Google, שנוצרו על ידי Google וממופות ל-Agentspace של כל אפליקציה. הפלט של כתובות ה-URL הוא דוגמאות שמבוססות על ארכיטקטורת ההפניה, ולכן חשוב לוודא שכתובות ה-URL מדויקות.
חשוב לשמור את הקישור לאפליקציית האינטרנט שלכם, לכל אפליקציה.
אפליקציית Drive
כתובת ה-URL של Agentspace באינטרנט:
https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
אפליקציית Sharepoint
כתובת ה-URL של 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. יצירת כלל מתקדם של מארח ונתיב
בקטע הבא נסביר איך לעדכן את כללי הניתוב של מאזני העומסים כדי להפעיל את האפשרות להגדיר כללי מארח וכללי נתיב באמצעות מסוף הענן. בטבלה הבאה מפורטים הערכים המותאמים אישית (בסדר מלמעלה למטה), והיא מתעדכנת בהתאם לסביבה שלכם:
ערך מותאם אישית | דוגמה שמבוססת על מדריך | |
מארחים | 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 path of 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 path of 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 |
כדי לגשת לכללי מארח ולכללי נתיב, עוברים אל
איזון עומסים ← agentspace-lb ← בחירה באפשרות 'עריכה'
בוחרים באפשרות Routing rules (כללי ניתוב) → Advanced host and path rules (כללים מתקדמים של מארח ונתיב).
בוחרים באפשרות 'הוספת כלל של מארח ונתיב'.
מוצגת לכם אפשרות ליצור כלל חדש של מארח ונתיב. בקטע hosts, מזינים את הערך agentspace.YOUR-EXTERNAL-IP.nip.io או דומיין מותאם אישית.
בשדה Path matcher (התאמות, פעולות ושירותים), מעדכנים את התוכן שלמטה בהתאם להגדרות הסביבה שלכם ולוחצים על update (עדכון).
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
צילום מסך לדוגמה:
11. אימות
הפריסה הושלמה. אפשר לגשת לאפליקציית 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: sharepoint-app
נתיב: agentspace.34.54.158.206.nip.io/sharepoint-app
12. הסרת המשאבים
כדי למחוק פרטי כניסה של OAuth:
עוברים אל APIs & Services → Credentials
בקטע OAuth 2.0 Client IDs (מזהי לקוחות ב-OAuth 2.0), בוחרים את פרטי הכניסה ומוחקים אותם.
ממסוף Cloud Shell יחיד, מוחקים את רכיבי ה-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. מזל טוב
הגדרתם ואימתתם בהצלחה את הקישוריות ל-Agentspace באמצעות דומיין בהתאמה אישית, באמצעות מאזן עומסים חיצוני של אפליקציות עם ניהול מתקדם של תנועת גולשים.
יצרתם את התשתית של איזון העומסים, למדתם איך ליצור Internet NEG, Cloud DNS וניהול מתקדם של תנועה שמאפשר הפניה אוטומטית של מארחים ונתיבים, וכך מאפשר קישור ל-Agentspace באמצעות דומיין מותאם אישית.
Cosmopup חושב ש-codelabs הם מדהימים!!
