התחברות באמצעות שרת proxy לאימות של AlloyDB

כדי ליצור חיבורים מוצפנים ומורשים למכונות AlloyDB, אפשר להשתמש ב-AlloyDB Auth Proxy. מידע נוסף זמין במאמר מידע על שרת proxy לאימות של AlloyDB.

כדי להשתמש ב-AlloyDB Auth Proxy, צריך לבצע כמה שלבי הגדרה חד-פעמיים, ואז להפעיל את לקוח ה-Auth Proxy ולהשתמש בו כדי להתחבר למסד נתונים.

לפני שמתחילים

המארח של הלקוח צריך לעמוד בדרישות הבאות:

  • ללקוח צריכה להיות גישה לרשת הענן הווירטואלי הפרטי (VPC) שבה נמצאים המופעים שרוצים להתחבר אליהם. למארחי לקוחות (כמו מכונות וירטואליות של Compute Engine) ברשת הענן הווירטואלי הפרטי (VPC) הזו יש באופן מובנה את הנראות הזו של הרשת.

    למארחי לקוחות ברשתות חיצוניות (רשתות מקומיות או רשתות VPC שונות) יש גישה לרשת הזו אם רשת ה-VPC של מופע AlloyDB מחוברת לרשת החיצונית באמצעות מנהרת Cloud VPN או באמצעות קובץ מצורף של VLAN ל-Dedicated Interconnect או ל-Partner Interconnect.

  • אם למארח הלקוח יש מדיניות חומת אש יוצאת, היא צריכה לאפשר חיבורים יוצאים ליציאה 5433 בכתובות ה-IP של מופעי AlloyDB, ולאפשר חיבורים יוצאים ליציאה 443 (יציאת HTTPS הרגילה) לכל כתובות ה-IP.

  • אם אתם משתמשים במכונה ב-Compute Engine כמארח לקוח, צריך להגדיר לה את היקף הגישה https://www.googleapis.com/auth/cloud-platform כדי שתוכל להשתמש ב-AlloyDB API. במקרה הצורך, משנים את היקף הגישה כדי לכלול את ההיקף הזה.

הורדת לקוח של שרת proxy לאימות

המחשב שאליו מורידים את לקוח Auth Proxy תלוי בשאלה אם רוצים להתחבר למכונות AlloyDB מתוך רשת ה-VPC או מחוצה לה.

אם רוצים להתחבר לאשכול באמצעות גישה לשירותים פרטיים, אפשר להוריד את לקוח ה-Auth Proxy למכונה וירטואלית (VM) של Compute Engine שפועלת ברשת ה-VPC שיש לה גישה לשירותים פרטיים באשכול.

אם אתם מתכוונים להתחבר לאשכול מחוץ ל-VPC, המכונה שבה תתקינו את התוסף תלויה באסטרטגיית החיבור החיצונית שבה אתם משתמשים. לדוגמה, אתם יכולים להתקין את לקוח ה-Auth Proxy במחשב macOS או Windows שנמצא באופן מקומי באפליקציה שלכם, ואז להשתמש בשרת SOCKS שפועל ברשת ה-VPC של AlloyDB בתור מתווך חיבור. מידע נוסף זמין במאמר התחברות לאשכול מחוץ ל-VPC שלו.

Linux

‫64 ביט (AMD)

  1. מורידים את לקוח Auth Proxy:

    wget https://storage.googleapis.com/alloydb-auth-proxy/v1.15.1/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

  2. הופכים את קובץ ההפעלה של לקוח Auth Proxy לניתן להרצה:

    chmod +x alloydb-auth-proxy

  3. מוסיפים את לקוח ה-Auth Proxy לנתיב:

    mkdir -p ~/.local/bin
mv alloydb-auth-proxy ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

    כדי שהשינויים האלה יישמרו בין סשנים, מוסיפים את export PATH="$HOME/.local/bin:$PATH" לקובץ ~/.bashrc או ~/.zshrc.

‫32 ביט (AMD)

  1. מורידים את לקוח Auth Proxy:

    wget https://storage.googleapis.com/alloydb-auth-proxy/v1.15.1/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy

  2. הופכים את קובץ ההפעלה של לקוח Auth Proxy לניתן להרצה:

    chmod +x alloydb-auth-proxy

  3. מוסיפים את לקוח ה-Auth Proxy לנתיב:

    mkdir -p ~/.local/bin
