Autorización con el proxy de Cloud SQL

En esta página, se explica cómo autorizar una conexión de proxy de Cloud SQL. Para obtener información sobre cómo conectarte a instancias de Cloud SQL mediante el proxy, consulta Descripción general de la conexión. Si deseas información detallada sobre cómo funciona el proxy y sugerencias para trabajar con él, consulta Información sobre el proxy de Cloud SQL.

El proxy de Cloud SQL controla la autenticación con Cloud SQL, lo que proporciona acceso seguro a las instancias de Cloud SQL sin la necesidad de administrar direcciones IP permitidas ni configurar conexiones SSL.

Antes de comenzar

Instala el proxy de Cloud SQL

El proxy de Cloud SQL se distribuye como una descarga gratuita, con ejecutables precompilados disponibles para plataformas Linux, macOS y Windows de 32 y 64 bits.

Linux de 64 bits

  1. Descarga el proxy con el siguiente comando:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. Haz que el proxy sea ejecutable con el siguiente comando:
    chmod +x cloud_sql_proxy
    

Linux de 32 bits

  1. Descarga el proxy con el siguiente comando:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. Haz que el proxy sea ejecutable con el siguiente comando:
    chmod +x cloud_sql_proxy
    

macOS de 64 bits

  1. Descarga el proxy con el siguiente comando:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. Haz que el proxy sea ejecutable con el siguiente comando:
    chmod +x cloud_sql_proxy
    

macOS de 32 bits

  1. Descarga el proxy con el siguiente comando:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. Haz que el proxy sea ejecutable con el siguiente comando:
    chmod +x cloud_sql_proxy
    

Windows de 64 bits

Para descargar el proxy, haz clic con el botón derecho en https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe y selecciona Guardar vínculo como. Cambia el nombre del archivo por cloud_sql_proxy.exe.

Windows de 32 bits

Para descargar el proxy, haz clic derecho en https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe y selecciona Guardar vínculo como. Cambia el nombre del archivo por cloud_sql_proxy.exe.
Si no se incluye aquí tu sistema operativo, también puedes compilar el proxy desde la fuente.

Habilita la API y configura permisos

El proxy de Cloud SQL usa los permisos de IAM de un usuario o cuenta de servicio para autenticar tu conexión a una instancia de Cloud SQL.

  1. Habilita la API Cloud SQL Admin.

    Habilita la API

  2. Agrega una o más de las funciones de IAM necesarias a tu cuenta de usuario o servicio:

    • Cloud SQL Client (recomendado)
    • Cloud SQL Editor
    • Cloud SQL Admin

    O bien, puedes asignar los siguientes permisos de IAM de forma manual:

    • cloudsql.instances.connect
    • cloudsql.instances.get

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

Para obtener más información sobre las funciones que admite Cloud SQL, consulta la sección Control de acceso a proyectos para Cloud SQL.

Usa credenciales del proxy de Cloud SQL

Antes de iniciar el proxy de Cloud SQL, debes proporcionar credenciales de cuenta de usuario o de servicio que el proxy pueda usar para autenticar una conexión. Existen varias opciones para especificar las credenciales que se usarán, y el proxy verifica cada opción en el siguiente orden:

Todas estas opciones usan un INSTANCE_CONNECTION_NAME como la string de conexión para identificar una instancia de Cloud SQL. La string de conexión está en formato PROJECT_ID:REGION:INSTANCE_ID. Puedes encontrar la string de la conexión de la instancia en la página de descripción general de la instancia.

Algunas de estas opciones usan un archivo de credenciales JSON que incluye la clave privada RSA de la cuenta. Si quieres obtener instrucciones para crear un archivo de credenciales JSON en una cuenta de servicio, consulta la sección sobre cómo crear una cuenta de servicio. Si necesitas crear un nuevo archivo de credenciales, ve a la página Cuentas de servicio de tu proyecto en Cloud Console. Luego, haz clic en Acciones de la cuenta de servicio y selecciona Crear una clave a fin de descargar un archivo de credenciales JSON para la cuenta de servicio.

