Connettiti utilizzando il proxy di autenticazione Cloud SQL

MySQL   |  PostgreSQL   |  SQL Server

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

Per saperne di più 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 connetterti 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 account utente o di servizio
• Inserisci 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 Functions
• Cloud Run

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

Nota: per la connessione da Google Kubernetes Engine, consigliamo di eseguire il proxy di autenticazione Cloud SQL in un pattern sidecar, come container aggiuntivo che condivide un pod con la tua applicazione. Consulta anche la relativa guida rapida.

Per un'introduzione di base al suo utilizzo, consulta la guida rapida all'utilizzo del proxy di autenticazione Cloud SQL.

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

Prima di iniziare

Prima di connetterti a un'istanza Cloud SQL, segui questi 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

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

2. Attiva l'API Cloud SQL Admin.

   Abilita l'API

3. Installa e inizializza gcloud CLI.
4. Facoltativo. Installa il client Docker del 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.11.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.11.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.11.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.11.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 pulsante destro del mouse su https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.0/cloud-sql-proxy.x64.exe e seleziona Salva link con nome per scaricare il proxy di autenticazione Cloud SQL. Rinomina il file come cloud-sql-proxy.exe.

Windows a 32 bit

Fai clic con il pulsante destro del mouse su https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.11.0/cloud-sql-proxy.x86.exe e seleziona Salva link con nome per scaricare il proxy di autenticazione Cloud SQL. Rinomina il file come cloud-sql-proxy.exe.

Immagine Docker del proxy di autenticazione Cloud SQL

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

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

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

Nota: il proxy di autenticazione Cloud SQL utilizza un repository che supporta il dominio gcr.io, ma gestisce le immagini da Artifact Registry. Per maggiori informazioni, consulta Transizione da Container Registry.

Altro sistema operativo

Per gli altri sistemi operativi non inclusi qui, puoi compilare il proxy di autenticazione Cloud SQL dall'origine.

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 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 o Unix. Altre applicazioni e servizi, come il codice dell'applicazione o gli strumenti client di gestione dei database, possono connettersi alle istanze Cloud SQL tramite queste connessioni socket TCP o Unix.

Avviso: fai attenzione quando associ il proxy di autenticazione Cloud SQL a un'interfaccia esterna. Chiunque abbia accesso a quell'interfaccia/porta sarà autorizzato a connettersi alla tua istanza.

socket 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 --port 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 fare in modo che il proxy di autenticazione Cloud SQL rimanga in ascolto su 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 dell'istanza nella console Google Cloud oppure eseguendo il comando seguente:

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

   .

   Ad esempio: myproject:myregion:myinstance.

2. Se per l'istanza è configurato un IP pubblico e 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:

   --private-ip

3. Se utilizzi un account di servizio per autenticare il proxy di autenticazione Cloud SQL, prendi nota della 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 del proxy di autenticazione Cloud SQL:

   • Utilizzo dell'autenticazione Cloud SDK:

     ./cloud-sql-proxy --port 5432 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 maggiori 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.

Socket Unix

Nota: attualmente il proxy di autenticazione Cloud SQL non supporta i socket Unix su Windows, pertanto questa opzione è disponibile solo per le piattaforme Linux e macOS.

Il proxy di autenticazione Cloud SQL può rimanere in ascolto su un socket Unix, un meccanismo standard Posix che consente di utilizzare una cartella per gestire la comunicazione tra due processi in esecuzione sullo stesso host. I vantaggi dell'utilizzo dei socket Unix sono una maggiore sicurezza e una minore latenza; tuttavia, non è possibile accedere a un socket Unix da una macchina esterna.

Nota: lo standard PostgreSQL richiede un suffisso ".s.PGSQL.5432" nel percorso del socket. Alcune librerie applicano questo suffisso automaticamente, mentre altre richiedono di specificare il percorso del socket come segue:

  /cloudsql/INSTANCE_CONNECTION_NAME/.s.PGSQL.5432
  

Per creare e utilizzare un socket Unix, deve esistere la directory di destinazione e sia il proxy di autenticazione Cloud SQL sia l'applicazione devono disporre dell'accesso in lettura e scrittura.

1. Se utilizzi una specifica esplicita dell'istanza, copia INSTANCE_CONNECTION_NAME. Puoi trovarlo nella pagina Panoramica dell'istanza nella console Google Cloud o eseguendo il comando seguente:

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

   Ad esempio: myproject:myregion:myinstance.

