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

סקירה כללית

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

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

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

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

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

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

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

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

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

  אם לא תפעילו את Cloud DNS API בפרויקט, לא תוכלו ליצור את תחום ה-DNS המקושר, ולא תוכלו להשתמש בשמות ה-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 ייצור נקודת קצה לכתיבה באופן אוטומטי, אתם צריכים ליצור רפליקה שמופעלת בה תוכנית התאוששות מתקדמת מאסון (DR).

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

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

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

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

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

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

    mysql -u root -h WRITE_ENDPOINT -p
  

חיבור לקוחות של מסד נתונים למכונות של מסד נתונים באמצעות נקודת קצה (endpoint) לכתיבה דרך חיבור SSL/TLS

  mysql -uroot -pcloudsql -h 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog. \
    --ssl-ca=SERVER_CA_SSL \
    --ssl-cert=SSL_CERT \
    --ssl-key=SSL_KEY \
    --ssl-verify-server-cert
  

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

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

לדוגמה, נניח שאפליקציה מוגדרת להתחבר באמצעות שם ה-DNS של נקודת הקצה לכתיבה: 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 למכונה הייעודית של הרפליקה להתאוששות מאסון: my-project:other-region:instance-b.

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

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

‫Cloud SQL Auth Proxy דוגם שינויים בשם ה-DNS כל 30 שניות.

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

אם המכונה נוצרה לפני 8 באוגוסט 2025, יכול להיות שתצטרכו לעדכן את הגדרות הרשת של המכונה כדי שמחברי השפה של Cloud SQL או Cloud SQL Auth Proxy יוכלו להשתמש בנקודת הקצה לכתיבה. צריך להריץ את משימת העדכון הזו רק פעם אחת לכל מכונה. מריצים את הפקודה הבאה:

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

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

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

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT
  

  mysql -uUSERNAME -h 127.0.0.1 -p PORT DATABASE_NAME
  

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

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

  String jdbcUrl = "jdbc:mysql://WRITE_ENDPOINT/DATABASE_NAME?"
    +   "&socketFactory=com.google.cloud.sql.mysql.SocketFactory"
    +   "&user=USERNAME"
    +   "&password=PASSWORD";
  

    db, err := sql.Open(
        "cloudsql-mysql",
        "USERNAME:PASSWORD@cloudsql-mysql(WRITE_ENDPOINT)/DATABASE_NAME",
    )
  

  pool = sqlalchemy.create_engine(
      "mysql+pymysql://",
      creator=lambda: connector.connect(
          "WRITE_ENDPOINT",  # using DNS name
          "pymysql",
          user="USERNAME",
          password="PASSWORD",
          db="DATABASE_NAME"
      ),
  )
  

  import mysql from 'mysql2/promise';
  import {Connector} from '@google-cloud/cloud-sql-connector';

  const connector = new Connector();
  const clientOpts = await connector.getOptions({
    domainName: 'WRITE_ENDPOINT',
    ipType: 'PUBLIC',
  });

  const pool = await mysql.createPool({
    ...clientOpts,
    user: 'USERNAME',
    password: 'PASSWORD',
    database: 'DATABASE_NAME',
  });
  

מגבלות

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

פתרון בעיות

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

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

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

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

• יוצר תחום DNS פרטי ברשת ה-VPC של ספק השירות של Cloud SQL.
• יוצר תחום DNS מקושר ברשת ה-VPC של הלקוח.
• יצירת רשומת DNS בתחום ה-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.

4. אם תחום הקישור בין רשתות שכנות לא קיים, אפשר לפתור את הבעיה באמצעות הפקודה gcloud sql instances patch:

   gcloud sql instances patch INSTANCE_NAME --reconcile-psa-networking

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

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

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

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

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

   אם נשאר תחום DNS של קישור עם הסיומת 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 המקושר הוא תחום DNS שנותר.

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

   gcloud dns managed-zones delete ZONE_NAME

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

3. כדי לתקן נקודת קצה חסרה לכתיבה במכונה מתאימה, אפשר להשתמש בפקודה gcloud sql instances patch:

   gcloud sql instances patch INSTANCE_NAME --reconcile-psa-networking

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

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

• מידע נוסף על פתרון בעיות ב-Cloud SQL