Conectarse con el proxy de autenticación de Cloud SQL

MySQL   |  PostgreSQL   |  SQL Server

En esta página, se describe cómo conectarse a tu instancia de Cloud SQL con el proxy de autenticación de Cloud SQL.

Para obtener más información sobre cómo funciona el proxy de autenticación de Cloud SQL, consulta Información sobre el proxy de autenticación de Cloud SQL.

Descripción general

El método recomendado para conectarse a una instancia de Cloud SQL es con el proxy de autenticación de Cloud SQL. El proxy de autenticación de Cloud SQL:

• Funciona con extremos de IP pública y privada
• Valida las conexiones mediante credenciales para un usuario o una cuenta de servicio.
• Une la conexión en una capa SSL/TLS autorizada para una instancia de Cloud SQL

Algunos servicios y aplicaciones de Google Cloud usan el proxy de autenticación de Cloud SQL para proporcionar conexiones a rutas de IP públicas con encriptación y autorización, que incluyen lo siguiente:

• Entorno estándar de App Engine
• Entorno flexible de App Engine
• Funciones de Cloud Run
• Cloud Run

Las aplicaciones que se ejecutan en Google Kubernetes Engine pueden conectarse mediante el proxy de autenticación de Cloud SQL.

Nota: para conectarte desde Google Kubernetes Engine, recomendamos ejecutar el proxy de autenticación de Cloud SQL en un patrón sidecar, como un contenedor adicional que comparte un Pod con tu aplicación. Consulta también la guía de inicio rápido relacionada.

Consulta la Guía de inicio rápido para usar el proxy de autenticación de Cloud SQL así obtienes una introducción básica al uso.

También puedes conectarte con o sin el proxy de autenticación de Cloud SQL con un cliente psql desde una máquina local o Compute Engine.

Antes de comenzar

Antes de que puedas conectarte a una instancia de Cloud SQL, haz lo siguiente:

1. • Para una cuenta de servicio o usuario, asegúrate de que tenga el rol de cliente de Cloud SQL. Este rol contiene el permiso cloudsql.instances.connect, que autoriza a una principal a conectarse a todas las instancias de Cloud SQL de un proyecto.

     Ir a la página de IAM

   • De manera opcional, puedes incluir una condición de IAM en la vinculación de la política de IAM que otorgue al permiso la cuenta para conectarse solo a una instancia específica de Cloud SQL.

2. Enable the Cloud SQL Admin API.

   Enable the API

3. Instala e inicializa gcloud CLI.
4. Opcional. Instala el cliente de Docker del proxy de Auth de Cloud SQL.

Descarga el proxy de autenticación de Cloud SQL

Linux de 64 bits

1. Descarga el proxy de autenticación de 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. Haz que el proxy de autenticación de Cloud SQL sea ejecutable:

   chmod +x cloud-sql-proxy

Linux de 32 bits

1. Descarga el proxy de autenticación de 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. Si no se encuentra el comando curl, ejecuta sudo apt install curl y repite el comando de descarga.
3. Haz que el proxy de autenticación de Cloud SQL sea ejecutable:

   chmod +x cloud-sql-proxy

macOS de 64 bits

1. Descarga el proxy de autenticación de 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. Haz que el proxy de autenticación de Cloud SQL sea ejecutable:

   chmod +x cloud-sql-proxy

Mac M1

1. Descarga el proxy de autenticación de 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. Haz que el proxy de autenticación de Cloud SQL sea ejecutable:

     chmod +x cloud-sql-proxy
     

Windows de 64 bits

Haz clic con el botón derecho en https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.x64.exe y selecciona Guardar vínculo como para descargar el proxy de autenticación de Cloud SQL. Cambia el nombre del archivo por cloud-sql-proxy.exe.

Windows de 32 bits

Haz clic con el botón derecho en https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.x86.exe y selecciona Guardar vínculo como para descargar el proxy de autenticación de Cloud SQL. Cambia el nombre del archivo por cloud-sql-proxy.exe.

Imagen de Docker del proxy de Cloud SQL 

El proxy de autenticación de Cloud SQL tiene diferentes imágenes de contenedor, como distroless, alpine y buster. La imagen de contenedor del proxy de autenticación de Cloud SQL predeterminada usa distroless, que no contiene shell. Si necesitas una shell o herramientas relacionadas, descarga una imagen basada en alpine o buster. Para obtener más información, consulta Imágenes de contenedor del proxy de autenticación de Cloud SQL.

Puedes extraer la última imagen a tu máquina local con Docker a través del siguiente comando:

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