2. Crea la directory in cui si trovano i socket del proxy di autenticazione Cloud SQL:

   sudo mkdir /cloudsql; sudo chmod 777 /cloudsql

3. Se utilizzi un account di servizio per autenticare il proxy di autenticazione Cloud SQL, prendi nota della posizione sul computer client del file della chiave privata creato al momento della creazione dell'account di servizio.
4. Apri una nuova finestra del terminale Cloud Shell e avvia il proxy di autenticazione Cloud SQL.

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

   • Utilizzo di un account di servizio e inclusione esplicita del nome della connessione dell'istanza (consigliato per ambienti di produzione):

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

   • Utilizzo dell'autenticazione Cloud SDK e del rilevamento automatico delle istanze:

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

   Avvia il proxy di autenticazione Cloud SQL nel suo terminale Cloud Shell in modo da poterne monitorare l'output senza che sia combinato con l'output di altri programmi.

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

NOTA: quando utilizzi un socket Unix per connetterti a Cloud SQL con il proxy di autenticazione Cloud SQL, assicurati che la lunghezza del nome file del socket non superi il limite del sistema. Dipende dal sistema, ma di solito è compreso tra 91 e 108 caratteri. Su Linux, la lunghezza è in genere definita come 108 ed è possibile utilizzare il seguente comando per verificare:

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

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 socket TCP o Unix, con i comandi mostrati di seguito. Le opzioni utilizzano INSTANCE_CONNECTION_NAME come stringa di connessione per identificare un'istanza Cloud SQL. Puoi trovare INSTANCE_CONNECTION_NAME nella pagina Panoramica dell'istanza nella console Google Cloud oppure eseguendo questo comando:

gcloud sql instances describe INSTANCE_NAME

.

Ad esempio: myproject:myregion:myinstance.

Nota: il proxy di autenticazione Cloud SQL non supporta l'ascolto sui socket di domini Unix su Windows.

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 applicazioni scritte nel linguaggio di programmazione Java o per l'ambiente Windows.

Utilizzo di socket TCP

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

Se utilizzi le credenziali fornite dall'istanza di Compute Engine, non includere i parametri --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 esposto all'esterno dell'host locale. Il valore "0.0.0.0" nel parametro delle istanze è obbligatorio per rendere accessibile la porta dall'esterno del container Docker.

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

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

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ù di un'istanza, separate da virgole. Puoi anche utilizzare i metadati di Compute Engine per determinare in modo dinamico le istanze a cui connettersi. Scopri di più sui parametri del proxy di autenticazione Cloud SQL.

Connettiti con il client psql

Debian/Ubuntu

Installa il client psql dal gestore di pacchetti:

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

CentOS/RHEL

Installa il client psql dal gestore di pacchetti:

sudo yum install postgresql

openSUSE

Installa il client psql dal gestore di pacchetti:

sudo zypper install postgresql

Altre piattaforme

1. Scarica PostgreSQL Core Distribution per la tua piattaforma dalla pagina dei download di PostgreSQL.
   La distribuzione principale include il client psql.
2. Installa il database PostgreSQL, seguendo le istruzioni riportate nella pagina di download.

La stringa di connessione da utilizzare varia a seconda che tu abbia avviato il proxy di autenticazione Cloud SQL utilizzando un socket TCP, un socket UNIX o Docker.

socket TCP

1. Avvia il client psql:

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

   Anche se il parametro sslmode è impostato su disable, il proxy di autenticazione Cloud SQL fornisce una connessione criptata.

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

Utilizzo di socket Unix

1. Avvia il client psql:

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

   Anche se il parametro sslmode è impostato su disable, il proxy di autenticazione Cloud SQL fornisce una connessione criptata.

2. Inserisci la password.
3. Viene visualizzato il prompt psql.

Serve aiuto? Per assistenza nella risoluzione dei problemi relativi al proxy, consulta la pagina relativa alla risoluzione dei problemi relativi alle connessioni al proxy di autenticazione di Cloud SQL o la pagina dell'assistenza di Cloud SQL.

Connetti a un'applicazione

Puoi connetterti al proxy di autenticazione Cloud SQL da qualsiasi linguaggio che consenta di connettersi a un socket Unix o TCP. Di seguito sono riportati alcuni snippet di codice provenienti da esempi completi su GitHub per aiutarti a capire come funzionano insieme nella tua applicazione.

Connessione tramite 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 ssl

import sqlalchemy


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

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

Java

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

Nota:

• CLOUD_SQL_CONNECTION_NAME deve essere rappresentata come <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
• Se utilizzi l'argomento ipTypes=PRIVATE, SocketIndustry forzerà la connessione all'IP privato associato a un'istanza
• Consulta qui i requisiti di versione di fabbrica del socket JDBC per il file pom.xml.

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

public class TcpConnectionPoolFactory extends ConnectionPoolFactory {

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

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


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

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

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


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

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

Node.js

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

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

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

Go

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

package cloudsql

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

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

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

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


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

	// ...

	return dbPool, nil
}

C#

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

using Npgsql;
using System;

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

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

Ruby

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

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

PHP

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

namespace Google\Cloud\Samples\CloudSQL\Postgres;

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

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

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

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

        return $conn;
    }
}

Connessione con prese Unix

Istruzione di chiamata del proxy di autenticazione Cloud SQL:

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

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

Java

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

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

public class ConnectorConnectionPoolFactory extends ConnectionPoolFactory {

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

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

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

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

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

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



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

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

Node.js

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

const Knex = require('knex');

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

C#

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

using Npgsql;
using System;

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

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

Go

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

package cloudsql

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

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

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

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

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

	// ...

	return dbPool, nil
}

Ruby

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

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

PHP

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

namespace Google\Cloud\Samples\CloudSQL\Postgres;

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

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

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

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

        return $conn;
    }
}

Argomenti aggiuntivi

Argomenti della riga di comando del proxy di autenticazione Cloud SQL

Gli esempi precedenti 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 documento README nel repository GitHub di autenticazione Cloud SQL per altri esempi di utilizzo delle opzioni della riga di comando del proxy di autenticazione Cloud SQL.

Opzioni per l'autenticazione del proxy di autenticazione Cloud SQL

Quando autentichi il proxy di autenticazione Cloud SQL, lo consenti ad accedere a Google Cloud per conto della tua applicazione, utilizzando un insieme di credenziali Google. Questa procedura è separata dall'autenticazione utente del database. L'autenticazione del database utente IAM è integrata con il proxy di autenticazione Cloud SQL.

Tutte queste opzioni utilizzano INSTANCE_CONNECTION_NAME come stringa di connessione per identificare un'istanza Cloud SQL. Puoi trovare INSTANCE_CONNECTION_NAME nella pagina Panoramica dell'istanza nella console Google Cloud oppure eseguendo questo 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 di credenziali JSON che include la chiave privata RSA dell'account. Per istruzioni sulla creazione di un file JSON delle credenziali per un account di servizio, consulta Creazione di un account di servizio.

Il proxy di autenticazione Cloud SQL offre diverse alternative per l'autenticazione, a seconda dell'ambiente. Il proxy di autenticazione Cloud SQL controlla ognuno dei seguenti elementi nel seguente ordine, utilizzando il primo trovato per tentare di eseguire l'autenticazione:

1. Credenziali fornite dal flag credentials-file.

   Utilizza un account di servizio per creare e scaricare il file JSON associato, quindi imposta il flag --credentials-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 nella riga di comando, richiama il comando cloud-sql-proxy con il flag --credentials-file impostato sul percorso e sul nome file 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 Concessione di 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 \
   INSTANCE_CONNECTION_NAME
     

3. Credenziali fornite da una variabile di ambiente.

   Questa opzione è simile all'utilizzo del flag --credentials-file, ad eccezione del fatto che specifichi il file di credenziali JSON che hai impostato nella variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS al posto dell'argomento della riga di comando --credentials-file.

4. Credenziali da 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 rendere operativo un ambiente di sviluppo.

   Per abilitare il proxy di autenticazione Cloud SQL per utilizzare le credenziali di 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 di Compute Engine, il proxy di autenticazione di 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 Cloud SQL, il proxy di autenticazione Cloud SQL viene autenticato correttamente.

   Se l'istanza di 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 di 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 nessuna delle posizioni illustrate in precedenza, segue la logica documentata in Configurazione dell'autenticazione per le applicazioni di produzione da server a 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 avere le autorizzazioni descritte in ruoli e autorizzazioni. Per ulteriori informazioni sull'approccio di Google Cloud all'autenticazione, consulta la Panoramica dell'autenticazione.

Crea un account di servizio

Se esegui la connessione da Compute Engine, assicurati che la VM disponga del scope corretto per connettersi utilizzando l'API Cloud SQL Admin.

