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 saperne di più su come funziona il 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
  • Aggrega la connessione in un livello SSL/TLS autorizzato per Cloud SQL istanza

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 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 sqlcmd da una macchina locale o da Compute Engine.

Prima di iniziare

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

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

      Vai alla pagina IAM

    • Se vuoi, puoi includere Condizione IAM nell'associazione dei criteri IAM che concede l'autorizzazione per l'account per la connessione a una sola istanza Cloud SQL specifica.

  2. Enable the Cloud SQL Admin API.

    Enable the API

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

Scarica il proxy di autenticazione Cloud SQL

Linux a 64 bit

  1. Scarica il proxy di autenticazione Cloud SQL: 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.linux.amd64
  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: 
    curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.linux.386
  2. Se il comando curl non viene trovato, esegui sudo apt install curl 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://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.darwin.amd64
  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://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/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://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.x64.exe e seleziona Salva link come 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://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.x86.exe e seleziona Salva link come per scaricare il proxy di autenticazione Cloud SQL. Rinomina il file in cloud-sql-proxy.exe.

Immagine Docker del proxy di autenticazione Cloud SQL

Il proxy di autenticazione Cloud SQL ha diverse immagini contenitore, ad esempio distroless, alpine e buster. L'immagine container proxy di autenticazione Cloud SQL predefinita utilizza distroless, che non contiene alcuna shell. Se hai bisogno di una shell o di strumenti correlati, scarica un'immagine basata su alpine o buster. Per ulteriori informazioni, consulta Immagini del contenitore del proxy di autenticazione Cloud SQL.

Puoi eseguire il pull dell'immagine più recente sulla tua macchina locale utilizzando Docker con il seguente comando:

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

Altro sistema operativo

Per altri sistemi operativi non inclusi qui, puoi compilare il proxy di autenticazione Cloud SQL dal codice sorgente.

Avvia il proxy di autenticazione Cloud SQL

Puoi avviare il proxy di autenticazione Cloud SQL utilizzando socket TCP 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 nella riga di comando e apre una connessione locale come un socket TCP. Altre applicazioni e servizi, come il codice dell'applicazione o di gestione di database, possono connettersi alle istanze Cloud SQL attraverso la connessione socket TCP.

Socket TCP

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

In alternativa, puoi specificare un indirizzo diverso per la connessione locale. Ad esempio, ecco come fare in modo che il proxy di autenticazione Cloud SQL ascolti sulla porta 0.0.0.0:1234 per la connessione locale:

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

  1. Copia il tuo INSTANCE_CONNECTION_NAME. Puoi trovarlo nella pagina Panoramica della tua istanza nella console Google Cloud o eseguendo il seguente comando:

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

    Ad esempio: myproject:myregion:myinstance.

  2. Se nell'istanza sono configurati sia l'IP pubblico che quello 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
  3. Se utilizzi un account di servizio per autenticare il proxy di autenticazione Cloud SQL, annota la posizione sul computer client del file della chiave privata creato quando hai creato l'account di servizio.
  4. Avviare il proxy di autenticazione Cloud SQL.

    Alcune possibili stringhe di chiamata del proxy di autenticazione Cloud SQL:

    • Utilizzo dell'autenticazione di Cloud SDK: 
      ./cloud-sql-proxy --port 1433 INSTANCE_CONNECTION_NAME
       La porta specificata non deve essere già in uso, ad esempio da un server di database locale.
    • Utilizzo di un account di servizio e inclusione esplicita del nome della connessione dell'istanza (consigliato per ambienti di produzione): 
      ./cloud-sql-proxy \
--credentials-file PATH_TO_KEY_FILE INSTANCE_CONNECTION_NAME &

    Per saperne di più sulle opzioni del proxy di autenticazione Cloud SQL, consulta Opzioni per l'autenticazione del proxy di autenticazione Cloud SQL.

Docker

Per eseguire Cloud SQL Auth Proxy in un container Docker, utilizza l'immagine Docker di Cloud SQL Auth Proxy disponibile in Google Container Registry.

Puoi avviare il proxy di autenticazione Cloud SQL utilizzando socket TCP o socket Unix, con illustrati di seguito. Le 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 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 socket Unix. I socket Unix non sono supportati per applicazioni scritte nel linguaggio di programmazione Java o per Windows completamente gestito di Google Cloud.

Utilizzo di socket TCP

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

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

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

