Verbindung zu einer Instanz über einen Schreibendpunkt herstellen

Übersicht

Auf dieser Seite wird beschrieben, wie Sie einen Schreibendpunkt verwenden, um von Clients in Ihrem VPC-Netzwerk (Virtual Private Cloud) aus über Zugriff auf private Dienste (Private Services Access, PSA) eine Verbindung zu einer Cloud SQL-Instanz herzustellen.

Ein Schreibendpunkt ist ein globaler DNS-Name (Domain Name Service), der automatisch in die IP-Adresse der aktuellen primären Instanz aufgelöst wird. Im Falle eines Failover oder Switchover eines Replikats leitet dieser Schreibendpunkt eingehende Verbindungen automatisch zur neuen primären Instanz um. Sie können den Schreibendpunkt in einem SQL-Verbindungsstring zur Cloud SQL-Instanz verwenden, anstatt eine IP-Adresse anzugeben. Wenn Sie einen Schreibendpunkt verwenden, müssen Sie keine Änderungen an den Anwendungsverbindungen vornehmen, wenn Sie einen Replikat-Failover- oder Switchover-Vorgang zur Wiederherstellung nach einem regionalen Ausfall oder zur Notfallwiederherstellung durchführen.

Jede infrage kommende Cloud SQL-Instanz hat einen integrierten Schreibendpunkt, dessen Name, Erstellung und Aktualisierung von Cloud SQL verwaltet werden. Das folgende Beispiel veranschaulicht das Format:

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

Der Schreibendpunkt endet immer mit dem Suffix .global.sql-psa.goog.. Sie können den Namen oder das Format dieses von Cloud SQL verwalteten Schreibendpunkts nicht ändern.

Sie können den Schreibendpunkt für alle Schreibvorgänge in der primären Instanz verwenden, einschließlich Einfügungen, Aktualisierungen, Löschungen und DDL-Änderungen. Sie können den Schreibendpunkt auch für Lesevorgänge wie Abfragen verwenden. Die private IP-Adresse, auf die der Schreibendpunkt verweist, wird von Cloud SQL automatisch geändert, wenn Sie einen Failover- oder Switchover-Vorgang für ein Replikat durchführen, um es zur neuen primären Instanz zu machen.

Schreibendpunkt generieren

Wenn Sie eine neue Cloud SQL-Instanz erstellen, wird der Schreibendpunkt automatisch von Cloud SQL erstellt, wenn die folgenden Voraussetzungen erfüllt sind:

• Die folgenden APIs müssen im Trusted Cloud Projekt, in dem sich Ihre Cloud SQL-Instanz befindet, aktiviert sein:
  • Compute Engine API
  • Cloud DNS API

  Wenn die Cloud DNS API im Projekt nicht aktiviert wird, kann die DNS-Peering-Zone nicht erstellt werden, wodurch die DNS-Namen unbrauchbar werden.

  Nachdem die DNS-Zone für das Peering erfolgreich erstellt wurde, darf sie nicht mehr geändert werden. Alle Änderungen, einschließlich Löschungen, führen dazu, dass der DNS für die Datenbankverbindung nicht mehr verwendet werden kann.

• Die Cloud SQL-Instanz muss die Cloud SQL Enterprise Plus-Version sein.
• Die Cloud SQL-Instanz muss für die Verwendung einer privaten IP-Adresse mit aktiviertem Zugriff auf private Dienste (Private Service Access, PSA) konfiguriert sein.
• Für die Funktion sind Instanzen in der neuen Netzwerkarchitektur erforderlich. In den meisten Fällen werden neue Instanzen mit der neuen Architektur erstellt. Prüfen Sie die Netzwerkarchitektur Ihrer Instanz, um dies zu bestätigen.

Wenn Sie ein Upgrade einer vorhandenen Cloud SQL Enterprise-Instanz auf eine Cloud SQL Enterprise Plus-Instanz ausführen, generiert Cloud SQL den Schreibendpunkt automatisch, sofern die oben aufgeführten Voraussetzungen erfüllt sind. Wenn sich Ihre vorhandene Instanz in der alten Netzwerkarchitektur befindet, müssen Sie sie zuerst auf die neue Netzwerkarchitektur umstellen, um den Schreibendpunkt zu erhalten.

Wenn Sie bereits eine Cloud SQL Enterprise Plus-Instanz ohne Schreibendpunkt haben und Cloud SQL automatisch einen Schreibendpunkt generieren soll, erstellen Sie ein Replikat, das für die erweiterte Notfallwiederherstellung aktiviert ist.

