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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

  אחרי שיוצרים בהצלחה את תחום ה-DNS של הקישור בין רשתות שכנות (peering), חשוב לא לשנות אותו בשום צורה. כל שינוי, כולל מחיקה, יגרום לכך שלא יהיה אפשר להשתמש ב-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 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
  

חיבור של לקוחות מסד נתונים למכונות של מסד נתונים באמצעות נקודת קצה לכתיבה דרך חיבור 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
  

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

כשמגדירים את שרת ה-proxy ל-Cloud SQL Auth או אחד מהמחברים של Cloud SQL Language באמצעות שם 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 למופע רפליקת DR שמוגדר:my-project:other-region:instance-b.

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

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

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

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

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

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

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

כדי להתחבר למכונה של Cloud SQL באמצעות נקודת הקצה לכתיבה ובאמצעות שרת proxy ל-Cloud SQL Auth, קודם צריך להפעיל את ה-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.
• נקודות קצה לכתיבה לא זמינות במקרים הבאים: מכונות וירטואליות עם כתובת IP ציבורית בלבד או מכונות וירטואליות עם Private Service Connect בלבד.

פתרון בעיות

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

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

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

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

• יוצר תחום DNS פרטי ברשת ה-VPC של ספק שירות Cloud SQL
• יוצר תחום DNS של קישור בין רשתות שכנות (peering) ברשת ה-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. אם אזור הקישור בין רשתות שכנות (peering) לא קיים, אפשר לפתור את הבעיה באמצעות הפקודה gcloud beta sql instances patch:

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

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

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

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

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

   תחום DNS מקושר הוא תחום DNS שנשאר אם לרשת שמשויכת לתחום ה-DNS אין קישור בין רשתות שכנות (peering) עם מזהה פרויקט עמית של תחום ה-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 של הפירינג הוא תחום 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.

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

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