התחברות למופע באמצעות נקודת קצה לכתיבה

סקירה כללית

בדף הזה מוסבר איך להשתמש בנקודת קצה (endpoint) לכתיבה כדי להתחבר מלקוחות ברשת של הענן הווירטואלי הפרטי (VPC) למופע Cloud SQL באמצעות גישה לשירותים פרטיים (PSA).

נקודת קצה לכתיבה היא שם גלובלי של Domain Name Service‏ (DNS) שמקבל באופן אוטומטי את כתובת ה-IP של המופע הראשי הנוכחי. במקרה של יתירות כשל או מעבר לגיבוי פעיל של רפליקה, נקודת הקצה הזו של הכתיבה מפנה אוטומטית את החיבורים הנכנסים למופע הראשי החדש. אפשר להשתמש בנקודת הקצה לכתיבה במחרוזת חיבור SQL למופע Cloud SQL במקום להשתמש בכתובת IP. שימוש בנקודת קצה לכתיבה מאפשר לכם להימנע משינויים בחיבור האפליקציה כשאתם מבצעים גיבוי אוטומטי של רפליקה או פעולת מעבר לגיבוי אוטומטי לצורך שחזור לאחר הפסקת חשמל באזור או תרגיל שחזור לאחר אסון.

לכל מופע שעומד בדרישות ב-Cloud SQL יש נקודת קצה מובנית אחת לכתיבה, שהשם, היצירה והעדכון שלה מנוהלים על ידי Cloud SQL. הדוגמה הבאה ממחישה את הפורמט:

  primary.103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.

נקודת הקצה לכתיבה תמיד מסתיימת בסיומת .global.sql-psa.goog.. אי אפשר לשנות את השם או הפורמט של נקודת הקצה הזו לכתיבה שמנוהלת על ידי Cloud SQL.

אפשר להשתמש בנקודת הקצה לכתיבה לכל פעולות הכתיבה במופע הראשי, כולל הוספות, עדכונים, מחיקות ושינויים ב-DDL. אפשר להשתמש בנקודת הקצה של הכתיבה גם לפעולות קריאה, כמו שאילתות. כתובת ה-IP הפרטית שאליה מצביעה נקודת הקצה לכתיבה משתנה באופן אוטומטי על ידי Cloud SQL כשמבצעים יתירות כשל של רפליקה או פעולת מעבר כדי להעלות מופע רפליקה לדרגת המופע הראשי החדש.

יצירת נקודת הקצה לכתיבה

אם יוצרים מכונה חדשה של Cloud SQL, ‏ Cloud SQL יוצר באופן אוטומטי את נקודת הקצה לכתיבה כשמתקיימים התנאים המוקדמים הבאים:

  • צריך להפעיל את ממשקי ה-API הבאים ב Google Cloud פרויקט שבו נמצאת מכונת Cloud SQL:

    אם לא מפעילים את Cloud DNS API בפרויקט, אי אפשר ליצור את תחום ה-DNS של ה-peering, ולכן אי אפשר להשתמש בשמות ה-DNS.

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

  • המכונה של Cloud SQL צריכה להיות מהדורות Cloud SQL Enterprise Plus.
  • צריך להגדיר את מכונת Cloud SQL לשימוש בכתובת IP פרטית עם גישה לשירותים פרטיים (PSA).
  • כדי להשתמש בתכונה הזו, צריך להשתמש במופעים בארכיטקטורת הרשת החדשה. ברוב המקרים, מופעים חדשים נוצרים עם הארכיטקטורה החדשה. כדי לוודא זאת, צריך לבדוק את ארכיטקטורת הרשת של המופע.

כשמשדרגים מכונה קיימת במהדורת Cloud SQL Enterprise למכונה במהדורת Cloud SQL Enterprise Plus, מערכת Cloud SQL יוצרת אוטומטית את נקודת הקצה לכתיבה אם מתקיימות הדרישות המוקדמות שצוינו קודם. אם המכונה הקיימת שלכם נמצאת בארכיטקטורת הרשת הישנה, אתם צריכים קודם לשדרג את המכונה לארכיטקטורת הרשת החדשה כדי לקבל את נקודת הקצה לכתיבה.

אם כבר יש לכם מופע של Cloud SQL Enterprise Plus ללא נקודת קצה לכתיבה ואתם רוצים ש-Cloud SQL ייצור נקודת קצה לכתיבה באופן אוטומטי, אתם צריכים ליצור רפליקה שמופעלת בה אפשרות מתקדמת לשחזור מאסון.

הצגת נקודת הקצה לכתיבה

gcloud