Schreibendpunkt ansehen

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

Schreibendpunkte enden immer mit dem Suffix .global.sql-psa.goog., wie im folgenden Beispiel:

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

Wenn Sie den Schreibendpunkt für eine berechtigte Instanz nicht sehen, lesen Sie den Abschnitt Fehlerbehebung.

Verbindung zu einer Cloud SQL-Instanz über einen Schreibendpunkt herstellen

    mysql -u root -h WRITE_ENDPOINT -p
  

Datenbankclients über eine SSL/TLS-Verbindung mit Datenbankinstanzen verbinden

  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
  

Datenbankclients über den Cloud SQL Auth-Proxy oder Cloud SQL Language Connectors mit Instanzen verbinden

Wenn Sie den Cloud SQL Auth-Proxy oder einen der Cloud SQL Language Connectors mit einem DNS-Namen für den Schreibendpunkt konfigurieren, prüft der Cloud SQL-Connector regelmäßig auf einen Switchover- oder Failover-Vorgang. Wenn der Cloud SQL-Connector erkennt, dass sich der DNS-Name des Schreibendpunkts auf eine andere Instanz bezieht, schließt er alle offenen Verbindungen zur alten Instanz. Nachfolgende Verbindungsversuche werden an die neue Instanz weitergeleitet.

Angenommen, eine Anwendung ist so konfiguriert, dass sie eine Verbindung über den DNS-Namen des Schreibendpunkts 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog herstellt. Anfangs wird die DNS-Zone mit einem Eintrag konfiguriert, der auf die primäre Instanz verweist: my-project:region:instance-a. Die Anwendung stellt Verbindungen zur Cloud SQL-Instanz my-project:region:instance-a her.

Wenn der Failover oder Switchover erfolgt, aktualisiert Cloud SQL den DNS-Eintrag von my-project:region:instance-a auf die angegebene DR-Replikatinstanz: my-project:other-region:instance-b.

Der von der Anwendung verwendete Cloud SQL-Connector erkennt die Änderung an diesem DNS-Eintrag. Wenn die Anwendung über den DNS-Namen des Schreibendpunkts 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog eine Verbindung zur Datenbank herstellt, wird eine Verbindung zur Cloud SQL-Instanz my-project:other-region:instance-b hergestellt.

Der Connector oder Auth-Proxy schließt automatisch alle bestehenden Verbindungen zu my-project:region:instance-a. Dadurch werden alle von der Anwendung verwendeten Verbindungspools gezwungen, neue Verbindungen herzustellen. Außerdem kann es dazu führen, dass laufende Datenbankabfragen fehlschlagen.

Der Cloud SQL Auth-Proxy ruft alle 30 Sekunden Änderungen am DNS-Namen ab.

Netzwerkkonfiguration der Instanz aktualisieren

Wenn Ihre Instanz vor dem 8. August 2025 erstellt wurde, müssen Sie möglicherweise die Netzwerkkonfiguration der Instanz aktualisieren, damit Sie den Schreibendpunkt für Cloud SQL Language Connectors oder den Cloud SQL Auth-Proxy verwenden können. Sie müssen diese Aktualisierungsaufgabe nur einmal für jede Instanz ausführen. Führen Sie dazu diesen Befehl aus:

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

Datenbankclients über den Cloud SQL Auth-Proxy mit Instanzen verbinden

Wenn Sie über den Schreibendpunkt und den Cloud SQL Auth-Proxy eine Verbindung zu einer Cloud SQL-Instanz herstellen möchten, müssen Sie den Proxy zuerst mit dem Schreibendpunkt anstelle des Namens der Instanzverbindung starten.

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT
  

  mysql -uUSERNAME -h 127.0.0.1 -p PORT DATABASE_NAME
  

Verbindung über Cloud SQL Language Connectors herstellen

Wenn Sie eine Verbindung über einen der Cloud SQL Language Connectors herstellen möchten, konfigurieren Sie Ihre Anwendung gemäß der Anleitung in der Dokumentation zu Cloud SQL Language Connectors. Ändern Sie dann Ihre Datenbankverbindung so, dass der Schreibendpunkt anstelle des DNS-Namens der Instanz verwendet wird.

  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',
  });
  

Beschränkungen

• Schreibendpunkte sind nicht für die Erstellung von Cloud SQL Enterprise-Instanzen verfügbar.
• Schreibendpunkte sind nicht für Instanzen mit nur öffentlichen IP-Adressen oder nur Private Service Connect-Instanzen verfügbar.

