Se connecter à l'aide du proxy d'authentification Cloud SQL

MySQL | PostgreSQL | SQL Server

Cette page explique comment se connecter à votre instance Cloud SQL en utilisant le proxy d'authentification Cloud SQL.

Pour en savoir plus sur le fonctionnement du proxy d'authentification Cloud SQL, consultez la page À propos du proxy d'authentification Cloud SQL.

Présentation

L'utilisation du proxy d'authentification Cloud SQL est la méthode recommandée pour se connecter à une instance Cloud SQL. Le proxy d'authentification Cloud SQL :

• fonctionne avec les points de terminaison d'adresses IP publiques et privées ;
• valide les connexions à l'aide des identifiants d'un utilisateur ou d'un compte de service ;
• encapsule la connexion dans une couche SSL/TLS autorisée pour une instance Cloud SQL.

Certains services et applications Google Cloud utilisent le proxy d'authentification Cloud SQL pour fournir des connexions aux chemins d'accès des adresses IP publiques avec chiffrement et autorisation, y compris :

• Environnement standard App Engine
• Environnement flexible App Engine
• Cloud Functions
• Cloud Run

Les applications exécutées dans Google Kubernetes Engine peuvent se connecter à l'aide du proxy d'authentification Cloud SQL.

Remarque : Pour vous connecter à partir de Google Kubernetes Engine, nous vous recommandons d'exécuter le proxy d'authentification Cloud SQL dans un modèle sidecar, en tant que conteneur supplémentaire qui partage un pod avec votre application. Consultez également le guide de démarrage rapide associé.

Pour une présentation rapide de son utilisation, reportez-vous au Guide de démarrage rapide pour l'utilisation du proxy d'authentification Cloud SQL.

Vous pouvez également vous connecter, avec ou sans proxy d'authentification Cloud SQL, à l'aide d'un client psql à partir d'une machine locale ou de Compute Engine.

Avant de commencer

Pour pouvoir vous connecter à une instance Cloud SQL, procédez comme suit :

1. • Pour un utilisateur ou un compte de service, assurez-vous que le compte dispose du rôle Client Cloud SQL. Ce rôle contient l'autorisation cloudsql.instances.connect, qui autorise un compte principal à se connecter à toutes les instances Cloud SQL d'un projet.

     Accéder à la page IAM

   • Vous pouvez éventuellement inclure une condition IAM dans la liaison de stratégie IAM qui autorise le compte à se connecter à une seule instance Cloud SQL spécifique.

2. Enable the Cloud SQL Admin API.

   Enable the API

3. Installez et initialisez gcloud CLI.
4. Facultatif. Installez le client Docker du proxy d'authentification Cloud SQL.

Télécharger le proxy d'authentification Cloud SQL

Linux 64 bits

1. Téléchargez le proxy d'authentification Cloud SQL :

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3/cloud-sql-proxy.linux.amd64
   

2. Rendez le proxy d'authentification Cloud SQL exécutable :

   chmod +x cloud-sql-proxy
   

Linux 32 bits

1. Téléchargez le proxy d'authentification Cloud SQL :

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3/cloud-sql-proxy.linux.386
   

2. Si la commande curl est introuvable, exécutez sudo apt install curl puis répétez la commande de téléchargement.
3. Rendez le proxy d'authentification Cloud SQL exécutable :

   chmod +x cloud-sql-proxy
   

macOS 64 bits

1. Téléchargez le proxy d'authentification Cloud SQL :

   curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3/cloud-sql-proxy.darwin.amd64
   

2. Rendez le proxy d'authentification Cloud SQL exécutable :

   chmod +x cloud-sql-proxy
   

Mac M1

1. Téléchargez le proxy d'authentification Cloud SQL :

     curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3/cloud-sql-proxy.darwin.arm64
     

2. Rendez le proxy d'authentification Cloud SQL exécutable :

     chmod +x cloud-sql-proxy
     

Windows 64 bits

Effectuez un clic droit sur https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3/cloud-sql-proxy.x64.exe et sélectionnez Enregistrer le lien sous pour télécharger le proxy d'authentification Cloud SQL. Renommez le fichier en cloud-sql-proxy.exe.

Windows 32 bits

Effectuez un clic droit sur https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.3/cloud-sql-proxy.x86.exe et sélectionnez Enregistrer le lien sous pour télécharger le proxy d'authentification Cloud SQL. Renommez le fichier en cloud-sql-proxy.exe.

Image Docker du proxy d'authentification Cloud SQL

Le proxy d'authentification Cloud SQL possède différentes images de conteneur, telles que distroless, alpine et buster. L'image de conteneur du proxy d'authentification Cloud SQL par défaut utilise distroless, qui ne contient aucune interface système. Si vous avez besoin d'une interface système ou d'outils associés, téléchargez une image basée sur alpine ou buster. Pour plus d'informations, consultez la page Images de conteneurs du proxy d'authentification Cloud SQL.

Vous pouvez extraire la dernière image sur votre ordinateur local en utilisant Docker avec la commande suivante :

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.3

Remarque : Le proxy d'authentification Cloud SQL utilise un dépôt compatible avec le domaine gcr.io, mais diffuse des images à partir d'Artifact Registry. Pour plus d'informations, consultez la section Transition depuis Container Registry.

Autres systèmes d'exploitation

Pour les autres systèmes d'exploitation non inclus ici, vous pouvez compiler le proxy d'authentification Cloud SQL à partir de la source.

Démarrer le proxy d'authentification Cloud SQL

Selon le langage et l'environnement que vous utilisez, vous pouvez démarrer le proxy d'authentification Cloud SQL à l'aide de sockets TCP, de sockets Unix ou de l'image Docker du proxy d'authentification Cloud SQL. Le binaire du proxy d'authentification Cloud SQL se connecte aux instances Cloud SQL spécifiées sur la ligne de commande et ouvre une connexion locale en tant que socket TCP ou Unix. D'autres applications et services, tels que votre code d'application ou vos outils clients de gestion de base de données, peuvent se connecter aux instances Cloud SQL via ces connexions de sockets TCP ou Unix.

Avertissement : Soyez vigilant lorsque vous associez le proxy d'authentification Cloud SQL à une interface externe. Toute personne ayant accès à cette interface ou à ce port sera autorisée à se connecter à votre instance.

Sockets TCP

Pour les connexions TCP, le proxy d'authentification Cloud SQL écoute localhost(127.0.0.1) par défaut. Ainsi, lorsque vous spécifiez --port PORT_NUMBER pour une instance, la connexion locale est à 127.0.0.1:PORT_NUMBER.

Vous pouvez également spécifier une autre adresse pour la connexion locale. Par exemple, voici comment faire en sorte que le proxy d'authentification Cloud SQL écoute 0.0.0.0:1234 pour la connexion locale :