Nota: El proxy de autenticación de Cloud SQL usa un repositorio que admite el dominio gcr.io, pero entrega imágenes de Artifact Registry. Para obtener más información, consulta Transición desde Container Registry.

Otro SO

Para otros sistemas operativos que no se incluyen aquí, puedes compilar el proxy de autenticación de Cloud SQL desde la fuente.

Inicia el proxy de autenticación de Cloud SQL

Según tu lenguaje y entorno, puedes iniciar el proxy de autenticación de Cloud SQL con sockets de TCP, de Unix o la imagen de Docker del proxy de autenticación de Cloud SQL. El objeto binario del proxy de autenticación de Cloud SQL se conecta a una o más instancias de Cloud SQL especificadas en la línea de comandos y abre una conexión local como un socket TCP o Unix. Otras aplicaciones y servicios, como el código de la aplicación o las herramientas de administración de bases de datos del cliente, pueden conectarse a las instancias de Cloud SQL mediante esos sockets.

Advertencia: Ten cuidado cuando vincules el proxy de autenticación de Cloud SQL a una interfaz externa. Cualquier persona con acceso a esa interfaz o puerto estará autorizada a conectarse a tu instancia.

Sockets TCP

En el caso de las conexiones de TCP, el proxy de autenticación de Cloud SQL escucha en localhost(127.0.0.1) de forma predeterminada. Por lo tanto, cuando especificas --port PORT_NUMBER en una instancia, la conexión local está en 127.0.0.1:PORT_NUMBER.

Como alternativa, puedes especificar una dirección diferente para la conexión local. Por ejemplo, a continuación, se muestra cómo hacer que el proxy de autenticación de Cloud SQL escuche en 0.0.0.0:1234 para la conexión local:

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

1. Copia tu INSTANCE_CONNECTION_NAME. Puedes encontrarlo en la página Descripción general de la instancia en la consola de Google Cloud o mediante la ejecución del siguiente comando:

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

   Por ejemplo: myproject:myregion:myinstance.

2. Si la instancia tiene configuradas una IP pública y una privada, y quieres que el proxy de autenticación de Cloud SQL use la dirección IP privada, debes proporcionar la siguiente opción cuando lo inicies:

   --private-ip

3. Si usas una cuenta de servicio para autenticar el proxy de autenticación de Cloud SQL, toma nota de la ubicación del archivo de claves privadas que se generó en la máquina cliente cuando creaste la cuenta de servicio.
4. Inicia el proxy de autenticación de Cloud SQL.

   Estas son algunas strings posibles para invocar al proxy de autenticación de Cloud SQL:

   • Si usas la autenticación del SDK de Cloud:

     ./cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME

     El puerto especificado no debe estar en uso, por ejemplo, por un servidor de base de datos local.
   • Si usas una cuenta de servicio y también incluyes de forma explícita el nombre de la conexión de la instancia (recomendado para entornos de producción):

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

   Para obtener más información sobre las opciones del proxy de autenticación de Cloud SQL, consulta Opciones para autenticar el proxy de autenticación de Cloud SQL.

Sockets Unix

Nota: actualmente, el proxy de autenticación de Cloud SQL no admite sockets de Unix en Windows, por lo que esta opción solo está disponible en plataformas Linux y macOS.

El proxy de autenticación de Cloud SQL puede escuchar en un socket de Unix, que es un mecanismo estándar de Posix para usar una carpeta y administrar la comunicación entre dos procesos que se ejecutan en el mismo host. Las ventajas de usar sockets Unix son seguridad mejorada y menor latencia; sin embargo, no puedes acceder a un socket de Unix desde una máquina externa.

Nota: PostgreSQL estándar requiere un sufijo “.s.PGSQL.5432” en la ruta del socket. Algunas bibliotecas aplican este sufijo automáticamente, pero otras requieren que especifiques la ruta del socket de la siguiente manera:

  /cloudsql/INSTANCE_CONNECTION_NAME/.s.PGSQL.5432
  

Para crear y usar un socket de Unix, el directorio de destino debe existir, y el proxy de autenticación de Cloud SQL y la aplicación deben tener acceso de lectura y escritura.

1. Copia tu INSTANCE_CONNECTION_NAME. Puedes encontrarlo en la página Descripción general de la instancia en la consola de Google Cloud o mediante la ejecución del siguiente comando:

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

   Por ejemplo: myproject:myregion:myinstance.

2. Crea el directorio en el que se alojarán los sockets del proxy de autenticación de Cloud SQL:

   sudo mkdir /cloudsql; sudo chmod 777 /cloudsql