Fehlerbehebung

In den folgenden Abschnitten wird die Architektur von Schreibendpunkten beschrieben und auf häufige Probleme bei der Fehlerbehebung eingegangen.

Architektur eines Schreibendpunkts

Wenn Sie eine berechtigte Instanz erstellen, wird standardmäßig ein Schreibendpunkt generiert.

Zum Erstellen eines Schreibendpunkts führt Cloud SQL die folgenden Einrichtungsschritte aus:

• Erstellt eine private DNS-Zone im VPC-Netzwerk des Cloud SQL-Diensterstellers.
• Erstellt eine DNS-Zone für das Peering im VPC-Netzwerk des Kunden.
• Erstellt einen DNS-Eintrag in der privaten DNS-Zone im Netzwerk des Dienstanbieters

Das folgende Diagramm veranschaulicht diesen Vorgang:

Probleme mit der DNS-Auflösung

Wenn die DNS-Auflösung nicht funktioniert, prüfen Sie die folgenden Punkte:

1. Prüfen Sie, ob alle Voraussetzungen erfüllt sind.
2. Achten Sie darauf, dass sich die Clients, auf denen die Auflösung erwartet wird, im selben Netzwerk befinden, mit dem die Cloud SQL-Instanz verbunden ist. Verwenden Sie den Befehl gcloud compute instances list, um dies zu prüfen:

   gcloud compute instances list \
      --format="table( name, zone.basename(), networkInterfaces[].network )" \
      --project=PROJECT_NAME

   Ersetzen Sie PROJECT_NAME durch den Namen des Projekts, in dem sich das DNS-Nutzerprojekt befindet.

3. Prüfen Sie, ob die Peering-Zone vorhanden ist. Verwenden Sie dazu den Befehl gcloud dns managed-zones list:

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

   Ersetzen Sie PROJECT_NAME durch den Namen des Projekts, in dem sich das DNS-Nutzer-Netzwerk befindet.

4. Wenn die Peering-Zone nicht vorhanden ist, können Sie das Problem mit dem Befehl gcloud beta sql instances patch beheben:

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

   Ersetzen Sie INSTANCE_NAME durch den Namen Ihrer Cloud SQL-Instanz.

Die neue Instanz hat keinen Schreibendpunkt.

Wenn eine neu erstellte Instanz keinen Schreibendpunkt enthält, prüfen Sie die folgenden Punkte:

1. Prüfen Sie, ob alle Voraussetzungen erfüllt sind.
2. Achten Sie darauf, dass keine DNS-Peering-Zone mit dem DNS-Namen sql-psa.goog. übrig geblieben ist.

   Eine DNS-Peering-Zone ist eine verbleibende DNS-Zone, wenn das der DNS-Zone zugeordnete Netzwerk kein VPC-Peering mit der Peer-Projekt-ID der DNS-Peering-Zone hat.

   Wenn eine übrig gebliebene Peering-DNS-Zone mit dem Suffix sql-psa.goog. vorhanden ist, löschen Sie sie.

   Verwenden Sie den Befehl gcloud dns managed-zones list, um nach verbleibenden DNS-Peering-Zonen zu suchen:

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

   Ersetzen Sie PROJECT_NAME durch den Namen des Projekts, in dem sich das DNS-Nutzerprojekt befindet.

   Wenn eine DNS-Zone mit dem Suffix sql-psa.goog. vorhanden ist, löschen Sie die DNS-Zone, nachdem Sie noch einmal überprüft haben, ob es sich bei der Peering-DNS-Zone um eine übrig gebliebene DNS-Zone handelt.

   Verwenden Sie zum Löschen einer DNS-Zone den Befehl gcloud dns managed-zones delete:

   gcloud dns managed-zones delete ZONE_NAME

   Ersetzen Sie ZONE_NAME durch den DNS-Zonennamen, der den Schreibendpunkten zugeordnet ist. Die Werte sind alphanumerisch und haben das folgende Format: cloud-sql-psa-dns-1234567890.

3. Sie können einen fehlenden Schreibendpunkt für eine berechtigte Instanz mit dem Befehl gcloud beta sql instances patch beheben:

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

   Ersetzen Sie INSTANCE_NAME durch den Namen Ihrer Cloud SQL-Instanz.

Nächste Schritte

• Weitere Informationen zur Fehlerbehebung bei Cloud SQL