mv alloydb-auth-proxy ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

    כדי שהשינויים האלה יישמרו בין סשנים, מוסיפים את export PATH="$HOME/.local/bin:$PATH" לקובץ ~/.bashrc או ~/.zshrc.

‫64 ביט (ARM)

  1. מורידים את לקוח Auth Proxy:

    wget https://storage.googleapis.com/alloydb-auth-proxy/v1.15.1/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy

  2. הופכים את קובץ ההפעלה של לקוח Auth Proxy לניתן להרצה:

    chmod +x alloydb-auth-proxy

  3. מוסיפים את לקוח ה-Auth Proxy לנתיב:

    mkdir -p ~/.local/bin
mv alloydb-auth-proxy ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

    כדי שהשינויים האלה יישמרו בין סשנים, מוסיפים את export PATH="$HOME/.local/bin:$PATH" לקובץ ~/.bashrc או ~/.zshrc.

‫32 ביט (ARM)

  1. מורידים את לקוח Auth Proxy:

    wget https://storage.googleapis.com/alloydb-auth-proxy/v1.15.1/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy

  2. הופכים את קובץ ההפעלה של לקוח Auth Proxy לניתן להרצה:

    chmod +x alloydb-auth-proxy

  3. מוסיפים את לקוח ה-Auth Proxy לנתיב:

    mkdir -p ~/.local/bin
mv alloydb-auth-proxy ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

    כדי שהשינויים האלה יישמרו בין סשנים, מוסיפים את export PATH="$HOME/.local/bin:$PATH" לקובץ ~/.bashrc או ~/.zshrc.

macOS

ARM64

  1. מורידים את לקוח Auth Proxy:

    curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.15.1/alloydb-auth-proxy.darwin.arm64

  2. הופכים את קובץ ההפעלה של לקוח Auth Proxy לניתן להרצה:

    chmod +x alloydb-auth-proxy

  3. מוסיפים את לקוח ה-Auth Proxy לנתיב:

    mkdir -p ~/.local/bin
mv alloydb-auth-proxy ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

    כדי שהשינויים האלה יישמרו בין סשנים, מוסיפים את export PATH="$HOME/.local/bin:$PATH" לקובץ ~/.bashrc או ~/.zshrc.

AMD64

  1. מורידים את לקוח Auth Proxy:

    curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.15.1/alloydb-auth-proxy.darwin.amd64

  2. הופכים את קובץ ההפעלה של לקוח Auth Proxy לניתן להרצה:

    chmod +x alloydb-auth-proxy

  3. מוסיפים את לקוח ה-Auth Proxy לנתיב:

    mkdir -p ~/.local/bin
mv alloydb-auth-proxy ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

    כדי שהשינויים האלה יישמרו בין סשנים, מוסיפים את export PATH="$HOME/.local/bin:$PATH" לקובץ ~/.bashrc או ~/.zshrc.

Windows

‫64 ביט

  1. לוחצים לחיצה ימנית על https://storage.googleapis.com/alloydb-auth-proxy/v1.15.1/alloydb-auth-proxy-x64.exe ובוחרים באפשרות שמירת קישור בשם כדי להוריד את לקוח ה-Auth Proxy. משנים את שם הקובץ ל-alloydb-auth-proxy.exe.

  2. מוסיפים את לקוח ה-Auth Proxy לנתיב:

    New-Item -ItemType Directory -Force -Path "$HOME\bin"
Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")

‫32 ביט

  1. לוחצים לחיצה ימנית על https://storage.googleapis.com/alloydb-auth-proxy/v1.15.1/alloydb-auth-proxy-x86.exe ובוחרים באפשרות שמירת הקישור בשם כדי להוריד את לקוח ה-Auth Proxy. משנים את שם הקובץ ל-alloydb-auth-proxy.exe.

  2. מוסיפים את לקוח ה-Auth Proxy לנתיב:

    New-Item -ItemType Directory -Force -Path "$HOME\bin"
Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")

קובץ אימג' של Docker

לנוחותכם, כמה תמונות של קונטיינרים שמכילות את לקוח Auth Proxy זמינות ב-Artifact Registry.

