Conéctate con el proxy de autenticación de AlloyDB

Para establecer conexiones autorizadas y encriptadas a instancias de AlloyDB para PostgreSQL, puedes usar el proxy de autenticación de AlloyDB. Para obtener más información, consulta Acerca del proxy de autenticación de AlloyDB.

Para usar el proxy de autenticación de AlloyDB, debes realizar varios pasos de configuración únicos, luego, iniciar el cliente del proxy de autenticación y usarlo para conectarte a una base de datos.

Antes de comenzar

El host del cliente debe cumplir con los siguientes requisitos:

• El cliente debe tener una ruta de red a la instancia de AlloyDB según tu método de conexión:

  • Acceso privado a servicios (predeterminado): El cliente debe tener visibilidad de red para la red de nube privada virtual (VPC) en la que residen las instancias. Los hosts de cliente (como las instancias de Compute Engine) en esta red de VPC tienen esta visibilidad de red de forma inherente. Los hosts de cliente en redes externas (redes locales o redes de VPC diferentes) tienen esta visibilidad si la red de VPC de la instancia de AlloyDB está conectada a la red externa con un túnel de Cloud VPN o un adjunto de VLAN para Interconexión dedicada o Interconexión de socio.
  • Private Service Connect: La red de VPC del cliente debe tener un extremo de Private Service Connect y un registro DNS privado coincidente, y debes iniciar el cliente del proxy de autenticación con la marca --psc.
  • IP pública: La instancia debe tener habilitada la IP pública y debes iniciar el cliente del proxy de autenticación con la marca --public-ip. Cuando te conectas con el proxy de autenticación, no necesitas agregar la dirección IP del host del cliente a las redes externas autorizadas.

• Si el host cliente tiene una política de firewall saliente, debe permitir las conexiones salientes al puerto 5433 en las direcciones IP de tus instancias de AlloyDB y permitir las conexiones salientes al puerto 443 (el puerto HTTPS estándar) a todas las direcciones IP.

• Si usas una instancia de Compute Engine como host del cliente, debe tener el permiso de acceso https://www.googleapis.com/auth/cloud-platform para que pueda usar la API de AlloyDB. Si es necesario, cambia su permiso de acceso para incluir este permiso.

Descarga el cliente del proxy de autenticación

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

Si deseas conectarte a tu clúster con el acceso privado a servicios, puedes descargar el cliente del proxy de autenticación en una instancia de máquina virtual (VM) de Compute Engine que se ejecute en la red de VPC que tiene acceso privado a servicios a tu clúster.

Si quieres 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 uses. Por ejemplo, puedes instalar el cliente del proxy de autenticación en una máquina con macOS o Windows que sea local para tu aplicación y, luego, usar un servidor SOCKS que se ejecute en tu red de VPC de AlloyDB como un intermediario de conexión. Para obtener más información, consulta Conéctate a un clúster desde fuera de su VPC.

Nota: Asegúrate de usar la versión más reciente del cliente del proxy de autenticación. Google lanza versiones nuevas del cliente del proxy de autenticación todos los meses. Puedes consultar la versión actual en la página de versiones de GitHub del cliente del proxy de autenticación.

Linux

64 bits (AMD)

1. Descarga el cliente del proxy de autenticación:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

2. Haz que el cliente del proxy de autenticación sea ejecutable:

   chmod +x alloydb-auth-proxy

3. Agrega el cliente del proxy de autenticación a tu PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Para conservar estos cambios en todas las sesiones, agrega export PATH="$HOME/.local/bin:$PATH" a tu archivo ~/.bashrc o ~/.zshrc.

32 bits (AMD)

1. Descarga el cliente del proxy de autenticación:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.386 -O alloydb-auth-proxy

2. Haz que el cliente del proxy de autenticación sea ejecutable:

   chmod +x alloydb-auth-proxy

3. Agrega el cliente del proxy de autenticación a tu PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Para conservar estos cambios en todas las sesiones, agrega export PATH="$HOME/.local/bin:$PATH" a tu archivo ~/.bashrc o ~/.zshrc.

64 bits (ARM)

1. Descarga el cliente del proxy de autenticación:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.arm64 -O alloydb-auth-proxy