Archivo de credenciales en la línea de comandos

Para usar esta opción, invoca el comando cloud_sql_proxy con la marca -credential_file configurada en la ruta de acceso y el nombre de archivo de un archivo de credenciales JSON. La ruta de acceso puede ser absoluta o relativa al directorio de trabajo actual. Por ejemplo:

./cloud_sql_proxy -credential_file=PATH_TO_KEY_FILE -instances=INSTANCE_CONNECTION_NAME

Token de acceso en la línea de comandos

Por lo general, estos tokens se usan para autorizar el acceso en nombre de una cuenta de usuario. Para obtener más información sobre cómo crear tokens de acceso de OAuth 2.0 y usarlos, consulta la sección sobre cómo autorizar solicitudes.

Si quieres usar esta opción, invoca el comentario cloud_sql_proxy con la marca -token configurada en un token de acceso de OAuth 2.0. Por ejemplo:

./cloud_sql_proxy -token=ACCESS_TOKEN -instances=INSTANCE_CONNECTION_NAME

Archivo de credenciales de una variable de entorno

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

Credenciales de usuario del SDK de Cloud

Si ya instalaste la herramienta de línea de comandos de gcloud y te autenticaste con tu cuenta personal, el proxy de Cloud SQL puede usar las mismas credenciales de la cuenta. Este método es útil, en particular, para poner en ejecución un entorno de desarrollo. En el caso de un entorno de producción, usa uno de los otros métodos de autenticación.

Para autenticar el SDK de Cloud, usa el comando gcloud auth login, selecciona tu cuenta y accede. Puedes usar el comando gcloud auth list para verificar qué cuenta está autenticada actualmente en el SDK de Cloud.

Si no se seleccionó ninguna cuenta para gcloud auth login, el proxy verifica una cuenta seleccionada para gcloud application-default login.

Cuenta de servicio predeterminada del entorno

Si el proxy no puede encontrar credenciales en ninguno de los lugares mencionados anteriormente, sigue la lógica que se documenta en la sección sobre cómo configurar la autenticación para aplicaciones de producción de servidor a servidor. Algunos entornos (como Compute Engine, App Engine y otros) proporcionan una cuenta de servicio predeterminada que tu aplicación puede usar para la autenticación de forma predeterminada. Si usas una cuenta de servicio predeterminada, esta debe tener los permisos que se detallan en la sección sobre cómo habilitar la API y configurar permisos.

Para obtener más información sobre el enfoque de autenticación de Google Cloud, consulta la sección Descripción general de la autenticación.

Ejecuta el proxy de Cloud SQL

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

A continuación, se proporcionan algunos ejemplos de uso de la línea de comandos del proxy de Cloud SQL.

Configura el TCP

Si quieres conectarte a una instancia de Cloud SQL con TCP, usa el argumento de línea de comandos -instances para especificar una lista separada por comas de strings de conexión, seguidas de un número de puerto TCP, como se muestra en este ejemplo:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER

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

Como alternativa, puedes especificar una dirección diferente para la conexión local. Por ejemplo, aquí se muestra cómo hacer que el proxy escuche la conexión local en 0.0.0.0:1234:

  ./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:1234

Para conectarte a varias instancias, puedes usar el proxy de Cloud SQL si especificas una lista separada por comas de nombres de conexión de instancia en el argumento -instances. Cada instancia debe tener su propio número de puerto, como se muestra en este ejemplo:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME_1=tcp:5432,INSTANCE_CONNECTION_NAME_2=tcp:5433

Configura un socket Unix

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

Para crear y usar un socket Unix, el directorio de destino debe existir, y el proxy y la aplicación deben tener acceso de lectura y escritura. Usa estos comandos para crear un directorio nuevo y configurar los permisos necesarios:

sudo mkdir ~/cloudsql
sudo chmod a+rw /cloudsql

Hay dos opciones para especificar el directorio del socket cuando se inicia el proxy. Una opción es usar el argumento de línea de comandos de -dir, como se muestra aquí:

./cloud_sql_proxy -dir=PATH_TO_TARGET_FOLDER -instances=INSTANCE_CONNECTION_NAME