כדי למצוא את נקודת הקצה של הכתיבה, משתמשים בפקודה הבאה ב-CLI של gcloud:

      gcloud sql instances describe INSTANCE_NAME \
      | grep writeEndpoint

מחליפים את הפרטים הבאים:

‫INSTANCE_NAME: השם של מכונת Cloud SQL.

נקודות קצה של כתיבה תמיד מסתיימות בסיומת .global.sql-psa.goog., כמו בדוגמה הבאה:

  primary.103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.

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

התחברות למכונה של Cloud SQL באמצעות נקודת קצה לכתיבה

sqlcmd

כדי לחבר לקוח sqlcmd למכונת Cloud SQL באמצעות נקודת הקצה לכתיבה, מריצים את הפקודה הבאה:

    sqlcmd -S WRITE_ENDPOINT -U USERNAME -d DATABASE_NAME

מחליפים את הפרטים הבאים:

  • ‫DATABASE_NAME: שם מסד הנתונים. לדוגמה: main.
  • ‫USERNAME: שם המשתמש. לדוגמה, sqlserver.
  • ‫WRITE_ENDPOINT: שם ה-DNS או נקודת הקצה לכתיבה הערך האלפאנומרי הזה תמיד מסתיים בסיומת .global.sql-psa.goog.. לדוגמה, primary.103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..

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

כשמגדירים את שרת ה-proxy ל-Cloud SQL Auth או את אחד ממחברי השפה של Cloud SQL באמצעות שם DNS של נקודת קצה לכתיבה, המחבר של Cloud SQL בודק מעת לעת אם יש פעולת העברה או מעבר לגיבוי בשל כשל. כשמחבר Cloud SQL מזהה ששם ה-DNS של נקודת הקצה לכתיבה מתייחס למכונה אחרת, הוא סוגר את כל החיבורים הפתוחים למכונה הישנה. ניסיונות חיבור עתידיים יופנו למופע החדש.

לדוגמה, נניח שאפליקציה מוגדרת להתחבר באמצעות שם ה-DNS של נקודת הקצה לכתיבה primary.103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog. בתחילה, תחום ה-DNS מוגדר עם רשומה שמפנה למופע הראשי, my-project:region:instance-a. האפליקציה יוצרת חיבורים למופע my-project:region:instance-a Cloud SQL.

כשמתרחש מעבר לגיבוי או מעבר פעיל, Cloud SQL מעדכן את רשומת ה-DNS מ-my-project:region:instance-a למופע השכפול של DR שמוגדר: my-project:other-region:instance-b.

מחבר Cloud SQL שבו האפליקציה משתמשת מזהה את השינוי ברשומת ה-DNS הזו. כשהאפליקציה מתחברת למסד הנתונים שלה באמצעות שם ה-DNS של נקודת הקצה לכתיבה primary.103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog, היא מתחברת למכונה של my-project:other-region:instance-bCloud SQL.

המחבר או שרת ה-Auth Proxy סוגרים אוטומטית את כל החיבורים הקיימים אל my-project:region:instance-a. הפעולה הזו מאלצת את כל מאגרי החיבורים שבהם נעשה שימוש באפליקציה ליצור חיבורים חדשים. היא גם עלולה לגרום לכשל בשאילתות של מסד נתונים שנמצאות בתהליך.

שרת ה-proxy ל-Cloud SQL Auth מבצע סקר כדי לבדוק אם יש שינויים בשם ה-DNS כל 30 שניות.

עדכון הגדרת הרשת של המכונה

אם המופע שלכם נוצר לפני 30 ביוני 2026, יכול להיות שתצטרכו לעדכן את הגדרות הרשת של המופע כדי שתוכלו להשתמש בנקודת הקצה לכתיבה באמצעות מחברי השפה של Cloud SQL או שרת ה-proxy של Cloud SQL Auth. צריך להריץ את משימת העדכון הזו רק פעם אחת לכל מופע. מריצים את הפקודה הבאה:

‫ה-CLI של gcloud

  # Update the primary instance DNS settings
  gcloud sql instances patch "PRIMARY_NAME" \
      --reconcile-psa-networking

מחליפים את הפרטים הבאים:

  • ‫PRIMARY_NAME: השם של המכונה. לדוגמה, my-instance.

חיבור של לקוחות מסד נתונים למכונות באמצעות שרת proxy ל-Cloud SQL Auth

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

sqlcmd

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT --private-ip

לאחר מכן מגדירים את לקוח מסד הנתונים להתחבר לשרת ה-proxy ל-Cloud SQL Auth:

  sqlcmd
    -S 127.0.0.1, PORT -U USERNAME \
    -d DATABASE_NAME