3. Si usas una cuenta de servicio para autenticar el proxy de autenticación de Cloud SQL, toma nota de la ubicación del archivo de claves privadas que se generó en la máquina cliente cuando creaste la cuenta de servicio.
4. Abre una nueva ventana de terminal de Cloud Shell y, luego, inicia el proxy de autenticación de Cloud SQL.

   Estas son algunas strings posibles para invocar al proxy de autenticación de Cloud SQL:

   • Si usas la autenticación del SDK de Google Cloud:

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

   • Usa una cuenta de servicio:

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

   Inicia el proxy de autenticación de Cloud SQL en su propia terminal de Cloud Shell para supervisar el resultado sin que se mezcle con el de otros programas.

   Para obtener más información sobre las opciones del proxy de autenticación de Cloud SQL, consulta Opciones para autenticar el proxy de autenticación de Cloud SQL.

   NOTA: cuando uses un socket de Unix para conectarte a Cloud SQL con el proxy de autenticación de Cloud SQL, deberás asegurarte de que la longitud del nombre de archivo del socket no supere el límite del sistema. Este límite depende del sistema, pero suele ser de entre 91 y 108 caracteres. En Linux, la longitud se suele definir como 108, y puedes usar el siguiente comando para verificar:

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

Docker

Para ejecutar el proxy de autenticación de Cloud SQL en un contenedor de Docker, usa la imagen de Docker del proxy de autenticación de Cloud SQL disponible en Google Container Registry.

Para iniciar el proxy de autenticación de Cloud SQL, usa los sockets de TCP o de Unix con los comandos que se muestran a continuación. Las opciones usan un INSTANCE_CONNECTION_NAME como la string de conexión para identificar una instancia de Cloud SQL. Puedes encontrar el INSTANCE_CONNECTION_NAME en la página Descripción general de tu instancia en la consola de Google Cloud o ejecutando el siguiente comando:

gcloud sql instances describe INSTANCE_NAME

.

Por ejemplo: myproject:myregion:myinstance.

Nota: El proxy de autenticación de Cloud SQL no admite la escucha en sockets de dominio Unix en Windows.

Según tu lenguaje y entorno, puedes iniciar el proxy de autenticación de Cloud SQL con sockets de TCP o de Unix. Los sockets de Unix no son compatibles con aplicaciones escritas en el lenguaje de programación Java o con el entorno de Windows.

Usa sockets 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.13.0 \\
  --address 0.0.0.0 --port 5432 \\
  --credentials-file /path/to/service-account-key.json INSTANCE_CONNECTION_NAME

Si usas las credenciales que proporciona tu instancia de Compute Engine, no incluyas el parámetro --credentials-file ni la línea -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Especifica siempre el prefijo 127.0.0.1 en -p para que el proxy de autenticación de Cloud SQL no se exponga fuera del host local. El “0.0.0.0” en el parámetro de las instancias es necesario para que se pueda acceder al puerto desde afuera del contenedor de Docker.

Usa sockets 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

Si usas las credenciales que proporciona tu instancia de Compute Engine, no incluyas el parámetro --credentials-file ni la línea -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Si usas una imagen optimizada para contenedores, usa un directorio que admita operaciones de escritura en lugar de /cloudsql, por ejemplo:

-v /mnt/stateful_partition/cloudsql:/cloudsql

Puedes especificar más de una instancia, separadas por comas. También puedes usar los metadatos de Compute Engine para determinar de forma dinámica las instancias que se conectarán. Obtén más información acerca del proxy de autenticación de Cloud SQL.

Conéctate con el cliente psql

Debian/Ubuntu

Instala el cliente psql desde el administrador de paquetes:

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

CentOS/RHEL

Instala el cliente psql desde el administrador de paquetes:

sudo yum install postgresql

openSUSE

Instala el cliente psql desde el administrador de paquetes:

sudo zypper install postgresql

Otras plataformas

1. Descarga la distribución principal de PostgreSQL para tu plataforma desde la página de descargas de PostgreSQL.
   La distribución principal incluye el cliente psql.
2. Instala la base de datos de PostgreSQL y sigue las instrucciones en la página de descargas.

La string de conexión que usas depende de si iniciaste el proxy de autenticación de Cloud SQL con un socket de TCP o uno de UNIX o un Docker.

Sockets TCP

1. Inicia el cliente psql:

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

   Aunque el parámetro sslmode se configuró como disable, el proxy de autenticación de Cloud SQL proporciona una conexión encriptada.

   Cuando te conectas con los sockets de TCP, se accede al proxy de autenticación de Cloud SQL a través de 127.0.0.1.

