Conectarse mediante el proxy de autenticación de Cloud SQL

MySQL   |  PostgreSQL   |  SQL Server

En esta página se describe cómo conectarse a una instancia de Cloud SQL mediante 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.

Información general

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

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

Algunos Google Cloud servicios y aplicaciones usan el proxy de autenticación de Cloud SQL para proporcionar conexiones para rutas de IP públicas con cifrado y autorización, como los siguientes:

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

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

Nota: Para conectarse desde Google Kubernetes Engine, le recomendamos que ejecute el proxy de autenticación de Cloud SQL con un patrón sidecar, como un contenedor adicional que comparta un pod con su 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 para obtener una introducción básica a su uso.

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

Antes de empezar

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

1. • En el caso de una cuenta de usuario o de servicio, asegúrate de que tenga el rol Cliente de Cloud SQL. Este rol contiene el permiso cloudsql.instances.connect, que autoriza a una entidad para que se conecte a todas las instancias de Cloud SQL de un proyecto.

     Ir a la página de gestión de identidades y accesos

   • También puedes incluir una condición de gestión de identidades y accesos en el enlace de la política de gestión de identidades y accesos que concede a la cuenta permiso para conectarse solo a una instancia de Cloud SQL específica.

2. Enable the Cloud SQL Admin API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

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

Descargar 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.18.2/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.18.2/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.18.2/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.18.2/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.18.2/cloud-sql-proxy.x64.exe y selecciona Guardar enlace como para descargar el proxy de autenticación de Cloud SQL. Cambia el nombre del archivo a 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.18.2/cloud-sql-proxy.x86.exe y selecciona Guardar enlace como para descargar el proxy de autenticación de Cloud SQL. Cambia el nombre del archivo a cloud-sql-proxy.exe.

Imagen de Docker del proxy de autenticación 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 predeterminada del proxy de autenticación de Cloud SQL usa distroless, que no contiene ningún shell. Si necesitas un 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 imagen más reciente en tu máquina local con Docker mediante el siguiente comando:

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

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

Otros SO

En el caso de otros sistemas operativos que no se incluyan aquí, puedes compilar el proxy de autenticación de Cloud SQL a partir del código fuente.

Iniciar el proxy de autenticación de Cloud SQL

En función del lenguaje y del entorno, puedes iniciar el proxy de autenticación de Cloud SQL mediante sockets TCP, sockets Unix o la imagen Docker del proxy de autenticación de Cloud SQL. El archivo binario del proxy de autenticación de Cloud SQL se conecta a una o varias instancias de Cloud SQL especificadas en la línea de comandos y abre una conexión local como TCP o como socket Unix. Otras aplicaciones y servicios, como el código de tu aplicación o las herramientas de cliente de gestión de bases de datos, pueden conectarse a instancias de Cloud SQL a través de esas conexiones TCP o de socket Unix.

Advertencia: Ten cuidado al enlazar el proxy de autenticación de Cloud SQL a una interfaz externa. Cualquier persona que tenga acceso a esa interfaz o puerto estará autorizada para conectarse a tu instancia.

Sockets TCP

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

También puedes especificar otra dirección para la conexión local. Por ejemplo, así se configura el proxy de autenticación de Cloud SQL para que escuche en 0.0.0.0:1234 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 Resumen de tu instancia en la Google Cloud consola o ejecutando el siguiente comando:

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

   Por ejemplo: myproject:myregion:myinstance.

2. Si la instancia tiene configuradas tanto la IP pública como la privada y quieres que el proxy de autenticación de Cloud SQL use la dirección IP privada, debes proporcionar la siguiente opción al iniciar el proxy de autenticación de Cloud SQL:

   --private-ip

