Connettiti utilizzando il proxy di autenticazione Cloud SQL

Questa pagina descrive come connetterti all'istanza Cloud SQL utilizzando il proxy di autenticazione Cloud SQL.

Per ulteriori informazioni sul funzionamento del proxy di autenticazione Cloud SQL, consulta Informazioni sul proxy di autenticazione Cloud SQL.

Panoramica

L'utilizzo del proxy di autenticazione Cloud SQL è il metodo consigliato per connettersi a un'istanza Cloud SQL. Il proxy di autenticazione Cloud SQL:

• Funziona con endpoint IP pubblici e privati
• Convalida le connessioni utilizzando le credenziali di un utente o di un account di servizio
• Incapsula la connessione in un livello SSL/TLS autorizzato per un'istanza Cloud SQL.

Alcuni servizi e applicazioni Google Cloud utilizzano il proxy di autenticazione Cloud SQL per fornire connessioni per percorsi IP pubblici con crittografia e autorizzazione, tra cui:

• Ambiente standard di App Engine
• Ambiente flessibile di App Engine
• Cloud Run Functions
• Cloud Run

Le applicazioni in esecuzione in Google Kubernetes Engine possono connettersi utilizzando il proxy di autenticazione Cloud SQL.

Consulta la guida rapida per l'utilizzo del proxy di autenticazione Cloud SQL per un'introduzione di base al suo utilizzo.

Puoi anche connetterti, con o senza il proxy di autenticazione Cloud SQL, utilizzando un client mysql da una macchina locale o da Compute Engine.

Prima di iniziare

Prima di poterti connettere a un'istanza Cloud SQL, svolgi i seguenti passaggi:

1. • Per un account utente o di servizio, assicurati che l'account abbia il ruolo Client Cloud SQL. Questo ruolo contiene l'autorizzazione cloudsql.instances.connect, che autorizza un entità a connettersi a tutte le istanze Cloud SQL di un progetto.

     Vai alla pagina IAM

   • Se vuoi, puoi includere una condizione IAM nel vincolo del criterio IAM che concede all'account l'autorizzazione per connettersi solo a un'istanza Cloud SQL specifica.

2. Enable the Cloud SQL Admin API.

   Enable the API

3. Installa e inizializza la gcloud CLI.
4. Facoltativo. Installa il client Docker del proxy di autenticazione Cloud SQL.

Scarica il proxy di autenticazione Cloud SQL

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

Avvia il proxy di autenticazione Cloud SQL

A seconda del linguaggio e dell'ambiente, puoi avviare il proxy di autenticazione Cloud SQL utilizzando socket TCP, socket Unix o l'immagine Docker del proxy di autenticazione Cloud SQL. Il file binario del proxy di autenticazione Cloud SQL si connette a una o più istanze Cloud SQL specificate sulla riga di comando e apre una connessione locale come TCP o una socket Unix. Altre applicazioni e altri servizi, come il codice dell'applicazione o gli strumenti client per la gestione del database, possono connettersi alle istanze Cloud SQL tramite queste connessioni socket TCP o 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

Connettiti al client mysql

1. Scarica MySQL Community Server per la tua piattaforma dalla pagina di download di MySQL Community Server.
   Il server della community include il client MySQL.
2. Installa Community Server seguendo le istruzioni riportate nella pagina di download.

Per ulteriori informazioni sull'installazione di MySQL, consulta Installazione e upgrade di MySQL.

La stringa di connessione utilizzata dipende dal fatto che tu abbia avviato il proxy di autenticazione Cloud SQL utilizzando un socket TCP o un socket UNIX o Docker.

Serve aiuto? Per assistenza nella risoluzione dei problemi relativi al proxy, consulta la sezione Risoluzione dei problemi di connessione del proxy di autenticazione Cloud SQL o la pagina Assistenza Cloud SQL.

Connettiti a un'applicazione

Puoi connetterti al proxy di autenticazione Cloud SQL da qualsiasi linguaggio che ti consenta di connetterti a una socket Unix o TCP. Di seguito sono riportati alcuni snippet di codice di esempi completi su GitHub per aiutarti a comprendere come interagiscono nella tua applicazione.

./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;
    }
}

Argomenti aggiuntivi

Argomenti della riga di comando del proxy di autenticazione Cloud SQL

Gli esempi riportati sopra riguardano i casi d'uso più comuni, ma il proxy di autenticazione Cloud SQL offre anche altre opzioni di configurazione che possono essere impostate con gli argomenti della riga di comando. Per assistenza sugli argomenti della riga di comando, utilizza il flag --help per visualizzare la documentazione più recente:

./cloud-sql-proxy --help

Consulta il file README nel repository GitHub di Cloud SQL Auth Proxy per altri esempi di utilizzo delle opzioni della riga di comando di Cloud SQL Auth Proxy.

Opzioni per l'autenticazione del proxy di autenticazione Cloud SQL

Tutte queste opzioni utilizzano un INSTANCE_CONNECTION_NAME come la stringa di connessione per identificare un'istanza Cloud SQL. Puoi trovare il valore INSTANCE_CONNECTION_NAME nella pagina Panoramica della tua istanza nella console Google Cloud o eseguendo il seguente comando:

gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME.

Ad esempio: gcloud sql instances describe --project myproject myinstance .

Alcune di queste opzioni utilizzano un file delle credenziali JSON che include la chiave privata RSA per l'account. Per istruzioni su come creare un file delle credenziali JSON per un account di servizio, consulta Creare un account di servizio.

Il proxy di autenticazione Cloud SQL offre diverse alternative per l'autenticazione, a seconda del tuo ambiente. Il proxy di autenticazione Cloud SQL controlla ciascuno dei seguenti elementi, nell'ordine indicato, utilizzando il primo trovato per tentare di autenticarsi:

1. Credenziali fornite dal flag file-delle-credenziali.

   Utilizza un account di servizio per creare e scaricare il file JSON associato e imposta il flag --credentials-file sul percorso del file quando avvii il proxy di autenticazione Cloud SQL. L'account di servizio deve disporre delle autorizzazioni richieste per l'istanza Cloud SQL.

   Per utilizzare questa opzione sulla riga di comando, invoca il comando cloud-sql-proxy con il flag --credentials-file impostato sul percorso e sul nome di un file di credenziali JSON. Il percorso può essere assoluto o relativo alla directory di lavoro corrente. Ad esempio:

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

   Per istruzioni dettagliate sull'aggiunta di ruoli IAM a un account di servizio, consulta Assegnare i ruoli agli account di servizio.

   Per saperne di più sui ruoli supportati da Cloud SQL, consulta Ruoli IAM per Cloud SQL.

2. Credenziali fornite da un token di accesso.

   Crea un token di accesso e invoca il comando cloud-sql-proxy con il flag --token impostato su un token di accesso OAuth 2.0. Ad esempio:

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

3. Le credenziali fornite da una variabile di ambiente.

   Questa opzione è simile all'utilizzo del flag --credentials-file, tranne per il fatto che specifichi il file delle credenziali JSON impostato nella variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS anziché utilizzare l'argomento della riga di comando --credentials-file.

4. Credenziali di un client gcloud CLI autenticato.

   Se hai installato gcloud CLI e hai eseguito l'autenticazione con il tuo account personale, il proxy di autenticazione Cloud SQL può utilizzare le stesse credenziali dell'account. Questo metodo è particolarmente utile per configurare un ambiente di sviluppo.

   Per consentire al proxy di autenticazione Cloud SQL di utilizzare le tue credenziali gcloud CLI, utilizza il seguente comando per autenticare gcloud CLI:

   gcloud auth application-default login

5. Le credenziali associate all'istanza Compute Engine.

   Se ti connetti a Cloud SQL da un'istanza Compute Engine, il proxy di autenticazione Cloud SQL può utilizzare l'account di servizio associato all'istanza Compute Engine. Se l'account di servizio dispone delle autorizzazioni richieste per l'istanza Cloud SQL, il proxy di autenticazione Cloud SQL si autentica correttamente.

   Se l'istanza Compute Engine si trova nello stesso progetto dell'istanza Cloud SQL, l'account di servizio predefinito per l'istanza Compute Engine dispone delle autorizzazioni necessarie per autenticare il proxy di autenticazione Cloud SQL. Se le due istanze si trovano in progetti diversi, devi aggiungere l'account di servizio dell'istanza Compute Engine al progetto contenente l'istanza Cloud SQL.

6. Account di servizio predefinito dell'ambiente

   Se il proxy di autenticazione Cloud SQL non riesce a trovare le credenziali in nessuno dei luoghi trattati in precedenza, segue la logica descritta in Configurazione dell'autenticazione per le applicazioni di produzione Server to Server. Alcuni ambienti (come Compute Engine, App Engine e altri) forniscono un account di servizio predefinito che l'applicazione può utilizzare per l'autenticazione per impostazione predefinita. Se utilizzi un account di servizio predefinito, questo deve disporre delle autorizzazioni descritte in Ruoli e autorizzazioni. Per saperne di più sull'approccio di Google Cloud all'autenticazione, consulta Panoramica dell'autenticazione.

