Conectarse mediante el proxy de autenticación de AlloyDB

En esta página se explica cómo configurar y usar el proxy de autenticación de AlloyDB para establecer conexiones autorizadas y cifradas con instancias de AlloyDB. Para obtener una descripción general conceptual del proxy de autenticación, consulta Información sobre el proxy de autenticación de AlloyDB.

Para usar el proxy de autenticación de AlloyDB, debes seguir varios pasos de configuración únicos, iniciar el cliente del proxy de autenticación y, a continuación, conectarte a las bases de datos mediante él:

1. Pasos de configuración:
   1. Descarga el cliente Auth Proxy en tu host cliente.
   2. Elige el principal de Gestión de Identidades y Accesos (IAM) que quieras usar para la autorización, comprueba que tenga los permisos necesarios y asegúrate de que sus credenciales estén disponibles en el host del cliente.
   3. Recopila los URIs de conexión de las instancias de AlloyDB a las que quieras conectarte.
2. Inicia el cliente Auth Proxy en el host del cliente.
3. Conecta una aplicación a una base de datos abriendo una conexión local al cliente proxy de autenticación.

Descarga el cliente Auth Proxy

La máquina en la que descargues el cliente del proxy de autenticación dependerá de si quieres conectarte a tus instancias de AlloyDB desde dentro o desde fuera de su red de VPC.

Si quieres conectarte a tu clúster mediante el acceso a servicios privados, puedes descargar el cliente Auth Proxy en una instancia de máquina virtual (VM) de Compute Engine que se ejecute en la red de VPC que tenga acceso a servicios privados a tu clúster.

Si tienes previsto conectarte a tu clúster desde fuera de la VPC, la máquina en la que lo instales dependerá de la estrategia de conexión externa que utilices. Por ejemplo, puedes instalar el cliente Auth Proxy en un ordenador macOS o Windows que esté en la misma red local que tu aplicación y, a continuación, usar un servidor SOCKS que se ejecute en tu red de VPC de AlloyDB como intermediario de conexión. Para obtener más información, consulta Conectarse a un clúster desde fuera de su VPC.

docker pull gcr.io/alloydb-connectors/alloydb-auth-proxy:latest

Elige la entidad de IAM y prepárala para la autorización

AlloyDB Auth Proxy admite el uso de estos tipos de principales de IAM para autorizar conexiones entre tu cliente y una instancia de AlloyDB:

• Una cuenta de servicio gestionada por el usuario. Puedes crear una cuenta de servicio de gestión de identidades y accesos para tu aplicación y, a continuación, autorizar las conexiones con ella.

  Google recomienda encarecidamente que utilices una cuenta de servicio para la autorización en entornos de producción.

• Tu cuenta de usuario. Puedes usar tu propia cuenta de usuario de IAM para autorizar conexiones.

  Usar tu propia cuenta de usuario es práctico en entornos de desarrollo en los que gestionas recursos de AlloyDB con la CLI de gcloud, desarrollas la base de datos con una herramienta como psql y desarrollas código de aplicación en el mismo host.

• La cuenta de servicio predeterminada de Compute Engine. Si el host del cliente es una instancia de Compute Engine, puedes usar la cuenta de servicio predeterminada de Compute Engine para autorizar las conexiones.

Después de elegir el principal de gestión de identidades y accesos que vas a usar, debes asegurarte de que tenga los permisos de gestión de identidades y accesos necesarios y de que sus credenciales estén disponibles en tu host cliente.

Permisos de gestión de identidades y accesos necesarios

La entidad de gestión de identidades y accesos que uses para autorizar las conexiones debe tener los permisos que proporcionan los roles predefinidos roles/alloydb.client (Cliente de Cloud AlloyDB) y roles/serviceusage.serviceUsageConsumer (Consumidor de uso de servicios).

Para asignar el rol de cliente de Cloud AlloyDB a un principal de IAM, sigue estos pasos:

• La API Cloud Resource Manager debe estar habilitada en el Google Cloud proyecto.

• Debes tener el rol básico de gestión de identidades y accesos roles/owner (Propietario) en elGoogle Cloud proyecto o un rol que te conceda estos permisos:

  • resourcemanager.projects.get
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.setIamPolicy

  Para obtener estos permisos y seguir el principio de mínimos accesos, pide a tu administrador que te asigne el rol roles/resourcemanager.projectIamAdmin (administrador de gestión de identidades y accesos del proyecto).