3. Si utilizas una cuenta de servicio para autenticar el proxy de autenticación de Cloud SQL, anota la ubicación en tu máquina cliente del archivo de clave privada que se creó cuando creaste la cuenta de servicio.
4. Inicia el proxy de autenticación de Cloud SQL.

   Estas son algunas cadenas de invocación del proxy de autenticación de Cloud SQL:

   • Con la autenticación del SDK de Google Cloud:

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

     El puerto especificado no debe estar en uso. Por ejemplo, no debe estarlo por un servidor de base de datos local.
   • Usar una cuenta de servicio e incluir explícitamente 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 Unix en Windows, por lo que esta opción solo está disponible para las plataformas Linux y macOS.

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

Nota: El estándar de PostgreSQL requiere el 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 Unix, el directorio de destino debe existir y tanto el proxy de autenticación de Cloud SQL como la aplicación deben tener acceso de lectura y escritura a él.

1. Copia tu INSTANCE_CONNECTION_NAME. Puedes encontrarlo en la página Resumen de tu instancia en la Google Cloud consola o ejecutando el siguiente comando:

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

   Por ejemplo: myproject:myregion:myinstance.

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

   sudo mkdir /cloudsql; sudo chmod 777 /cloudsql

3. Si utilizas una cuenta de servicio para autenticar el proxy de autenticación de Cloud SQL, anota la ubicación en tu máquina cliente del archivo de clave privada que se creó cuando creaste la cuenta de servicio.
4. Abre una nueva ventana de terminal de Cloud Shell e inicia el proxy de autenticación de Cloud SQL.

   Estas son algunas cadenas de invocación del proxy de autenticación de Cloud SQL:

   • Usar la autenticación del SDK de Google Cloud:

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

   • Usar 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 propio terminal de Cloud Shell para poder monitorizar su salida sin que se mezcle con la 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 Unix para conectarte a Cloud SQL mediante el proxy de autenticación de Cloud SQL, asegúrate de que la longitud del nombre de archivo del socket no supere el límite del sistema. Depende del sistema, pero suele ser de entre 91 y 108 caracteres. En Linux, la longitud suele ser de 108. Puedes usar el siguiente comando para comprobarlo:

   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 Docker, usa la imagen Docker del proxy de autenticación de Cloud SQL, disponible en Google Container Registry.

Puedes iniciar el proxy de autenticación de Cloud SQL mediante sockets TCP o sockets Unix con los comandos que se muestran a continuación. Las opciones usan un INSTANCE_CONNECTION_NAME como cadena de conexión para identificar una instancia de Cloud SQL. Puedes encontrar el INSTANCE_CONNECTION_NAME en la página Resumen de tu instancia en la Google Cloud consola 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 de Unix en Windows.

En función del lenguaje y del entorno, puedes iniciar el proxy de autenticación de Cloud SQL mediante sockets TCP o sockets Unix. Los sockets Unix no son compatibles con las aplicaciones escritas en lenguaje de programación Java o pensadas para el entorno Windows.

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

Si usas las credenciales proporcionadas por 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. En el parámetro de instancias se requiere el valor "0.0.0.0" para que sea posible acceder al puerto desde fuera del contenedor Docker.

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

Si usas las credenciales proporcionadas por 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, utiliza un directorio en el que se pueda escribir en lugar de /cloudsql. Por ejemplo:

-v /mnt/stateful_partition/cloudsql:/cloudsql

Puedes especificar más de una instancia si las separas por comas. También puedes usar los metadatos de Compute Engine para determinar de forma dinámica las instancias a las que conectarte. Consulta más información sobre los parámetros del proxy de autenticación de Cloud SQL.

Conectarse con el cliente psql

Debian o Ubuntu

Instala el cliente psql desde el administrador de paquetes:

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

CentOS o 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 básica de PostgreSQL para la plataforma en la página de descargas de PostgreSQL.
   La distribución principal incluye el cliente psql.
2. Instala la base de datos PostgreSQL según se indica en las instrucciones de la página de descarga.

La cadena de conexión que utilices dependerá de si has iniciado el proxy de autenticación de Cloud SQL mediante un socket TCP, un socket UNIX o 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 esté definido como disable, el proxy de autenticación de Cloud SQL proporciona una conexión cifrada.

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

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