Crea un account di servizio

1. Nella console Google Cloud, vai alla pagina Account di servizio.

   Vai ad Account di servizio

2. Seleziona il progetto che contiene l'istanza Cloud SQL.
3. Fai clic su Crea account di servizio.
4. Nel campo Nome account di servizio, inserisci un nome descrittivo per l'account di servizio.
5. Modifica l'ID account di servizio in un valore univoco e riconoscibile, quindi fai clic su Crea e continua.
6. Fai clic sul campo Seleziona un ruolo e seleziona uno dei seguenti ruoli:
   • Cloud SQL > Client Cloud SQL
   • Cloud SQL > Cloud SQL Editor
   • Cloud SQL > Amministratore Cloud SQL

7. Fai clic su Fine per completare la creazione dell'account di servizio.
8. Fai clic sul menu di azioni del nuovo account di servizio e seleziona Gestisci chiavi.
9. Fai clic sul menu a discesa Aggiungi chiave, quindi su Crea nuova chiave.
10. Verifica che il tipo di chiave sia JSON e fai clic su Crea.

    Il file della chiave privata viene scaricato sulla tua macchina. Puoi spostarlo in un'altra posizione. Tieni al sicuro il file della chiave.

Utilizzare il proxy di autenticazione Cloud SQL con IP privato

Per connetterti a un'istanza Cloud SQL utilizzando un IP privato, il proxy di autenticazione Cloud SQL deve trovarsi su una risorsa con accesso alla stessa rete VPC dell'istanza.

Il proxy di autenticazione Cloud SQL utilizza l'IP per stabilire una connessione con l'istanza Cloud SQL. Per impostazione predefinita, il proxy di autenticazione Cloud SQL tenta di connettersi utilizzando un indirizzo IPv4 pubblico.

Se l'istanza Cloud SQL ha solo IP privato o se sono configurati sia l'IP pubblico sia l'IP privato e vuoi che il proxy di autenticazione Cloud SQL utilizzi l'indirizzo IP privato, devi fornire la seguente opzione quando avvii il proxy di autenticazione Cloud SQL:

--private-ip

Utilizzare il proxy di autenticazione Cloud SQL con le istanze in cui è attivato Private Service Connect

Puoi utilizzare il proxy di autenticazione Cloud SQL per connetterti a un'istanza Cloud SQL con Private Service Connect abilitato.

Il proxy di autenticazione Cloud SQL è un connettore che fornisce accesso sicuro a questa istanza senza la necessità di reti autorizzate o di configurazione di SSL.

Per consentire le connessioni dei client del proxy di autenticazione Cloud SQL, devi configurare un record DNS che corrisponda al nome DNS consigliato fornito per l'istanza. Il record DNS è una mappatura tra una risorsa DNS e un nome di dominio.

Per ulteriori informazioni sull'utilizzo del proxy di autenticazione Cloud SQL per connetterti alle istanze con Private Service Connect abilitato, consulta Connessione tramite il proxy di autenticazione Cloud SQL.

Crea un account utente del database per il proxy di autenticazione Cloud SQL

Quando ti connetti all'istanza utilizzando il proxy di autenticazione Cloud SQL, fornisci un account utente per accedere all'istanza. Puoi utilizzare qualsiasi account utente del database per questo scopo. Tuttavia, poiché il proxy di autenticazione Cloud SQL si connette sempre da un nome host a cui non è possibile accedere tranne che dal proxy di autenticazione Cloud SQL, puoi creare un account utente che può essere utilizzato solo dal proxy di autenticazione Cloud SQL. Il vantaggio di questa operazione è che puoi specificare questo account senza una password senza compromettere la sicurezza della tua istanza o dei tuoi dati.

Per creare un account utente che può essere utilizzato solo con il proxy di autenticazione Cloud SQL, specifica il nome host come 'cloudsqlproxy~[IP_ADDRESS]'. Puoi anche utilizzare il carattere jolly per gli indirizzi IP, che avrà come risultato 'cloudsqlproxy~%'. Il nome completo dell'account utente sarà:

'[USER_NAME]'@'cloudsqlproxy~%'

o

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

Per assistenza sulla creazione di un utente, consulta Creare e gestire gli utenti. Per informazioni su come Cloud SQL funziona con gli account utente, consulta Utenti.