אפשר למשוך את התמונה העדכנית ביותר למחשב המקומי באמצעות Docker עם הפקודה הבאה:

docker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:latest

מערכת הפעלה אחרת

למערכות הפעלה אחרות שלא נכללות כאן, אפשר לקמפל את לקוח ה-Auth Proxy ממקור.

בחירת החשבון הראשי ב-IAM והכנתו להרשאה

שרת ה-proxy לאימות ב-AlloyDB תומך בשימוש בסוגים הבאים של חשבונות משתמשים ב-IAM כדי לתת הרשאה לחיבורים בין הלקוח לבין מכונת AlloyDB:

  • חשבון שירות שמנוהל על ידי משתמש. אתם יכולים ליצור חשבון שירות ב-IAM עבור האפליקציה שלכם, ואז לאשר חיבורים באמצעות החשבון הזה.

    מומלץ מאוד להשתמש בחשבון שירות להרשאה בסביבות ייצור.

  • חשבון המשתמש. אתם יכולים להשתמש בחשבון משתמש IAM משלכם כדי לאשר חיבורים.

    השימוש בחשבון המשתמש שלכם נוח בסביבות פיתוח שבהן אתם מנהלים משאבי AlloyDB באמצעות ה-CLI של gcloud, מפתחים את מסד הנתונים באמצעות כלי כמו psql ומפתחים קוד אפליקציה, והכול באותו מארח.

  • חשבון השירות של Compute Engine שמוגדר כברירת מחדל. אם מארח הלקוח הוא מכונה של Compute Engine, אפשר להשתמש בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine כדי לאשר חיבורים.

אחרי שבוחרים את חשבון המשתמש ב-IAM שבו רוצים להשתמש, צריך לוודא שיש לו את הרשאות ה-IAM הנדרשות ולוודא שפרטי הכניסה שלו זמינים במארח הלקוח.

הרשאות IAM נדרשות

לישות המורשית של IAM שמשמשת לאישור החיבורים צריכות להיות ההרשאות שמוגדרות מראש בתפקידים roles/alloydb.client (לקוח Cloud AlloyDB) ו-roles/serviceusage.serviceUsageConsumer (Service Usage Consumer).

כדי להקצות את התפקיד Cloud AlloyDB Client למשתמש ב-IAM:

  • צריך להפעיל את Cloud Resource Manager API בפרויקט ב- Google Cloud .

  • צריך להיות לכם תפקיד ה-IAM הבסיסי roles/owner (בעלים) בGoogle Cloud פרויקט, או תפקיד שמעניק את ההרשאות הבאות:

    • resourcemanager.projects.get
    • resourcemanager.projects.getIamPolicy
    • resourcemanager.projects.setIamPolicy

    כדי לקבל את ההרשאות האלה תוך שמירה על עקרון ההרשאות המינימליות, צריך לבקש מהאדמין להקצות לכם את התפקיד roles/resourcemanager.projectIamAdmin (אדמין IAM בפרויקט).

הפיכת פרטי הכניסה של IAM לזמינים במארח הלקוח

הדרך שבה מעבירים את פרטי הכניסה של IAM למארח הלקוח תלויה בסוג חשבון המשתמש ב-IAM שבו אתם משתמשים כדי לאשר חיבורים:

  • חשבון שירות בניהול המשתמשים

    כדי לספק פרטי כניסה ל-IAM עבור חשבון שירות בניהול המשתמש, יוצרים מפתח לחשבון שירות בפורמט JSON ומורידים אותו למארח הלקוח. כשמפעילים את לקוח Auth Proxy, מציינים את המיקום של קובץ המפתח באמצעות הדגל --credentials-file.

  • חשבון המשתמש

    כדי לספק פרטי כניסה של IAM לחשבון המשתמש, מתקינים את Google Cloud CLI במארח הלקוח ואז מריצים את הפקודה gcloud auth application-default login כדי ליצור את קובץ Application Default Credentials‏ (ADC):

    gcloud auth application-default login

    כשמפעילים את לקוח Auth Proxy, הוא מזהה את פרטי הכניסה של חשבון המשתמש ומשתמש בהם באופן אוטומטי, אלא אם מספקים לו פרטי כניסה של חשבון שירות בניהול המשתמש.

  • חשבון השירות של Compute Engine שמוגדר כברירת מחדל

    אם אתם משתמשים במופע של Compute Engine כמארח לקוח, פרטי הכניסה של חשבון השירות שמשמש כברירת המחדל של Compute Engine כבר נמצאים במארח. כשמפעילים את לקוח Auth Proxy, הוא מזהה את פרטי הכניסה האלה ומשתמש בהם באופן אוטומטי אם פרטי הכניסה של חשבון השירות בניהול המשתמש ושל חשבון המשתמש לא זמינים.