Usar 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 esté definido como disable, el proxy de autenticación de Cloud SQL proporciona una conexión cifrada.

2. Introduce la contraseña.
3. Aparecerá el prompt de psql.

¿Necesitas ayuda? Para obtener ayuda para solucionar problemas con el proxy, consulta el artículo Solucionar problemas de conexiones del proxy de autenticación de Cloud SQL o visita nuestra página de asistencia de Cloud SQL.

Conectarse con una aplicación

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

Conexión 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:

• NOMBRE_CONEXIÓN_CLOUD_SQL debe representarse como <MI-PROYECTO>:<REGIÓN-INSTANCIA>:<NOMBRE-INSTANCIA>.
• Si usas el argumento ipTypes=PRIVATE, se obligará a SocketFactory a conectarse con la IP privada asociada a una instancia.
• Consulta los requisitos de la versión de la fábrica de sockets JDBC para el archivo 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

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;
    }
}

Conexión con sockets 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);
    }


    // cloudSqlRefreshStrategy set to "lazy" is used to perform a
    // refresh when needed, rather than on a scheduled interval.
    // This is recommended for serverless environments to
    // avoid background refreshes from throttling CPU.
    config.addDataSourceProperty("cloudSqlRefreshStrategy", "lazy");

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

En los ejemplos anteriores se tratan los casos prácticos más habituales, pero el proxy de autenticación de Cloud SQL también tiene otras opciones de configuración que se pueden definir con argumentos de línea de comandos. Para obtener ayuda sobre 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 del repositorio de GitHub del proxy de autenticación de Cloud SQL para ver más ejemplos de 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

Cuando autenticas el proxy de autenticación de Cloud SQL, le permites acceder aGoogle Cloud en nombre de tu aplicación mediante un conjunto de credenciales de Google. Se trata de un proceso aparte de la autenticación de usuario de la base de datos. La autenticación de bases de datos de usuarios de gestión de identidades y accesos está integrada con el proxy de autenticación de Cloud SQL.

Todas estas opciones usan un INSTANCE_CONNECTION_NAME como cadena de conexión para identificar una instancia de Cloud SQL. Puedes encontrar el INSTANCE_CONNECTION_NAME en la página Resumen de tu instancia en la Google Cloud consola 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. Para obtener instrucciones sobre cómo crear un archivo de credenciales JSON para una cuenta de servicio, consulta el artículo Crear una cuenta de servicio.

El proxy de autenticación de Cloud SQL ofrece varias alternativas para la autenticación, en función de tu entorno. El proxy de autenticación de Cloud SQL comprueba cada uno de los siguientes elementos, en el orden que se indica, y utiliza el primero que encuentra para intentar autenticarse:

1. Credenciales proporcionadas por la marca credentials-file.

   Usa una cuenta de servicio para crear y descargar el archivo JSON asociado, y define la marca --credentials-file en la ruta del archivo cuando inicies 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 definida en la ruta y el nombre de archivo de un archivo de credenciales JSON. La ruta 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 añadir roles de gestión de identidades y accesos a una cuenta de servicio, consulta el artículo Conceder roles a cuentas de servicio.

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

2. Credenciales proporcionadas por un token de acceso.

   Crea un token de acceso e invoca el comando cloud-sql-proxy con la marca --token definida en un token de acceso de OAuth 2.0. Por ejemplo:

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

3. Credenciales proporcionadas por una variable de entorno.

   Esta opción es similar a usar la marca --credentials-file, pero en lugar de usar el argumento de línea de comandos --credentials-file, debes especificar el archivo de credenciales JSON que has definido en la variable de entorno GOOGLE_APPLICATION_CREDENTIALS.