2. Si se te solicita, ingresa la contraseña.
3. Aparecerá el mensaje de psql.

Usa sockets Unix

1. Inicia el cliente psql:

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

   Aunque el parámetro sslmode se configuró como disable, el proxy de autenticación de Cloud SQL proporciona una conexión encriptada.

2. Ingresa la contraseña.
3. Aparecerá el mensaje de psql.

¿Necesitas ayuda? Para solucionar problemas del proxy, consulta Solución de problemas de conexión del proxy de autenticación de Cloud SQL o nuestra página Asistencia de Cloud SQL.

Conéctate con una aplicación

Puedes conectarte al proxy de autenticación de Cloud SQL desde cualquier lenguaje que permita conectarte a un socket de Unix o de TCP. A continuación, se incluyen algunos fragmentos de código de ejemplos completos en GitHub para ayudarte a comprender cómo funcionan juntos en tu aplicación.

Conéctate con TCP

Instrucción de invocación del proxy de autenticación de Cloud SQL:

./cloud-sql-proxy INSTANCE_CONNECTION_NAME &

Python

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en 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

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en GitHub.

Nota:

• CLOUD_SQL_CONNECTION_NAME debe representarse como <MY-PROJECT>:<INSTANCE-REGION>:<INSTANCE-NAME>
• Con el argumento ipTypes=PRIVATE, se forzará a SocketFactory a la conexión con la IP privada asociada de una instancia
• Consulta los requisitos de la versión de fábrica de los sockets de JDBC para el archivo pom.xml aquí.

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

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en 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

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en 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#

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en 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

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en 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

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en 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;
    }
}

Conéctate con sockets de Unix

Instrucción de invocación del proxy de autenticación de Cloud SQL:

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

Python

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en 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

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en 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

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en 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#

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en 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

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en 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

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en 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

Para ver este fragmento en el contexto de una aplicación web, consulta el archivo README en 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;
    }
}

Temas adicionales

Argumentos de línea de comandos del proxy de autenticación de Cloud SQL

Los ejemplos anteriores abarcan los casos de uso más comunes, pero el proxy de autenticación de Cloud SQL también tiene otras opciones de configuración que se pueden establecer con argumentos de línea de comandos. Si necesitas ayuda con los argumentos de la línea de comandos, usa la marca --help para ver la documentación más reciente:

./cloud-sql-proxy --help

Consulta el archivo README en el repositorio del proxy de autenticación de Cloud SQL en GitHub para ver ejemplos adicionales sobre cómo usar las opciones de línea de comandos del proxy de autenticación de Cloud SQL.

Opciones para autenticar el proxy de autenticación de Cloud SQL

Nota: Cuando autenticas el proxy de autenticación de Cloud SQL, lo habilitas para acceder a Google Cloud en nombre de tu aplicación, con un conjunto de credenciales de Google. Esto es diferente de la autenticación de usuario de la base de datos. La autenticación de la base de datos de usuarios del IAM está integrada en el proxy de autenticación de Cloud SQL.

Todas estas opciones usan un INSTANCE_CONNECTION_NAME como la string de conexión para identificar una instancia de Cloud SQL. Puedes encontrar el INSTANCE_CONNECTION_NAME en la página Descripción general de tu instancia en la consola de Google Cloud o ejecutando el siguiente comando:

gcloud sql instances describe --project PROJECT_ID INSTANCE_CONNECTION_NAME.

Por ejemplo: gcloud sql instances describe --project myproject myinstance.

Algunas de estas opciones usan un archivo de credenciales JSON que incluye la clave privada RSA de la cuenta. Si quieres obtener instrucciones para crear un archivo de credenciales JSON en una cuenta de servicio, consulta la sección sobre cómo crear una cuenta de servicio.

El proxy de autenticación de Cloud SQL ofrece varias alternativas de autenticación, según el entorno. El proxy de autenticación de Cloud SQL verifica cada uno de los siguientes elementos, en el siguiente orden, y usa el primero que encuentra para intentar llevar a cabo la autenticación:

1. Credenciales provistas por la marca credential_file.

   Usa una cuenta de servicio para crear y descargar el archivo JSON asociado y establece la marca --credentials-file en la ruta de acceso del archivo cuando inicias el proxy de autenticación de Cloud SQL. La cuenta de servicio debe tener los permisos necesarios para la instancia de Cloud SQL.

   Para usar esta opción en la línea de comandos, invoca el comando cloud-sql-proxy con la marca --credentials-file establecida en la ruta y el nombre de archivo de un archivo de credenciales JSON. La ruta de acceso puede ser absoluta o relativa al directorio de trabajo actual. Por ejemplo:

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

   Para obtener instrucciones detalladas sobre cómo agregar funciones de IAM a una cuenta de servicio, consulta la sección Cómo asignar funciones a las cuentas de servicio.

   Si quieres obtener más información sobre los roles que admite Cloud SQL, consulta Roles de IAM para Cloud SQL.

2. Credenciales provistas por un token de acceso.

   Crea un token de acceso y, luego, invoca el comando cloud-sql-proxy con la marca --token establecida en un token de acceso de OAuth 2.0. Por ejemplo:

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

3. Credenciales provistas por una variable de entorno.

   Esta opción es similar a usar la marca --credentials-file, excepto que se especifica el archivo de credenciales JSON que estableciste en la variable de entorno GOOGLE_APPLICATION_CREDENTIALS, en lugar de usar el argumento de línea de comandos --credentials-file.

4. Credenciales de un cliente autenticado de gcloud CLI.

   Si instalaste gcloud CLI y te autenticaste con tu cuenta personal, el proxy de autenticación de Cloud SQL puede usar las mismas credenciales de cuenta. Este método es útil, en particular, para poner en ejecución un entorno de desarrollo.

   Sí quieres habilitar el proxy de autenticación de Cloud SQL y poder usar tus credenciales de gcloud CLI, usa el comando para autenticar gcloud CLI.

   gcloud auth application-default login

5. Credenciales asociadas con la instancia de Compute Engine.

   Si te conectas a Cloud SQL desde una instancia de Compute Engine, el proxy de autenticación de Cloud SQL puede usar la cuenta de servicio asociada a esa instancia. Si la cuenta de servicio tiene los permisos necesarios para la instancia de Cloud SQL, el proxy de autenticación de Cloud SQL se puede autenticar de forma correcta.

   Si la instancia de Compute Engine se encuentra en el mismo proyecto que la instancia de Cloud SQL, la cuenta de servicio predeterminada de la instancia de Compute Engine tiene los permisos que se necesitan para autenticar el proxy de autenticación de Cloud SQL. Si las dos instancias se encuentran en proyectos diferentes, deberás agregar la cuenta de servicio de la instancia de Compute Engine al proyecto que contiene la de Cloud SQL.

6. Cuenta de servicio predeterminada del entorno

   Si el proxy de autenticación de Cloud SQL no puede encontrar credenciales en ninguno de los lugares ya mencionados, sigue la lógica que se documenta en la sección cómo configurar la autenticación para aplicaciones de producción de servidor a servidor. Algunos entornos (como Compute Engine, App Engine y otros) proporcionan una cuenta de servicio predeterminada que tu aplicación puede usar para la autenticación según la configuración predeterminada. Si usas una cuenta de servicio predeterminada, debe tener los permisos descritos en funciones y permisos Si deseas obtener más información sobre el enfoque de Google Cloud para la autenticación, consulta la sección Descripción general de la autenticación.

Cree una cuenta de servicio

Si te conectas desde Compute Engine, asegúrate de que tu VM tenga el scope adecuado para conectarse con la API de Cloud SQL Admin.

Configura la cuenta de servicio para que tenga uno de los siguientes permisos de acceso:

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

1. En la consola de Google Cloud, ve a la página Cuentas de servicio.

   Ir a Cuentas de servicio

2. Selecciona el proyecto que contiene la instancia de Cloud SQL.
3. Haga clic en Crear cuenta de servicio.
4. En el campo Nombre de la cuenta de servicio, ingresa un nombre descriptivo para la cuenta de servicio.
5. Cambia el ID de la cuenta de servicio a un valor único y reconocible y, luego, haz clic en Crear y continuar.
6. Haz clic en el campo Seleccionar un rol y selecciona uno de los siguientes roles:
   • Cloud SQL > Cliente de Cloud SQL
   • Cloud SQL > Editor de Cloud SQL
   • Cloud SQL > Administrador de Cloud SQL
   Nota: Para crear una cuenta de servicio con los permisos necesarios, debes tener el permiso resourcemanager.projects.setIamPolicy. Este permiso se incluye en las funciones de propietario del proyecto, administrador de IAM del proyecto y administrador de la organización.
   También debes tener habilitada la API de Cloud SQL Admin. Si usas las funciones de proyecto heredadas (Visualizador, Editor o Propietario), la cuenta de servicio debe tener, al menos, la función Editor.