Configura l'account di servizio in modo che abbia uno dei seguenti ambiti di accesso:

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

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.
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 scegli uno dei seguenti ruoli:
   • Cloud SQL > Client Cloud SQL
   • Cloud SQL > Editor Cloud SQL
   • Cloud SQL > Amministratore Cloud SQL
   Nota: per creare un account di servizio con le autorizzazioni richieste, devi avere l'autorizzazione resourcemanager.projects.setIamPolicy. Questa autorizzazione è inclusa nei ruoli Proprietario progetto, Amministratore IAM del progetto e Amministratore organizzazione.
   Devi anche aver abilitato l'API Cloud SQL Admin. Se utilizzi i ruoli legacy per il progetto (Visualizzatore, Editor, Proprietario), l'account di servizio deve disporre almeno del ruolo Editor.
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 Crea.

    Il file della chiave privata viene scaricato sul tuo computer. Puoi spostarlo in un'altra posizione. Tieni al sicuro il file della chiave.

Utilizza il proxy di autenticazione Cloud SQL con IP privato

Per connettersi 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 la tua istanza Cloud SQL ha solo un IP privato o ha configurato un IP sia pubblico che 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 Private Service Connect è abilitato

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 l'accesso sicuro a questa istanza senza bisogno di reti autorizzate o per la configurazione di SSL.

Per consentire le connessioni 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 la connessione alle istanze in cui Private Service Connect è abilitato, consulta Connessione tramite il proxy di autenticazione Cloud SQL.

Esegui il proxy di autenticazione Cloud SQL in un processo separato

L'esecuzione del proxy di autenticazione Cloud SQL in un processo del terminale Cloud Shell separato 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 un carattere & 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 in 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.11.0

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

Nota: i socket Unix non sono supportati per applicazioni scritte nel linguaggio di programmazione Java o per l'ambiente Windows.

socket TCP

    docker run -d \
      -v PATH_TO_KEY_FILE:/path/to/service-account-key.json \
      -p 127.0.0.1:5432:5432 \
      gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.11.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.11.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 riga -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 i carichi di lavoro di sviluppo e produzione locali. In fase di sviluppo, quando devi accedere all'istanza 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 attualmente non offre 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.

Nota: se esegui il proxy di autenticazione Cloud SQL come servizio, tieni presente che utilizza una connessione sicura per comunicare con le istanze Cloud SQL, ma le connessioni dall'applicazione al proxy di autenticazione Cloud SQL non sono criptate. Per questo motivo, assicurati che solo gli utenti attendibili siano in grado di accedere all'indirizzo e alla porta su cui il proxy di autenticazione Cloud SQL è in ascolto.

Applica l'utilizzo del proxy di autenticazione Cloud SQL

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

gcloud

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

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

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

REST v1

Il comando seguente applica l'uso dei connettori Cloud SQL

Prima di utilizzare i dati della richiesta, effettua 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 di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando:

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

PowerShell (Windows)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando:

$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

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": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

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

REST v1beta4

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

Prima di utilizzare i dati della richiesta, effettua 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 di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando:

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

PowerShell (Windows)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json ed esegui questo comando:

$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

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": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

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

Suggerimenti per l'utilizzo del proxy di autenticazione Cloud SQL

Richiama il proxy di autenticazione Cloud SQL

Tutte le chiamate proxy di esempio avviano il proxy di autenticazione Cloud SQL in background, quindi viene restituito un messaggio. Riserva il terminale Cloud Shell per il proxy di autenticazione Cloud SQL, in modo da evitare che l'output sia combinato con quello di altri programmi. Inoltre, l'output del proxy di autenticazione Cloud SQL può aiutarti a diagnosticare i problemi di connessione, in modo da risultare utile acquisire in un file di log. Se non avvii il proxy di autenticazione Cloud SQL in background, l'output va a stdout a meno che non venga reindirizzato.

Non è necessario utilizzare /cloudsql come directory per i socket del proxy di autenticazione Cloud SQL. (Il nome della directory è stato scelto per ridurre al minimo le differenze con le stringhe di connessione di App Engine.) Se cambi il nome della directory, tuttavia, mantieni al minimo la lunghezza complessiva; questa viene incorporata in una stringa più lunga con un limite di lunghezza imposto dal sistema operativo. Dipende dal sistema, ma in genere è compreso tra 91 e 108 caratteri. Su Linux, la lunghezza è in genere definita come 108. Puoi usare il seguente comando per controllare:

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

Utilizzare 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 esegui questa operazione dipende dall'utilizzo o meno di socket Unix o TCP.

Socket Unix