מחליפים את הפרטים הבאים:

  • ‫WRITE_ENDPOINT: שם ה-DNS או נקודת הקצה לכתיבה הערך האלפאנומרי הזה תמיד מסתיים בסיומת .global.sql-psa.goog.. לדוגמה, primary.103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
  • ‫PORT: מספר היציאה שנעשה בו שימוש. לדוגמה, 1433.
  • ‫USERNAME: שם המשתמש. לדוגמה, sqlserver-user.
  • ‫DATABASE_NAME: שם מסד הנתונים. לדוגמה: sqlserver-database.

חיבור באמצעות מחברי שפה של Cloud SQL

כדי להתחבר באמצעות אחד מ-Cloud SQL Language Connectors, צריך להגדיר את האפליקציה לפי ההוראות במאמר חיבור באמצעות Cloud SQL Language Connectors. לאחר מכן, משנים את חיבור מסד הנתונים כך שישתמש בנקודת הקצה של הכתיבה במקום בשם ה-DNS של המופע.

Java

  String jdbcUrl = "jdbc:sqlserver://WRITE_ENDPOINT:1433;"
  "databaseName=DATABASE_NAME;"
    +   "socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;"
    +   "socketFactoryConstructorArg=WRITE_ENDPOINT?ipTypes=PRIVATE;"
    +   "user=USERNAME;"
    +   "password=PASSWORD;"

מחליפים את הפרטים הבאים:

  • ‫WRITE_ENDPOINT: שם ה-DNS או נקודת הקצה לכתיבה הערך האלפאנומרי הזה תמיד מסתיים בסיומת .global.sql-psa.goog..
  • ‫DATABASE_NAME: שם מסד הנתונים. לדוגמה, my-database.
  • ‫USERNAME: שם המשתמש. לדוגמה, sqlserver-user.
  • ‫PASSWORD: סיסמת מסד הנתונים.
מידע נוסף זמין במאמרי העזרה של Java Connector ב-GitHub.

המשך

  db, err := sql.Open(
      "cloudsql-sqlserver",
      "sqlserver://USERNAME:PASSWORD@WRITE_ENDPOINT?database=DATABASE_NAME&encrypt=disable",
  )

מחליפים את הפרטים הבאים:

  • ‫WRITE_ENDPOINT: שם ה-DNS או נקודת הקצה לכתיבה הערך האלפאנומרי הזה תמיד מסתיים בסיומת .global.sql-psa.goog..
  • ‫DATABASE_NAME: שם מסד הנתונים. לדוגמה, my-database.
  • ‫USERNAME: שם המשתמש. לדוגמה, sqlserver-user.
  • ‫PASSWORD: סיסמת מסד הנתונים.
מידע נוסף זמין במאמרי העזרה של מחבר Go ב-GitHub.

Python

  Connector = Connector(resolver=DnsResolver)
  engine = sqlalchemy.create_engine(
      "mssql+pytds://",
      creator=lambda: connector.connect(
          "WRITE_ENDPOINT",  # using DNS name
          "pytds",
          user="USERNAME",
          password="PASSWORD",
          db="DATABASE_NAME"
      ),
  )

מחליפים את הפרטים הבאים:

  • ‫WRITE_ENDPOINT: שם ה-DNS או נקודת הקצה לכתיבה הערך האלפאנומרי הזה תמיד מסתיים בסיומת .global.sql-psa.goog..
  • ‫DATABASE_NAME: שם מסד הנתונים. לדוגמה, my-database.
  • ‫USERNAME: שם המשתמש. לדוגמה, sqlserver-user.
  • ‫PASSWORD: סיסמת מסד הנתונים.
מידע נוסף זמין במאמרי העזרה של Python Connector ב-GitHub.

Node.js

  import sql from 'mssql';
  import {Connector} from '@google-cloud/cloud-sql-connector';

  const connector = new Connector();
  const clientOpts = await connector.getTediousOptions({
    domainName: 'WRITE_ENDPOINT',
    ipType: 'PRIVATE',
  });
  const pool = new sql.ConnectionPool({
    ...clientOpts,
    user: 'USERNAME',
    password: 'PASSWORD',
    database: 'DATABASE_NAME',
    pool: {
      max: 5,
    }
  });
  Await pool.connect();

מחליפים את הפרטים הבאים:

  • ‫WRITE_ENDPOINT: שם ה-DNS או נקודת הקצה לכתיבה הערך האלפאנומרי הזה תמיד מסתיים בסיומת .global.sql-psa.goog..
  • ‫DATABASE_NAME: שם מסד הנתונים. לדוגמה, my-database.
  • ‫USERNAME: שם המשתמש. לדוגמה, sqlserver-user.
  • ‫PASSWORD: סיסמת מסד הנתונים.