7. Haz clic en Listo para terminar de crear la cuenta de servicio.
8. Haz clic en el menú de acciones de tu nueva cuenta de servicio y, luego, selecciona Administrar claves.
9. Haz clic en el menú desplegable Agregar clave y, luego, en Crear clave nueva.
10. Confirma que el tipo de clave sea JSON y, luego, haz clic en Crear.

    El archivo de claves privadas se descargará en tu equipo. Puedes moverlo a otra ubicación. Protege el archivo de claves.

Usa el proxy de autenticación de Cloud SQL con una IP privada

Para conectarse a una instancia de Cloud SQL mediante una IP privada, el proxy de autenticación de Cloud SQL debe estar en un recurso que tenga acceso a la misma red de VPC que la instancia.

El proxy de autenticación de Cloud SQL usa la IP para establecer una conexión con tu instancia de Cloud SQL. De forma predeterminada, el proxy de autenticación de Cloud SQL intenta conectarse con una dirección IPv4 pública.

Si la instancia de Cloud SQL solo tiene una IP privada o la instancia tiene configuradas una IP pública y una privada, y quieres que el proxy de autenticación de Cloud SQL use la dirección IP privada, debes proporcionar la siguiente opción cuando comiences el proxy de autenticación de Cloud SQL:

--private-ip

Usa el proxy de autenticación de Cloud SQL con instancias que tengan habilitado Private Service Connect

Puedes usar el proxy de autenticación de Cloud SQL para conectarte a una instancia de Cloud SQL con Private Service Connect habilitado.

El proxy de autenticación de Cloud SQL es un conector que proporciona acceso seguro a esta instancia sin necesidad de tener redes autorizadas ni de configurar SSL.

Para permitir conexiones cliente de proxy de autenticación de Cloud SQL, debes configurar un registro DNS que coincida con el nombre de DNS recomendado que se proporciona para la instancia. El registro DNS es una asignación entre un recurso DNS y un nombre de dominio.

Si deseas obtener más información sobre el uso del proxy de autenticación de Cloud SQL para conectarte a instancias con Private Service Connect habilitado, consulta Conéctate con el proxy de autenticación de Cloud SQL.

Ejecuta el proxy de Cloud SQL Auth en un proceso independiente

Ejecutar el proxy de autenticación de Cloud SQL en un proceso terminal de Cloud Shell separado puede ser útil para evitar mezclar el resultado de la consola con el de otros programas. Usa la sintaxis que se muestra a continuación para invocar el proxy de autenticación de Cloud SQL en un proceso separado.

Linux

En Linux o macOS, usa un & al final de la línea de comandos para iniciar el proxy de autenticación de Cloud SQL en un proceso separado:

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

Windows

En Windows PowerShell, usa el comando Start-Process para iniciar el proxy de autenticación de Cloud SQL en un proceso separado:

Start-Process --filepath "cloud-sql-proxy.exe"
  --ArgumentList "
  --credentials-file PATH_TO_KEY_FILEINSTANCE_CONNECTION_NAME"

Ejecuta el proxy de autenticación de Cloud SQL en un contenedor de Docker

Para ejecutar el proxy de autenticación de Cloud SQL en un contenedor de Docker, usa la imagen de Docker del proxy de autenticación de Cloud SQL disponible en Google Container Registry. Puedes instalar la imagen de Docker del proxy de autenticación de Cloud SQL con este comando gcloud:

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

Para iniciar el proxy de autenticación de Cloud SQL, usa los sockets de TCP o de Unix con los comandos que se muestran a continuación.

Nota: Los sockets de Unix no son compatibles con aplicaciones escritas en el lenguaje de programación Java o con el entorno de Windows.

Sockets 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.13.0 \
      --address 0.0.0.0 \
      --credentials-file /path/to/service-account-key.json \
      INSTANCE_CONNECTION_NAME

Sockets 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

Si usas una imagen optimizada para contenedores, usa un directorio que admita operaciones de escritura en lugar de /cloudsql, por ejemplo:

v /mnt/stateful_partition/cloudsql:/cloudsql

Si usas las credenciales que proporciona tu instancia de Compute Engine, no incluyas el parámetro credential_file ni la línea -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Ejecuta el proxy de autenticación de Cloud SQL como servicio

La ejecución del proxy de autenticación de Cloud SQL como servicio en segundo plano es una opción para las cargas de trabajo de desarrollo y producción locales. En desarrollo, cuando necesites acceder a tu instancia de Cloud SQL, puedes iniciar el servicio en segundo plano y detenerlo cuando termines.