./cloud-sql-proxy --address 0.0.0.0 --port 1234 INSTANCE_CONNECTION_NAME

1. Copiez le nom de connexion de votre instance (INSTANCE_CONNECTION_NAME). Vous le trouverez sur la page Présentation de votre instance dans Google Cloud Console ou en exécutant la commande suivante :

       gcloud sql instances describe INSTANCE_NAME --format='value(connectionName)'

   .

   Exemple : myproject:myregion:myinstance.

2. Si des adresses IP publiques et privées sont configurées pour l'instance et que vous souhaitez que le proxy d'authentification Cloud SQL utilise l'adresse IP privée, vous devez indiquer l'option suivante au démarrage du proxy d'authentification Cloud SQL :

   --private-ip

3. Si vous utilisez un compte de service pour authentifier le proxy d'authentification Cloud SQL, notez l'emplacement sur votre machine cliente du fichier de clé privée généré au moment de la création du compte de service.
4. Démarrez le proxy d'authentification Cloud SQL.

   Voici des exemples de chaînes d'appel du proxy d'authentification Cloud SQL :

   • Avec l'authentification via le SDK Cloud :

     ./cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
     

     Le port spécifié ne doit pas déjà être utilisé, par exemple par un serveur de base de données local.
   • Utilisez un compte de service et incluez explicitement le nom de la connexion à l'instance (recommandé pour les environnements de production) :

     ./cloud-sql-proxy \
     --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &
     
     

   Pour en savoir plus sur les options du proxy d'authentification Cloud SQL, consultez les sections Options du proxy d'authentification Cloud SQL et Options de spécification d'instances.

Sockets Unix

Remarque : Le proxy d'authentification Cloud SQL n'est actuellement pas compatible avec les sockets Unix sous Windows. Cette option n'est donc disponible que pour les plates-formes Linux et macOS.

Le proxy d'authentification Cloud SQL peut écouter un socket Unix, qui est un mécanisme POSIX standard permettant d'utiliser un dossier pour gérer la communication entre deux processus exécutés sur le même hôte. Les avantages des sockets Unix sont les suivants : amélioration de la sécurité et latence réduite. Toutefois, vous ne pouvez pas accéder à un socket Unix depuis une machine externe.

Remarque : La norme PostgreSQL requiert un suffixe ".s.PGSQL.5432" dans le chemin d'accès au socket. Certaines bibliothèques appliquent automatiquement ce suffixe, mais d'autres exigent de spécifier le chemin d'accès au socket comme suit :

  /cloudsql/INSTANCE_CONNECTION_NAME/.s.PGSQL.5432
  

Pour créer et utiliser un socket Unix, le répertoire cible doit exister. Le proxy d'authentification Cloud SQL et l'application doivent également disposer tous les deux d'un accès en lecture et en écriture.

1. Si vous utilisez une spécification explicite d'instance, copiez la chaîne de connexion INSTANCE_CONNECTION_NAME. Pour la trouver, accédez à la page Présentation de votre instance dans la console Google Cloud ou exécutez la commande suivante :

   gcloud sql instances describe INSTANCE_NAME  --format='value(connectionName)'

   Exemple : myproject:myregion:myinstance.

2. Créez le répertoire où se situeront les sockets du proxy d'authentification Cloud SQL :

   sudo mkdir /cloudsql; sudo chmod 777 /cloudsql

3. Si vous utilisez un compte de service pour authentifier le proxy d'authentification Cloud SQL, notez l'emplacement sur votre machine cliente du fichier de clé privée généré au moment de la création du compte de service.
4. Ouvrez une nouvelle fenêtre de terminal Cloud Shell et démarrez le proxy d'authentification Cloud SQL.

   Voici des exemples de chaînes d'appel du proxy d'authentification Cloud SQL :

   • Utilisez un compte de service et incluez explicitement le nom de la connexion à l'instance (recommandé pour les environnements de production) :

     ./cloud-sql-proxy --unix-socket /cloudsql
     --credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &

   • Avec l'authentification via le SDK Cloud et la détection automatique d'instances :

     ./cloud-sql-proxy --unix-socket /cloudsql &

   Démarrez le proxy d'authentification Cloud SQL dans son propre terminal Cloud Shell afin de pouvoir surveiller sa sortie sans qu'elle ne soit mélangée avec celle d'autres programmes.

   Pour en savoir plus sur les options du proxy d'authentification Cloud SQL, consultez les sections Options du proxy d'authentification Cloud SQL et Options de spécification d'instances.

REMARQUE : Lorsque vous utilisez un socket Unix pour vous connecter à Cloud SQL à l'aide du proxy d'authentification Cloud SQL, assurez-vous que la longueur du nom de fichier du socket ne dépasse pas la limite du système. Cela dépend du système, mais il comporte généralement entre 91 et 108 caractères. Sous Linux, la longueur est généralement définie sur 108 caractères, et vous pouvez la vérifier à l'aide de la commande suivante :

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

Docker

Pour exécuter le proxy d'authentification Cloud SQL dans un conteneur Docker, utilisez l'image Docker du proxy d'authentification Cloud SQL disponible dans Google Container Registry.

Vous pouvez démarrer le proxy d'authentification Cloud SQL à l'aide de sockets TCP ou Unix, au moyen des commandes indiquées ci-dessous. Les options utilisent une chaîne de connexion INSTANCE_CONNECTION_NAME pour identifier une instance Cloud SQL. Pour trouver la chaîne de connexion INSTANCE_CONNECTION_NAME, accédez à la page Présentation de votre instance dans Google Cloud Console ou exécutez la commande suivante :

gcloud sql instances describe INSTANCE_NAME

.

Exemple : myproject:myregion:myinstance.

Remarque : Le proxy d'authentification Cloud SQL ne permet pas d'écouter sur les sockets de domaine Unix sous Windows.

Selon le langage et l'environnement que vous employez, vous pouvez démarrer le proxy d'authentification Cloud SQL à l'aide de sockets TCP ou Unix. Les sockets Unix ne sont pas compatibles avec les applications écrites en langage de programmation Java ou avec un environnement Windows.

Utiliser des sockets TCP

docker run -d \\
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\
  -p 127.0.0.1:5432:5432 \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.3 \\
  --address 0.0.0.0 --port 5432 \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Si vous utilisez les identifiants fournis par votre instance Compute Engine, n'incluez pas le paramètre --credentials-file ni la ligne -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Spécifiez toujours le préfixe 127.0.0.1 dans -p afin de ne pas exposer le proxy d'authentification Cloud SQL en dehors de l'hôte local. La valeur "0.0.0.0" dans les paramètres de l'instance est requise pour rendre le port accessible de l'extérieur du conteneur Docker.