איסוף כתובות URI לחיבור למכונות AlloyDB

כשמפעילים את לקוח אימות ה-Proxy, מציינים את מופע או מופעי AlloyDB שאליהם רוצים להתחבר באמצעות הפורמט של מזהה ה-URI של החיבור:

projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

כדי לראות רשימה של כל כתובות ה-URI של החיבור של המכונות, משתמשים בפקודה alloydb instances list של ה-CLI של gcloud.

אוספים את מזהי ה-URI של החיבור למופע של כל מופע שרוצים להתחבר אליו.

הפעלת לקוח של שרת proxy לאימות

כשמפעילים את לקוח שרת ה-proxy לאימות, מספקים לו מידע על מופעי AlloyDB שאליהם רוצים להתחבר, ובמקרה הצורך, פרטי כניסה לשימוש באימות החיבורים האלה.

כשהוא מתחיל, לקוח Auth Proxy:

  • נותן הרשאה לחיבורים למופעי AlloyDB באמצעות האישורים וההרשאות של הישות המורשית ב-IAM שהגדרתם. הוא מחפש את פרטי הכניסה על ידי ביצוע רצף ספציפי של שלבים.
  • מאשר באופן אוטומטי חיבורים של כתובות IP ציבוריות לרשת המקור, אם כתובת ה-IP הציבורית מופעלת במופע.
  • הגדרת חיבור פרטי מסוג mTLS 1.3 לכל שרת proxy לאימות של מכונה.
  • מתחיל להאזין לבקשות חיבור של לקוחות מקומיים.

כברירת מחדל, לקוח Auth Proxy מאזין לחיבורי TCP בכתובת IP‏ 127.0.0.1, החל מיציאה 5432, ומוסיף מספר יציאה אחד לכל מופע AlloyDB מעבר לראשון. אפשר לציין כתובת מאזין אחרת ויציאות שונות כשמפעילים את לקוח Auth Proxy.

שורת הפקודה

./alloydb-auth-proxy INSTANCE_URI... \
    [ --credentials-file PATH_TO_KEY_FILE \ ]
    [ --token OAUTH_ACCESS_TOKEN \ ]
    [ --port INITIAL_PORT_NUMBER \ ]
    [ --address LOCAL_LISTENER_ADDRESS \ ]
    [ --auto-iam-authn \ ]
    [ --psc \ ]
    [ --public-ip \ ]
    [ --disable-built-in-telemetry ]

מחליפים את מה שכתוב בשדות הבאים:

  • ‫INSTANCE_URI: ה-URI של חיבור המכונה של מכונת AlloyDB שאליה רוצים להתחבר, בפורמט הבא:

    projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

    אפשר לשנות את יציאת ברירת המחדל של מאזין מקומי שבה לקוח Auth Proxy ישתמש עבור המופע, על ידי הוספת פרמטר השאילתה port ל-URI:

    "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

  • אופציונלי: PATH_TO_KEY_FILE: הנתיב לקובץ מפתח ה-JSON של חשבון השירות שמנוהל על ידי המשתמש, שבו יש להשתמש לאישור החיבור.

  • אופציונלי: OAUTH_ACCESS_TOKEN: ערך של טוקן OAuth2 לשימוש בהרשאת חיבור.

  • אופציונלי: INITIAL_PORT_NUMBER: מספר היציאה ההתחלתי לשימוש במקום יציאת ברירת המחדל 5432 כשמאזינים לחיבורי TCP מקומיים.

  • אופציונלי: LOCAL_LISTENER_ADDRESS: כתובת המאזין לשימוש במקום ברירת המחדל 127.0.0.1 כשמאזינים לחיבורי TCP מקומיים.