Hacer que las credenciales de gestión de identidades y accesos estén disponibles en el host del cliente

La forma de poner las credenciales de gestión de identidades y accesos a disposición del host del cliente depende del tipo de principal de gestión de identidades y accesos que utilices para autorizar las conexiones:

• Cuenta de servicio gestionada por el usuario

  Para proporcionar credenciales de IAM a una cuenta de servicio gestionada por el usuario, crea una clave de cuenta de servicio en formato JSON y descárgala en tu host cliente. Cuando inicies el cliente Auth Proxy, especifica la ubicación del archivo de claves con la marca --credentials-file.

• Tu cuenta de usuario

  Para proporcionar credenciales de IAM a tu cuenta de usuario, instala la CLI de Google Cloud en tu host cliente y, a continuación, ejecuta el comando gcloud init para inicializarla con tu cuenta de usuario. Cuando inicias el cliente Auth Proxy, descubre y usa automáticamente las credenciales de tu cuenta de usuario si no proporcionas credenciales de cuenta de servicio gestionadas por el usuario.

• Cuenta de servicio predeterminada de Compute Engine

  Si usas una instancia de Compute Engine como host de cliente, las credenciales de la cuenta de servicio predeterminada de Compute Engine ya estarán en el host. Cuando inicias el cliente Auth Proxy, este descubre y usa automáticamente estas credenciales si no hay disponibles credenciales de cuenta de servicio gestionada por el usuario ni de cuenta de usuario.

Recopilar URIs de conexión de las instancias de AlloyDB

Cuando inicias el cliente de proxy de autenticación, identificas la instancia o las instancias de AlloyDB a las que quieres conectarte mediante este formato de URI de conexión:

projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

Para ver una lista de todos los URIs de conexión de tus instancias, usa el comando de la CLI de gcloud alloydb instances list.

Obtenga el URI de conexión de la instancia de cada instancia a la que quiera conectarse.

Iniciar el cliente de proxy de autenticación

Cuando inicias el cliente Auth Proxy, le proporcionas información sobre las instancias de AlloyDB a las que debe conectarse y, si es necesario, información de las credenciales que debe usar al autorizar estas conexiones.

Cuando empieza, el cliente de Auth Proxy hace lo siguiente:

• Autoriza las conexiones a instancias de AlloyDB mediante las credenciales y los permisos de gestión de identidades y accesos de la cuenta principal de gestión de identidades y accesos que hayas configurado. Busca las credenciales siguiendo una secuencia específica de pasos.
• Autoriza automáticamente las conexiones IP públicas a la red de origen si la instancia tiene habilitada la IP pública.
• Configura una conexión privada TLS 1.3 con el servidor proxy de autenticación de cada instancia.
• Empieza a escuchar las solicitudes de conexión de clientes locales.

De forma predeterminada, el cliente de Auth Proxy escucha las conexiones TCP en la dirección IP 127.0.0.1, empezando por el puerto 5432 y aumentando en uno el número de puerto por cada instancia de AlloyDB posterior a la primera. Puedes especificar otra dirección de escucha y otros puertos al iniciar el cliente Auth Proxy.

./alloydb-auth-proxy INSTANCE_URI... \
    [ --credentials-file PATH_TO_KEY_FILE \ ]
    [ --token OAUTH_ACCESS_TOKEN \ ]
    [ --port INITIAL_PORT_NUMBER \ ]
    [ --address LOCAL_LISTENER_ADDRESS \ ]
    [ --auto-iam-authn \ ]
    [ --psc \ ]
    [ --public-ip \ ]
    [ --disable-built-in-telemetry ]

docker run \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  INSTANCE_URI

docker run \
  --volume PATH_TO_KEY_FILE:/key.json \
  --publish 127.0.0.1:PORT:PORT \
  gcr.io/alloydb-connectors/alloydb-auth-proxy:latest \
  --address 0.0.0.0 \
  --port PORT \
  --credentials-file=/key.json \
  INSTANCE_URI

Ejemplos de startups

En los siguientes ejemplos se muestran varias formas de iniciar el cliente Auth Proxy. Usan estos URIs de conexión de instancias de ejemplo:

projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary

projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool

Inicio básico

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary"

En este ejemplo, el cliente proxy de autenticación autoriza la conexión siguiendo su secuencia de pasos de autorización normal y, a continuación, empieza a escuchar las conexiones locales a la instancia myprimary en 127.0.0.1:5432.

