Connessione tramite il proxy di autenticazione Cloud SQL

Questa pagina descrive come connettersi 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 la connessione a un'istanza Cloud SQL. Il proxy di autenticazione Cloud SQL:

  • Compatibile con endpoint IP pubblici e privati
  • Convalida le connessioni utilizzando le credenziali per un account utente o di servizio
  • Aggrega 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:

Le applicazioni in esecuzione in Google Kubernetes Engine possono connettersi mediante 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 sqlcmd da una macchina locale o Compute Engine.

Prima di iniziare

Prima di poterti connettere a un'istanza Cloud SQL:

    • Per un account utente o di servizio, assicurati che l'account disponga del 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

    • Facoltativamente, puoi includere una condizione IAM nell'associazione dei criteri IAM che concede all'account l'autorizzazione di connessione a una sola istanza Cloud SQL specifica.

  2. Attiva l'API Cloud SQL Admin.

    Abilita l'API

  3. Installa e inizializza l'interfaccia a riga di comando gcloud.
  4. (Facoltativo) Installa il client Docker Cloud Auth proxy.

Scarica il proxy di autenticazione Cloud SQL

Linux a 64 bit

  1. Scarica il proxy di autenticazione Cloud SQL: 
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
  2. Rendi eseguibile il proxy di autenticazione Cloud SQL: 
    chmod +x cloud_sql_proxy

Linux a 32 bit

  1. Scarica il proxy di autenticazione Cloud SQL: 
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
  2. Se non viene trovato il comando wget, esegui sudo apt-get install wget e ripeti il comando di download.
  3. Rendi eseguibile il proxy di autenticazione Cloud SQL: 
    chmod +x cloud_sql_proxy

macOS a 64 bit

  1. Scarica il proxy di autenticazione Cloud SQL: 
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
  2. Rendi eseguibile il proxy di autenticazione Cloud SQL: 
    chmod +x cloud_sql_proxy

macOS a 32 bit

  1. Scarica il proxy di autenticazione Cloud SQL: 
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
  2. Rendi eseguibile il proxy di autenticazione Cloud SQL: 
    chmod +x cloud_sql_proxy

Mac M1

  1. Scarica il proxy di autenticazione Cloud SQL: 
      curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.arm64
  2. Rendi eseguibile il proxy di autenticazione Cloud SQL: 
      chmod +x cloud_sql_proxy

Windows a 64 bit

Fai clic con il tasto destro del mouse su https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe e seleziona Salva link con nome per scaricare il proxy di autenticazione Cloud SQL. Rinomina il file in cloud_sql_proxy.exe.

Windows a 32 bit

Fai clic con il tasto destro del mouse su https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe e seleziona Salva link con nome per scaricare il proxy di autenticazione Cloud SQL. Rinomina il file in cloud_sql_proxy.exe.

Immagine Docker proxy Cloud SQL Auth

Per comodità, diverse immagini container che contengono il proxy di autenticazione Cloud SQL sono disponibili su GitHub nel repository proxy di Cloud SQL Auth. Puoi eseguire il pull dell'immagine più recente sulla tua macchina locale usando Docker con il seguente comando: 
docker pull gcr.io/cloudsql-docker/gce-proxy:1.31.2

Altro sistema operativo

Per altri sistemi operativi non inclusi in questa versione, puoi compilare il proxy di autenticazione Cloud SQL dall'origine.

Avvia il proxy di autenticazione Cloud SQL

Puoi avviare il proxy di autenticazione Cloud SQL utilizzando i socket TCP o l'immagine Docker del proxy di autenticazione Cloud SQL. Il programma binario del proxy di autenticazione Cloud SQL si connette a una o più istanze Cloud SQL specificate nella riga di comando e apre una connessione locale come socket TCP. Altri servizi e applicazioni, come il codice dell'applicazione o gli strumenti client di gestione del database, possono connettersi alle istanze Cloud SQL tramite tale connessione socket TCP.

Prese TCP

Per le connessioni TCP, il proxy di autenticazione Cloud SQL rimane in ascolto su localhost(127.0.0.1) per impostazione predefinita. Quindi, quando specifichi tcp:PORT_NUMBER per un'istanza, la connessione locale è 127.0.0.1:PORT_NUMBER.