Como alternativa, puedes agregar el directorio del socket al argumento de la string de conexión:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=unix:/PATH_TO_TARGET_FOLDER

Elige una IP pública o privada

Las instancias de Cloud SQL usan conectividad de IP pública de forma predeterminada, pero también puedes configurar una instancia para admitir conectividad de IP privada. La IP privada usa direcciones IP internas alojadas en una red de VPC, a las que solo se puede acceder desde otros recursos dentro de la misma red de VPC. Los beneficios de usar IP privadas incluyen mayor seguridad, ya que el tráfico de IP nunca se expone a Internet, y un mayor rendimiento, porque en algunos casos la IP privada ofrece una latencia menor que la IP pública.

Si deseas configurar tu instancia de Cloud SQL para que use una IP privada, consulta Configura IP privadas.

La marca de línea de comandos -ip_address_types del proxy especifica el orden preferido de IP que se usa cuando te conectas a una instancia de Cloud SQL. La configuración predeterminada es -ip_address_types=PUBLIC,PRIVATE, lo que significa que el proxy intenta conectarse primero con la IP pública si la instancia la tiene habilitada y, luego, intenta hacerlo con una IP privada si está habilitada. Para especificar que el proxy solo intenta conectarse con una IP privada, usa la marca -ip_address_types=PRIVATE, como se muestra en este ejemplo:

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:5432 -ip_address_types=PRIVATE

Otros argumentos de la línea de comandos

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

./cloud_sql_proxy -help

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

Información adicional

Ejecuta el proxy en un proceso separado

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

Linux

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

./cloud_sql_proxy -instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE &

Windows

En Windows PowerShell, usa el comando Start-Process para iniciar el proxy en un proceso separado:

Start-Process -filepath "cloud_sql_proxy.exe"
  -ArgumentList "-instances=INSTANCE_CONNECTION_NAME=tcp:PORT_NUMBER
  -credential_file=PATH_TO_KEY_FILE"

Ejecuta el proxy de Cloud SQL en un contenedor de Docker

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

docker pull gcr.io/cloudsql-docker/gce-proxy:1.16

Puedes iniciar el proxy con sockets TCP o Unix, con los comandos que se muestran a continuación.

Sockets TCP

docker run -d \
  -v PATH_TO_KEY_FILE:/config \
  -p 127.0.0.1:5432:5432 \
  gcr.io/cloudsql-docker/gce-proxy:1.16 /cloud_sql_proxy \
  -instances=INSTANCE_CONNECTION_NAME=tcp:0.0.0.0:5432 \
  -credential_file=/config

Sockets Unix

docker run -d \
  -v /PATH_TO_HOST_TARGET:/PATH_TO_GUEST_TARGET \
  -v PATH_TO_KEY_FILE:/config \
  gcr.io/cloudsql-docker/gce-proxy:1.16 /cloud_sql_proxy -dir=/cloudsql \
  -instances=INSTANCE_CONNECTION_NAME
  -credential_file=/config/PATH_TO_KEY_FILE

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

-v /mnt/stateful_partition/cloudsql:/cloudsql

Si usas las credenciales que proporciona tu instancia de Compute Engine, no incluyas el parámetro credential_file ni la línea -v PATH_TO_KEY_FILE:/config</span>.

Ejecuta el proxy de Cloud SQL como servicio

Ejecutar el proxy como un servicio en segundo plano puede ser conveniente para desarrollar y realizar pruebas de forma local. Cuando necesites acceder a tu instancia de Cloud SQL, puedes iniciar el servicio en segundo plano y detenerlo cuando termines.

Windows

En este momento, el proxy de Cloud SQL no cuenta con compatibilidad integrada para ejecutarse como un servicio de Windows, pero puedes usar administradores de servicios de terceros a fin de hacerlo. Por ejemplo, puedes usar NSSM para configurar el proxy como un servicio de Windows, así como para supervisarlo y reiniciarlo automáticamente si deja de responder. Consulta la documentación de NSSM para obtener más información.

Próximos pasos