Inicio con una cuenta de servicio gestionada por el usuario

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \\
  --credentials-file "myappaccount/key.json"

En este ejemplo, el cliente de Auth Proxy autoriza la conexión mediante la clave JSON de la cuenta de servicio gestionada por el usuario almacenada en myappaccount/key.json y, a continuación, empieza a escuchar las conexiones locales a la instancia myprimary en 127.0.0.1:5432.

Startup connecting to multiple instances

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool"

En este ejemplo, el cliente de proxy de autenticación autoriza la conexión siguiendo su secuencia de pasos de autorización normal y, a continuación, empieza a escuchar las conexiones locales a la instancia myprimary en 127.0.0.1:5432 y a la instancia myreadpool en 127.0.0.1:5433.

Iniciar la escucha en puertos personalizados

Usar puertos personalizados para el cliente del proxy de autenticación puede ser útil cuando necesites reservar el puerto 5432 para otras conexiones de PostgreSQL.

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary?port=5000" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool?port=5001"

En este ejemplo, el cliente de proxy de autenticación autoriza la conexión siguiendo su secuencia de pasos de autorización normal y, a continuación, empieza a escuchar las conexiones locales a la instancia myprimary en 127.0.0.1:5000 y a la instancia myreadpool en 127.0.0.1:5001.

Como estos puertos personalizados son secuenciales, se puede conseguir el mismo efecto con este comando de inicio:

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myreadpool" \
  --port 5000

Iniciar la escucha en una dirección IP personalizada

./alloydb-auth-proxy \
  "projects/myproject/locations/us-central1/clusters/mycluster/instances/myprimary" \
  --address "0.0.0.0"

En este ejemplo, el cliente proxy de autenticación autoriza la conexión siguiendo su secuencia de pasos de autorización normal y, a continuación, empieza a escuchar las conexiones locales a la instancia myprimary en 0.0.0.0:5432.

Conectar una aplicación a una base de datos mediante el proxy de autenticación de AlloyDB

En los siguientes ejemplos se muestra cómo puedes conectar una aplicación a una base de datos mediante el proxy de autenticación de AlloyDB.

El ejemplo de psql muestra cómo conectar una herramienta de línea de comandos.

Conectarse a una instancia de AlloyDB mediante el proxy de autenticación de AlloyDB es, en varios lenguajes de programación, idéntico a conectarse a una instancia de Cloud SQL para PostgreSQL mediante el proxy de autenticación de Cloud SQL, por lo que los ejemplos de lenguaje que se muestran aquí son los mismos que los de Cloud SQL para PostgreSQL.

Estos ejemplos se basan en un inicio predeterminado del cliente proxy de autenticación para que escuche las conexiones TCP locales en 127.0.0.1:5432.

psql -h 127.0.0.1 -p 5432 -U DB_USER

import os

import sqlalchemy


# connect_tcp_socket initializes a TCP connection pool
# for an AlloyDB instance.
def connect_tcp_socket() -> sqlalchemy.engine.base.Engine:
    # 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.
    INSTANCE_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>@<INSTANCE_HOST>:<db_port>/<db_name>
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,
            password=db_pass,
            host=INSTANCE_HOST,
            port=db_port,
            database=db_name,
        ),
        # ...
    )
    return pool

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

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

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

// createTcpPool initializes a TCP connection pool for an AlloyDB cluster.
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);
};

package alloydb

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

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

// connectTCPSocket initializes a TCP connection pool for an AlloyDB cluster.
func connectTCPSocket() (*sql.DB, error) {
	mustGetenv := func(k string) string {
		v := os.Getenv(k)
		if v == "" {
			log.Fatalf("Warning: %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' or IP Address of Cluster
		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: %v", err)
	}

	// ...

	return dbPool, nil
}

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

development:
  adapter: postgresql
  # Configure additional properties here.
  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("DB_HOST") { "127.0.0.1" }%> # '172.17.0.1' if deployed to GAE Flex
  port: <%= ENV.fetch("DB_PORT")  { 5432 }%>

// $username = 'your_db_user';
// $password = 'yoursupersecretpassword';
// $dbName = 'your_db_name';
// $dbHost = "127.0.0.1";

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

// Connect to the database
$conn = new PDO($dsn, $username, $password, $connConfig);