In alternativa, puoi specificare un indirizzo diverso per la connessione locale. Ad esempio, ecco come impostare il proxy di autenticazione Cloud SQL in ascolto su 0.0.0.0:1234 per la connessione locale:

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234

  1. Copia il tuo INSTANCE_CONNECTION_NAME. Puoi trovarlo nella pagina Panoramica dell'istanza in Google Cloud Console oppure eseguendo il comando seguente:

    gcloud sql instances describe INSTANCE_NAME
    .

    Ad esempio: myproject:myregion:myinstance.

  2. Se l'istanza ha sia un IP pubblico sia un IP privato e vuoi che il proxy di autenticazione Cloud SQL utilizzi l'indirizzo IP privato, devi fornire la seguente opzione all'avvio del proxy di autenticazione Cloud SQL: 
    -ip_address_types=PRIVATE
  3. Se utilizzi un account di servizio per autenticare il proxy di autenticazione Cloud SQL, nota la posizione sul computer client del file della chiave privata creato al momento della creazione dell'account di servizio.
  4. Avvia il proxy di autenticazione Cloud SQL.

    Alcune possibili stringhe di chiamata proxy Cloud SQL Auth:

    • Utilizzo dell'autenticazione Cloud SDK: 
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:1433
      La porta specificata non deve essere già in uso, ad esempio per un server di database locale.
    • Utilizzo di un account di servizio e inclusione esplicita del nome della connessione all'istanza (consigliato per gli ambienti di produzione): 
      ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:1433 \
                  -credential_file=PATH_TO_KEY_FILE &

    Per ulteriori informazioni sulle opzioni del proxy di autenticazione Cloud SQL, vedi Opzioni per l'autenticazione del proxy di autenticazione Cloud SQL e Opzioni per specificare le istanze.

Docker

Per eseguire il proxy di autenticazione Cloud SQL in un container Docker, utilizza l'immagine Docker del proxy di autenticazione Cloud SQL disponibile in Google Container Registry.

Puoi avviare il proxy di autenticazione Cloud SQL utilizzando i socket TCP o Unix, con i comandi mostrati di seguito. Le opzioni utilizzano un INSTANCE_CONNECTION_NAME come stringa di connessione per identificare un'istanza Cloud SQL. Puoi trovare INSTANCE_CONNECTION_NAME nella pagina Panoramica dell'istanza in Google Cloud Console oppure eseguendo il comando seguente:

gcloud sql instances describe INSTANCE_NAME
.

Ad esempio: myproject:myregion:myinstance.

A seconda del linguaggio e dell'ambiente, puoi avviare il proxy di autenticazione Cloud SQL utilizzando socket TCP o Unix. I socket Unix non sono supportati per le applicazioni scritte nel linguaggio di programmazione Java o per l'ambiente Windows.

Utilizzo di socket TCP

docker run -d \\
  -v PATH_TO_KEY_FILE:/config \\
  -p 127.0.0.1:1433:1433 \\
  gcr.io/cloudsql-docker/gce-proxy:1.31.2 /cloud_sql_proxy \\
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1433 -credential_file=/config

Se utilizzi le credenziali fornite dall'istanza di Compute Engine, non includere il parametro credential_file e la riga -v PATH_TO_KEY_FILE:/config.

Specifica sempre il prefisso 127.0.0.1 in -p in modo che il proxy di autenticazione Cloud SQL non sia esposto all'esterno dell'host locale. Il parametro "0.0.0.0" nel parametro instances è necessario per rendere la porta accessibile dall'esterno del container Docker.

Utilizzo di socket Unix

docker run -d -v /cloudsql:/cloudsql \\
  -v PATH_TO_KEY_FILE:/config \\
  gcr.io/cloudsql-docker/gce-proxy:1.31.2 /cloud_sql_proxy -dir=/cloudsql \\
  -instances=INSTANCE_CONNECTION_NAME -credential_file=/config

Se utilizzi le credenziali fornite dall'istanza di Compute Engine, non includere il parametro credential_file e la riga -v PATH_TO_KEY_FILE:/config.

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

-v /mnt/stateful_partition/cloudsql:/cloudsql

Puoi specificare più istanze, separate da virgole. Puoi anche utilizzare i metadati di Compute Engine per determinare in modo dinamico le istanze a cui connetterti. Scopri di più sui parametri del proxy di autenticazione Cloud SQL.

Connettiti al client sqlcmd

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

Prese TCP

  1. Avvia il client sqlcmd: 
    sqlcmd -S tcp:127.0.0.1,1433 -U USERNAME -P PASSWORD

    Quando ti connetti utilizzando i socket TCP, si accede al proxy di autenticazione Cloud SQL tramite 127.0.0.1.

  2. Se richiesto, inserisci la password.
  3. Viene visualizzato il prompt di sqlcmd.

Serve aiuto? Per assistenza per la risoluzione dei problemi del proxy, vedi Risoluzione dei problemi relativi alle connessioni proxy Cloud Auth o visita la pagina Assistenza di Cloud SQL.