2. Haz que el cliente del proxy de autenticación sea ejecutable:

   chmod +x alloydb-auth-proxy

3. Agrega el cliente del proxy de autenticación a tu PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Para conservar estos cambios en todas las sesiones, agrega export PATH="$HOME/.local/bin:$PATH" a tu archivo ~/.bashrc o ~/.zshrc.

32 bits (ARM)

1. Descarga el cliente del proxy de autenticación:

   wget https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.linux.arm -O alloydb-auth-proxy

2. Haz que el cliente del proxy de autenticación sea ejecutable:

   chmod +x alloydb-auth-proxy

3. Agrega el cliente del proxy de autenticación a tu PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Para conservar estos cambios en todas las sesiones, agrega export PATH="$HOME/.local/bin:$PATH" a tu archivo ~/.bashrc o ~/.zshrc.

macOS

ARM64

1. Descarga el cliente del proxy de autenticación:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.darwin.arm64

2. Haz que el cliente del proxy de autenticación sea ejecutable:

   chmod +x alloydb-auth-proxy

3. Agrega el cliente del proxy de autenticación a tu PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Para conservar estos cambios en todas las sesiones, agrega export PATH="$HOME/.local/bin:$PATH" a tu archivo ~/.bashrc o ~/.zshrc.

AMD64

1. Descarga el cliente del proxy de autenticación:

   curl -o alloydb-auth-proxy https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy.darwin.amd64

2. Haz que el cliente del proxy de autenticación sea ejecutable:

   chmod +x alloydb-auth-proxy

3. Agrega el cliente del proxy de autenticación a tu PATH:

   mkdir -p ~/.local/bin
   mv alloydb-auth-proxy ~/.local/bin/
   export PATH="$HOME/.local/bin:$PATH"

   Para conservar estos cambios en todas las sesiones, agrega export PATH="$HOME/.local/bin:$PATH" a tu archivo ~/.bashrc o ~/.zshrc.

Windows

64 bits

1. Haz clic con el botón derecho en https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy-x64.exe y selecciona Guardar vínculo como para descargar el cliente del proxy de autenticación. Cambia el nombre del archivo por alloydb-auth-proxy.exe.