Utiliser des sockets Unix

docker run -d -v /cloudsql:/cloudsql \\
  -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \\
  gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.3 --unix-socket=/cloudsql \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Si vous utilisez les identifiants fournis par votre instance Compute Engine, n'incluez pas le paramètre --credentials-file ni la ligne -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Si vous utilisez une image de conteneur optimisée, utilisez un répertoire avec accès en écriture à la place de /cloudsql, par exemple :

-v /mnt/stateful_partition/cloudsql:/cloudsql

Vous pouvez spécifier plusieurs instances en les séparant par des virgules. Il est également possible d'utiliser les métadonnées Compute Engine afin de déterminer de manière dynamique les instances auxquelles vous connecter. Apprenez-en plus sur les paramètres du proxy d'authentification Cloud SQL.

Se connecter à l'aide du client psql

Debian/Ubuntu

Installez le client psql à partir du gestionnaire de packages :

sudo apt-get update
sudo apt-get install postgresql-client

CentOS/RHEL

Installez le client psql à partir du gestionnaire de packages :

sudo yum install postgresql

openSUSE

Installez le client psql à partir du gestionnaire de packages :

sudo zypper install postgresql

Autres plates-formes

1. Téléchargez PostgreSQL Core Distribution sur votre plate-forme depuis la page des téléchargements PostgreSQL.
   Core Distribution inclut le client psql.
2. Installez la base de données PostgreSQL en suivant les instructions de la page de téléchargement.

La chaîne de connexion que vous utilisez varie selon que vous avez démarré le proxy d'authentification Cloud SQL à l'aide d'un socket TCP ou UNIX, ou Docker.

Sockets TCP

1. Démarrez le client psql :

   psql "host=127.0.0.1 sslmode=disable dbname=DB_NAME user=USERNAME"
   

   Même si le paramètre sslmode est défini sur disable, le proxy d'authentification Cloud SQL fournit une connexion chiffrée.

   Lorsque vous vous connectez à l'aide de sockets TCP, l'accès au proxy d'authentification Cloud SQL s'effectue via 127.0.0.1.

2. Si vous y êtes invité, saisissez le mot de passe.
3. L'invite psql s'affiche.

Utiliser des sockets Unix

1. Démarrez le client psql :

   psql "sslmode=disable host=/cloudsql/INSTANCE_CONNECTION_NAME dbname=DB_NAME user=USERNAME"
   

   Même si le paramètre sslmode est défini sur disable, le proxy d'authentification Cloud SQL fournit une connexion chiffrée.

2. Saisissez le mot de passe.
3. L'invite psql s'affiche.

Besoin d'aide ? Pour obtenir de l'aide sur le dépannage du proxy, consultez la section Dépannage des connexions via le proxy d'authentification Cloud SQL ou la page Assistance Cloud SQL.

Se connecter avec une application

Vous pouvez vous connecter au proxy d'authentification Cloud SQL au moyen de n'importe quel langage permettant la connexion à un socket Unix ou TCP. Vous trouverez ci-dessous des extraits de code tirés d'exemples complets disponibles sur GitHub pour vous aider à comprendre comment ils fonctionnent ensemble dans votre application.

Se connecter avec TCP

Instruction d'appel du proxy d'authentification Cloud SQL :

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

import os
import ssl

import sqlalchemy


def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of Postgres."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_host = os.environ[
        "INSTANCE_HOST"
    ]  # e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
    db_user = os.environ["DB_USER"]  # e.g. 'my-db-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-db-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    db_port = os.environ["DB_PORT"]  # e.g. 5432

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=db_host,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

Java

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

Remarque :

• CLOUD_SQL_CONNECTION_NAME doit être représenté sous la forme <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>.
• L'utilisation de l'argument ipTypes=PRIVATE force la connexion de SocketFactory à l'adresse IP privée associée à une instance.
• Pour en savoir plus sur les exigences de version Socket Factory des sockets JDBC pour le fichier pom.xml, cliquez ici.

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  private static final String INSTANCE_HOST = System.getenv("INSTANCE_HOST");
  private static final String DB_PORT = System.getenv("DB_PORT");


  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql://<INSTANCE_HOST>:<DB_PORT>/<DB_NAME>?user=<DB_USER>&password=<DB_PASS>
    // See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
    // https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"


    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

const Knex = require('knex');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
const createTcpPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  const dbConfig = {
    client: 'pg',
    connection: {
      host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
      port: process.env.DB_PORT, // e.g. '5432'
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
    },
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return Knex(dbConfig);
};

Go

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v5 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of Postgres.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_tcp.go: %s environment variable not set.", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
		dbPort    = mustGetenv("DB_PORT")       // e.g. '5432'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("host=%s user=%s password=%s port=%s database=%s",
		dbTCPHost, dbUser, dbPwd, dbPort, dbName)


	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

C#

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlTcp
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_HOST"),     // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user'
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Ruby

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

tcp: &tcp
  adapter: postgresql
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  host: <%= ENV.fetch("INSTANCE_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT") { 5432 }%>

PHP

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

namespace Google\Cloud\Samples\CloudSQL\Postgres;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseTcp
{
    public static function initTcpDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceHost = getenv('INSTANCE_HOST'); // e.g. '127.0.0.1' ('172.17.0.1' for GAE Flex)

            // Connect using TCP
            $dsn = sprintf('pgsql:dbname=%s;host=%s', $dbName, $instanceHost);

