Acerca del proxy de Cloud SQL

En esta página, se ofrece una introducción básica al proxy de Cloud SQL y se describen las opciones del proxy.

Qué proporciona el proxy

El proxy de Cloud SQL proporciona acceso seguro a tus instancias sin necesidad de tener redes autorizadas ni de configurar SSL.

Acceder a tu instancia de Cloud SQL con el proxy de Cloud SQL ofrece las siguientes ventajas:

  • Conexiones seguras: el proxy encripta automáticamente el tráfico hacia y desde la base de datos mediante el uso de TLS 1.2 con un algoritmo de cifrado AES de 128 bits. Se usan certificados SSL para verificar las identidades del cliente y del servidor.
  • Administración de conexión más sencilla: el proxy controla la autenticación con Cloud SQL, por lo que ya no es necesario proporcionar direcciones IP estáticas.

El proxy no proporciona una ruta de conectividad nueva, sino que se basa en la conectividad IP existente. Para conectarse a una instancia de Cloud SQL mediante una IP privada, el proxy debe estar en un recurso que tenga acceso a la misma red de VPC que la instancia.

Cómo funciona el proxy de Cloud SQL

El proxy de Cloud SQL funciona con un cliente local, llamado proxy, que se ejecuta en el entorno local. La aplicación se comunica con el proxy a través del protocolo de base de datos estándar que usa tu base de datos. El proxy usa un túnel seguro para comunicarse con el proceso complementario que se ejecuta en el servidor.

Si bien el proxy puede escuchar en cualquier puerto, solo crea conexiones salientes a tu instancia de Cloud SQL en el puerto 3307. Si tienes una política de firewall saliente, asegúrate de que permita conexiones al puerto 3307 en la IP de tu instancia de Cloud SQL.

En el siguiente diagrama se explica cómo se conecta el proxy con Cloud SQL:

Diagrama de la conexión del proxy desde el software del cliente a una instancia de SQL

Requisitos para usar el proxy de Cloud SQL

Para usar el proxy, debes cumplir con los siguientes requisitos:

  • La API de Administrador de Cloud SQL debe estar habilitada.
  • Debes proporcionar al proxy credenciales de autenticación de Google Cloud.
  • Debes proporcionar una cuenta de usuario y una contraseña válidas para la base de datos al proxy.
  • La instancia debe tener una dirección IPv4 pública o estar configurada para usar una IP privada.

    No es necesario que la dirección IP pública sea accesible para ninguna dirección externa (no es necesario agregarla como una dirección de red autorizada).

Instala el proxy de Cloud SQL

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.

Opciones de inicio del proxy

Cuando inicias el proxy, le brindas la siguiente información:

  • Con qué instancias de Cloud SQL establecer conexiones
  • Dónde escuchará los datos que vienen desde tu aplicación y que se enviarán a Cloud SQL.
  • Dónde encontrará las credenciales que usará para autenticar tu aplicación en Cloud SQL.
  • El tipo de dirección IP que usará, si fuera necesario.

Las opciones de inicio del proxy que proporciones determinan si el proxy escuchará en un puerto TCP o en un socket Unix. Si lo hace en un socket Unix, creará el socket en la ubicación que elegiste, que suele ser el directorio /cloudsql/. En TCP, el proxy escucha en localhost de forma predeterminada.

Inicia el ejecutable cloud_sql_proxy con el argumento --help para ver la lista completa de opciones de inicio.

Puedes instalar el proxy en cualquier parte de tu entorno local. La ubicación de los objetos binarios del proxy no afecta el lugar en el que se escuchan los datos desde tu aplicación.

Usa una cuenta de servicio para la autenticación

El proxy requiere autenticación. La ventaja de usar una cuenta de servicio en este caso es que puedes crear un archivo de credenciales específico para el proxy, que quedará vinculado a él de manera explícita y permanente mientras esté en ejecución. Por este motivo, el uso de una cuenta de servicio es el método recomendado para autenticar las instancias de producción que no se ejecutan en una instancia de Compute Engine.

Si necesitas invocar el proxy de Cloud SQL desde varias máquinas, puedes duplicar el archivo de credenciales en una imagen del sistema.

Para usar este método, debes crear y administrar el archivo de credenciales; Solo los usuarios que tengan el permiso resourcemanager.projects.setIamPolicy (como los propietarios de proyectos) pueden crear la cuenta de servicio. Si tu usuario de Google Cloud no tiene este permiso, debes hacer que otra persona cree la cuenta de servicio por ti o debes usar otro método para autenticar el proxy.

Para obtener ayuda con la creación de un archivo de credenciales, consulta la sección sobre cómo crear una cuenta de servicio y genera un archivo de claves.