Connettiti con un'applicazione

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

Connessione con TCP

Dichiarazione di chiamata proxy Cloud SQL Auth:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:1433 &

Python

Per vedere questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

cloud-sql/sql-server/sqlalchemy/connect_tcp.py 
import os

import sqlalchemy

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

    driver_name = "mssql+pytds"
    query = {
        "driver": "ODBC Driver 17 for SQL Server"
    }
    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # <driver_name>://<db_user>:<db_pass>@<db_host>:<db_port>/<db_name>?driver=ODBC+Driver+17+for+SQL+Server
        sqlalchemy.engine.url.URL.create(
            drivername=driver_name,
            username=db_user,
            password=db_pass,
            database=db_name,
            host=db_host,
            port=db_port,
            query=query,
        ),
        # ...
    )

    return pool

Java

Per vedere questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

Nota:

  • CLOUD_SQL_CONNECTION_NAME deve essere rappresentata come <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
  • L'uso dell'argomento ipTypes=PRIVATE impone a SocketFactory di connettersi con un IP privato associato a un'istanza
  • Consulta i requisiti di versione di fabbrica del socket JDBC per il file pom.xml qui.

cloud-sql/sqlserver/servlet/src/main/java/com/example/cloudsql/TcpConnectionPoolFactory.java 

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

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

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

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

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

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

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

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

Node.js

Per vedere questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

cloud-sql/sqlserver/mssql/connect-tcp.js 
const mssql = require('mssql');

// createTcpPool initializes a TCP connection pool for a Cloud SQL
// instance of SQL Server.
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 = {
    server: process.env.INSTANCE_HOST, // e.g. '127.0.0.1'
    port: parseInt(process.env.DB_PORT), // e.g. 1433
    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'
    options: {
      trustServerCertificate: true,
    },
    // ... Specify additional properties here.
    ...config,
  };
  return await mssql.connect(dbConfig);
};

Go

Per vedere questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

cloudsql/sqlserver/database-sql/connect_tcp.go 
package cloudsql

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

	_ "github.com/denisenkom/go-mssqldb"
)

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

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

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

	// ...

	return dbPool, nil
}

C#

Per vedere questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

cloud-sql/sql-server/ConnectTcp.cs 
using Microsoft.Data.SqlClient;
using System;

namespace CloudSql
{
    public class SqlServerTcp
    {
        public static SqlConnectionStringBuilder NewSqlServerTCPConnectionString()
        {
            // Equivalent connection string:
            // "User Id=<DB_USER>;Password=<DB_PASS>;Server=<INSTANCE_HOST>;Database=<DB_NAME>;"
            var connectionString = new SqlConnectionStringBuilder()
            {
                // 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.
                DataSource = 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'
                InitialCatalog = Environment.GetEnvironmentVariable("DB_NAME"), // e.g. 'my-database'

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

Ruby

Per vedere questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

cloud-sql/sqlserver/activerecord/config/database_tcp.yml 
tcp: &tcp
  adapter: sqlserver
  # 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") { 1433 }%>

PHP

Per vedere questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

cloud_sql/sqlserver/pdo/src/DatabaseTcp.php 
namespace Google\Cloud\Samples\CloudSQL\SQLServer;

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(
                'sqlsrv:server=%s;Database=%s',
                $instanceHost,
                $dbName
            );

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

        return $conn;
    }
}

Argomenti aggiuntivi

Argomenti della riga di comando del proxy Cloud SQL Auth

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

./cloud_sql_proxy -help

Per ulteriori esempi su come utilizzare le opzioni della riga di comando del proxy di autenticazione Cloud SQL, vedi README nel repository GitHub di Cloud SQL Auth.

Opzioni per l'autenticazione del proxy di autenticazione Cloud SQL

Tutte queste opzioni utilizzano un INSTANCE_CONNECTION_NAME come stringa di connessione per identificare un'istanza Cloud SQL. Puoi trovare INSTANCE_CONNECTION_NAME nella pagina Panoramica dell'istanza in Google Cloud Console oppure eseguendo il comando seguente:

gcloud sql instances describe INSTANCE_NAME --project PROJECT_ID.

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

Alcune di queste opzioni utilizzano un file di credenziali JSON che include la chiave privata RSA per l'account. Per istruzioni sulla creazione di un file delle credenziali JSON per un account di servizio, consulta la sezione Creazione di un account di servizio.

Il proxy di autenticazione Cloud SQL offre diverse alternative per l'autenticazione, in base all'ambiente. Il proxy di autenticazione Cloud SQL verifica la presenza di ciascuno dei seguenti elementi, nel seguente ordine, utilizzando il primo che rileva per tentare di eseguire l'autenticazione:

  1. Credenziali fornite dal flag credential_file.

    Usa un account di servizio per creare e scaricare il file JSON associato e impostare il flag -credential_file sul percorso del file quando avvii il proxy di autenticazione Cloud SQL. L'account di servizio deve avere le autorizzazioni richieste per l'istanza Cloud SQL.

    Per utilizzare questa opzione dalla riga di comando, richiama il comando cloud_sql_proxy con il flag -credential_file impostato sul percorso e sul nome file di un file delle credenziali JSON. Il percorso può essere assoluto o relativo alla directory di lavoro corrente. Ad esempio: 

    ./cloud_sql_proxy -credential_file=PATH_TO_KEY_FILE \
                  -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER

    Per istruzioni dettagliate sull'aggiunta di ruoli IAM a un account di servizio, consulta la pagina relativa alla concessione dei ruoli agli account di servizio.

    Per maggiori informazioni 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 richiama 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 \
                  -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER

  3. Credenziali fornite da una variabile di ambiente.

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

  4. Credenziali di un client gcloud autenticato.

    Se hai installato l'interfaccia a riga di comando gcloud 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 implementare un ambiente di sviluppo.

    Se non è stato selezionato alcun account per gcloud auth login, il proxy di autenticazione Cloud SQL cerca un account selezionato per gcloud auth application-default login.

  5. Credenziali associate all'istanza di Compute Engine.

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

    Se l'istanza di Compute Engine si trova nello stesso progetto dell'istanza di Cloud SQL, l'account di servizio predefinito per l'istanza di Compute Engine dispone delle autorizzazioni necessarie per l'autenticazione del proxy di autenticazione Cloud SQL. Se le due istanze si trovano in progetti diversi, devi aggiungere l'account di servizio dell'istanza di Compute Engine al progetto contenente l'istanza di 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 descritti in precedenza, segue la logica documentata in Configurazione dell'autenticazione per le applicazioni di produzione server-server. Alcuni ambienti (come Compute Engine, App Engine e altri) forniscono un account di servizio predefinito che la tua applicazione può utilizzare per l'autenticazione per impostazione predefinita. Se utilizzi un account di servizio predefinito, deve avere le autorizzazioni descritte in ruoli e autorizzazioni Per saperne di più sull'approccio di Google Cloud all'autenticazione, consulta la Panoramica dell'autenticazione.

Crea un account di servizio

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

    Vai agli 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. Cambia l'ID account di servizio in un valore univoco e riconoscibile e fai clic su Crea e continua.
  6. Fai clic nel campo Seleziona un ruolo e seleziona uno dei seguenti ruoli:
    • Client Cloud SQL > Cloud SQL
    • Cloud SQL > Editor Cloud SQL
    • Amministratore Cloud SQL > Cloud SQL

  7. Fai clic su Fine per completare la creazione dell'account di servizio.
  8. Fai clic sul menu azioni per il 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 Create (Crea).

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

Utilizza 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 la tua 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 un IP privato, il proxy di autenticazione Cloud SQL utilizza l'indirizzo IP privato per connettersi.

Se l'istanza ha sia un IP pubblico sia un IP privato e vuoi che il proxy di autenticazione Cloud SQL utilizzi l'indirizzo IP privato, devi fornire la seguente opzione all'avvio del proxy di autenticazione Cloud SQL:

-ip_address_types=PRIVATE

Esegui il proxy di autenticazione Cloud SQL in un processo separato

L'esecuzione del proxy di autenticazione Cloud SQL in un processo terminale separato di Cloud Shell può essere utile, per evitare di combinare l'output della console con l'output di altri programmi. Utilizza la sintassi mostrata di seguito per richiamare il proxy di autenticazione Cloud SQL in un processo separato.

Linux

Su Linux o macOS, utilizza una riga finale & nella riga di comando per avviare il proxy di autenticazione Cloud SQL in un processo separato:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE &

Windows

In Windows PowerShell, usa il comando Start-Process per avviare il proxy di autenticazione Cloud SQL in un processo separato:

Start-Process -filepath "cloud_sql_proxy.exe"
  -ArgumentList "-instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE"

Esegui il proxy di autenticazione Cloud SQL in un container Docker

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

docker pull gcr.io/cloudsql-docker/gce-proxy:1.31.2

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

Prese TCP