Para las cargas de trabajo de producción, el proxy de autenticación de Cloud SQL no cuenta con compatibilidad integrada de ejecución como un servicio de Windows, pero puedes usar administradores de servicios de terceros. Por ejemplo, puedes usar NSSM para configurar el proxy de autenticación de Cloud SQL como un servicio de Windows, así como supervisarlo y reiniciarlo automáticamente si deja de responder. Consulta la documentación de NSSM para obtener más información.

Nota: si ejecutas el proxy de autenticación de Cloud SQL como servicio, ten en cuenta que usa una conexión segura para comunicarse con instancias de Cloud SQL, pero las conexiones de tu aplicación al proxy de autenticación de Cloud SQL no se encriptan. Por este motivo, asegúrate de que solo los usuarios de confianza puedan acceder a la dirección y al puerto que escucha el proxy de autenticación de Cloud SQL.

Aplica el uso del proxy de autenticación de Cloud SQL

Habilita el uso del proxy de autenticación de Cloud SQL en Cloud SQL mediante ConnectorEnforcement.

gcloud

El siguiente comando aplica el uso de conectores de Cloud SQL.

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

Para inhabilitar la aplicación, usa la siguiente línea de código: --connector-enforcement NOT_REQUIRED La actualización no activa un reinicio.

REST v1

El siguiente comando aplica el uso de conectores de Cloud SQL

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• project-id: El ID del proyecto
• instance-id: El ID de la instancia

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Para inhabilitar la aplicación, usa "connectorEnforcement": "NOT_REQUIRED" en su lugar. La actualización no activa un reinicio.

REST v1beta4

El siguiente comando aplica el uso de conectores de Cloud SQL.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• project-id: El ID del proyecto
• instance-id: El ID de la instancia

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente 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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Para inhabilitar la aplicación, usa "connectorEnforcement": "NOT_REQUIRED" en su lugar. La actualización no activa un reinicio.

Sugerencias para trabajar con el proxy de autenticación de Cloud SQL

Invoca el proxy de autenticación de Cloud SQL

En todas las muestras de invocaciones del proxy, este se inicia en segundo plano con el proxy de autenticación de Cloud SQL, por lo que se mostrará un mensaje. Reserva esa terminal de Cloud Shell para el proxy de autenticación de Cloud SQL así evitas que los resultados se mezclen con los de otros programas. Además, el resultado del proxy de autenticación de Cloud SQL puede ayudarte a diagnosticar problemas de conexión, por lo que podría resultar útil capturarlo en un archivo de registro. Si no inicias el proxy de autenticación de Cloud SQL en segundo plano, el resultado se dirige a stdout, a menos que se redireccione.

No es necesario que uses /cloudsql como el directorio para los sockets del proxy de autenticación de Cloud SQL. (Ese nombre de directorio se eligió para minimizar las diferencias con las strings de conexión de App Engine). Pero, si decides cambiar el nombre del directorio, recuerda mantener la longitud al mínimo, ya que se incorporará a una string más extensa que tiene límites de longitud impuestos por el sistema operativo. Este límite depende del sistema, pero suele ser de entre 91 y 108 caracteres. En Linux, la longitud se suele definir como 108, y puedes usar el siguiente comando para verificar:

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

Usa el proxy de autenticación de Cloud SQL para conectar varias instancias

Puedes usar un cliente de proxy de autenticación de Cloud SQL local para conectarte a varias instancias de Cloud SQL. La forma de hacerlo depende de si usas sockets de Unix o de TCP.

Sockets Unix

Para conectar el proxy de autenticación de Cloud SQL a varias instancias, proporciona cada nombre de conexión de instancia como un argumento al proxy de autenticación de Cloud SQL en una lista separada por espacios. El proxy de autenticación de Cloud SQL se conecta a cada instancia cuando se inicia.

Conectas cada instancia con su socket, en el directorio especificado.

Por ejemplo:

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

Sockets TCP

Cuando te conectas con TCP, debes especificar un puerto en tu máquina para que el proxy de autenticación de Cloud SQL escuche en cada instancia de Cloud SQL. Cuando te conectes a varias instancias de Cloud SQL, cada puerto especificado debe ser único y estar disponible para usarlo en tu máquina.

Por ejemplo:

    # 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
  

Soluciona problemas relacionados con las conexiones del proxy de autenticación de Cloud SQL

