Se connecter à une instance à l'aide d'un point de terminaison d'écriture

Présentation

Cette page explique comment utiliser un point de terminaison d'écriture pour vous connecter à une instance Cloud SQL à partir de clients de votre réseau Virtual Private Cloud (VPC) à l'aide de l' accès privé aux services.

Un point de terminaison d'écriture est un nom de service de nom de domaine (DNS) global qui pointe automatiquement vers l'adresse IP de l'instance principale actuelle. En cas d'opération de basculement d'instance répliquée ou de commutation, ce point de terminaison d'écriture redirige automatiquement les connexions entrantes vers la nouvelle instance principale. Vous pouvez utiliser le point de terminaison d'écriture dans une chaîne de connexion SQL à l'instance Cloud SQL au lieu d'une adresse IP. En utilisant un point de terminaison d'écriture, vous pouvez éviter d'avoir à modifier la connexion de l'application lorsque vous effectuez une opération de basculement d'instance répliquée ou de commutation pour la reprise après sinistre ou un exercice de reprise après sinistre.

Chaque instance Cloud SQL éligible dispose d'un point de terminaison d'écriture intégré unique dont le nom, la création et la mise à jour sont gérés par Cloud SQL. L'exemple suivant illustre son format :

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

Le point de terminaison d'écriture se termine toujours par le suffixe .global.sql-psa.goog.. Vous ne pouvez pas modifier le nom ni le format de ce point de terminaison d'écriture géré par Cloud SQL.

Vous pouvez utiliser le point de terminaison d'écriture pour toutes les opérations d'écriture sur l'instance principale, y compris les insertions, les mises à jour, les suppressions et les modifications LDD. Vous pouvez également utiliser le point de terminaison d'écriture pour les opérations de lecture, telles que les requêtes. L'adresse IP privée vers laquelle pointe le point de terminaison d'écriture est automatiquement modifiée par Cloud SQL lorsque vous effectuez une opération de basculement d'instance répliquée ou de commutation pour promouvoir une instance répliquée en tant que nouvelle instance principale.

Générer le point de terminaison d'écriture

Si vous créez une instance Cloud SQL, Cloud SQL crée automatiquement le point de terminaison d'écriture lorsque les conditions préalables suivantes sont remplies :

• Les API suivantes doivent être activées dans le Cloud de Confiance projet dans lequel réside votre instance Cloud SQL :
  • API Compute Engine
  • API Cloud DNS

  Si vous n'activez pas l'API Cloud DNS dans le projet, la zone DNS d'appairage ne pourra pas être créée, ce qui rendra les noms DNS inutilisables.

  Une fois la zone DNS d'appairage créée, il est important de ne pas la modifier. Toute modification, y compris la suppression, rendra le DNS inutilisable pour la connexion à la base de données.

• L'instance Cloud SQL doit être de l'édition Cloud SQL Enterprise Plus.
• L'instance Cloud SQL doit être configurée pour utiliser une adresse IP privée avec l'accès privé aux services activé.
• La fonctionnalité nécessite des instances sur la nouvelle architecture réseau. Dans la plupart des cas, les nouvelles instances sont créées avec la nouvelle architecture. Pour le vérifier, consultez l'architecture réseau de votre instance.

Lorsque vous mettez à niveau une instance Cloud SQL Enterprise existante vers une instance Cloud SQL Enterprise Plus, Cloud SQL génère automatiquement le point de terminaison d'écriture si les conditions préalables listées précédemment sont remplies. Si votre instance existante utilise l'ancienne architecture réseau, vous devez d'abord la mettre à niveau vers la nouvelle architecture réseau pour obtenir le point de terminaison d'écriture.

Si vous disposez déjà d'une instance Cloud SQL Enterprise Plus sans point de terminaison d'écriture et que vous souhaitez que Cloud SQL génère automatiquement un point de terminaison d'écriture, alors créez une instance répliquée qui gère la reprise après sinistre avancée.

Afficher le point de terminaison d'écriture

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

Les points de terminaison d'écriture se terminent toujours par le suffixe .global.sql-psa.goog., comme dans l'exemple suivant :

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

Si vous ne voyez pas le point de terminaison d'écriture pour une instance éligible, consultez la section Dépannage.

Se connecter à une instance Cloud SQL à l'aide d'un point de terminaison d'écriture

    mysql -u root -h WRITE_ENDPOINT -p
  

Connecter des clients de base de données à des instances de base de données à l'aide d'un point de terminaison d'écriture via une connexion 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
  

Connecter des clients de base de données à des instances à l'aide du proxy d'authentification Cloud SQL ou des connecteurs de langage Cloud SQL

Lorsque vous configurez le proxy d'authentification Cloud SQL ou l'un des connecteurs de langage Cloud SQL à l'aide d'un nom DNS de point de terminaison d'écriture, le connecteur Cloud SQL vérifie régulièrement si une opération de commutation ou de basculement a lieu. Lorsque le connecteur Cloud SQL détecte que le nom DNS du point de terminaison d'écriture fait référence à une autre instance, il ferme toutes les connexions ouvertes à l'ancienne instance. Les tentatives de connexion suivantes sont dirigées vers la nouvelle instance.

Supposons, par exemple, qu'une application soit configurée pour se connecter à l'aide du nom DNS du point de terminaison d'écriture 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog. Au départ, la zone DNS est configurée avec un enregistrement pointant vers l'instance principale, my-project:region:instance-a. L'application établit des connexions à l'instance Cloud SQL my-project:region:instance-a.

Lorsque le basculement ou la commutation se produit, Cloud SQL met à jour l'enregistrement DNS de my-project:region:instance-a vers l'instance répliquée de reprise après sinistre désignée : my-project:other-region:instance-b.

