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

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
• Fonctions Cloud Run
• Cloud Run

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

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 mysql à 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

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

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.

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

gcloud sql instances describe INSTANCE_NAME

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

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.14.1 --unix-socket=/cloudsql \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

-v /mnt/stateful_partition/cloudsql:/cloudsql

Se connecter avec le client mysql

1. Téléchargez le serveur MySQL Community Server destiné à votre plate-forme sur la page de téléchargement de MySQL Community Server.
   Ce serveur inclut le client MySQL.
2. Installez le serveur Community Server conformément aux instructions indiquées sur la page de téléchargement.

Pour en savoir plus sur l'installation de MySQL, consultez la section Installer et mettre à niveau MySQL.

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.

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.

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

import os

import sqlalchemy


def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a TCP connection pool for a Cloud SQL instance of MySQL."""
    # 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. 3306

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

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

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

  // Saving credentials in environment variables is convenient, but not secure - consider a more
  // secure solution such as 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:mysql://<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:mysql://%s:%s/%s", INSTANCE_HOST, DB_PORT, DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "mysql"
    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);
  }
}

const mysql = require('promise-mysql');
const fs = require('fs');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of MySQL.
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 = {
    host: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
    port: process.env.DB_PORT, // e.g. '3306'
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    // ... Specify additional properties here.
    ...config,
  };
  // Establish a connection to the database.
  return mysql.createPool(dbConfig);
};

package cloudsql

import (
	"crypto/tls"
	"crypto/x509"
	"database/sql"
	"errors"
	"fmt"
	"log"
	"os"

	"github.com/go-sql-driver/mysql"
)

// connectTCPSocket initializes a TCP connection pool for a Cloud SQL
// instance of MySQL.
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'
		dbName    = mustGetenv("DB_NAME")       // e.g. 'my-database'
		dbPort    = mustGetenv("DB_PORT")       // e.g. '3306'
		dbTCPHost = mustGetenv("INSTANCE_HOST") // e.g. '127.0.0.1' ('172.17.0.1' if deployed to GAE Flex)
	)

	dbURI := fmt.Sprintf("%s:%s@tcp(%s:%s)/%s?parseTime=true",
		dbUser, dbPwd, dbTCPHost, dbPort, dbName)


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

	// ...

	return dbPool, nil
}

using MySql.Data.MySqlClient;
using System;

namespace CloudSql
{
    public class MySqlTcp
    {
        public static MySqlConnectionStringBuilder NewMysqlTCPConnectionString()
        {
            // Equivalent connection string:
            // "Uid=<DB_USER>;Pwd=<DB_PASS>;Host=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new MySqlConnectionStringBuilder()
            {
                // 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.
                Server = Environment.GetEnvironmentVariable("INSTANCE_HOST"),   // e.g. '127.0.0.1'
                // Set Host to 'cloudsql' when deploying to App Engine Flexible environment
                UserID = 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 = MySqlSslMode.Disabled,
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;

        }
    }
}

tcp: &tcp
  adapter: mysql2
  # 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") { 3306 }%>

namespace Google\Cloud\Samples\CloudSQL\MySQL;

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('mysql: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/mysql/connect-external-app',
                    $e->getMessage()
                ),
                $e->getCode(),
                $e
            );
        }

        return $conn;
    }
}

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

import os

import sqlalchemy


def connect_unix_socket() -> sqlalchemy.engine.base.Engine:
    """Initializes a Unix socket connection pool for a Cloud SQL instance of MySQL."""
    # 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:
        # mysql+pymysql://<db_user>:<db_pass>@/<db_name>?unix_socket=<socket_path>/<cloud_sql_instance_name>
        sqlalchemy.engine.url.URL.create(
            drivername="mysql+pymysql",
            username=db_user,
            password=db_pass,
            database=db_name,
            query={"unix_socket": unix_socket_path},
        ),
        # ...
    )
    return pool

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:mysql:///<DB_NAME>?cloudSqlInstance=<INSTANCE_CONNECTION_NAME>&
    // socketFactory=com.google.cloud.sql.mysql.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:mysql:///%s", DB_NAME));
    config.setUsername(DB_USER); // e.g. "root", "mysql"
    config.setPassword(DB_PASS); // e.g. "my-password"

    config.addDataSourceProperty("socketFactory", "com.google.cloud.sql.mysql.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);
  }
}

const mysql = require('promise-mysql');

// createUnixSocketPool initializes a Unix socket connection pool for
// a Cloud SQL instance of MySQL.
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 mysql.createPool({
    user: process.env.DB_USER, // e.g. 'my-db-user'
    password: process.env.DB_PASS, // e.g. 'my-db-password'
    database: process.env.DB_NAME, // e.g. 'my-database'
    socketPath: process.env.INSTANCE_UNIX_SOCKET, // e.g. '/cloudsql/project:region:instance'
    // Specify additional properties here.
    ...config,
  });
};

using MySql.Data.MySqlClient;
using System;

namespace CloudSql
{
    public class MySqlUnix
    {
        public static MySqlConnectionStringBuilder NewMysqlUnixSocketConnectionString()
        {
            // Equivalent connection string:
            // "Server=<INSTANCE_UNIX_SOCKET>;Uid=<DB_USER>;Pwd=<DB_PASS>;Database=<DB_NAME>;Protocol=unix"
            var connectionString = new MySqlConnectionStringBuilder()
            {
                // The Cloud SQL proxy provides encryption between the proxy and instance.
                SslMode = MySqlSslMode.Disabled,

                // 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.
                Server = Environment.GetEnvironmentVariable("INSTANCE_UNIX_SOCKET"), // e.g. '/cloudsql/project:region:instance'
                UserID = 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'
                ConnectionProtocol = MySqlConnectionProtocol.UnixSocket
            };
            connectionString.Pooling = true;
            // Specify additional properties here.
            return connectionString;
        }
    }
}

package cloudsql

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

	_ "github.com/go-sql-driver/mysql"
)

// connectUnixSocket initializes a Unix socket connection pool for
// a Cloud SQL instance of MySQL.
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.", 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'
		dbName         = mustGetenv("DB_NAME")              // e.g. 'my-database'
		unixSocketPath = mustGetenv("INSTANCE_UNIX_SOCKET") // e.g. '/cloudsql/project:region:instance'
	)

	dbURI := fmt.Sprintf("%s:%s@unix(%s)/%s?parseTime=true",
		dbUser, dbPwd, unixSocketPath, dbName)

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

	// ...

	return dbPool, nil
}

unix: &unix
  adapter: mysql2
  # 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
  socket: "<%= ENV["INSTANCE_UNIX_SOCKET"] %>"

namespace Google\Cloud\Samples\CloudSQL\MySQL;

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(
                'mysql:dbname=%s;unix_socket=%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/mysql/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

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

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

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.

Créer un compte utilisateur de base de données pour le proxy d'authentification Cloud SQL

Lorsque vous vous connectez à votre instance à l'aide du proxy d'authentification Cloud SQL, vous fournissez un compte utilisateur pour vous connecter à l'instance. À cette fin, vous pouvez utiliser n'importe quel compte utilisateur de base de données. Toutefois, comme le proxy d'authentification Cloud SQL se connecte toujours à partir d'un nom d'hôte auquel seul le proxy a accès, il est recommandé de créer un compte utilisateur spécifique au proxy Cloud SQL. L'avantage de cette méthode, c'est que vous pouvez spécifier ce compte sans mot de passe, et ce sans compromettre la sécurité de votre instance ou de vos données.

Pour créer un compte utilisateur qui ne peut être utilisé qu'avec le proxy d'authentification Cloud SQL, spécifiez le nom d'hôte 'cloudsqlproxy~[IP_ADDRESS]'. Vous pouvez également utiliser le caractère générique d'adresse IP, ce qui donne : 'cloudsqlproxy~%'. Le nom de compte utilisateur complet serait donc :

'[USER_NAME]'@'cloudsqlproxy~%'

ou

'[USER_NAME]'@'cloudsqlproxy~[IP_ADDRESS]'

Pour obtenir de l'aide sur la création d'un utilisateur, consultez la section Créer et gérer des utilisateurs. Pour plus d'informations sur le fonctionnement de Cloud SQL avec les comptes utilisateur, consultez la page Utilisateurs.

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.

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

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.14.1

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.

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

    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.14.1 --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.

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.

Si vous utilisez une instance avec Private Service Connect activé, vous devez tenir compte d'une limitation. Si l'instance dispose d'une application des connecteurs activée, vous ne pouvez pas créer d'instances dupliquées avec accès en lecture pour l'instance. De même, si l'instance comporte des instances dupliquées avec accès en lecture, vous ne pouvez pas activer l'application des connecteurs pour l'instance.

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

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

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

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"

$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

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "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"
}

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

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

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"

$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

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "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"
}

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.

      ./cloud-sql-proxy --unix-socket /cloudsql \
      myProject:us-central1:myInstance myProject:us-central1:myInstance2 &
      mysql -u myUser -S /cloudsql/myProject:us-central1:myInstance2
  

    # 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=3306" \
    "myProject:us-central1:myInstance2?port=1234"

    # Connect to "myInstance" using port 3306 on your machine:
    mysql -u myInstanceUser --host 127.0.0.1  --port 3306

    # Connect to "myInstance2" using port 1234 on your machine:
    mysql -u myInstance2User --host 127.0.0.1  --port 1234
  

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 que vous utilisez l'adresse IP pour vous connecter à l'instance, et non le point de terminaison d'écriture.

• 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, $PROJECT_ID@appspot.gserviceaccount.com) 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.

• 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/3306 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.
• Informez-vous sur le client MySQL.
• En savoir plus sur les Options de support