Utilizzo dei socket Unix

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

Se utilizzi le credenziali fornite dalla tua istanza Compute Engine, non includono il parametro --credentials-file e -v PATH_TO_KEY_FILE:/path/to/service-account-key.json dalla riga di comando.

Se utilizzi un'immagine ottimizzata per i container, usa 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 Metadati Compute Engine per determinare dinamicamente le istanze a cui connettersi. Scopri di più sui parametri del proxy di autenticazione Cloud SQL.

Connettiti al client sqlcmd

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

Socket TCP

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

    Quando ti connetti utilizzando le socket TCP, accedi a Cloud SQL Auth Proxy tramite 127.0.0.1.

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

Serve aiuto? Per assistenza nella risoluzione dei problemi relativi al proxy, consulta Risoluzione dei problemi di connessioni del proxy di autenticazione Cloud SQL. o consulta la pagina dell'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 TCP. Di seguito sono riportati alcuni snippet di codice di esempi completi su GitHub per aiutarti a comprendere come interagiscono nella tua applicazione.

Connessione con TCP

Istruzione di chiamata del proxy di autenticazione Cloud SQL:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

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

import os

import sqlalchemy


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

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

    return pool

Java

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

Nota:

  • CLOUD_SQL_CONNECTION_NAME deve essere rappresentato come <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
  • L'uso dell'argomento ipTypes=PRIVATE forzerà l'esecuzione di per la connessione all'IP privato associato a un'istanza
  • Consulta i requisiti di versione di fabbrica del socket JDBC per pom.xml qui . 


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 visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

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,
  };
  // Establish a connection to the database.
  return mssql.connect(dbConfig);
};

Vai

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

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("Fatal Error in connect_tcp.go: %s environment variable not set.\n", k)
		}
		return v
	}
	// Note: Saving credentials in environment variables is convenient, but not
	// secure - consider a more secure solution such as
	// Cloud Secret Manager (https://cloud.google.com/secret-manager) to help
	// keep secrets safe.
	var (
		dbUser    = mustGetenv("DB_USER")       // e.g. 'my-db-user'
		dbPwd     = mustGetenv("DB_PASS")       // e.g. 'my-db-password'
		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: %w", err)
	}

	// ...

	return dbPool, nil
}

C#

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

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 visualizzare questo snippet nel contesto di un'applicazione web, visualizza il file README su GitHub.

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 visualizzare questo snippet nel contesto di un'applicazione web, consulta il file README su GitHub.

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 di autenticazione Cloud SQL

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

./cloud-sql-proxy --help

Consulta le README nel repository GitHub del proxy di autenticazione Cloud SQL per ulteriori esempi di utilizzo delle opzioni a riga di comando del proxy di autenticazione Cloud SQL.

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 INSTANCE_CONNECTION_NAME nella pagina Panoramica del tuo nella console Google Cloud. o eseguendo il comando 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 sulla creazione di un file di credenziali JSON per un l'account di servizio, consulta Creazione di 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 credentials-file.

    Utilizza un account di servizio per crea e scarica il file JSON associato e imposta --credentials-file al percorso del file all'avvio del proxy di autenticazione Cloud SQL. L'account di servizio deve avere autorizzazioni richieste per l'istanza Cloud SQL.

    Per utilizzare questa opzione dalla riga di comando, richiama il comando cloud-sql-proxy con Il flag --credentials-file impostato sul percorso e sul nome file di una credenziale 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 Concessione di ruoli agli account di servizio.

    Per ulteriori informazioni sui ruoli supportati da Cloud SQL, consulta Ruoli IAM per Cloud SQL.

  2. Credenziali fornite da un token di accesso.

    Crea una il token di accesso e richiamare il comando cloud-sql-proxy 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 ottenere completamente operativo dell'ambiente di sviluppo.

    Per consentire a Cloud SQL Auth Proxy di utilizzare le tue credenziali gcloud CLI, utilizza il seguente comando per autenticare gcloud CLI:

    gcloud auth application-default login

  5. 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 di Cloud SQL l'account di servizio predefinito per l'istanza Compute Engine ha le autorizzazioni necessarie per autenticare il proxy di autenticazione Cloud SQL. Se le due istanze si trovano in progetti diversi, devi aggiungere l'istanza Compute Engine l'account di servizio dell'istanza al progetto contenente in esecuzione in un'istanza Compute Engine.

  6. Service account predefinito dell'ambiente

    Se il proxy di autenticazione Cloud SQL non riesce a trovare le credenziali in nessuna delle posizioni descritte in precedenza, segue la logica documentata Impostazione dell'autenticazione per la produzione da server a server Applicazioni. 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, quest'ultimo deve avere le autorizzazioni descritte in ruoli e autorizzazioni Per ulteriori informazioni sull'approccio di Google Cloud all'autenticazione, vedi 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 impostando un valore univoco e riconoscibile, poi fai clic su Crea e continua.
  6. Fai clic sul campo Seleziona un ruolo e scegli 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 Azioni per il nuovo account di servizio e seleziona Gestisci chiavi.
  9. Fai clic sul menu a discesa Aggiungi chiave e 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 in ogni località. 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 la tua istanza Cloud SQL ha solo IP privato o ha entrambi l'IP pubblico e privato configurato e vuoi che il proxy di autenticazione Cloud SQL utilizzi il token Indirizzo IP, 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 in cui è abilitato Private Service Connect.