La imagen de Docker del proxy de autenticación de Cloud SQL se basa en una versión específica del proxy de autenticación de Cloud SQL. Cuando esté disponible una versión nueva del proxy de autenticación de Cloud SQL, extrae la versión nueva de la imagen de Docker del proxy de autenticación de Cloud SQL para mantener actualizado el entorno. Para ver la versión actual del proxy de autenticación de Cloud SQL, consulta la página de versiones de GitHub del proxy de autenticación de Cloud SQL.

Si no puedes conectar tu instancia de Cloud SQL con el proxy de autenticación de Cloud SQL, ten en cuenta los siguientes consejos para intentar descubrir la causa del problema.

• Comprueba el resultado del proxy de autenticación de Cloud SQL.

  A menudo, el resultado del proxy de autenticación de Cloud SQL puede ayudarte a determinar el origen del problema y cómo resolverlo. Canaliza el resultado a un archivo o mira la terminal de Cloud Shell desde la que iniciaste el proxy de autenticación de Cloud SQL.

• Si recibes un error 403 notAuthorized y usas una cuenta de servicio para autenticar el proxy de autenticación de Cloud SQL, asegúrate de que la cuenta de servicio tenga los permisos correctos.

  Para verificar la cuenta de servicio, puedes buscar su ID en la página del IAM. Debe tener el permiso cloudsql.instances.connect. Las funciones predefinidas Cloud SQL Admin, Client y Editor tienen este permiso.

• Si te conectas desde App Engine y recibes un error 403 notAuthorized, verifica el valor cloud_sql_instances de app.yaml para ver si hay un nombre de conexión de instancia mal escrito o incorrecto. Los nombres de las conexiones de instancias siempre tienen el formato PROJECT:REGION:INSTANCE.

  Además, comprueba que la cuenta de servicio de App Engine (por ejemplo, $[e-mail]) tenga el rol de IAM de cliente de Cloud SQL.

  Si el servicio de App Engine reside en un proyecto (proyecto A) y la base de datos se encuentra en otro (proyecto B), este error significa que la cuenta de servicio de App Engine no tiene la función de IAM de cliente de Cloud SQL en el proyecto con la base de datos (proyecto B).

• Asegúrate de habilitar la API de Cloud SQL Admin.

  De lo contrario, verás un resultado como Error 403: Access Not Configured en los registros del proxy de autenticación de Cloud SQL.

• Si incluyes varias instancias en tu lista de instancias, asegúrate de usar una coma como delimitador, sin espacios. Si usas TCP, asegúrate de especificar puertos diferentes para cada instancia.

• Si te conectas con sockets de UNIX, confirma que los sockets se crearon con la lista del directorio que proporcionaste cuando se inició el proxy de autenticación de Cloud SQL.

• Si tienes una política de firewall saliente, asegúrate de que permita conexiones al puerto 3307 en la instancia de Cloud SQL de destino.

  Nota: el proxy de autenticación de Cloud SQL usa 3307 para conectarse al servidor proxy de autenticación de Cloud SQL. El puerto 5432 es el predeterminado para el protocolo PostgreSQL a través de una conexión TCP directa (en la que no se usa el proxy de autenticación de Cloud SQL).

• Puedes confirmar que el proxy de autenticación de Cloud SQL se inició de manera correcta revisando los registros en la sección Operaciones > Registros > Explorador de registros de la consola de Google Cloud. Una operación exitosa se ve de esta forma:

  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
  

• Problemas de cuota: Cuando se incumple la cuota de la API de Cloud SQL Admin, el proxy de autenticación de Cloud SQL se inicia con el siguiente mensaje de error:

  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 vez que una aplicación se conecta al proxy, este informa el siguiente error:

  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
  

  Solución: Identifica la fuente del problema de cuota, por ejemplo, una aplicación que usa el conector de forma incorrecta y crea conexiones nuevas de forma innecesaria, o comunícate con el equipo de asistencia para solicitar un aumento de la cuota de la API de Cloud SQL Admin. Si el error de cuota aparece en el inicio, debes volver a implementar la aplicación para reiniciar el proxy. Si el error de cuota aparece después del inicio, no es necesario volver a implementar.

¿Qué sigue?

• Obtén más información sobre el proxy de autenticación de Cloud SQL.
• Obtén más información sobre la Identity and Access Management (IAM).
• Obtén más información sobre cuentas de servicio.
• Obtén información sobre los dos niveles de control de acceso para las instancias de Cloud SQL.
• Crea usuarios y bases de datos.
• Obtén información sobre cómo conectarte a la instancia desde tu aplicación.
• Obtén más información sobre el cliente psql.
• Obtén información sobre opciones de asistencia.