הדגל --auto-iam-authn הוא אופציונלי ומאפשר לבצע אימות אוטומטי למכונה. האפשרות הזו פועלת רק עבור משתמש מסד הנתונים שמשויך לחשבון IAM שמריץ את לקוח Auth Proxy. מידע נוסף זמין במאמר אימות אוטומטי באמצעות שרת proxy לאימות.

הדגל האופציונלי --psc מאפשר ל-Auth Proxy להתחבר למופע עם Private Service Connect מופעל. מידע נוסף על הגדרת DNS עם Private Service Connect זמין במאמר הגדרת אזור מנוהל של DNS ורשומת DNS.

הסימון האופציונלי --public-ip מאפשר לשרת ה-proxy של Auth להתחבר למכונה עם כתובת IP ציבורית באמצעות כתובת ה-IP הציבורית של המכונה. מידע נוסף על כתובת IP ציבורית זמין במאמר חיבור באמצעות כתובת IP ציבורית.

הדגל האופציונלי --disable-built-in-telemetry משבית את הכלי הפנימי לדיווח על מדדים שמשמש את שרת ה-Auth Proxy לדיווח על החיבור ועל תקינות הרשת. כברירת מחדל, שרת ה-Proxy לאימות מדווח על הפעולות הפנימיות שלו לקידומת המדד של המערכת alloydb.googleapis.com. המדדים האלה עוזרים ל-AlloyDB לשפר את הביצועים ולזהות בעיות בקישוריות של הלקוח. האפשרות הזו שימושית לאפליקציות שפועלות בסביבות שבהן יש הגבלה על ייצוא מדדים יוצאים. כדי להפסיק את השליחה של נתוני הטלמטריה האלה, משתמשים בדגל הזה.

מאגר Docker

מריצים את לקוח Auth Proxy באמצעות הפקודה docker run.

אם אתם משתמשים בפרטי הכניסה שסופקו על ידי מכונת Compute Engine, אתם יכולים להשתמש בפקודה שדומה לפקודה הבאה:

docker run \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  INSTANCE_URI

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PORT: היציאה לשימוש בחיבורים מקומיים ללקוח של שרת ה-Proxy לאימות. ערך ברירת המחדל הוא 5432.

  • ‫INSTANCE_URI: ה-URI של חיבור המכונה למכונת AlloyDB שאליה רוצים להתחבר, בפורמט הבא:

    projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

    אפשר לשנות את יציאת ברירת המחדל של מאזין מקומי שמשמש את לקוח Auth Proxy עבור המופע, על ידי הוספת פרמטר השאילתה port ל-URI:

    "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

תמיד מציינים את הקידומת 127.0.0.1 בדגל --publish כדי שלקוח ה-Auth Proxy לא ייחשף מחוץ למארח המקומי.

הערך 0.0.0.0 בדגל --address נדרש כדי שהמאזין יהיה נגיש מחוץ למאגר Docker.

כדי לספק פרטי כניסה ששמרתם בקובץ JSON מקומי, צריך לכלול את הדגלים --volume ו---credentials-file כשמריצים את הפקודה docker run:

docker run \
  --volume PATH_TO_KEY_FILE:/key.json \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  --credentials-file=/key.json \
  INSTANCE_URI

מחליפים את PATH_TO_KEY_FILE בנתיב לקובץ מפתח ה-JSON של חשבון השירות שמנוהל על ידי המשתמש, שבו רוצים להשתמש לאישור הגישה.

דוגמאות לסטארט-אפים

בדוגמאות הבאות מוצגות דרכים שונות להפעלת לקוח Auth Proxy. הם משתמשים בכתובות ה-URI הבאות של חיבור למופע לדוגמה:

projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary

projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool

הפעלה בסיסית

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary"

בדוגמה הזו, לקוח שרת ה-Proxy לאימות מאשר את החיבור על ידי ביצוע רצף שלבי האימות הרגיל שלו, ואז מתחיל להאזין לחיבורים מקומיים למופע myprimary ב-127.0.0.1:5432.

הפעלה באמצעות חשבון שירות שמנוהל על ידי משתמש

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \\
  --credentials-file "myappaccount/key.json"