    docker run -d \
      -v PATH_TO_KEY_FILE:/config \
      -p 127.0.0.1:1433:1433 \
      gcr.io/cloudsql-docker/gce-proxy:1.31.2 /cloud_sql_proxy \
      -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1433 \
      -credential_file=/config

Prese Unix

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/config \
      gcr.io/cloudsql-docker/gce-proxy:1.31.2 /cloud_sql_proxy -dir=/cloudsql \
      -instances=INSTANCE_CONNECTION_NAME
      -credential_file=/config/PATH_TO_KEY_FILE

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

-v /mnt/stateful_partition/cloudsql:/cloudsql

Se utilizzi le credenziali fornite dall'istanza di Compute Engine, non includere il parametro credential_file e la riga -v PATH_TO_KEY_FILE:/config.

Esecuzione del proxy di autenticazione Cloud SQL come servizio

L'esecuzione del proxy di autenticazione Cloud SQL come servizio in background può essere utile per lo sviluppo e il test locali. Quando devi accedere all'istanza Cloud SQL, puoi avviare il servizio in background e arrestarlo quando hai finito.

  • Il proxy di autenticazione Cloud SQL attualmente non fornisce 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 e NSSM monitora il proxy di autenticazione Cloud SQL e lo riavvia automaticamente se smette di rispondere. Per ulteriori informazioni, consulta la documentazione NSSM.

Connessione quando è richiesto SSL

Suggerimenti per lavorare con il proxy di autenticazione Cloud SQL

Utilizza il proxy di autenticazione Cloud SQL per connetterti a più istanze

Puoi utilizzare un client proxy di autenticazione Cloud SQL locale per connetterti a più istanze Cloud SQL. Il modo in cui puoi farlo dipende dal fatto che utilizzi socket Unix o TCP.

Prese TCP

Quando ti connetti tramite TCP, devi specificare una porta sulla tua macchina affinché il proxy di autenticazione Cloud SQL possa rimanere in ascolto per ogni istanza di Cloud SQL. Quando ti connetti a più istanze Cloud SQL, ogni porta specificata deve essere univoca e disponibile per essere utilizzata sul tuo computer.

Ad esempio:

    # 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 -instances=myProject:us-central1:myInstance=tcp:1433,myProject:us-central1:myInstance2=tcp:1234

    # Connect to "myInstance" using port 1433 on your machine:
    sqlcmd -U myUser -S "127.0.0.1,1433"

    # Connect to "myInstance2" using port 1234 on your machine:
    sqlcmd -U myUser -S "127.0.0.1,1234"

Risoluzione dei problemi di connessione al 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 è disponibile una nuova versione del proxy di autenticazione Cloud SQL, esegui il pull della nuova versione dell'immagine Docker del proxy di autenticazione Cloud SQL per mantenere aggiornato il tuo ambiente. Puoi visualizzare la versione corrente del proxy di autenticazione Cloud SQL controllando la pagina delle release di GitHub di Cloud SQL Auth.

Se hai difficoltà a connetterti alla tua istanza Cloud SQL utilizzando il proxy di autenticazione Cloud SQL, ecco alcuni suggerimenti per cercare di capire cosa causa il problema.

  • 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. Indirizza l'output a un file oppure osserva il terminale Cloud Shell da 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 cercandone l'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 visualizzi un errore 403 notAuthorized, controlla che il valore del app.yaml cloud_sql_instances errore per il nome dell'istanza non sia corretto. I nomi di connessione delle istanze sono sempre nel formato PROJECT:REGION:INSTANCE.

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

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

  • Assicurati di abilitare l'API Cloud SQL Admin.

    In caso contrario, nei log del proxy di autenticazione Cloud SQL vedrai un output come Error 403: Access Not Configured.

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

  • Se ti connetti utilizzando i socket UNIX, verifica che 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 Operazioni > Logging > Esplora log di Google Cloud Console. Un'operazione riuscita avrà il seguente aspetto:

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

  • Problemi di quota: quando la quota dell'API Cloud SQL Admin viene violata, il proxy di autenticazione Cloud SQL viene visualizzato 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

    Quando un'applicazione si connette al proxy, il proxy 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 l'origine del problema di quota, ad esempio un'applicazione sta utilizzando in modo improprio il connettore e creando inutilmente nuove connessioni oppure contatta l'assistenza per richiedere un aumento della quota dell'API Cloud SQL Admin. Se all'avvio viene visualizzato l'errore di quota, devi eseguire nuovamente il deployment dell'applicazione per riavviare il proxy. Se l'errore della quota viene visualizzato all'avvio, non è necessario eseguire nuovamente il deployment.

Passaggi successivi