Conectar desde Compute Engine

En esta página, se describe cómo usar el cliente psql, instalarlo en una instancia de Compute Engine y conectarlo a Cloud SQL.

Puedes usar una IP privada, una IP pública, el proxy de Cloud SQL Auth o la imagen de Docker del proxy de Cloud SQL Auth.

Para obtener instrucciones paso a paso sobre cómo ejecutar una aplicación web de muestra de Compute Engine conectada a Cloud SQL, consulta la guía de inicio rápido para conectarse desde Compute Engine.

Antes de comenzar

Esta tarea no incluye instrucciones para configurar la instancia de Compute Engine. Si necesitas ayuda para crear y configurar una instancia de Compute Engine, consulta la documentación de Compute Engine.

IP privada

A fin de conectarte a Cloud SQL desde una instancia de Compute Engine con una IP privada, el acceso a servicios privados debe estar configurado para tu entorno y la instancia de Cloud SQL debe estar configurada para usar una IP privada. La instancia de Compute Engine debe estar en la misma región que la instancia de Cloud SQL y en la red configurada para una conexión privada. Obtén más información.

1. Configura tu instancia para que utilice una IP privada.

Usa las instrucciones de Cómo configurar la conectividad de IP privada.

2. Abre una conexión de terminal de Cloud Shell en tu instancia de Compute Engine.

Sigue las instrucciones correspondientes según el sistema operativo de la instancia:

Si tu instancia de Compute Engine ejecuta una imagen pública CentOS o RHEL, es posible que SELinux bloquee la conexión del proxy. Si esto sucede, debes configurar la función SELinux para permitir la conexión.

Si deseas obtener más información sobre SELinux para RHEL, consulta la documentación de RHEL. Si deseas obtener más información sobre SELinux para CentOS, consulta la documentación de CentOS.

3. Instala el cliente psql en la instancia de Compute Engine, si todavía no está instalado.

Debian/Ubuntu

Instala el cliente psql desde el administrador de paquetes:

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

CentOS/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 principal de PostgreSQL para tu plataforma desde la página de descargas de PostgreSQL.
    La distribución principal incluye el cliente psql.
  2. Instala la base de datos de PostgreSQL y sigue las instrucciones en la página de descargas.

4. Conéctate con el cliente psql.

psql -h CLOUD_SQL_PRIVATE_IP_ADDRESS -U USERNAME

Puedes encontrar la dirección IP privada en la página Instancias de Cloud SQL o mediante la ejecución del siguiente comando de gcloud:

gcloud sql instances list

IP pública

Para conectarte mediante una IP pública, sigue estos pasos:

1. Agrega una dirección IP IPv4 estática a la instancia de Compute Engine, si no tiene una.

No puedes conectarte a Compute Engine con IPv6. Para obtener más información sobre cómo agregar una dirección IP estática, consulta Reserva una nueva dirección IP externa estática en la documentación de Compute Engine.

2. Autoriza la dirección IP estática de la instancia de Compute Engine como una red para que se pueda conectar a tu instancia de Cloud SQL.

Si quieres obtener más información, consulta Configura el acceso para conexiones IP públicas.

3. Abre una conexión de terminal de Cloud Shell en tu instancia de Compute Engine.

Sigue las instrucciones correspondientes según el sistema operativo de la instancia:

Si tu instancia de Compute Engine ejecuta una imagen pública CentOS o RHEL, es posible que SELinux bloquee la conexión del proxy. Si esto sucede, debes configurar la función SELinux para permitir la conexión.

Si deseas obtener más información sobre SELinux para RHEL, consulta la documentación de RHEL. Si deseas obtener más información sobre SELinux para CentOS, consulta la documentación de CentOS.

4. Instala el cliente psql en la instancia de Compute Engine, si todavía no está instalado.

Debian/Ubuntu

Instala el cliente psql desde el administrador de paquetes:

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

CentOS/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 principal de PostgreSQL para tu plataforma desde la página de descargas de PostgreSQL.
    La distribución principal incluye el cliente psql.
  2. Instala la base de datos de PostgreSQL y sigue las instrucciones en la página de descargas.

5. Conéctate con el cliente psql.

psql -h CLOUD_SQL_PUBLIC_IP_ADDR -U USERNAME

Puedes encontrar la dirección IP pública en la página de instancias de Cloud SQL o mediante la ejecución del siguiente comando de gcloud:

gcloud sql instances list

Para ver un ejemplo sobre cómo conectarte con SSL, consulta Conéctate con SSL.

6. Aparecerá el mensaje de psql.

7. Si necesitas mantener activas las conexiones que no se usan, sigue estos pasos:

Configura el TCP keepalive.

Para obtener más información, consulta la página sobre cómo comunicar tus instancias a Internet en la documentación de Compute Engine.

Las conexiones se mantienen activas automáticamente para las instancias.

Proxy de Cloud SQL Auth

Para conectarte mediante el proxy de Cloud SQL Auth desde Compute Engine, sigue estos pasos:

1. Habilita la API de Cloud SQL Admin

Enable the API

2. Crea una cuenta de servicio.

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

    Ir a Cuentas de servicio

  2. Selecciona el proyecto que contiene la instancia de Cloud SQL.
  3. Haga clic en Crear cuenta de servicio.
  4. En el campo Nombre de la cuenta de servicio, ingresa un nombre descriptivo para la cuenta de servicio.
  5. Cambia el ID de la cuenta de servicio a un valor único y reconocible y, luego, haz clic en Crear y continuar.
  6. Haz clic en el campo Seleccionar un rol y selecciona uno de los siguientes roles:
    • Cloud SQL > Cliente de Cloud SQL
    • Cloud SQL > Editor de Cloud SQL
    • Cloud SQL > Administrador de Cloud SQL
  7. Haz clic en Listo para terminar de crear la cuenta de servicio.
  8. Haz clic en el menú de acciones de tu nueva cuenta de servicio y, luego, selecciona Administrar claves.
  9. Haz clic en el menú desplegable Agregar clave y, luego, en Crear clave nueva.
  10. Confirma que el tipo de clave sea JSON y, luego, haz clic en Crear.

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

Si la instancia de Compute Engine se encuentra en un proyecto diferente que la instancia de Cloud SQL, asegúrate de que la cuenta de servicio tenga los permisos correspondientes en el proyecto que contiene la instancia de Cloud SQL:

  1. Ve a la lista de instancias de Compute Engine en la consola de Google Cloud.

    Ir a la lista de instancias de Compute Engine

  2. Si es necesario, selecciona el proyecto asociado con la instancia de Compute Engine.
  3. Selecciona la instancia de Compute Engine para ver las propiedades.
  4. En las propiedades de la instancia de Compute Engine, copia el nombre de la cuenta de servicio.
  5. Ve a la página Proyectos de IAM y de administración en la consola de Google Cloud.

    Ir a la página Proyectos de IAM y de administración

  6. Selecciona el proyecto que contiene la instancia de Cloud SQL.
  7. Busca el nombre de la cuenta de servicio.
  8. Si la cuenta de servicio ya existe y tiene una función que incluye el permiso cloudsql.instances.connect, puedes continuar con el paso 4.

    Las funciones de Cloud SQL Client, Cloud SQL Editor y Cloud SQL Admin brindan los permisos necesarios, al igual que las funciones de proyecto heredadas Editor y Owner.

  9. De lo contrario, haz clic en Agregar para incluir la cuenta de servicio.
  10. En el diálogo Agregar principales, ingresa el nombre de la cuenta de servicio y selecciona una función que incluya el permiso cloudsql.instances.connect (cualquier función predefinida de Cloud SQL funcionará, excepto la función de visualizador).

    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, accede a la página de IAM en la consola de Google Cloud y busca tu ID de usuario.

  11. Haz clic en Agregar.

    Ahora verás que la cuenta de servicio aparece con la función especificada.

3. Abre una conexión terminal en tu instancia de Compute Engine.

Sigue las instrucciones correspondientes según el sistema operativo de la instancia:

Si tu instancia de Compute Engine ejecuta una imagen pública CentOS o RHEL, es posible que SELinux bloquee la conexión del proxy. Si esto sucede, debes configurar la función SELinux para permitir la conexión.

Si deseas obtener más información sobre SELinux para RHEL, consulta la documentación de RHEL. Si deseas obtener más información sobre SELinux para CentOS, consulta la documentación de CentOS.

4. Instala el cliente psql en la instancia de Compute Engine, si todavía no está instalado.

Debian/Ubuntu

Instala el cliente psql desde el administrador de paquetes:

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

CentOS/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 principal de PostgreSQL para tu plataforma desde la página de descargas de PostgreSQL.
    La distribución principal incluye el cliente psql.
  2. Instala la base de datos de PostgreSQL y sigue las instrucciones en la página de descargas.

5. Instala el proxy de autenticación de Cloud SQL en la instancia de Compute Engine.

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

Windows de 64 bits

Haz clic con el botón derecho en https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.13.0/cloud-sql-proxy.x64.exe y selecciona Guardar vínculo como para descargar el proxy de autenticación de Cloud SQL. Cambia el nombre del archivo por 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.13.0/cloud-sql-proxy.x86.exe y selecciona Guardar vínculo como para descargar el proxy de autenticación de Cloud SQL. Cambia el nombre del archivo por cloud-sql-proxy.exe.

Imagen de Docker del proxy 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 del proxy de autenticación de Cloud SQL predeterminada usa distroless, que no contiene shell. Si necesitas una 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 última imagen a tu máquina local con Docker a través del siguiente comando:

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

Otro SO

Para otros sistemas operativos que no se incluyen aquí, puedes compilar el proxy de Cloud SQL Auth desde la fuente.

6. Inicia el proxy de autenticación de Cloud SQL.