            // Connect to the database
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, and $instanceHost (for TCP mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/postgres/connect-external-app',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Se connecter avec des sockets Unix

Instruction d'appel du proxy d'authentification Cloud SQL :

./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &

Python

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

import os

import sqlalchemy


def connect_unix_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a Unix socket connection pool for a Cloud SQL instance of Postgres."""
    # Note: Saving credentials in environment variables is convenient, but not
    # secure - consider a more secure solution such as
    # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
    # keep secrets safe.
    db_user = os.environ["DB_USER"]  # e.g. 'my-database-user'
    db_pass = os.environ["DB_PASS"]  # e.g. 'my-database-password'
    db_name = os.environ["DB_NAME"]  # e.g. 'my-database'
    unix_socket_path = os.environ[
        "INSTANCE_UNIX_SOCKET"
    ]  # e.g. '/cloudsql/project:region:instance'

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgresql+pg8000://<db_user>:<db_pass>@/<db_name>
        #                         ?unix_sock=<INSTANCE_UNIX_SOCKET>/.s.PGSQL.5432
        # Note: Some drivers require the `unix_sock` query parameter to use a different key.
        # For example, 'psycopg2' uses the path set to `host` in order to connect successfully.
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            database=db_name,
            query={"unix_sock": f"{unix_socket_path}/.s.PGSQL.5432"},
        ),
        # ...
    )
    return pool

Java

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import javax.sql.DataSource;

public class ConnectorConnectionPoolFactory extends ConnectionPoolFactory {

  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  private static final String INSTANCE_CONNECTION_NAME =
      System.getenv("INSTANCE_CONNECTION_NAME");
  private static final String INSTANCE_UNIX_SOCKET = System.getenv("INSTANCE_UNIX_SOCKET");
  private static final String DB_USER = System.getenv("DB_USER");
  private static final String DB_PASS = System.getenv("DB_PASS");
  private static final String DB_NAME = System.getenv("DB_NAME");

  public static DataSource createConnectionPool() {
    // The configuration object specifies behaviors for the connection pool.
    HikariConfig config = new HikariConfig();

    // The following URL is equivalent to setting the config options below:
    // jdbc:postgresql:///<DB_NAME>?cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&
    // socketFactory=com.google.cloud.sql.postgres.SocketFactory&user=<DB_USER>&password=<DB_PASS>
    // See the link below for more info on building a JDBC URL for the Cloud SQL JDBC Socket Factory
    // https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory#creating-the-jdbc-url

    // Configure which instance and what database user to connect with.
    config.setJdbcUrl(String.format("jdbc:postgresql:///%s", DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", _postgres"
    config.setPassword(DB_PASS); // e.g. "my-password"

    config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.postgres.SocketFactory");
    config.addDataSourceProperty("cloudSqlInstance", INSTANCE_CONNECTION_NAME);

    // Unix sockets are not natively supported in Java, so it is necessary to use the Cloud SQL
    // Java Connector to connect. When setting INSTANCE_UNIX_SOCKET, the connector will 
    // call an external package that will enable Unix socket connections.
    // Note: For Java users, the Cloud SQL Java Connector can provide authenticated connections
    // which is usually preferable to using the Cloud SQL Proxy with Unix sockets.
    // See https://github.com/GoogleCloudPlatform/cloud-sql-jdbc-socket-factory for details.
    if (INSTANCE_UNIX_SOCKET != null) {
      config.addDataSourceProperty("unixSocketPath", INSTANCE_UNIX_SOCKET);
    }



    // ... Specify additional connection properties here.
    // ...

    // Initialize the connection pool using the configuration object.
    return new HikariDataSource(config);
  }
}

Node.js

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

const Knex = require('knex');

// createUnixSocketPool initializes a Unix socket connection pool for
// a Cloud SQL instance of Postgres.
const createUnixSocketPool = async config => {
  // Note: Saving credentials in environment variables is convenient, but not
  // secure - consider a more secure solution such as
  // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  // keep secrets safe.
  return Knex({
    client: 'pg',
    connection: {
      user: process.env.DB_USER, // e.g. 'my-user'
      password: process.env.DB_PASS, // e.g. 'my-user-password'
      database: process.env.DB_NAME, // e.g. 'my-database'
      host: process.env.INSTANCE_UNIX_SOCKET, // e.g. '/cloudsql/project:region:instance'
    },
    // ... Specify additional properties here.
    ...config,
  });
};

C#

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

using Npgsql;
using System;

namespace CloudSql
{
    public class PostgreSqlUnix
    {
        public static NpgsqlConnectionStringBuilder NewPostgreSqlUnixSocketConnectionString()
        {
            // Equivalent connection string:
            // "Server=<INSTANCE_UNIX_SOCKET>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>"
            var connectionString = new NpgsqlConnectionStringBuilder()
            {
                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = SslMode.Disable,

                // Note: Saving credentials in environment variables is convenient, but not
                // secure - consider a more secure solution such as
                // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
                // keep secrets safe.
                Host = Environment.GetEnvironmentVariable("INSTANCE_UNIX_SOCKET"), // e.g. '/cloudsql/project:region:instance'
                Username = Environment.GetEnvironmentVariable("DB_USER"), // e.g. 'my-db-user
                Password = Environment.GetEnvironmentVariable("DB_PASS"), // e.g. 'my-db-password'
                Database = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

Go

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

package cloudsql

import (
	"database/sql"
	"fmt"
	"log"
	"os"

	// Note: If connecting using the App Engine Flex Go runtime, use
	// "github.com/jackc/pgx/stdlib" instead, since v5 requires
	// Go modules which are not supported by App Engine Flex.
	_ "github.com/jackc/pgx/v5/stdlib"
)

// connectUnixSocket initializes a Unix socket connection pool for
// a Cloud SQL instance of Postgres.
func connectUnixSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Fatal Error in connect_unix.go: %s environment variable not set.\n", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser         = mustGetenv("DB_USER")              // e.g. 'my-db-user'
		dbPwd          = mustGetenv("DB_PASS")              // e.g. 'my-db-password'
		unixSocketPath = mustGetenv("INSTANCE_UNIX_SOCKET") // e.g. '/cloudsql/project:region:instance'
		dbName         = mustGetenv("DB_NAME")              // e.g. 'my-database'
	)

	dbURI := fmt.Sprintf("user=%s password=%s database=%s host=%s",
		dbUser, dbPwd, dbName, unixSocketPath)

	// dbPool is the pool of database connections.
	dbPool, err := sql.Open("pgx", dbURI)
	if err != nil {
		return nil, fmt.Errorf("sql.Open: %w", err)
	}

	// ...

	return dbPool, nil
}

Ruby

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

unix: &unix
  adapter: postgresql
  # Configure additional properties here.
  # Note: Saving credentials in environment variables is convenient, but not
  # secure - consider a more secure solution such as
  # Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
  # keep secrets safe.
  username: <%= ENV["DB_USER"] %>  # e.g. "my-database-user"
  password: <%= ENV["DB_PASS"] %> # e.g. "my-database-password"
  database: <%= ENV.fetch("DB_NAME") { "vote_development" } %>
  # Specify the Unix socket path as host
  host: "<%= ENV["INSTANCE_UNIX_SOCKET"] %>"

PHP

Pour afficher cet extrait dans le contexte d'une application Web, consultez le fichier README sur GitHub.

namespace Google\Cloud\Samples\CloudSQL\Postgres;

use PDO;
use PDOException;
use RuntimeException;
use TypeError;

class DatabaseUnix
{
    public static function initUnixDatabaseConnection(): PDO
    {
        try {
            // Note: Saving credentials in environment variables is convenient, but not
            // secure - consider a more secure solution such as
            // Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
            // keep secrets safe.
            $username = getenv('DB_USER'); // e.g. 'your_db_user'
            $password = getenv('DB_PASS'); // e.g. 'your_db_password'
            $dbName = getenv('DB_NAME'); // e.g. 'your_db_name'
            $instanceUnixSocket = getenv('INSTANCE_UNIX_SOCKET'); // e.g. '/cloudsql/project:region:instance'

            // Connect using UNIX sockets
            $dsn = sprintf(
                'pgsql:dbname=%s;host=%s',
                $dbName,
                $instanceUnixSocket
            );

            // Connect to the database.
            $conn = new PDO(
                $dsn,
                $username,
                $password,
                # ...
            );
        } catch (TypeError $e) {
            throw new RuntimeException(
                sprintf(
                    'Invalid or missing configuration! Make sure you have set ' .
                        '$username, $password, $dbName, ' .
                        'and $instanceUnixSocket (for UNIX socket mode). ' .
                        'The PHP error was %s',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        } catch (PDOException $e) {
            throw new RuntimeException(
                sprintf(
                    'Could not connect to the Cloud SQL Database. Check that ' .
                        'your username and password are correct, that the Cloud SQL ' .
                        'proxy is running, and that the database exists and is ready ' .
                        'for use. For more assistance, refer to %s. The PDO error was %s',
                    'https://cloud.google.com/sql/docs/postgres/connect-external-app',
                    $e->getMessage()
                ),
                (int) $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

Autres sujets

Arguments de ligne de commande du proxy d'authentification Cloud SQL

Les exemples ci-dessus couvrent les cas d'utilisation les plus courants, mais le proxy d'authentification Cloud SQL propose d'autres options de configuration pouvant être définies avec des arguments de ligne de commande. Pour obtenir de l'aide sur les arguments de ligne de commande, utilisez l'option --help pour consulter la dernière documentation :

./cloud-sql-proxy --help

Pour obtenir d'autres exemples sur l'utilisation des options de ligne de commande du proxy d'authentification Cloud SQL, consultez le fichier README sur le dépôt GitHub du proxy d'authentification Cloud SQL.

Options d'authentification du proxy d'authentification Cloud SQL

Lorsque vous authentifiez le proxy d'authentification Cloud SQL, vous l'autorisez à accéder à Google Cloud pour le compte de votre application, à l'aide d'un ensemble d'identifiants Google. Il s'agit d'un processus distinct de l'authentification des utilisateurs de bases de données. L'authentification de la base de données utilisateur IAM est intégrée au proxy d'authentification Cloud SQL.

Toutes ces options utilisent une chaîne de connexion INSTANCE_CONNECTION_NAME pour identifier une instance Cloud SQL. Pour trouver la chaîne de connexion INSTANCE_CONNECTION_NAME, accédez à la page Présentation de votre instance dans Google Cloud Console ou exécutez la commande suivante :

gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME.

Par exemple : gcloud sql instances describe --project myproject myinstance.

Certaines de ces options utilisent un fichier d'identifiants JSON qui inclut la clé privée RSA du compte. Pour obtenir des instructions sur la création d'un fichier d'identifiants JSON pour un compte de service, consultez la page Créer un compte de service.

Le proxy d'authentification Cloud SQL propose plusieurs alternatives pour l'authentification, en fonction de votre environnement. Le proxy d'authentification Cloud SQL recherche chacun des éléments suivants, dans cet ordre, et effectue une tentative d'authentification avec le premier qu'il trouve :

1. Identifiants fournis par l'option credential_file

   Utilisez un compte de service pour créer et télécharger le fichier JSON associé, et définissez l'option --credentials-file sur le chemin du fichier lorsque vous démarrez le proxy d'authentification Cloud SQL. Le compte de service doit disposer des autorisations requises pour l'instance Cloud SQL.

   Pour utiliser cette option sur la ligne de commande, appelez la commande cloud-sql-proxy avec l'option --credentials-file définie sur le chemin d'accès et le nom de fichier d'un fichier d'identifiants JSON. Le chemin d'accès peut être absolu, ou relatif au répertoire de travail actuel. Par exemple,

   ./cloud-sql-proxy --credentials-file PATH_TO_KEY_FILE \
   INSTANCE_CONNECTION_NAME
     

   .

   Pour obtenir des instructions détaillées sur l'ajout de rôles IAM à un compte de service, consultez la page Attribuer des rôles aux comptes de service.

   Pour en savoir plus sur les rôles acceptés par Cloud SQL, consultez la page Rôles IAM pour Cloud SQL.

2. Identifiants fournis par un jeton d'accès

   Créez un jeton d'accès et appelez la commande cloud-sql-proxy avec l'option --token définie sur un jeton d'accès OAuth 2.0. Par exemple,

   ./cloud-sql-proxy --token ACCESS_TOKEN \
   INSTANCE_CONNECTION_NAME
     

   .

3. Identifiants fournis par une variable d'environnement

   Cette option est semblable à l'utilisation de l'option --credentials-file, sauf que vous spécifiez le fichier d'identifiants JSON que vous définissez dans la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS au lieu d'utiliser l'argument de ligne de commande --credentials-file.

4. Identifiants d'un client gcloud CLI authentifié.

   Si vous avez installé gcloud CLI et que vous vous êtes authentifié avec votre compte personnel, le proxy d'authentification Cloud SQL peut utiliser les mêmes identifiants de compte. Cette méthode est particulièrement utile pour rendre opérationnel un environnement de développement.

   Pour permettre au proxy d'authentification Cloud SQL d'utiliser vos identifiants de gcloud CLI, exécutez la commande suivante pour authentifier gcloud CLI :

   gcloud auth application-default login

5. Identifiants associés à l'instance Compute Engine

   Si vous vous connectez à Cloud SQL depuis une instance Compute Engine, le proxy d'authentification Cloud SQL peut utiliser le compte de service associé à celle-ci. Si le compte de service dispose des autorisations requises pour l'instance Cloud SQL, l'authentification du proxy d'authentification Cloud SQL aboutit.

   Si l'instance Compute Engine se trouve dans le même projet que l'instance Cloud SQL, le compte de service par défaut de l'instance Compute Engine dispose des autorisations nécessaires pour authentifier le proxy d'authentification Cloud SQL. Si ces deux instances sont dans des projets différents, vous devez ajouter le compte de service de l'instance Compute Engine au projet contenant l'instance Cloud SQL.

6. Compte de service par défaut de l'environnement

   Si le proxy d'authentification Cloud SQL ne trouve pas les identifiants dans l'un des emplacements abordés précédemment, il suit la logique décrite dans la section Configurer l'authentification pour les applications de production serveur à serveur. Certains environnements (tels que Compute Engine, App Engine et d'autres) fournissent un compte de service par défaut que votre application peut utiliser pour s'authentifier par défaut. Si vous utilisez un compte de service par défaut, celui-ci doit disposer des autorisations décrites dans la section Rôles et autorisations. Pour en savoir plus sur l'approche de Google Cloud en matière d'authentification, consultez la page Présentation de l'authentification.

Créer un compte de service

Si vous vous connectez à partir de Compute Engine, assurez-vous que votre VM dispose du scope approprié pour se connecter à l'aide de l'API Cloud SQL Admin.

Configurez le compte de service pour qu'il possède l'un des champs d'application d'accès suivants :

• https://www.googleapis.com/auth/sqlservice.admin
• https://www.googleapis.com/auth/cloud-platform

1. Dans Google Cloud Console, accédez à la page Comptes de service.

   Accéder à la page "Comptes de service"

2. Sélectionnez le projet contenant l'instance Cloud SQL.
3. Cliquez sur Créer un compte de service.
4. Dans le champ Nom du compte de service, attribuez un nom descriptif au compte de service.
5. Remplacez l'ID du compte de service par une valeur unique et facilement reconnaissable, puis cliquez sur Créer et continuer.
6. Cliquez sur le champ Sélectionner un rôle, puis sélectionnez l'un des rôles suivants :
   • Cloud SQL > Client Cloud SQL
   • Cloud SQL > Éditeur Cloud SQL
   • Cloud SQL > Administrateur Cloud SQL
   Remarque : Pour créer un compte de service avec les autorisations requises, vous devez disposer de l'autorisation resourcemanager.projects.setIamPolicy. Cette autorisation est incluse dans les rôles de propriétaire de projet, d'administrateur de projet IAM et d'administrateur de l'organisation.
   Vous devez également avoir activé l'API Cloud SQL Admin. Si vous utilisez les anciens rôles de projet (Lecteur, Éditeur, Propriétaire), le compte de service doit disposer au minimum du rôle Éditeur.
7. Cliquez sur OK pour terminer la création du compte de service.
8. Cliquez sur le menu Action de votre nouveau compte de service, puis sélectionnez Gérer les clés.
9. Cliquez sur le menu déroulant Ajouter une clé, puis sur Créer une clé.
10. Vérifiez que le type de clé est bien JSON et cliquez sur Créer.

    Le fichier de clé privée est téléchargé sur votre machine. Vous pouvez le changer d'emplacement. Conservez le fichier de clé à un endroit sécurisé.

Utiliser le proxy d'authentification Cloud SQL avec une adresse IP privée

Pour permettre la connexion à une instance Cloud SQL à l'aide d'une adresse IP privée, le proxy d'authentification Cloud SQL doit se trouver sur une ressource ayant accès au même réseau VPC que l'instance.

Le proxy d'authentification Cloud SQL utilise une adresse IP pour établir une connexion avec votre instance Cloud SQL. Par défaut, le proxy d'authentification Cloud SQL tente de se connecter à l'aide d'une adresse IPv4 publique.

Si votre instance Cloud SQL n'a qu'une adresse IP privée ou si l'instance est configurée à la fois avec une adresse IP publique et une adresse IP privée, et que vous souhaitez que le proxy d'authentification Cloud SQL utilise l'adresse IP privée, vous devez indiquer l'option suivante au démarrage du proxy d'authentification Cloud SQL :

--private-ip

Utiliser le proxy d'authentification Cloud SQL avec des instances sur lesquelles Private Service Connect est activé

Vous pouvez utiliser le proxy d'authentification Cloud SQL pour vous connecter à une instance Cloud SQL avec Private Service Connect activé.

Le proxy d'authentification Cloud SQL est un connecteur qui fournit un accès sécurisé à cette instance sans nécessiter de réseaux autorisés ni de configuration SSL.

Pour autoriser les connexions client via le proxy d'authentification Cloud SQL, vous devez configurer un enregistrement DNS correspondant au nom DNS recommandé fourni pour l'instance. L'enregistrement DNS est un mappage entre une ressource DNS et un nom de domaine.

Pour en savoir plus sur l'utilisation du proxy d'authentification Cloud SQL pour vous connecter à des instances avec Private Service Connect activé, consultez la section Se connecter à l'aide du proxy d'authentification Cloud SQL.

Exécuter le proxy d'authentification Cloud SQL dans un processus distinct

L'exécution du proxy d'authentification Cloud SQL dans un processus de terminal Cloud Shell distinct peut être utile pour éviter de mélanger le résultat de la console avec le résultat d'autres programmes. Utilisez la syntaxe ci-dessous pour appeler le proxy d'authentification Cloud SQL dans un processus distinct.

Linux

Sous Linux ou macOS, insérez un & final sur la ligne de commande pour lancer le proxy d'authentification Cloud SQL dans un processus distinct :

./cloud-sql-proxy INSTANCE_CONNECTION_NAME
  --credentials-file PATH_TO_KEY_FILE &

Windows

Dans Windows PowerShell, utilisez la commande Start-Process pour lancer le proxy d'authentification Cloud SQL dans un processus distinct :

Start-Process --filepath "cloud-sql-proxy.exe"
  --ArgumentList "
  --credentials-file PATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME"

Exécuter le proxy d'authentification Cloud SQL dans un conteneur Docker

Pour exécuter le proxy d'authentification Cloud SQL dans un conteneur Docker, utilisez l'image Docker du proxy d'authentification Cloud SQL disponible dans Google Container Registry. Vous pouvez installer l'image Docker du proxy d'authentification Cloud SQL à l'aide de la commande gcloud suivante :

docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.3

Vous pouvez démarrer le proxy d'authentification Cloud SQL à l'aide de sockets TCP ou Unix, au moyen des commandes indiquées ci-dessous.

Remarque : Les sockets Unix ne sont pas compatibles avec les applications écrites en langage de programmation Java ou avec un environnement Windows.

Sockets TCP

    docker run -d \
      -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
      -p 127.0.0.1:5432:5432 \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.3 \
      --address 0.0.0.0 \
      --credentials-file /path/to/service-account-key.json \
      INSTANCE_CONNECTION_NAME

Sockets Unix

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.3 --unix-socket /cloudsql \
      --credentials-file /path/to/service-account-key.json/PATH_TO_KEY_FILE \
      INSTANCE_CONNECTION_NAME

Si vous utilisez une image optimisée pour les conteneurs, utilisez un répertoire avec accès en écriture à la place de /cloudsql, par exemple :

v /mnt/stateful_partition/cloudsql:/cloudsql

Si vous utilisez les identifiants fournis par votre instance Compute Engine, n'incluez pas le paramètre credential_file ni la ligne -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Exécuter le proxy d'authentification Cloud SQL en tant que service

L'exécution du proxy d'authentification Cloud SQL en tant que service d'arrière-plan est une option pour les charges de travail de développement et de production locales. En phase de développement, lorsque vous devez accéder à votre instance Cloud SQL, vous pouvez démarrer le service en arrière-plan et l'arrêter lorsque vous avez terminé.

Pour les charges de travail de production, le proxy d'authentification Cloud SQL ne fournit actuellement pas d'assistance intégrée pour l'exécution en tant que service Windows, mais des gestionnaires de services tiers peuvent être utilisés pour l'exécuter en tant que service. Par exemple, vous pouvez utiliser NSSM pour configurer le proxy d'authentification Cloud SQL en tant que service Windows afin que NSSM surveille le proxy d'authentification Cloud SQL et le redémarre automatiquement s'il cesse de répondre. Pour plus d'informations, consultez la documentation NSSM.

Remarque : Si vous exécutez le proxy d'authentification Cloud SQL en tant que service, n'oubliez pas que bien qu'il utilise une connexion sécurisée pour communiquer avec les instances Cloud SQL, les connexions de votre application au proxy d'authentification Cloud SQL ne sont pas chiffrées. Pour cette raison, assurez-vous que seuls les utilisateurs de confiance peuvent accéder à l'adresse et au port sur lesquels le proxy Cloud SQL écoute.

Imposer l'utilisation du proxy d'authentification Cloud SQL

Activez l'utilisation du proxy d'authentification Cloud SQL dans Cloud SQL à l'aide de ConnectorEnforcement.

gcloud

La commande suivante impose l'utilisation de connecteurs Cloud SQL.

    gcloud sql instances patch INSTANCE_NAME \
    --connector-enforcement REQUIRED
  

Pour désactiver cette application forcée, utilisez la ligne de code suivante : --connector-enforcement NOT_REQUIRED. La mise à jour ne déclenche pas de redémarrage.

REST v1

La commande suivante impose l'utilisation de connecteurs Cloud SQL.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

• project-id : ID du projet
• instance-id : ID de l'instance.

Méthode HTTP et URL :

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Corps JSON de la requête :

{
  "settings": {                     
    "connectorEnforcement": "REQUIRED"    
  }                                             
}   

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

PowerShell (Windows)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Pour désactiver cette application forcée, utilisez plutôt "connectorEnforcement": "NOT_REQUIRED". La mise à jour ne déclenche pas de redémarrage.

REST v1beta4

La commande suivante impose l'utilisation de connecteurs Cloud SQL.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

• project-id : ID du projet
• instance-id : ID de l'instance.

Méthode HTTP et URL :

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Corps JSON de la requête :

{
  "settings": {
    "connectorEnforcement": "REQUIRED"
  }
}

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

PowerShell (Windows)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Pour désactiver cette application forcée, utilisez plutôt "connectorEnforcement": "NOT_REQUIRED". La mise à jour ne déclenche pas de redémarrage.

Conseils d'utilisation du proxy d'authentification Cloud SQL

Appeler le proxy d'authentification Cloud SQL

Tous les exemples d'appels du proxy démarrent le proxy Cloud SQL en arrière-plan, ce qui implique qu'une requête est renvoyée. Réservez ce terminal Cloud Shell au proxy d'authentification Cloud SQL afin d'éviter que sa sortie ne soit mélangée à celle d'autres programmes. La sortie du proxy d'authentification Cloud SQL peut vous aider à diagnostiquer les problèmes de connexion et il peut donc être utile de l'enregistrer dans un fichier journal. Si vous ne démarrez pas le proxy d'authentification Cloud SQL en arrière-plan, la sortie est transmise à stdout à moins d'être redirigée.

Vous n'avez pas besoin d'utiliser /cloudsql comme répertoire pour les sockets du proxy d'authentification Cloud SQL. (Ce nom de répertoire a été choisi de façon à réduire au minimum les différences avec les chaînes de connexion App Engine.) Toutefois, si vous modifiez le nom du répertoire, limitez-en au maximum la longueur totale. En effet, ce nom est incorporé dans une chaîne plus longue présentant une limite de longueur imposée par le système d'exploitation. Cela dépend du système, mais il comporte généralement entre 91 et 108 caractères. Sous Linux, la longueur est généralement définie sur 108 caractères, et vous pouvez la vérifier à l'aide de la commande suivante :

cat /usr/include/linux/un.h | grep "define UNIX_PATH_MAX"

Utiliser le proxy d'authentification Cloud SQL pour se connecter à plusieurs instances

Vous pouvez utiliser un client proxy Cloud SQL local pour vous connecter à plusieurs instances Cloud SQL. La marche à suivre varie selon que vous utilisez des sockets Unix ou TCP.

Sockets Unix

Pour connecter le proxy d'authentification Cloud SQL à plusieurs instances, vous devez indiquer chaque nom de connexion d'instance en tant qu'argument au proxy d'authentification Cloud SQL, dans une liste d'éléments séparés par des espaces. Le proxy Cloud SQL se connecte à chaque instance au démarrage.

Vous vous connectez à chaque instance à l'aide de son socket, dans le répertoire spécifié.

Exemple :

      ./cloud-sql-proxy --unix-socket /cloudsql \
      myProject:us-central1:myInstance myProject:us-central1:myInstance2 &
      psql -U myUser -h /cloudsql/myProject:us-central1:myInstance2
  

Sockets TCP

Lorsque vous vous connectez à l'aide de TCP, vous devez spécifier un port sur votre machine via lequel le proxy d'authentification Cloud SQL doit écouter pour chaque instance Cloud SQL. Lorsque vous vous connectez à plusieurs instances Cloud SQL, chaque port spécifié doit être unique et disponible sur votre machine.

Exemple :

    # Start the Cloud SQL Auth Proxy to connect to two different Cloud SQL instances
    # Give the Cloud SQL Auth Proxy a unique port on your machine to use for each Cloud SQL instance.

    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" \
    "myProject:us-central1:myInstance2?port=1234"

    # Connect to "myInstance" using port 5432 on your machine:
    psql -U myUser -h 127.0.0.1  --port 5432

    # Connect to "myInstance2" using port 1234 on your machine:
    psql -U myUser -h 127.0.0.1  --port 1234
  

Appels du proxy d'authentification Cloud SQL et chaînes de connexion au client psql

Vous pouvez utiliser les appels du proxy d'authentification Cloud SQL et les chaînes de connexion, par exemple dans les commandes pour un utilisateur PostgreSQL myUser pour l'instance myInstance située dans us-central1 dans le projet myProject.

En utilisant la détection automatique d'instances avec des identifiants gcloud CLI :

    ./cloud-sql-proxy --unix-socket /cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance
 

En utilisant la détection de projets avec des identifiants gcloud CLI :

    ./cloud-sql-proxy --unix-socket /cloudsql &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance

Pour une instance Compute Engine, avec spécification explicite d'instances :

    ./cloud-sql-proxy --unix-socket /cloudsql myProject:us-central1:myInstance &
    psql -U myUser -h /cloudsql/myProject:us-central1:myInstance

Pour Unix, en utilisant TCP :

    ./cloud-sql-proxy "myProject:us-central1:myInstance?port=5432" &
    psql -U myUser -h 127.0.0.1

Pour Windows (à l'invite de ligne de commande) :

    cloud-sql-proxy.exe "myProject:us-central1:myInstance?port=5432"
    psql -U myUser -h 127.0.0.1

Remarque : 5432 est le port par défaut utilisé pour le client psql. Si vous utilisez un autre numéro de port, vous devez le spécifier lorsque vous démarrez le client psql à l'aide du paramètre --port.

Pour en savoir plus sur les chaînes de connexion et les options du proxy d'authentification Cloud SQL, consultez la page GitHub relative au proxy d'authentification Cloud SQL.

Résoudre les problèmes de connexion via le proxy d'authentification Cloud SQL

L'image Docker du proxy d'authentification Cloud SQL est basée sur une version spécifique du proxy d'authentification Cloud SQL. Lorsqu'une nouvelle version du proxy d'authentification Cloud SQL est disponible, vous devez extraire la nouvelle version de l'image Docker du proxy afin de maintenir votre environnement à jour. Pour savoir quelle est la version actuelle du proxy d'authentification Cloud SQL, consultez la page GitHub relative aux versions du proxy d'authentification Cloud SQL.

Si vous ne parvenez pas à vous connecter à votre instance Cloud SQL à l'aide du proxy d'authentification Cloud SQL, voici quelques conseils qui pourraient vous permettre de trouver la cause du problème.

• Vérifiez la sortie du proxy d'authentification Cloud SQL.

  Souvent, la sortie du proxy d'authentification Cloud SQL peut vous aider à déterminer la source du problème et à le résoudre. Dirigez la sortie vers un fichier, ou surveillez le terminal Cloud Shell dans lequel vous avez démarré le proxy d'authentification Cloud SQL.

• Si vous obtenez une erreur 403 notAuthorized et que vous authentifiez le proxy Cloud SQL à l'aide d'un compte de service, assurez-vous que celui-ci dispose des autorisations appropriées.

  Pour vérifier le compte de service, recherchez son ID sur la page IAM. Il doit disposer de l'autorisation cloudsql.instances.connect. Les rôles prédéfinis Cloud SQL Admin, Client et Editor disposent de cette autorisation.

• Si vous vous connectez à partir d'App Engine et que vous obtenez une erreur 403 notAuthorized, recherchez un nom de connexion d'instance mal orthographié ou incorrect dans la valeur app.yamlcloud_sql_instances. Les noms de connexion d'instance sont toujours au format PROJECT:REGION:INSTANCE.

  Vérifiez également que le compte de service App Engine (par exemple, $[e-mail]) dispose du rôle IAM du client Cloud SQL.

  Si le service App Engine se trouve dans un projet (projet A) et que la base de données se trouve dans un autre (projet B), cette erreur signifie que le rôle IAM du client Cloud SQL n'a pas été attribué au compte de service App Engine dans le projet avec la base de données (projet B).

• Assurez-vous d'avoir activé l'API Cloud SQL Admin.

  Si ce n'est pas le cas, une sortie semblable à Error 403: Access Not Configured s'affiche dans les journaux du proxy d'authentification Cloud SQL.

• Si la liste d'instances comprend plusieurs instances, veillez à les séparer par une virgule, sans inclure d'espaces. Si vous utilisez le protocole TCP, assurez-vous de spécifier des ports différents pour chaque instance.

• Si vous vous connectez à l'aide de sockets UNIX, vérifiez qu'ils ont été créés en utilisant le répertoire que vous avez fourni lors du démarrage du proxy d'authentification Cloud SQL.

• Si vous avez mis en place des règles de pare-feu pour le trafic sortant, assurez-vous qu'elles autorisent les connexions au port 3307 sur l'instance Cloud SQL cible.

  Remarque : Le proxy d'authentification Cloud SQL utilise le code 3307 pour se connecter au serveur proxy d'authentification Cloud SQL. Le port 5432 est le port par défaut du protocole PostgreSQL via une connexion TCP directe (sans utiliser le proxy d'authentification Cloud SQL).

• Vous pouvez vérifier que le proxy d'authentification Cloud SQL a démarré correctement en consultant les journaux dans la section Opérations > Journalisation > Explorateur de journaux de Google Cloud Console. Une opération réussie ressemble à ce qui suit :

  2021/06/14 15:47:56 Listening on /cloudsql/$PROJECT_ID:$REGION:$INSTANCE_NAME/5432 for $PROJECT_ID:$REGION:$INSTANCE_NAME
  2021/06/14 15:47:56 Ready for new connections
  

• Problèmes de quotas : lorsque le quota de l'API Cloud SQL Admin est dépassé, le proxy d'authentification Cloud SQL démarre avec le message d'erreur suivant :

  There was a problem when parsing a instance configuration but ignoring due
  to the configuration. Error: googleapi: Error 429: Quota exceeded for quota
  metric 'Queries' and limit 'Queries per minute per user' of service
  'sqladmin.googleapis.com' for consumer 'project_number:$PROJECT_ID.,
  rateLimitExceeded
  

  Une fois qu'une application se connecte au proxy, celui-ci signale l'erreur suivante :

  failed to refresh the ephemeral certificate for $INSTANCE_CONNECTION_NAME:
  googleapi: Error 429: Quota exceeded for quota metric 'Queries' and limit
  'Queries per minute per user' of service 'sqladmin.googleapis.com' for
  consumer 'project_number:$PROJECT_ID., rateLimitExceeded
  

  Solution : identifiez l'origine du problème de quota. Par exemple, une application utilise de manière abusive le connecteur et crée inutilement des connexions. Vous pouvez également contacter l'assistance pour demander une augmentation du quota de l'API Cloud SQL Admin. Si l'erreur de quota apparaît au démarrage, vous devez redéployer l'application pour redémarrer le proxy. Si l'erreur de quota apparaît après le démarrage, un redéploiement est inutile.

Étapes suivantes

• Apprenez-en plus sur le proxy d'authentification Cloud SQL.
• Obtenez plus d'informations sur Identity and Access Management (IAM).
• En savoir plus sur les comptes de service
• Découvrez les deux niveaux de contrôle d'accès pour les instances Cloud SQL.
• Créez des utilisateurs et des bases de données.
• Découvrez comment vous connecter à une instance depuis une application.
• Découvrez le client psql.
• En savoir plus sur les Options de support