Per connettere il proxy di autenticazione Cloud SQL a più istanze, devi fornire ogni nome di connessione dell'istanza come argomento al proxy di autenticazione Cloud SQL, in un elenco separato da spazi. Il proxy di autenticazione Cloud SQL si connette a ogni istanza all'avvio.

Puoi connetterti a ogni istanza utilizzando il relativo socket, nella directory specificata.

Ad esempio:

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

socket TCP

Quando ti connetti utilizzando TCP, specifichi una porta sulla tua macchina su cui il proxy di autenticazione Cloud SQL deve rimanere in ascolto per ogni istanza Cloud SQL. Quando ti connetti a più istanze Cloud SQL, ogni porta specificata deve essere univoca e disponibile per l'utilizzo sulla tua macchina.

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

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

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

Chiamate al proxy di autenticazione Cloud SQL e stringhe di connessione client psql

Puoi utilizzare le chiamate del proxy di autenticazione Cloud SQL e le stringhe di connessione, ad esempio, nei comandi per un utente PostgreSQL myUser, per l'istanza myInstance, che si trova in us-central1, nel progetto myProject.

Utilizzo del rilevamento automatico delle istanze con le credenziali gcloud CLI:

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

Utilizzo del rilevamento dei progetti con le credenziali gcloud CLI:

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

Per un'istanza Compute Engine, con specifica esplicita dell'istanza:

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

Per Unix, utilizzando TCP:

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

Per Windows (al prompt della riga di comando):

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

Nota: la porta 5432 utilizzata per il client predefinitopsql Se utilizzi un numero di porta diverso, devi specificarlo all'avvio del client psql utilizzando il parametro --port.

Per ulteriori informazioni sulle opzioni e sulle stringhe di connessione del proxy di autenticazione Cloud SQL, consulta la pagina GitHub di autenticazione del proxy di Cloud SQL.

Risolvere i problemi relativi alle connessioni al proxy di autenticazione Cloud SQL

L'immagine Docker del proxy di autenticazione Cloud SQL è basata su una versione specifica del proxy di autenticazione Cloud SQL. Quando una nuova versione del proxy di autenticazione Cloud SQL diventa disponibile, esegui il pull della nuova versione dell'immagine Docker del proxy di autenticazione Cloud SQL per mantenere aggiornato l'ambiente. Puoi visualizzare la versione attuale del proxy di autenticazione Cloud SQL consultando la pagina delle release GitHub del proxy di autenticazione Cloud SQL.

Se hai difficoltà a connetterti alla tua istanza Cloud SQL utilizzando il proxy di autenticazione Cloud SQL, ecco alcune cose da provare per capire la causa del 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. Reindirizza l'output a un file o osserva il terminale Cloud Shell da cui hai avviato il proxy di autenticazione Cloud SQL.

• Se visualizzi 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 suo ID nella pagina IAM. Deve avere l'autorizzazione cloudsql.instances.connect. I ruoli predefiniti Cloud SQL Admin, Client e Editor hanno questa autorizzazione.

• Se ti connetti da App Engine e ricevi un errore 403 notAuthorized, controlla se nel valore app.yaml cloud_sql_instances è presente un nome di connessione all'istanza non scritto correttamente o in modo errato. I nomi delle connessioni all'istanza sono sempre nel formato PROJECT:REGION:INSTANCE.

  Verifica inoltre che l'account di servizio App Engine (ad esempio $[e-mail]) abbia il ruolo IAM client Cloud SQL.

  Se il servizio App Engine risiede in un progetto (progetto A) e il database risiede in un altro (progetto B), questo errore significa 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, verrà visualizzato un output simile a Error 403: Access Not Configured nei log del proxy di autenticazione Cloud SQL.

• 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 ti connetti utilizzando socket UNIX, verifica che siano stati creati elencando la directory fornita all'avvio del 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.

  Nota: il proxy di autenticazione Cloud SQL utilizza 3307 per connettersi al server proxy di autenticazione Cloud SQL. La porta 5432 è la porta predefinita per il protocollo PostgreSQL su una connessione TCP diretta (non utilizzando il proxy di autenticazione Cloud SQL).

• Puoi verificare che il proxy di autenticazione Cloud SQL sia stato avviato correttamente cercando nei log nella sezione Operazioni > Logging > Esplora log della console Google Cloud. Un'operazione riuscita si presenta come la seguente:

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

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

  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 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 di più sulla connessione all'istanza dalla tua applicazione.
• Scopri di più sul client psql.
• Scopri le opzioni di assistenza.