Verbindung zu einer Instanz über einen Schreibendpunkt herstellen

Übersicht

Auf dieser Seite wird beschrieben, wie Sie einen Schreibendpunkt verwenden, um Clients in Ihrem VPC-Netzwerk (Virtual Private Cloud) über den Zugriff auf private Dienste (PSA) mit einer Cloud SQL-Instanz zu verbinden.

Ein Schreibendpunkt ist ein globaler Domainname-Service (DNS)-Name, der automatisch in die IP-Adresse der aktuellen primären Instanz aufgelöst wird. Im Falle eines Failovers oder Switchovers des Replikats leitet dieser Schreibendpunkt eingehende Verbindungen automatisch an die neue primäre Instanz weiter. Sie können den Schreibendpunkt in einem SQL-Verbindungsstring zur Cloud SQL-Instanz verwenden, anstatt eine IP-Adresse zu verwenden. Wenn Sie einen Schreibendpunkt verwenden, müssen Sie keine Änderungen an der Anwendungsverbindung vornehmen, wenn Sie einen Replikat-Failover- oder Switchover-Vorgang zur Wiederherstellung nach einem regionalen Ausfall oder für eine Notfallwiederherstellungsübung durchführen.

Jede berechtigte Cloud SQL-Instanz hat einen einzelnen 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 Endpunkt für Schreibvorgänge 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 auf 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 Replikat-Failover- oder ‑Switchover-Vorgang ausführen, um eine Replikatinstanz zur neuen primären Instanz hochzustufen.

Endpunkt für Schreibvorgänge generieren

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

• Die folgenden APIs müssen im Cloud de Confiance -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 Peering-DNS-Zone nicht erstellt werden, wodurch die DNS-Namen unbrauchbar werden.

  Nachdem die Peering-DNS-Zone erstellt wurde, darf sie nicht mehr geändert werden. Alle Änderungen, einschließlich Löschen, machen das DNS für die Datenbankverbindung unbrauchbar.

• Die Cloud SQL-Instanz muss die Cloud SQL Enterprise Plus-Version sein.
• Die Cloud SQL-Instanz muss so konfiguriert sein, dass sie eine private IP-Adresse mit aktiviertem Zugriff auf private Dienste (PSA) verwendet.
• 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 automatisch den Schreibendpunkt, wenn die zuvor aufgeführten Voraussetzungen erfüllt sind. Wenn sich Ihre vorhandene Instanz in der alten Netzwerkarchitektur befindet, müssen Sie zuerst ein Upgrade der Instanz auf die neue Netzwerkarchitektur durchführen, um den Schreibendpunkt zu erhalten.

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

Endpunkt für Schreibvorgänge ansehen

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

Schreibendpunkte enden immer mit dem Suffix .global.sql-psa.goog., ähnlich 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 dem Schreibendpunkt 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, ob ein Wechsel oder ein Failover stattfindet. Wenn der Cloud SQL-Connector erkennt, dass der DNS-Name des Schreibendpunkts auf eine andere Instanz verweist, werden alle offenen Verbindungen zur alten Instanz geschlossen. 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. Anfänglich ist die DNS-Zone mit einem Eintrag konfiguriert, der auf die primäre Instanz my-project:region:instance-a verweist. 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 designierte 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 zu ihrer Datenbank herstellt, wird sie mit der Cloud SQL-Instanz my-project:other-region:instance-b verbunden.

Der Connector oder Auth-Proxy schließt automatisch alle vorhandenen Verbindungen zu my-project:region:instance-a. Dadurch werden alle von der Anwendung verwendeten Verbindungspools gezwungen, neue Verbindungen herzustellen. Außerdem können laufende Datenbankabfragen fehlschlagen.

Der Cloud SQL Auth-Proxy fragt alle 30 Sekunden nach Änderungen am DNS-Namen.

Netzwerkkonfiguration der Instanz aktualisieren

Wenn Ihre Instanz vor dem 8. August 2025 erstellt wurde, müssen Sie möglicherweise die Netzwerkkonfiguration der Instanz für Cloud SQL Language Connectors oder den Cloud SQL Auth-Proxy aktualisieren, um den Schreibendpunkt verwenden zu 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 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, starten Sie zuerst den Proxy mit dem Schreibendpunkt anstelle des Instanzverbindungsnamens.

  $ 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 zum Herstellen einer Verbindung über 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 für Cloud SQL Enterprise-Instanzen nicht verfügbar.
• Schreibendpunkte sind nicht für Instanzen mit nur öffentlichen IP-Adressen oder Instanzen mit nur Private Service Connect verfügbar.

Fehlerbehebung

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

Architektur eines Endpunkts für Schreibvorgänge

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

Zum Erstellen eines Schreibendpunkts führt Cloud SQL die folgende Einrichtung durch:

• Erstellt eine private DNS-Zone im VPC-Netzwerk des Cloud SQL-Diensterstellers.
• Erstellt eine Peering-DNS-Zone im VPC-Netzwerk des Kunden.
• Erstellt einen DNS-Eintrag in der privaten DNS-Zone im Diensterstellernetzwerk.

Das folgende Diagramm veranschaulicht diesen Prozess:

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 dazu den Befehl gcloud compute instances list:

   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-Nutzernetzwerk 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-Nutzernetzwerk befindet.

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

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

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

Neue Instanz hat keinen Schreibendpunkt

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

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

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

   Wenn eine verbleibende 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 Peering-DNS-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-Nutzernetzwerk befindet.

   Wenn eine DNS-Zone mit dem Suffix sql-psa.goog. vorhanden ist, löschen Sie die DNS-Zone, nachdem Sie geprüft haben, ob die Peering-DNS-Zone eine übrig gebliebene DNS-Zone ist.

   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 infrage kommende Instanz mit dem Befehl gcloud sql instances patch beheben:

   gcloud 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 in Cloud SQL