מידע נוסף זמין במאמרי העזרה בנושא מחבר Node.js ב-GitHub.

מגבלות

  • נקודות קצה לכתיבה לא זמינות ליצירת מופעים במהדורת Cloud SQL Enterprise.
  • נקודות קצה לכתיבה לא זמינות במקרים הבאים: מכונות וירטואליות עם כתובת IP ציבורית בלבד או מכונות וירטואליות עם Private Service Connect בלבד.

פתרון בעיות

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

ארכיטקטורה של נקודת קצה לכתיבה

כשיוצרים מופע שעומד בדרישות, נוצרת כברירת מחדל נקודת קצה לכתיבה.

כדי ליצור נקודת קצה לכתיבה, Cloud SQL מבצע את ההגדרה הבאה:

  • יצירה של אזור DNS פרטי ברשת ה-VPC של ספק שירות Cloud SQL
  • יוצר תחום DNS של peering ברשת ה-VPC של הלקוח
  • יצירת רשומת DNS באזור DNS פרטי ברשת של בעלי השירות

התרשים הבא ממחיש איך התהליך הזה עובד:

דיאגרמה שמראה איך קישור בין רשתות שכנות (peering) של VPC תומך בקישור בין רשתות שכנות (peering) של תחום DNS בין פרויקטים.
איור 1. תרשים שמראה איך קישור בין רשתות VPC שכנות (peering) תומך בקישור בין אזורי DNS בין רשת של ספק שירות לרשת של לקוח.

בעיות בפענוח DNS

אם פתרון ה-DNS לא פועל, כדאי לבדוק כל אחד מהפריטים הבאים:

  1. חשוב לוודא שכל הדרישות המוקדמות מתקיימות.
  2. מוודאים שהלקוחות שבהם אמורה להתבצע ההחלטה נמצאים באותה רשת שאליה מצורפת מכונת Cloud SQL. כדי לבדוק את זה, משתמשים בפקודה gcloud compute instances list: 
    gcloud compute instances list \
   --format="table( name, zone.basename(), networkInterfaces[].network )" \
   --project=PROJECT_NAME

    מחליפים את PROJECT_NAME בשם הפרויקט שבו נמצאת רשת צרכני ה-DNS.

  3. מוודאים שאזור הפירינג קיים. כדי לעשות זאת, משתמשים בפקודה gcloud dns managed-zones list: 
    gcloud dns managed-zones list \
    --project=PROJECT_NAME

    מחליפים את PROJECT_NAME בשם הפרויקט שבו נמצאת רשת צרכני ה-DNS.

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

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

  1. חשוב לוודא שכל הדרישות המוקדמות מולאו.
  2. מוודאים שאין תחום DNS של שותפות פעילה עם שם ה-DNS sql-psa.goog..

    תחום DNS מקושר הוא תחום DNS שנשאר אם לרשת שמשויכת לתחום ה-DNS אין קישור בין רשתות VPC עם מזהה פרויקט עמית של תחום ה-DNS המקושר.

    אם נשאר אזור DNS של שירותי Peering עם הסיומת sql-psa.goog., צריך למחוק אותו.

    כדי לבדוק אם נשארו אזורי DNS של שירותי Peering, משתמשים בפקודה gcloud dns managed-zones list:

    gcloud dns managed-zones list \
   --project=PROJECT_NAME

    מחליפים את PROJECT_NAME בשם הפרויקט שבו נמצאת רשת הצרכן של ה-DNS.

    אם קיים תחום DNS עם הסיומת sql-psa.goog., צריך למחוק את תחום ה-DNS אחרי שמוודאים שתחום ה-DNS של הקישור בין רשתות שכנות (peering) הוא תחום DNS שנותר.

    כדי למחוק תחום DNS, משתמשים בפקודה gcloud dns managed-zones delete:

    gcloud dns managed-zones delete ZONE_NAME

    מחליפים את ZONE_NAME בשם תחום ה-DNS שמשויך לנקודות הקצה של הכתיבה. הערכים הם אלפאנומריים ומופיעים בפורמט הבא: cloud-sql-psa-dns-1234567890.

  3. כדי לתקן נקודת קצה חסרה לכתיבה במכונה שעומדת בדרישות, משתמשים בפקודה gcloud beta sql instances patch: 
    gcloud beta sql instances patch INSTANCE_NAME --reconcile-psa-networking

    מחליפים את INSTANCE_NAME בשם של מופע Cloud SQL.

המאמרים הבאים