Le connecteur Cloud SQL utilisé par l'application détecte la modification de cet enregistrement DNS. Lorsque l'application se connecte à sa base de données à l'aide du nom DNS du point de terminaison d'écriture 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog, elle se connecte à l'instance Cloud SQL my-project:other-region:instance-b.

Le connecteur ou le proxy d'authentification ferme automatiquement toutes les connexions existantes à my-project:region:instance-a. Cela force tous les pools de connexions utilisés par l'application à établir de nouvelles connexions. Cela peut également entraîner l'échec des requêtes de base de données en cours.

Le proxy d'authentification Cloud SQL interroge les modifications apportées au nom DNS toutes les 30 secondes.

Mettre à jour la configuration réseau de l'instance

Si votre instance a été créée avant le 8 août 2025, vous devrez peut-être mettre à jour la configuration réseau de l'instance pour que les connecteurs de langage Cloud SQL ou le proxy d'authentification Cloud SQL puissent utiliser le point de terminaison d'écriture. Vous ne devez exécuter cette tâche de mise à jour qu'une seule fois pour chaque instance. Exécutez la commande suivante :

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

Connecter des clients de base de données à des instances à l'aide du proxy d'authentification Cloud SQL

Pour vous connecter à une instance Cloud SQL par son point de terminaison d'écriture et à l'aide du proxy d'authentification Cloud SQL, démarrez d'abord le proxy à l'aide du point de terminaison d'écriture au lieu du nom de connexion de l'instance.

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT
  

  mysql -uUSERNAME -h 127.0.0.1 -p PORT DATABASE_NAME
  

Se connecter à l'aide de connecteurs de langage Cloud SQL

Pour vous connecter à l'aide de l'un des connecteurs de langage Cloud SQL, configurez votre application en suivant les instructions de la documentation Se connecter à l'aide de connecteurs de langage Cloud SQL. Modifiez ensuite votre connexion à la base de données pour utiliser le point de terminaison d'écriture au lieu du nom DNS de l'instance.

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

Limites

• Les points de terminaison d'écriture ne sont pas disponibles pour les créations d'instances Cloud SQL Enterprise.
• Les points de terminaison d'écriture ne sont pas disponibles pour les instances IP publiques uniquement ni pour les instances Private Service Connect uniquement.

Dépannage

Les sections suivantes décrivent l'architecture des points de terminaison d'écriture et traitent des problèmes de dépannage courants.

Architecture d'un point de terminaison d'écriture

Lorsque vous créez une instance éligible, un point de terminaison d'écriture est généré par défaut.

Pour créer un point de terminaison d'écriture, Cloud SQL effectue la configuration suivante :

• Crée une zone DNS privée dans le réseau VPC du producteur de services Cloud SQL
• Crée une zone DNS d'appairage dans le réseau VPC du client
• Crée un enregistrement DNS dans la zone DNS privée du réseau du producteur de services

Le schéma suivant illustre le fonctionnement de ce processus :

Problèmes de résolution DNS

Si la résolution DNS ne fonctionne pas, vérifiez chacun des éléments suivants :

1. Assurez-vous que toutes les conditions préalables sont remplies.
2. Assurez-vous que les clients pour lesquels la résolution est attendue se trouvent dans le même réseau que celui auquel l'instance Cloud SQL est associée. Pour le vérifier, utilisez la gcloud compute instances list commande :

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

   Remplacez PROJECT_NAME par le nom du projet dans lequel réside le réseau consommateur DNS.

3. Vérifiez que la zone d'appairage existe. Pour ce faire, utilisez la gcloud dns managed-zones list commande :

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

   Remplacez PROJECT_NAME par le nom du projet dans lequel réside le réseau consommateur DNS.

4. Si la zone d'appairage n'existe pas, vous pouvez résoudre le problème à l'aide de la gcloud sql instances patch commande :

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

   Remplacez INSTANCE_NAME par le nom de votre instance Cloud SQL.

La nouvelle instance ne possède pas de point de terminaison d'écriture

Si une instance nouvellement créée ne contient pas de point de terminaison d'écriture, vérifiez chacun des éléments suivants :

1. Assurez-vous que toutes les conditions préalables sont remplies.
2. Assurez-vous qu'il n'y a pas de zone DNS d'appairage restante avec le nom DNS sql-psa.goog..

   Une zone DNS d'appairage est une zone DNS restante si le réseau associé avec la zone DNS ne dispose pas d'un appairage VPC avec l'ID du projet pair de la zone DNS d'appairage.

   S'il existe une zone DNS d'appairage restante avec le sql-psa.goog. suffixe, supprimez-la.

   Pour vérifier s'il existe des zones DNS d'appairage restantes, utilisez la gcloud dns managed-zones list commande :

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

   Remplacez PROJECT_NAME par le nom du projet dans lequel réside le réseau consommateur DNS.

   Si une zone DNS existe avec le suffixe sql-psa.goog., supprimez-la après avoir vérifié que la zone DNS d'appairage est une zone DNS restante.

   Pour supprimer une zone DNS, utilisez la commande gcloud dns managed-zones delete :

   gcloud dns managed-zones delete ZONE_NAME

   Remplacez ZONE_NAME par le nom de la zone DNS associée aux points de terminaison d'écriture. Les valeurs sont alphanumériques et utilisent le format suivant : cloud-sql-psa-dns-1234567890.

3. Vous pouvez corriger un point de terminaison d'écriture manquant pour une instance éligible à l'aide de la commande gcloud beta sql instances patch :

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

   Remplacez INSTANCE_NAME par le nom de votre instance Cloud SQL.

Étape suivante

• En savoir plus sur le dépannage de Cloud SQL.