Connettiti da Cloud Run Functions

Questa pagina contiene informazioni ed esempi per la connessione a un'istanza Cloud SQL da un servizio in esecuzione nelle funzioni Cloud Run.

Per istruzioni passo passo sull'esecuzione di un'applicazione web di esempio di Cloud Run Functions connessa a Cloud SQL, consulta la guida rapida per la connessione da Cloud Run Functions.

Cloud SQL è un servizio di database completamente gestito che semplifica la configurazione, la manutenzione, la gestione e l'amministrazione dei database relazionali nel cloud.

Cloud Run Functions è una soluzione di calcolo leggera che consente agli sviluppatori di creare funzioni autonome a uso specifico, che rispondano a eventi Cloud senza la necessità di gestire un ambiente server o di runtime.

Configura un'istanza Cloud SQL

  1. Abilita l'API Cloud SQL Admin nel progetto Google Cloud da cui ti connetti, se non l'hai già fatto:

    Enable the API

  2. Crea un'istanza Cloud SQL per PostgreSQL. Per una latenza migliore, per evitare alcuni costi di networking e per ridurre i rischi di errori tra regioni, ti consigliamo di scegliere una posizione dell'istanza Cloud SQL nella stessa regione del servizio Cloud Run.

    Per impostazione predefinita, Cloud SQL assegna un indirizzo IP pubblico a una nuova istanza. Hai anche la possibilità di assegnare un indirizzo IP privato. Per ulteriori informazioni sulle opzioni di connettività per entrambi, consulta la pagina Panoramica della connessione.

  3. Quando crei l'istanza, puoi scegliere la gerarchia dei certificati server (CA) per l'istanza e poi configurare la gerarchia come serverCaMode per l'istanza. Devi selezionare l'opzione CA per istanza (GOOGLE_MANAGED_INTERNAL_CA) come modalità CA del server per le istanze a cui vuoi connetterti dalle applicazioni web.

Configura Cloud Run Functions

I passaggi per configurare Cloud Run Functions dipendono dal tipo di indirizzo IP assegnato all'istanza Cloud SQL.

IP pubblico (predefinito)

Per configurare le funzioni Cloud Run in modo da abilitare le connessioni a un'istanza Cloud SQL:

  • Verifica che l'istanza creata sopra abbia un indirizzo IP pubblico. Puoi verificarlo nella pagina Panoramica dell'istanza nella consoleGoogle Cloud . Se devi aggiungere un indirizzo IP pubblico, consulta Configura IP pubblico.
  • Recupera INSTANCE_CONNECTION_NAME dell'istanza. Questo valore è disponibile:
    • Nella pagina Panoramica dell'istanza, nella Google Cloud console o
    • Eseguendo questo comando: gcloud sql instances describe [INSTANCE_NAME]
  • Configura il service account per la tua funzione. Se il account di servizio di autorizzazione appartiene a un progetto diverso dall'istanza Cloud SQL, devi abilitare l'API Cloud SQL Admin e aggiungere il Cloud SQL Client ruolo IAM a entrambi i progetti.
  • Verifica che il account di servizio disponga di questo ruolo in modo che possa connettersi a Cloud SQL.
  • Se utilizzi Cloud Run Functions e non Cloud Run Functions (1ª generazione), sono necessari i seguenti elementi (vedi anche Configurare Cloud Run):
    1. Esegui il deployment iniziale della funzione.
      Quando inizi a creare una funzione Cloud Run nella console Google Cloud , il servizio Cloud Run sottostante non è ancora stato creato. Non puoi configurare una connessione Cloud SQL finché il servizio non viene creato (eseguendo il deployment della funzione Cloud Run).
    2. Nella console Google Cloud , in alto a destra della pagina Dettagli funzione, nella sezione Basato su Cloud Run, fai clic sul link per accedere al servizio Cloud Run sottostante.
    3. Nella pagina Dettagli del servizio di Cloud Run, seleziona la scheda Modifica ed esegui il deployment della nuova revisione.
    4. Segui i passaggi standard (come nel caso di qualsiasi modifica della configurazione) per impostare una nuova configurazione per una connessione Cloud SQL.
      Viene creata una nuova revisione di Cloud Run e le revisioni successive ricevono automaticamente questa connessione Cloud SQL, a meno che tu non la modifiche esplicitamente.

IP privato

Se il account di servizio di autorizzazione appartiene a un progetto diverso da quello contenente l'istanza Cloud SQL, procedi nel seguente modo:

  • In entrambi i progetti, abilita l'API Cloud SQL Admin.
  • Per il account di servizio nel progetto che contiene l'istanza Cloud SQL, aggiungi le autorizzazioni IAM.