Opciones para autenticar el proxy de Cloud SQL

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

  1. Credenciales provistas por la marca credential_file.

    Usa una cuenta de servicio para crear y descargar el archivo JSON asociado y establece la marca -credential_file en la ruta de acceso del archivo cuando inicias el proxy de Cloud SQL. La cuenta de servicio debe tener los permisos necesarios para la instancia de Cloud SQL.
  2. Credenciales provistas por un token de acceso.

    Crea un token de acceso y proporciónalo en la línea de comandos con la marca -token cuando inicies el proxy de Cloud SQL.
  3. Credenciales provistas por una variable de entorno.

    Puedes establecer la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta del archivo de claves json creado para una cuenta de servicio.
  4. Credenciales de un cliente del SDK de Cloud autenticado.

    Si ya instalaste el SDK de Cloud y lo usaste para autenticarte en Google Cloud, el proxy de Cloud SQL puede usar las mismas credenciales. 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, utiliza uno de los otros métodos de autenticación.
  5. Credenciales asociadas con la instancia de Compute Engine.

    Si te conectas a Cloud SQL desde una instancia de Compute Engine, el proxy puede usar la cuenta de servicio asociada con la instancia de Compute Engine. Si la cuenta de servicio tiene los permisos necesarios para la instancia de Cloud SQL, el proxy se autentica correctamente.

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

Permisos necesarios para las cuentas de servicio

Cuando usas una cuenta de servicio para proporcionar credenciales al proxy, debes crearla con los permisos necesarios. Si usas las funciones más detalladas de Identity Access and Management (IAM) para administrar tus permisos de Cloud SQL, debes otorgar a la cuenta de servicio una función que incluya el permiso cloudsql.instances.connect. A continuación, se enumeran las funciones predefinidas de Cloud SQL que incluyen este permiso:

  • Cliente de Cloud SQL
  • Editor de Cloud SQL
  • Administrador de Cloud SQL

Si usas las funciones de proyecto heredadas (Lector, Editor, Propietario), la cuenta de servicio debe tener, al menos, la función de Editor.

Opciones para especificar las instancias de Cloud SQL

Existen varias formas de indicarle al proxy a qué instancias deseas conectarte. Algunas son explícitas y otras, implícitas. En algunas configuraciones, no tienes que indicarle al proxy con anticipación las instancias a las que deseas que se conecte porque lo hace según las solicitudes de conexión.

Las opciones para especificación de instancias dependen de tu sistema operativo y de tu entorno:

Opción Beneficios Advertencias y requisitos Linux/macOS
(sockets Unix)
Java Windows Notas
Descubrimiento automático de instancias No es necesario especificar instancias; los sockets se crean para todas las instancias en el proyecto predeterminado. Aumenta el uso de la API del proxy. Se debe tener instalado y autenticado el SDK de Cloud con una configuración de proyecto predeterminada. Se debe reiniciar el proxy para agregar una instancia nueva. Compatible No No No se recomienda en instancias de producción.
Descubrimiento del proyecto No es necesario especificar instancias; los sockets se crean para todas las instancias en proyectos específicos. Aumenta el uso de la API del proxy. Se debe tener instalado y autenticado el SDK de Cloud. Se debe reiniciar el proxy para agregar una instancia nueva. Compatible No No Usa el parámetro -projects. No se recomienda en instancias de producción.
Instancias especificadas en la invocación del proxy Lista de instancias conocidas y estáticas. Se debe reiniciar el proxy para agregar una instancia nueva. Compatible Compatible con los sockets TCP. Compatible con los sockets TCP. Usa el parámetro -instances. Cuando haya varias instancias, usa una lista separada por comas, sin espacios. Más información
Instancias especificadas con metadatos de Compute Engine La lista de instancias se puede actualizar solo con cambiar el valor de los metadatos, sin reiniciar el proxy. Disponible solo en Compute Engine. Compatible Compatible con los sockets TCP. Compatible con los sockets TCP. Usa la marca -instances_metadata. Más información.

Consulta los ejemplos de invocaciones y strings de conexión.

Usa el proxy con una dirección IP privada

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

El proxy establece una conexión con tu instancia de Cloud SQL mediante la IP. De forma predeterminada, el proxy intenta conectarse a través de una dirección IPv4 pública. Si la instancia de Cloud SQL solo tiene IP privadas, el proxy usa la dirección IP privada para conectarse.

Si la instancia tiene configuradas IP públicas y privadas, y quieres que el proxy use la dirección IP privada, deberás proporcionar la siguiente opción cuando inicies el proxy:

-ip_address_types=PRIVATE

Sugerencias para trabajar con el proxy de Cloud SQL

Cómo invocar el proxy de Cloud SQL

En todos los ejemplos de invocaciones del proxy, este se inicia en segundo plano, por lo que se mostrará un mensaje. Se recomienda reservar esa terminal para el proxy, a fin de evitar que los resultados se mezclen con los de otros programas. Además, el resultado del proxy puede ayudarte a diagnosticar problemas de conexión, por lo que podría resultar útil capturarlo en un archivo de registro. Si no inicias el proxy en segundo plano, el resultado se dirige a stdout, a menos que se redireccione.

No es necesario que uses /cloudsql como el directorio para los sockets del proxy. (Ese nombre de directorio se eligió para minimizar las diferencias con las strings de conexión de App Engine). Pero, si decides cambiar el nombre del directorio, recuerda mantener la longitud al mínimo, ya que se incorporará a una string más extensa que tiene límites de longitud impuestos por el sistema operativo.

Cómo usar el proxy para conectarte a varias instancias

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

Sockets Unix

Para conectar el proxy a varias instancias, proporciona los nombres de conexión de las instancias con el parámetro -instances, en una lista separada por comas (sin espacios). El proxy se conectará a cada instancia cuando se inicie.

Debes conectar cada instancia con su socket, en el directorio especificado.

TCP

Si te conectas mediante TCP, debes especificar el puerto en tu máquina que se usará para conectarte a la instancia, y cada instancia debe tener su propio puerto. La herramienta sqlcmd usa el puerto 1433 de forma predeterminada, pero puedes especificar otro.

Por ejemplo:

  # Start the proxy for two instances, each with its own port:

  ./cloud_sql_proxy -instances=myProject:us-central1:myInstance=tcp:1433,myProject:us-central1:myInstance2=tcp:1234

  # Connect to "myInstance" on port 1433, and "myInstance2" on port 1234

  sqlcmd -U myUser -S "127.0.0.1,1433"
  sqlcmd -U myUser -S "127.0.0.1,1234"

Mantén actualizado el proxy de Cloud SQL

En ocasiones, Google lanza versiones nuevas del proxy. Puedes consultar la página de versiones GitHub del proxy de Cloud SQL para saber cuál es la versión actual. Las próximas versiones también se especificarán en el foro de anuncios de Cloud SQL de Grupos de Google.

Uso de la API

El proxy de Cloud SQL envía solicitudes a la API de Administrador de Cloud SQL. Estas solicitudes se deducen de la cuota de API para tu proyecto.

El mayor uso de la API se produce cuando inicias el proxy, en especial, si usas el descubrimiento automático de instancias o el parámetro -projects. Mientras el proxy está en ejecución, emite dos llamadas a la API por hora, por cada instancia conectada.

Parámetros y marcadores del proxy de Cloud SQL

El proxy de Cloud SQL acepta diversos marcadores y parámetros cuando inicia. Estas opciones determinan dónde y cómo el proxy de Cloud SQL crea los sockets que usa para comunicarse con Cloud SQL y cómo los autentica.

Para obtener ayuda con las opciones del proxy, consulta la siguiente información:

Invocaciones de proxy y strings de conexión del cliente sqlcmd

Puedes usar invocaciones del proxy y strings de conexión, por ejemplo, en comandos destinados a un usuario SQL Server myUser, para la instancia myInstance, ubicada en us-central1, en el proyecto myProject.

Para obtener más información sobre las opciones del proxy de Cloud SQL y las strings de conexión, consulta la página de GitHub del proxy de Cloud SQL.

Crea una cuenta de servicio y genera un archivo de claves

Para crear una cuenta de servicio:

Cuando usas una cuenta de servicio a fin de proporcionar credenciales para el proxy, debes crearla con los permisos necesarios. Si usas las funciones más específicas de Identity Access and Management (IAM) para administrar los permisos de Cloud SQL, debes asignarle a la cuenta de servicio una función que incluya el permiso cloudsql.instances.connect. A continuación, se enumeran las funciones predefinidas de Cloud SQL que incluyen este permiso:

  • Cliente de Cloud SQL
  • Editor de Cloud SQL
  • Administrador de Cloud SQL