Esegui il proxy di autenticazione Cloud SQL in un processo separato

Può essere utile eseguire il proxy di autenticazione Cloud SQL in un processo di terminale Cloud Shell separato per evitare di mescolare l'output della console con quello di altri programmi. Utilizza la sintassi riportata di seguito per richiamare il proxy di autenticazione Cloud SQL in un processo separato.

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

Esegui il proxy di autenticazione Cloud SQL in un contenitore Docker

Per eseguire il proxy di autenticazione Cloud SQL in un container Docker, utilizza l'immagine Docker del proxy di autenticazione Cloud SQL disponibile nel Google Container Registry. Puoi installare l'immagine Docker del proxy di autenticazione Cloud SQL con questo comando gcloud:

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

Puoi avviare il proxy di autenticazione Cloud SQL utilizzando socket TCP o socket Unix, con i comandi riportati di seguito.

    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

Se utilizzi un'immagine ottimizzata per i container, usa una directory scrivibile al posto di /cloudsql, ad esempio:

v /mnt/stateful_partition/cloudsql:/cloudsql

Se utilizzi le credenziali fornite dall'istanza Compute Engine, non includere il parametro credential_file e la linea-v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Eseguire il proxy di autenticazione Cloud SQL come servizio

L'esecuzione del proxy di autenticazione Cloud SQL come servizio in background è un'opzione per lo sviluppo locale e i carichi di lavoro di produzione. Durante lo sviluppo, quando devi accedere alla tua istanza Cloud SQL, puoi avviare il servizio in background e interromperlo al termine.

Per i carichi di lavoro di produzione, al momento il proxy di autenticazione Cloud SQL non fornisce il supporto integrato per l'esecuzione come servizio Windows, ma è possibile utilizzare gestori di servizi di terze parti per eseguirlo come servizio. Ad esempio, puoi utilizzare NSSM per configurare il proxy di autenticazione Cloud SQL come servizio Windows. NSSM monitora il proxy di autenticazione Cloud SQL e lo riavvia automaticamente se smette di rispondere. Per ulteriori informazioni, consulta la documentazione di NSSM.

Applicare l'utilizzo del proxy di autenticazione Cloud SQL

Attiva l'utilizzo del proxy di autenticazione Cloud SQL in Cloud SQL utilizzando ConnectorEnforcement.

Se utilizzi un'istanza abilitata per Private Service Connect, è presente una limitazione. Se per l'istanza è attiva l'applicazione dei connettori, non puoi creare repliche di lettura per l'istanza. Analogamente, se l'istanza ha repliche di lettura, non puoi attivare l'applicazione dei connettori per l'istanza.

    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"
}

Suggerimenti per l'utilizzo di Cloud SQL Auth Proxy

Richiama il proxy di autenticazione Cloud SQL

Tutte le chiamate del proxy di esempio avviano il proxy di autenticazione Cloud SQL in background, quindi viene restituito un prompt. Riserva il terminale Cloud Shell per il proxy di autenticazione Cloud SQL per evitare che il relativo output venga mescolato con quello di altri programmi. Inoltre, l'output del proxy di autenticazione Cloud SQL può aiutarti a diagnosticare i problemi di connessione, quindi può essere utile acquisirlo in un file di log. Se non avvii il proxy di autenticazione Cloud SQL in background, l'output viene inviato a stdout, a meno che non venga reindirizzato.

Non è necessario utilizzare /cloudsql come directory per le socket del proxy di autenticazione Cloud SQL. Questo nome di directory è stato scelto per ridurre al minimo le differenze con le stringhe di connessione di App Engine. Tuttavia, se modifichi il nome della directory, mantieni la lunghezza complessiva al minimo; viene incorporata in una stringa più lunga che ha un limite di lunghezza imposto dal sistema operativo. Dipende dal sistema, ma in genere è compreso tra 91 e 108 caratteri. Su Linux, la lunghezza è solitamente definita come 108 e puoi utilizzare il seguente comando per verificarlo:

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

Utilizzare il proxy di autenticazione Cloud SQL per connettersi a più istanze

Puoi utilizzare un client proxy di autenticazione Cloud SQL locale per connetterti a più istanze Cloud SQL. Il modo in cui esegui questa operazione dipende dal fatto che tu stia utilizzando socket Unix o 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
  

Risolvere i problemi di connessione del proxy di autenticazione Cloud SQL