בדוגמה הזו, לקוח שרת ה-proxy ל-Auth מאשר את החיבור באמצעות מפתח ה-JSON של חשבון השירות שמנוהל על ידי המשתמש, שמאוחסן ב-myappaccount/key.json, ואז מתחיל להאזין לחיבורים מקומיים למופע myprimary ב-127.0.0.1:5432.

הפעלה של חיבור לכמה מופעים

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool"

בדוגמה הזו, לקוח שרת ה-proxy ל-Auth מאשר את החיבור על ידי ביצוע רצף שלבי ההרשאה, ואז מתחיל להאזין לחיבורים מקומיים למופע myprimary ב-127.0.0.1:5432 ולמופע myreadpool ב-127.0.0.1:5433.

הפעלה של האזנה ביציאות בהתאמה אישית

שימוש ביציאות מותאמות אישית עבור לקוח Auth Proxy יכול להיות שימושי כשצריך לשריין את יציאה 5432 לחיבורים אחרים של PostgreSQL.

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary?port=5000" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool?port=5001"

בדוגמה הזו, לקוח שרת ה-proxy ל-Auth מאשר את החיבור על ידי ביצוע רצף שלבי ההרשאה, ואז מתחיל להאזין לחיבורים מקומיים למופע myprimary ב-127.0.0.1:5000 ולמופע myreadpool ב-127.0.0.1:5001.

מכיוון שהיציאות המותאמות אישית האלה הן עוקבות, אפשר להשיג את אותו אפקט באמצעות פקודת ההפעלה הזו:

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool" \
  --port 5000

הפעלת האזנה בכתובת IP מותאמת אישית

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  --address "0.0.0.0"

בדוגמה הזו, לקוח שרת ה-Proxy לאימות מאשר את החיבור על ידי ביצוע רצף שלבי האימות הרגיל שלו, ואז מתחיל להאזין לחיבורים מקומיים למופע myprimary ב-0.0.0.0:5432.

חיבור אפליקציה למסד נתונים באמצעות שרת ה-proxy לאימות של AlloyDB

בדוגמאות הבאות אפשר לראות איך מחברים אפליקציה למסד נתונים באמצעות שרת proxy לאימות של AlloyDB.

בדוגמה psql מוסבר איך לחבר כלי שורת פקודה.

החיבור למכונת AlloyDB באמצעות שרת proxy ל-Auth זהה בכמה שפות תכנות לחיבור ל-Cloud SQL ל-PostgreSQL באמצעות שרת proxy ל-Cloud SQL Auth, ולכן דוגמאות השפות זהות לאלה של Cloud SQL ל-PostgreSQL.

הדוגמאות האלה מבוססות על הפעלה של לקוח Auth Proxy כברירת מחדל, כך שהוא מאזין לחיבורי TCP מקומיים בכתובת 127.0.0.1:5432.

psql

psql -h 127.0.0.1 -p 5432 -U DB_USER

מחליפים את DB_USER במשתמש במסד הנתונים שאליו רוצים להתחבר – לדוגמה, postgres.

תוצג בקשה להזין את הסיסמה של המשתמש DB_USER.

Python

import os

import sqlalchemy


# connect_tcp_socket initializes a TCP connection pool
# for an AlloyDB instance.
def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    INSTANCE_HOST = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<INSTANCE_HOST>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=INSTANCE_HOST,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java


import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>l

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"



    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for an AlloyDB cluster.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

המשך

כדי לראות את קטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין בקובץ ה-README ב-GitHub.

package alloydb

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v4 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for an AlloyDB cluster.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Warning: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' or IP Address of Cluster
		dbPort    = mustGetenv("DB_PORT")       // e.g. '5432'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %v", err)
	}

	// ...

	return dbPool, nil
}

C#‎

כדי לראות את קטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין בקובץ ה-README ב-GitHub.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

כדי לראות את קטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין בקובץ ה-README ב-GitHub.

development:
  adapter: postgresql
  # Configure additional properties here.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT")  { 5432 }%>

PHP

כדי לראות את קטע הקוד הזה בהקשר של אפליקציית אינטרנט, אפשר לעיין בקובץ ה-README ב-GitHub.

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

// Connect using TCP
$dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $dbHost);

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);