2. Agrega el cliente del proxy de autenticación a tu PATH:

   New-Item -ItemType Directory -Force -Path "$HOME\bin"
   Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
   $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
   [Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")
   

32 bits

1. Haz clic con el botón derecho en https://storage.googleapis.com/alloydb-auth-proxy/v1.17.2/alloydb-auth-proxy-x86.exe y selecciona Guardar vínculo como para descargar el cliente del proxy de autenticación. Cambia el nombre del archivo por alloydb-auth-proxy.exe.

2. Agrega el cliente del proxy de autenticación a tu PATH:

   New-Item -ItemType Directory -Force -Path "$HOME\bin"
   Move-Item -Path .\alloydb-auth-proxy.exe -Destination "$HOME\bin"
   $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
   [Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")
   

Imagen de Docker

Para mayor comodidad, varias imágenes de contenedor que contienen el cliente del proxy de autenticación están disponibles en Artifact Registry.

Puedes extraer la última imagen a tu máquina local usando Docker mediante el siguiente comando:

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

Otro SO

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

Elige la principal de Identity and Access Management (IAM) y prepárala para la autorización

El proxy de autenticación de AlloyDB admite el uso de estos tipos de principales de IAM para autorizar las conexiones entre tu cliente y una instancia de AlloyDB:

• Una cuenta de servicio conectada. Si tu host de cliente se ejecuta en Google Cloud, por ejemplo, en una instancia de Compute Engine, puedes autorizar las conexiones con la cuenta de servicio conectada a ese recurso.

  Te recomendamos que uses una cuenta de servicio para la autorización en entornos de producción. Una cuenta de servicio conectada es la opción más segura, ya que no requiere una clave descargada.

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

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

• Una cuenta de servicio administrada por el usuario. Puedes crear una cuenta de servicio de IAM para tu aplicación y, luego, autorizar las conexiones con la cuenta de servicio.

  Usa una cuenta de servicio administrada por el usuario cuando el host del cliente se ejecute fuera de Google Cloud y no pueda usar una cuenta de servicio adjunta.

Después de elegir qué principal de IAM usar, verifica que tenga los permisos de IAM necesarios y que sus credenciales estén disponibles en tu host de cliente.

Permisos de IAM obligatorios

La principal de IAM que usas para autorizar conexiones debe tener los permisos que proporcionan los roles predefinidos roles/alloydb.client (Cliente de AlloyDB) y roles/serviceusage.serviceUsageConsumer (Consumidor de Service Usage).

Nota: El rol roles/alloydb.admin (administrador de AlloyDB) también proporciona los permisos necesarios.

Para asignar el rol de cliente de AlloyDB a un principal de IAM, haz lo siguiente:

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

• Debes tener el rol básico de IAM roles/owner (Propietario) en el proyecto deGoogle Cloud o un rol que otorgue estos permisos:

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

  Para obtener estos permisos mientras sigues el principio de privilegio mínimo, pídele a tu administrador que te otorgue el rol de roles/resourcemanager.projectIamAdmin (Administrador de IAM del proyecto).

Haz que las credenciales de IAM estén disponibles en el host del cliente

El cliente del proxy de autenticación usa las credenciales predeterminadas de la aplicación (ADC) para ubicar las credenciales de IAM en el host del cliente. En la mayoría de los entornos, estas credenciales ya están presentes, por lo que no necesitas configurar nada. El cliente del proxy de autenticación busca las siguientes fuentes de credenciales, en orden:

• Tu cuenta de usuario. Cuando desarrolles de forma local, autentícate con tu propia cuenta de usuario ejecutando el siguiente comando de gcloud CLI:

  gcloud auth application-default login
  

  El cliente del proxy de autenticación detecta y usa estas credenciales. No es necesario que descargues una clave de cuenta de servicio.

• Una cuenta de servicio conectada. Cuando el host de tu cliente se ejecuta en Google Cloud, por ejemplo, en una instancia de Compute Engine, el servidor de metadatos del entorno proporciona credenciales de la cuenta de servicio adjunta. El cliente del proxy de autenticación descubre y usa estas credenciales sin configuración adicional.

Otras fuentes de credenciales

Usa los siguientes métodos solo cuando las credenciales predeterminadas de la aplicación no estén disponibles, por ejemplo, cuando ejecutes el cliente del proxy de autenticación fuera de Google Cloudo cuando necesites anular las credenciales en el entorno.

• Una clave de cuenta de servicio. Usa una clave de cuenta de servicio cuando el host del cliente se ejecute fuera de Google Cloud, por ejemplo, en un centro de datos local o en otro proveedor de servicios en la nube, y no puedas usar la federación de identidades para cargas de trabajo.

  Crea una clave de cuenta de servicio en formato JSON y descárgala en tu host de cliente. Luego, configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta del archivo de claves:

  export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
  

  De manera opcional, puedes especificar la ruta con la marca --credentials-file cuando inicias el cliente del proxy de autenticación:

  alloydb-auth-proxy --credentials-file /path/to/service-account-key.json INSTANCE_URI
  

  Precaución: Las claves de las cuentas de servicio son un riesgo de seguridad si no se administran de forma adecuada. Antes de crear una clave, considera una alternativa más segura.

• Un token de acceso de OAuth 2.0. Usa un token de acceso cuando otro sistema ya emita tokens de corta duración para ti, por ejemplo, una canalización de integración continua que obtenga un token antes de iniciar el cliente del proxy de autenticación.

  Si ya tienes un token de acceso de OAuth 2.0 válido, pásalo directamente cuando inicies el cliente del proxy de autenticación:

  alloydb-auth-proxy --token "ACCESS_TOKEN" INSTANCE_URI
  

• Credenciales de gcloud CLI Usa la marca --gcloud-auth solo cuando debas volver a usar una sesión de gcloud auth login existente y no puedas ejecutar gcloud auth application-default login.

  La marca --gcloud-auth hace que el cliente del proxy de autenticación use la cuenta con la que te autenticaste con gcloud auth login en lugar de usar las credenciales predeterminadas de la aplicación. No recomendamos esta marca. En su lugar, ejecuta gcloud auth application-default login.

Recopila los URI de conexión para las instancias de AlloyDB

Cuando inicias el cliente del proxy de autenticación, identificas la instancia o las instancias de AlloyDB a las que deseas conectarte con 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 URI de conexión de tus instancias, usa el comando alloydb instances list de gcloud CLI:

gcloud alloydb instances list \
    --region=REGION_ID \
    --cluster=CLUSTER_ID \
    --project=PROJECT_ID

Reemplaza lo siguiente:

• REGION_ID: la región en la que se ubican las instancias
• CLUSTER_ID: Es el ID del clúster en el que se colocan las instancias.
• PROJECT_ID: Es el ID del proyecto en el que se coloca el clúster.

Recopila el URI de conexión de instancia para cada instancia a la que quieras conectarte.

Inicia el cliente del proxy de autenticación

Cuando inicias el cliente del proxy de autenticación, le proporcionas información sobre las instancias de AlloyDB a las que se conectará y, si es necesario, información de credenciales para usar cuando autorices estas conexiones.

Cuando se inicia, el cliente del proxy de autenticación hace lo siguiente:

• Autoriza las conexiones a las instancias de AlloyDB con las credenciales y los permisos de IAM de la principal de IAM que configuraste. Busca credenciales siguiendo una secuencia específica de pasos.
• Autoriza las conexiones IP públicas a la red de origen de forma automática si la instancia tiene habilitada la IP pública.
• Configura una conexión privada de mTLS 1.3 al servidor del proxy de autenticación de cada instancia.
• Comienza a escuchar las solicitudes de conexión de clientes locales.

De forma predeterminada, el cliente del proxy de autenticación escucha las conexiones TCP en la dirección IP 127.0.0.1, a partir del puerto 5432 y aumenta en un número de puerto para cada instancia de AlloyDB más allá de la primera. Puedes especificar una dirección de objeto de escucha y puertos diferentes cuando inicies el cliente del proxy de autenticación.

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

Nota: Google recomienda que ejecutes el cliente del proxy de autenticación como un servicio persistente en entornos de producción.

Línea de comandos

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 ]

Reemplaza lo siguiente:

• INSTANCE_URI: Es el URI de conexión de la instancia de AlloyDB a la que se conectará, especificado con este formato:

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

  Puedes anular el puerto de escucha local predeterminado que usará el cliente del proxy de autenticación para la instancia agregando el parámetro de consulta port al URI:

  "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

• Opcional: PATH_TO_KEY_FILE: Es la ruta de acceso al archivo de claves JSON de la cuenta de servicio administrada por el usuario que se usará para la autorización de la conexión.

• Opcional: OAUTH_ACCESS_TOKEN: Es un valor de token de OAuth2 que se usará para la autorización de la conexión.

• Opcional: INITIAL_PORT_NUMBER: Es el número de puerto inicial que se usará en lugar del puerto predeterminado 5432 cuando se escuchen las conexiones TCP locales.

• Opcional: LOCAL_LISTENER_ADDRESS: Es la dirección del objeto de escucha que se usará en lugar de la predeterminada 127.0.0.1 cuando se escuchen las conexiones TCP locales.

La marca opcional --auto-iam-authn te permite autenticarte de forma automática en la instancia. Esto solo funciona para el usuario de la base de datos asociado con la cuenta de IAM que ejecuta el cliente del proxy de autenticación. Para obtener más información, consulta Autentica automáticamente con el proxy de autenticación.

La marca opcional --psc permite que el proxy de autenticación se conecte a una instancia con Private Service Connect habilitado. Para obtener más información sobre cómo configurar el DNS con Private Service Connect, consulta Configura una zona administrada de DNS y un registro DNS.

La marca opcional --public-ip permite que el proxy de autenticación se conecte a una instancia con la IP pública habilitada usando la dirección IP pública de la instancia. Para obtener más información sobre la IP pública, consulta Conéctate con una IP pública.

La marca opcional --disable-built-in-telemetry inhabilita el generador de informes de métricas interno que usa el proxy de autenticación para informar sobre el estado de la conexión y de la red. De forma predeterminada, el proxy de autenticación informa sobre sus operaciones internas al prefijo de métrica del sistema alloydb.googleapis.com. Estas métricas ayudan a AlloyDB a mejorar el rendimiento y a identificar problemas de conectividad del cliente. Esta opción es útil para las aplicaciones que operan en entornos en los que se restringe la exportación de métricas salientes. Para inhabilitar esta telemetría, usa esta marca.

Contenedor de Docker

Inicia el cliente del proxy de autenticación con el comando docker run.

Si usas las credenciales que proporciona tu instancia de Compute Engine, puedes usar un comando similar al siguiente:

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

Reemplaza lo siguiente:

• PORT: Es el puerto que se usará para las conexiones locales al cliente del proxy de autenticación. El valor predeterminado es 5432.

• INSTANCE_URI: Es el URI de conexión de la instancia de AlloyDB a la que se conectará, especificado con el siguiente formato:

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

  Puedes anular el puerto de escucha local predeterminado que usa el cliente del proxy de autenticación para la instancia agregando el parámetro de consulta port al URI:

  "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?port=PORT"

Especifica siempre el prefijo 127.0.0.1 en la marca --publish para que el cliente del proxy de autenticación no se exponga fuera del host local.

El valor 0.0.0.0 en la marca --address es necesario para que se pueda acceder al objeto de escucha desde afuera del contenedor de Docker.

Para proporcionar las credenciales que almacenaste en un archivo JSON local, incluye las marcas --volume y --credentials-file cuando ejecutes el comando docker run:

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

Reemplaza PATH_TO_KEY_FILE por la ruta de acceso al archivo de claves JSON de la cuenta de servicio administrada por el usuario que se usará para la autorización de la conexión.

Ejemplos de startups

En los siguientes ejemplos, se muestran varias formas de iniciar el cliente del proxy de autenticación. Usan estos URI de conexión de instancia 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 del proxy de autenticación autoriza la conexión siguiendo su secuencia normal de pasos de autorización y, luego, comienza a escuchar las conexiones locales a la instancia myprimary en 127.0.0.1:5432.

Inicio con una cuenta de servicio administrada 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 del proxy de autenticación autoriza la conexión con la clave JSON de la cuenta de servicio administrada por el usuario almacenada en myappaccount/key.json y, luego, comienza a escuchar las conexiones locales a la instancia myprimary en 127.0.0.1:5432.

Startup que se conecta a varias instancias

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 del proxy de autenticación autoriza la conexión siguiendo su secuencia normal de pasos de autorización y, luego, comienza 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.

Escucha de inicio en puertos personalizados

Usar puertos personalizados para el cliente del proxy de autenticación puede ser útil cuando necesitas 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 del proxy de autenticación autoriza la conexión siguiendo su secuencia normal de pasos de autorización y, luego, comienza 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.

Debido a que estos puertos personalizados son secuenciales, se puede lograr 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

Inicio de 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 del proxy de autenticación autoriza la conexión siguiendo su secuencia normal de pasos de autorización y, luego, comienza a escuchar las conexiones locales a la instancia myprimary en 0.0.0.0:5432.

Conecta una aplicación a una base de datos con 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 con el proxy de autenticación de AlloyDB.

En el ejemplo de psql, se muestra cómo conectar una herramienta de línea de comandos.

La conexión a una instancia de AlloyDB con el proxy de autenticación es, en varios lenguajes de programación, idéntica a la conexión a una instancia de Cloud SQL para PostgreSQL con el proxy de autenticación de Cloud SQL, por lo que los ejemplos de lenguaje son los mismos que los de Cloud SQL para PostgreSQL.

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

Nota: Con un clúster nuevo, puedes conectarte como el usuario postgres con la contraseña que especificaste cuando creaste el clúster.

psql

psql -h 127.0.0.1 -p 5432 -U DB_USER

Reemplaza DB_USER por el usuario de la base de datos con el que deseas conectarte, por ejemplo, postgres.

Se te solicitará que ingreses la contraseña del usuario DB_USER.

Python

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

Java

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

Node.js

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

Go

Para ver este fragmento en el contexto de una aplicación web, consulta los ejemplos de Go en GitHub.

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
}

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.

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

PHP

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

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