Si usas las funciones de proyecto heredadas (visualizador, editor o propietario), la cuenta de servicio debe tener, al menos, la función de editor.

  1. Ve a la página Cuentas de servicio de Google Cloud Console.

    Ve a la página Cuentas de servicio

  2. Selecciona el proyecto que contiene la instancia de Cloud SQL.
  3. Haz clic en Crear cuenta de servicio.
  4. En el cuadro de diálogo Crear cuenta de servicio, ingresa un nombre descriptivo para la cuenta de servicio.
  5. En Función, selecciona una de las siguientes funciones:
    • Cloud SQL > Cliente de Cloud SQL
    • Cloud SQL > Editor de Cloud SQL
    • Cloud SQL > Administrador de Cloud SQL

    O bien, puedes seleccionar Proyecto > Editor a fin de usar la función básica de editor, pero esta incluye permisos para todo Google Cloud.

    Si no ves estas funciones, es posible que tu usuario de Google Cloud no tenga el permiso resourcemanager.projects.setIamPolicy. Para comprobar tus permisos, ve a la página de IAM en Google Cloud Console y busca tu ID de usuario.

  6. Cambia el ID de la cuenta de servicio por un valor único y reconocible.
  7. Haz clic en Proporcionar una nueva clave privada y confirma que el tipo de clave sea JSON.
  8. Haz clic en Crear.

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

Para obtener más información sobre las cuentas de servicio, consulta Descripción general de la autenticación.

Cómo usar el proxy de Cloud SQL en un entorno de producción

Cuando usas el proxy de Cloud SQL en un entorno de producción, debes seguir algunos pasos para asegurarte de que el proxy proporcione la disponibilidad que tu aplicación necesita.

Asegúrate de que el proxy de Cloud SQL se ejecute como un servicio persistente

Si se detiene el proceso del proxy, se descartan todas las conexiones existentes durante el proceso y tu aplicación no podrá crear más conexiones en la instancia de Cloud SQL con el proxy. Para evitar esta situación, asegúrate de ejecutar el proxy como un servicio persistente, de modo que si el proxy se cierra por algún motivo, se reinicie automáticamente. Esto se puede lograr mediante un servicio como systemd, upstart o supervisor. En el sistema operativo Windows, ejecuta el proxy como un servicio de Windows. En general, asegúrate de que el proxy tenga los mismos requisitos de tiempo de actividad que el proceso de tu aplicación.

Cuántas copias del proxy de Cloud SQL necesita tu aplicación

No es necesario crear un proceso de proxy para cada proceso de la aplicación. Muchos procesos de la aplicación pueden compartir el mismo proceso de proxy. Ejecuta un proceso de cliente proxy por estación de trabajo o máquina virtual.

Si usas el ajuste de escala automático para máquinas virtuales, asegúrate de que el proxy esté incluido en la configuración de tu máquina virtual. De esta forma, cada vez que se inicie una máquina virtual nueva, tendrá su propio proceso de proxy.

Depende de ti administrar la cantidad de conexiones que necesita tu aplicación, ya sea limitando o agrupando las conexiones. El proxy no impone ningún límite a las tasas de conexiones nuevas o al recuento de conexiones persistentes.

Cómo reducir el resultado del proxy de Cloud SQL

Si necesitas reducir el tamaño del registro del proxy, puedes configurar -verbose=false cuando inicies el proxy. Sin embargo, recuerda que esta acción reducirá la efectividad del resultado del proxy para diagnosticar problemas de conexión.

Cómo afecta la conmutación por error al proxy de Cloud SQL

Si estás ejecutando el proxy en una instancia configurada para alta disponibilidad y ocurre una conmutación por error, las conexiones mediante el proxy se verán afectadas de la misma manera que las conexiones por IP: se pierden todas las conexiones existentes y la aplicación debe establecer conexiones nuevas. Sin embargo, no se necesita intervención manual; la aplicación puede continuar con las mismas strings de conexión que antes.

Solución de problemas de conexión del proxy de Cloud SQL

Si tienes problemas para conectar tu instancia de Cloud SQL con el proxy de Cloud SQL, ten en cuenta los siguientes consejos a fin de intentar descubrir la causa del problema.

  • Verifica el resultado del proxy.

    A menudo, el resultado del proxy te ayudará a determinar el origen del problema y cómo resolverlo. Canaliza el resultado a un archivo o mira la terminal desde la que iniciaste el proxy.

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

    Para verificar la cuenta de servicio, puedes buscar su ID en la página de IAM. Debe tener el permiso cloudsql.instances.connect. Todas las funciones predefinidas de Cloud SQL tienen este permiso, excepto Cloud SQL Viewer. Además, las funciones de proyecto heredadas de Editor y Owner tienen el permiso necesario.

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

    De lo contrario, verás un resultado como Error 403: Access Not Configured en los registros de proxy.

  • 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 intentas conectarte desde una aplicación, hazlo primero con un cliente administrativo para evitar cualquier problema con la aplicación.

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

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

Qué sigue