L'immagine Docker del proxy di autenticazione Cloud SQL si basa su una versione specifica del proxy di autenticazione Cloud SQL. Quando diventa disponibile una nuova versione del proxy di autenticazione Cloud SQL, estrai la nuova versione dell'immagine Docker del proxy di autenticazione Cloud SQL per mantenere aggiornato il tuo ambiente. Puoi vedere la versione corrente del proxy di autenticazione Cloud SQL controllando la pagina delle release di GitHub del proxy di autenticazione Cloud SQL.

Se hai difficoltà a connetterti all'istanza Cloud SQL utilizzando il proxy di autenticazione Cloud SQL, ecco alcuni passaggi da seguire per provare a capire cosa causa il problema.

• Verifica di utilizzare l'indirizzo IP per connetterti all'istanza e non l'endpoint di scrittura.

• Controlla l'output del proxy di autenticazione Cloud SQL.

  Spesso l'output del proxy di autenticazione Cloud SQL può aiutarti a determinare l'origine del problema e come risolverlo. Invia l'output a un file o controlla il terminale Cloud Shell in cui hai avviato il proxy di autenticazione Cloud SQL.

• Se ricevi un errore 403 notAuthorized e utilizzi un account di servizio per autenticare il proxy di autenticazione Cloud SQL, assicurati che l'account di servizio disponga delle autorizzazioni corrette.

  Puoi controllare l'account di servizio cercando il relativo ID nella pagina IAM. Deve avere l'autorizzazione cloudsql.instances.connect. I ruoli predefiniti Cloud SQL Admin, Client e Editor dispongono di questa autorizzazione.

• Se ti connetti da App Engine e ricevi un errore 403 notAuthorized, controlla il valore app.yamlcloud_sql_instances per verificare se il nome della connessione all'istanza contiene errori ortografici o è errato. I nomi delle connessioni all'istanza sono sempre nel formato PROJECT:REGION:INSTANCE.

  Inoltre, verifica che l'account di servizio App Engine (ad esempio $PROJECT_ID@appspot.gserviceaccount.com) abbia il ruolo IAM client Cloud SQL.

  Se il servizio App Engine si trova in un progetto (progetto A) e il database in un altro (progetto B), questo errore indica che all'account del servizio App Engine non è stato assegnato il ruolo IAM client Cloud SQL nel progetto con il database (progetto B).

• Assicurati di attivare l'API Cloud SQL Admin.

  In caso contrario, nei log del proxy di autenticazione Cloud SQL viene visualizzato un output simile a Error 403: Access Not Configured.

• Se includi più istanze nell'elenco delle istanze, assicurati di utilizzare una virgola come delimitatore, senza spazi. Se utilizzi TCP, assicurati di specificare porte diverse per ogni istanza.

• Se esegui la connessione utilizzando socket UNIX, verifica che i socket siano stati creati elencando la directory che hai fornito quando hai avviato il proxy di autenticazione Cloud SQL.

• Se hai un criterio firewall in uscita, assicurati che consenta le connessioni alla porta 3307 sull'istanza Cloud SQL di destinazione.

• Puoi verificare che il proxy di autenticazione Cloud SQL sia stato avviato correttamente esaminando i log nella sezione Operations > Logging > Logs Explorer della console Google Cloud. Un'operazione riuscita è simile alla seguente:

  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
  

• Problemi di quota: quando viene superata la quota dell'API Cloud SQL Admin, il proxy di autenticazione Cloud SQL si avvia con il seguente messaggio di errore:

  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
  

  Una volta che un'applicazione si connette al proxy, quest'ultimo segnala il seguente errore:

  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
  

  Soluzione: identifica la fonte del problema di quota, ad esempio un'applicazione che utilizza in modo improprio il connettore e crea inutilmente nuove connessioni oppure contatta l'assistenza per richiedere un aumento della quota dell'API Cloud SQL Admin. Se l'errore di quota viene visualizzato all'avvio, devi eseguire nuovamente il deployment dell'applicazione per riavviare il proxy. Se l'errore di quota viene visualizzato dopo l'avvio, non è necessario eseguire nuovamente il deployment.

Passaggi successivi

• Scopri di più sul proxy di autenticazione Cloud SQL.
• Scopri di più su Identity and Access Management (IAM).
• Scopri di più sugli account di servizio.
• Scopri i due livelli di controllo dell'accesso per le istanze Cloud SQL.
• Crea utenti e database.
• Scopri come collegarti all'istanza dalla tua applicazione.
• Scopri di più su MySQL Client.
• Scopri le opzioni di assistenza.