Un connettore di accesso VPC serverless utilizza indirizzi IP privati per gestire la comunicazione con la tua rete VPC. Per connetterti direttamente con indirizzi IP privati, devi procedere nel seguente modo:
  1. Assicurati che l'istanza Cloud SQL creata in precedenza abbia un indirizzo IP privato. Se devi aggiungerne uno, consulta Configurare l'IP privato per istruzioni.
  2. Crea un connettore di accesso VPC serverless nella stessa rete VPC dell'istanza Cloud SQL. Tieni presente le seguenti condizioni:
    • A meno che tu non utilizzi il VPC condiviso, il connettore deve trovarsi nello stesso progetto e nella stessa regione della risorsa che lo utilizza, ma può inviare traffico alle risorse in regioni diverse.
    • L'accesso VPC serverless supporta la comunicazione con le reti VPC connesse tramite Cloud VPN e peering di rete VPC.
    • L'accesso VPC serverless non supporta le reti legacy.
  3. Configura le funzioni Cloud Run per utilizzare il connettore.
  4. Connettiti utilizzando l'indirizzo IP privato e la porta 5432 della tua istanza.

Connettiti a Cloud SQL

Dopo aver configurato le funzioni Cloud Run, puoi connetterti alla tua istanza Cloud SQL.

IP pubblico (predefinito)

Per i percorsi IP pubblici, le funzioni Cloud Run forniscono la crittografia e si connettono utilizzando il proxy di autenticazione Cloud SQL in due modi:

IP privato

Per i percorsi IP privati, la tua applicazione si connette direttamente alla tua istanza tramite una rete VPC. Questo metodo utilizza TCP per connettersi direttamente all'istanza Cloud SQL senza utilizzare il proxy di autenticazione Cloud SQL.

Connettiti tramite TCP

Connettiti utilizzando l'indirizzo IP privato dell'istanza Cloud SQL come host e porta 5432.

Python

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

Nota:


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, consulta 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);
};

Vai

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta 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
}

PHP

Per visualizzare questo snippet nel contesto di un'applicazione web, consulta 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;
    }
}

Best practice e altre informazioni

Puoi utilizzare il proxy di autenticazione Cloud SQL durante il test dell'applicazione in locale. Per istruzioni dettagliate, consulta la guida rapida per l'utilizzo del proxy di autenticazione Cloud SQL.

Pool di connessioni

Le connessioni ai database sottostanti potrebbero essere interrotte dal server di database stesso o dall'infrastruttura sottostante delle funzioni Cloud Run. Ti consigliamo di utilizzare una libreria client che supporti i pool di connessioni che si riconnettono automaticamente alle connessioni client interrotte. Inoltre, ti consigliamo di utilizzare un pool di connessioni con ambito globale per aumentare la probabilità che la tua funzione riutilizzi la stessa connessione per le invocazioni successive della funzione e chiuda la connessione in modo naturale quando l'istanza viene eliminata (ridimensionamento automatico). Per esempi più dettagliati su come utilizzare i pool di connessioni, vedi Gestione delle connessioni ai database.

Limiti di connessione

Cloud SQL impone un limite massimo alle connessioni simultanee e questi limiti possono variare a seconda delmotore del databasee scelto (vedi Quote e limiti di Cloud SQL). È consigliabile utilizzare una connessione con Cloud Run functions, ma è importante impostare il numero massimo di connessioni su 1.

Ove possibile, devi fare attenzione a inizializzare un pool di connessioni solo per le funzioni che devono accedere al tuo database. Alcuni pool di connessioni creano connessioni in modo preventivo, il che può consumare risorse in eccesso e rientrare nei limiti di connessione. Per questo motivo, ti consigliamo di utilizzare l'inizializzazione differita per ritardare la creazione di un pool di connessioni fino a quando non è necessario e includere il pool di connessioni solo nelle funzioni in cui viene utilizzato.

Per esempi più dettagliati su come limitare il numero di connessioni, vedi Gestione delle connessioni ai database.

Limiti di quota API

Le funzioni Cloud Run forniscono un meccanismo che si connette utilizzando il proxy di autenticazione Cloud SQL, che utilizza l'API Cloud SQL Admin. I limiti di quota API si applicano al proxy di autenticazione Cloud SQL. La quota dell'API Cloud SQL Admin utilizzata è circa il doppio del numero di istanze Cloud SQL configurate moltiplicato per il numero totale di funzioni di cui è stato eseguito il deployment. Puoi impostare il numero di chiamate simultanee massime per modificare la quota API prevista consumata. Le funzioni Cloud Run impongono anche limiti di frequenza al numero di chiamate API consentite ogni 100 secondi.

Passaggi successivi