Il proxy di autenticazione Cloud SQL è un connettore che fornisce accesso sicuro a questa istanza senza bisogno 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 saperne di più sull'utilizzo del proxy di autenticazione Cloud SQL per connetterti alle istanze in cui è abilitato Private Service Connect, consulta Connettiti utilizzando il proxy di autenticazione Cloud SQL.

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. Utilizzare la sintassi mostrato di seguito per richiamare il proxy di autenticazione Cloud SQL in un processo separato.

Linux

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

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

Windows

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

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

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

socket TCP

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

Socket Unix

    docker run -d \
      -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
      -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.13.0 --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.

Esecuzione del 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. In fase di sviluppo, quando devi accedere Cloud SQL, puoi avviare il servizio in background e arrestarlo al termine dell'operazione.

Per i carichi di lavoro di produzione, il proxy di autenticazione Cloud SQL al momento non fornisce funzionalità per l'esecuzione come servizio Windows, ma i gestori di servizi di terze parti possono 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 di NSSM.

Connettiti quando è richiesto SSL

Applicare l'utilizzo del proxy di autenticazione Cloud SQL

Abilita l'utilizzo del proxy di autenticazione Cloud SQL in Cloud SQL tramite ConnectorEnforcement.

gcloud

Il comando seguente applica in modo forzato l'utilizzo dei connettori Cloud SQL.

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

Per disabilitare l'applicazione forzata, utilizza la seguente riga di codice: --connector-enforcement NOT_REQUIRED L'aggiornamento non attiva un riavvio.

REST v1

Il comando seguente applica l'utilizzo dei connettori Cloud SQL

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • project-id: l'ID progetto.
  • instance-id: l'ID istanza.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una delle seguenti opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Per disattivare l'applicazione, usa "connectorEnforcement": "NOT_REQUIRED". L'aggiornamento non attiva un riavvio.

REST v1beta4

Il seguente comando impone l'utilizzo dei connettori Cloud SQL.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • project-id: l'ID progetto.
  • instance-id: l'ID istanza.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una delle seguenti opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Per disattivare l'applicazione forzata, utilizza "connectorEnforcement": "NOT_REQUIRED" . L'aggiornamento non attiva un riavvio.

Suggerimenti per l'utilizzo di Cloud SQL Auth Proxy

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ù Cloud SQL di Compute Engine. Il modo in cui esegui questa operazione dipende dall'uso o meno di socket Unix o TCP.

Socket TCP

Quando ti connetti utilizzando TCP, specifichi una porta sulla tua macchina su cui il proxy di autenticazione Cloud SQL deve ascoltare per ogni istanza Cloud SQL. Al momento della connessione a più istanze Cloud SQL, ogni porta specificata deve essere univoca e disponibili per l'uso 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 "myProject:us-central1:myInstance?port=1433" \
    "myProject:us-central1:myInstance2?port=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"

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.

  • 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 403 notAuthorized errore, controlla il valore app.yaml cloud_sql_instances per un nome di connessione all'istanza non corretto o con errori ortografici. 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 abilitare l'API Cloud SQL Admin.

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

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

  • Se ti connetti utilizzando socket UNIX, verifica che siano creato mediante l'elenco della 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 consultando i log nella sezione Operazioni > Logging > Esplora log dell'interfaccia nella console Google Cloud. Un'operazione riuscita è simile alla seguente:

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