4. Credenciales de un cliente de CLI de gcloud autenticado.

   Si has instalado la CLI de gcloud y te has autenticado con tu cuenta personal, el proxy de autenticación de Cloud SQL puede usar las mismas credenciales de cuenta. Este método es especialmente útil para poner en marcha un entorno de desarrollo.

   Para habilitar el proxy de autenticación de Cloud SQL para que use tus credenciales de gcloud CLI, usa el siguiente comando para autenticar gcloud CLI:

   gcloud auth application-default login

5. Credenciales asociadas a 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 la instancia de Compute Engine. Si la cuenta de servicio tiene los permisos necesarios para la instancia de Cloud SQL, el proxy de autenticación de Cloud SQL se autenticará correctamente.

   Si la instancia de Compute Engine está en el mismo proyecto que la instancia de Cloud SQL, la cuenta de servicio predeterminada de la instancia de Compute Engine tiene los permisos necesarios para autenticar el proxy de autenticación de Cloud SQL. Si las dos instancias están en proyectos diferentes, debe añadir la cuenta de servicio de la instancia de Compute Engine al proyecto que contiene la instancia de Cloud SQL.

6. Cuenta de servicio predeterminada del entorno

   Si Cloud SQL Auth Proxy no encuentra credenciales en ninguno de los lugares que hemos mencionado anteriormente, sigue la lógica que se describe en 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 autenticarse de forma predeterminada. Si usas una cuenta de servicio predeterminada, debe tener los permisos que se indican en la sección sobre roles y permisos. Para obtener más información sobre el enfoque de Google Cloud en la autenticación, consulta el resumen de la autenticación.

Crear una cuenta de servicio

Si te conectas desde Compute Engine, asegúrate de que tu máquina virtual tenga el scope adecuado para conectarse mediante la API Cloud SQL Admin.

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

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

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

   Ir a Cuentas de servicio

2. Selecciona el proyecto que contiene tu instancia de Cloud SQL.
3. Haz clic en Crear cuenta de servicio.
4. En el campo Nombre de cuenta de servicio, escribe un nombre descriptivo para la cuenta de servicio.
5. Cambia el ID de cuenta de servicio por un valor único y reconocible y, a continuación, haz clic en Crear y continuar.
6. Haz clic en el campo Selecciona un rol y elige uno de los siguientes:
   • 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 los roles Propietario del proyecto, Administrador de IAM del proyecto y Administrador de la organización.
   También debes haber habilitado la API Admin de Cloud SQL. Si usas los roles de proyecto antiguos (Lector, Editor y Propietario), la cuenta de servicio debe tener al menos el rol Editor.
7. Haz clic en Hecho para terminar de crear la cuenta de servicio.
8. Haz clic en el menú de acciones de tu nueva cuenta de servicio y, a continuación, selecciona Gestionar claves.
9. Haz clic en el menú desplegable Añadir clave y, a continuación, en Crear clave.
10. Confirma que el tipo de clave es JSON y, a continuación, haz clic en Crear.

    El archivo de clave privada se descarga en tu máquina. Puedes moverlo a otra ubicación. Debes proteger el archivo de clave.

Usar el proxy de autenticación de Cloud SQL con IP privada

Para conectarte 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 mediante una dirección IPv4 pública.

Si tu instancia de Cloud SQL solo tiene una IP privada o tiene configuradas tanto una IP pública como 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 al iniciar el proxy de autenticación de Cloud SQL:

--private-ip

Usar 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 redes autorizadas ni de configurar SSL.

Para permitir las conexiones de clientes del proxy de autenticación de Cloud SQL, debe 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.

Para obtener más información sobre cómo usar el proxy de autenticación de Cloud SQL para conectarse a instancias con Private Service Connect habilitado, consulta Conectarse mediante el proxy de autenticación de Cloud SQL.

Ejecutar el proxy de autenticación de Cloud SQL en un proceso independiente

Ejecutar el proxy de autenticación de Cloud SQL en un proceso de terminal de Cloud Shell independiente puede ser útil para evitar que su salida de consola se mezcle con la salida 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 independiente.

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 independiente:

./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 independiente:

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

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

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

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

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

Nota: Los sockets Unix no se admiten en aplicaciones escritas en el lenguaje de programación Java ni en el entorno 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.18.2 \
      --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.18.2 --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, utiliza un directorio en el que se pueda escribir en lugar de /cloudsql. Por ejemplo:

v /mnt/stateful_partition/cloudsql:/cloudsql

Si utiliza las credenciales proporcionadas por su instancia de Compute Engine, no incluya el parámetro credential_file ni la línea -v PATH_TO_KEY_FILE:/path/to/service-account-key.json.

Ejecutar el proxy de autenticación de Cloud SQL como un servicio

Ejecutar el proxy de autenticación de Cloud SQL como servicio en segundo plano es una opción para el desarrollo local y las cargas de trabajo de producción. Durante el desarrollo, cuando necesites acceder a tu instancia de Cloud SQL, puedes iniciar el servicio en segundo plano y detenerlo cuando hayas terminado.

En el caso de las cargas de trabajo de producción, el proxy de autenticación de Cloud SQL no ofrece actualmente compatibilidad integrada para ejecutarse como un servicio de Windows, pero se pueden usar gestores de servicios de terceros para ejecutarlo como un servicio. Por ejemplo, puedes usar NSSM para configurar el proxy de autenticación de Cloud SQL como un servicio de Windows. NSSM monitoriza el proxy de autenticación de Cloud SQL y lo reinicia 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 un servicio, ten en cuenta que utiliza una conexión segura para comunicarse con las instancias de Cloud SQL, pero las conexiones de tu aplicación al proxy de autenticación de Cloud SQL no están cifradas. Por este motivo, asegúrate de que solo los usuarios de confianza puedan acceder a la dirección y al puerto en los que escucha el proxy de autenticación de Cloud SQL.

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

Si usas una instancia habilitada para Private Service Connect, hay una limitación. Si la instancia tiene habilitada la aplicación de conectores, no puedes crear réplicas de lectura para la instancia. Del mismo modo, si la instancia tiene réplicas de lectura, no puedes habilitar la aplicación de conectores en ella.

gcloud

El siguiente comando obliga a usar conectores de Cloud SQL.

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

Para inhabilitar la medida, usa la siguiente línea de código: --connector-enforcement NOT_REQUIRED La actualización no requiere que se reinicie.

REST v1

El siguiente comando obliga a usar conectores de Cloud SQL

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• project-id: el ID del proyecto.
• instance-id: el ID de 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, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, 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 presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, 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 siguiente:

{
  "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 provoca un reinicio.

REST v1beta4

El siguiente comando obliga a usar conectores de Cloud SQL.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• project-id: el ID del proyecto.
• instance-id: el ID de 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, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, 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 presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, 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 siguiente:

{
  "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 provoca un reinicio.

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

Invocar el proxy de autenticación de Cloud SQL

Todas las invocaciones de proxy de ejemplo inician el proxy de autenticación de Cloud SQL en segundo plano, por lo que se devuelve un prompt. Reserva esa terminal de Cloud Shell para el proxy de autenticación de Cloud SQL para evitar que su salida se mezcle con la de otros programas. Además, la salida del proxy de autenticación de Cloud SQL puede ayudarte a diagnosticar problemas de conexión, por lo que puede ser útil registrarla en un archivo de registro. Si no inicias el proxy de autenticación de Cloud SQL en segundo plano, la salida se dirigirá a stdout a menos que se redirija.

No es obligatorio usar /cloudsql como directorio para los sockets del proxy de autenticación de Cloud SQL. (Ese nombre de directorio se eligió para que no hubiera apenas diferencias con las cadenas de conexión de App Engine). Sin embargo, si cambias el nombre del directorio, procura que sea lo más corto posible, ya que se incorpora a una cadena más larga que tiene un límite de longitud impuesto por el sistema operativo. Depende del sistema, pero suele ser de entre 91 y 108 caracteres. En Linux, la longitud suele ser de 108 y puedes usar el siguiente comando para comprobarlo:

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

Usar el proxy de autenticación de Cloud SQL para conectarse a varias instancias

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

Sockets Unix

Para conectar el proxy de autenticación de Cloud SQL a varias instancias, debes proporcionar el nombre de conexión de cada instancia como argumento del 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.

Te conectas a cada instancia mediante 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 mediante TCP, especificas 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
  

Solucionar problemas de 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 haya una nueva versión del proxy de autenticación de Cloud SQL, extrae la nueva versión de la imagen Docker del proxy de autenticación de Cloud SQL para mantener tu entorno actualizado. Puedes consultar la versión actual del proxy de autenticación de Cloud SQL en la página de lanzamientos de GitHub del proxy de autenticación de Cloud SQL.

Si tienes problemas para conectarte a tu instancia de Cloud SQL mediante el proxy de autenticación de Cloud SQL, prueba lo siguiente para averiguar qué está causando el problema.

• Comprueba que estás usando la dirección IP para conectarte a la instancia y no el endpoint de escritura.

• Comprueba la salida del proxy de autenticación de Cloud SQL.

  A menudo, la salida del proxy de autenticación de Cloud SQL puede ayudarte a determinar el origen del problema y cómo solucionarlo. Dirige la salida a un archivo o consulta la terminal de Cloud Shell en la que has iniciado 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.

  Puedes consultar la cuenta de servicio buscándola por su ID en la página de gestión de identidades y accesos. Debe tener el permiso cloudsql.instances.connect. Los roles predefinidos Cloud SQL Admin, Client y Editor tienen este permiso.

• Si te conectas desde App Engine y recibes un error 403 notAuthorized, comprueba el valor app.yaml cloud_sql_instances para ver si el nombre de conexión de la instancia está mal escrito o es incorrecto. Los nombres de conexión de la instancia 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 gestión de identidades y accesos Cliente de Cloud SQL.

  Si el servicio de App Engine se encuentra en un proyecto (proyecto A) y la base de datos en otro (proyecto B), este error significa que no se ha asignado el rol de cliente de Cloud SQL a la cuenta de servicio de App Engine en el proyecto que contiene la base de datos (proyecto B).

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

  Si no es así, 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 mediante sockets UNIX, comprueba que se hayan creado los sockets. Para ello, muestra el directorio que proporcionaste al iniciar el proxy de autenticación de Cloud SQL.

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

  Nota: El proxy de autenticación de Cloud SQL usa el puerto 3307 para conectarse al servidor del proxy de autenticación de Cloud SQL. El puerto 5432 es el puerto predeterminado del protocolo PostgreSQL en una conexión TCP directa (sin usar el proxy de autenticación de Cloud SQL).

• Para confirmar que Cloud SQL Auth Proxy se ha iniciado correctamente, consulta los registros en la sección Operaciones > Registro > Explorador de registros de la consola deGoogle Cloud . Una operación correcta tiene el siguiente aspecto:

  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 supera la cuota de la API Admin de Cloud SQL, 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 del 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 el origen del problema de cuota (por ejemplo, una aplicación está haciendo un uso inadecuado del conector y creando conexiones innecesarias) o ponte en contacto con el equipo de Asistencia para solicitar un aumento de la cuota de la API Admin de Cloud SQL. Si el error de cuota aparece al iniciar, 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.

Siguientes pasos

• Consulta más información sobre el proxy de autenticación de Cloud SQL.
• Consulta más información sobre la gestión de identidades y accesos (IAM).
• Consulta más información sobre las cuentas de servicio.
• Consulta información sobre los dos niveles de control de acceso de las instancias de Cloud SQL.
• Crea usuarios y bases de datos.
• Consulta información sobre cómo conectarte a tu instancia desde tu aplicación.
• Consulta información sobre el cliente psql.
• Más información sobre las opciones de asistencia