Según tu lenguaje y entorno, puedes iniciar el proxy de autenticación de Cloud SQL con sockets de TCP, sockets de Unix o la imagen de Docker del proxy de autenticación de Cloud SQL. El objeto binario del proxy de autenticación de Cloud SQL 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 la aplicación o las herramientas de administración de bases de datos del cliente, pueden conectarse a las instancias de Cloud SQL mediante esos sockets.

Sockets TCP

En el caso de las conexiones de TCP, el proxy de autenticación de Cloud SQL escucha en localhost(127.0.0.1) de forma predeterminada. Por lo tanto, cuando especificas --port 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, a continuación, se muestra cómo hacer que el proxy de autenticación de Cloud SQL escuche en 0.0.0.0:1234 para 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 Descripción general de la instancia en la consola de Google Cloud o mediante la ejecución del siguiente comando:

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

    Por ejemplo: myproject:myregion:myinstance.

  2. Si la instancia tiene configuradas una IP pública y 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 cuando lo inicies:
    --private-ip
  3. Si usas una cuenta de servicio para autenticar el proxy de autenticación de Cloud SQL, toma nota de la ubicación del archivo de claves privadas que se generó en la máquina cliente cuando creaste la cuenta de servicio.
  4. Inicia el proxy de autenticación de Cloud SQL.

    Estas son algunas strings posibles para invocar al proxy de autenticación de Cloud SQL:

    • Si usas la autenticación del SDK de Cloud:
      ./cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
      El puerto especificado no debe estar en uso, por ejemplo, por un servidor de base de datos local.
    • Si usas una cuenta de servicio y también incluyes de forma explícita 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

El proxy de autenticación de Cloud SQL puede escuchar en un socket de Unix, que es un mecanismo estándar de Posix para usar una carpeta y administrar la 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 de Unix desde una máquina externa.

Para crear y usar un socket de Unix, el directorio de destino debe existir, y el proxy de autenticación de Cloud SQL y la aplicación deben tener acceso de lectura y escritura.

  1. Copia tu INSTANCE_CONNECTION_NAME. Puedes encontrarlo en la página Descripción general de la instancia en la consola de Google Cloud o mediante la ejecución del siguiente comando:

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

    Por ejemplo: myproject:myregion:myinstance.

  2. Crea el directorio en el que se alojarán los sockets del proxy de autenticación de Cloud SQL:
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  3. Si usas una cuenta de servicio para autenticar el proxy de autenticación de Cloud SQL, toma nota de la ubicación del archivo de claves privadas que se generó en la máquina cliente cuando creaste la cuenta de servicio.
  4. Abre una nueva ventana de terminal de Cloud Shell y, luego, inicia el proxy de autenticación de Cloud SQL.

    Estas son algunas strings posibles para invocar al proxy de autenticación de Cloud SQL:

    • Si usas la autenticación del SDK de Google Cloud:
      ./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &
    • Usa 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 propia terminal de Cloud Shell para supervisar el resultado sin que se mezcle con el 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.

Docker

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

Para iniciar el proxy de autenticación de Cloud SQL, usa los sockets de TCP o de Unix con los comandos que se muestran a continuación. Las opciones usan un INSTANCE_CONNECTION_NAME como la string de conexión para identificar una instancia de Cloud SQL. Puedes encontrar el INSTANCE_CONNECTION_NAME en la página Descripción general de tu instancia en la consola de Google Cloud o ejecutando el siguiente comando:

gcloud sql instances describe INSTANCE_NAME
.

Por ejemplo: myproject:myregion:myinstance.

Según tu lenguaje y entorno, puedes iniciar el proxy de autenticación de Cloud SQL con sockets de TCP o de Unix. Los sockets de Unix no son compatibles con aplicaciones escritas en el lenguaje de programación Java o con el entorno de Windows.

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

Si usas las credenciales que proporciona 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. El “0.0.0.0” en el parámetro de las instancias es necesario para que se pueda acceder al puerto desde afuera del contenedor de Docker.

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

Si usas las credenciales que proporciona 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, usa un directorio que admita operaciones de escritura en lugar de /cloudsql, por ejemplo:

-v /mnt/stateful_partition/cloudsql:/cloudsql

Puedes especificar más de una instancia, separadas por comas. También puedes usar los metadatos de Compute Engine para determinar de forma dinámica las instancias que se conectarán. Obtén más información acerca de los parámetros del proxy de autenticación de Cloud SQL.

7. Inicia la sesión psql.

La string de conexión que usas depende de si iniciaste el proxy de Cloud SQL Auth con un socket TCP o 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 se configuró como disable, el proxy de autenticación de Cloud SQL proporciona una conexión encriptada.

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

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

Usa 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 se configuró como disable, el proxy de autenticación de Cloud SQL proporciona una conexión encriptada.

  2. Ingresa la contraseña.
  3. Aparecerá el mensaje de psql.

¿Necesitas ayuda? Para solucionar problemas del proxy, consulta Solución de problemas de conexión del proxy de autenticación de Cloud SQL o nuestra página Asistencia de Cloud SQL.

¿Qué sigue?