Conectarse desde Compute Engine

En esta página se explica cómo utilizar el cliente psql, instalado en una instancia de Compute Engine, para conectar con Cloud SQL.

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

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

Antes de empezar

Esta tarea no incluye instrucciones para configurar tu 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

Para conectarte a Cloud SQL desde una instancia de Compute Engine mediante una IP privada, debes configurar el acceso a servicios privados en tu entorno y configurar tu instancia de Cloud SQL para que use una IP privada. Tu instancia de Compute Engine debe estar en la misma región que tu instancia de Cloud SQL y en la red configurada para una conexión privada. Más información

1. Configurar una instancia para que use una IP privada

Sigue las instrucciones de la sección Configurar la conectividad de IP privada.

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

Utiliza las instrucciones adecuadas según el sistema operativo de la instancia:

Si la instancia de Compute Engine ejecuta una imagen pública de RHEL o CentOS, SELinux podría bloquear la conexión de proxy. En ese caso, debes configurar la función SELinux para permitir la conexión.

Si quieres obtener más información sobre SELinux para RHEL, consulta la documentación de RHEL. Para 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 no está ya instalado.

Debian o Ubuntu

Instala el cliente psql desde el administrador de paquetes:

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

CentOS o 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 básica de PostgreSQL para la plataforma en la página de descargas de PostgreSQL.
    La distribución principal incluye el cliente psql.
  2. Instala la base de datos PostgreSQL según se indica en las instrucciones de la página de descarga.

4. Conectate con el cliente psql.

psql -h CLOUD_SQL_PRIVATE_IP_ADDRESS -U USERNAME

Puedes encontrar la dirección IP privada en la página de instancias de Cloud SQL o ejecutando el siguiente comando gcloud:

gcloud sql instances list

IP pública

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

1. Añade una dirección IPv4 estática a la instancia de Compute Engine si no tienes ya una.

No puedes conectarte a Compute Engine mediante direcciones IPv6. Para obtener información sobre cómo añadir una dirección IP estática, consulta el artículo Reservar una dirección IP externa estática nueva de la documentación de Compute Engine.

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

Para obtener más información, consulta la sección Configurar el acceso para conexiones IP públicas.

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

Utiliza las instrucciones adecuadas según el sistema operativo de la instancia:

Si la instancia de Compute Engine ejecuta una imagen pública de RHEL o CentOS, SELinux podría bloquear la conexión de proxy. En ese caso, debes configurar la función SELinux para permitir la conexión.

Si quieres obtener más información sobre SELinux para RHEL, consulta la documentación de RHEL. Para 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 no está ya instalado.

Debian o Ubuntu

Instala el cliente psql desde el administrador de paquetes:

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

CentOS o 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 básica de PostgreSQL para la plataforma en la página de descargas de PostgreSQL.
    La distribución principal incluye el cliente psql.
  2. Instala la base de datos PostgreSQL según se indica en las instrucciones de la página de descarga.

5. Conectate 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 Instancias de Cloud SQL o ejecutando el siguiente comando gcloud:

gcloud sql instances list

Para ver un ejemplo de cómo conectarse mediante SSL, consulta Conectarse mediante SSL.

6. Aparecerá el prompt de psql.

7. Si necesitas mantener activas las conexiones que no se usan:

Define el tiempo de actividad de TCP.

Para obtener más información, consulta el artículo Comunicación entre las instancias e Internet de la documentación de Compute Engine.

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

Proxy de autenticación de Cloud SQL

Para conectarte mediante el proxy de autenticación de Cloud SQL desde Compute Engine, haz lo siguiente:

1. Habilita la API Admin de Cloud SQL.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

2. Crea una cuenta de servicio.

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

    Ir a Cuentas de servicio

  2. Selecciona el proyecto que contiene tu instancia de Cloud SQL.
  3. Haz clic en Crear cuenta de servicio.
  4. En el campo Nombre de cuenta de servicio, escribe un nombre descriptivo para la cuenta de servicio.
  5. Cambia el ID de cuenta de servicio por un valor único y reconocible y, a continuación, haz clic en Crear y continuar.
  6. Haz clic en el campo Selecciona un rol y elige uno de los siguientes:
    • Cloud SQL > Cliente de Cloud SQL
    • Cloud SQL > Editor de Cloud SQL
    • Cloud SQL > Administrador de Cloud SQL

  7. Haz clic en Hecho para terminar de crear la cuenta de servicio.
  8. Haz clic en el menú de acciones de tu nueva cuenta de servicio y, a continuación, selecciona Gestionar claves.
  9. Haz clic en el menú desplegable Añadir clave y, a continuación, en Crear clave.
  10. Confirma que el tipo de clave es JSON y, a continuación, haz clic en Crear.

    El archivo de clave privada se descarga en tu máquina. Puedes moverlo a otra ubicación. Debes proteger el archivo de clave.

Si la instancia de Compute Engine se encuentra en un proyecto distinto que la instancia de Cloud SQL, asegúrate de que su cuenta de servicio tiene los permisos necesarios en el proyecto que contiene la instancia de Cloud SQL:

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

    Ir a la lista de instancias de Compute Engine

  2. Si fuera necesario, selecciona el proyecto asociado con la instancia de Compute Engine.
  3. Selecciona la instancia de Compute Engine para ver sus 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 administración en la Google Cloud consola.

    Ve a la página Proyectos de IAM y 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 está ahí y tiene un rol que incluye el permiso cloudsql.instances.connect, puedes ir al paso 4.

    Los roles Cloud SQL Client, Cloud SQL Editor y Cloud SQL Admin proporcionan el permiso necesario, al igual que los roles de proyecto antiguos Editor y Owner.

  9. De lo contrario, añade la cuenta de servicio haciendo clic en Añadir.

  10. En el cuadro de diálogo Añadir principales, indica el nombre de la cuenta de servicio y selecciona un rol que incluya el permiso cloudsql.instances.connect. Puedes usar cualquier rol predefinido de Cloud SQL que no sea Lector.

    También puedes usar el rol Editor básico seleccionando Proyecto > Editor, pero este rol incluye permisos en Google Cloud.

    Si no ve estos roles, es posible que su Google Cloud usuario no tenga el permisoresourcemanager.projects.setIamPolicy. Para comprobar tus permisos, ve a la página Gestión de identidades y accesos de la Google Cloud consola y busca tu ID de usuario.

  11. Haz clic en Añadir.

    Ahora verás la cuenta de servicio con el rol especificado.

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

Utiliza las instrucciones adecuadas según el sistema operativo de la instancia:

Si la instancia de Compute Engine ejecuta una imagen pública de RHEL o CentOS, SELinux podría bloquear la conexión de proxy. En ese caso, debes configurar la función SELinux para permitir la conexión.

Si quieres obtener más información sobre SELinux para RHEL, consulta la documentación de RHEL. Para 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 no está ya instalado.

Debian o Ubuntu

Instala el cliente psql desde el administrador de paquetes:

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

CentOS o 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 básica de PostgreSQL para la plataforma en la página de descargas de PostgreSQL.
    La distribución principal incluye el cliente psql.
  2. Instala la base de datos PostgreSQL según se indica en las instrucciones de la página de descarga.

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.18.2/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.18.2/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.18.2/cloud-sql-proxy.x64.exe y selecciona Guardar enlace como para descargar el proxy de autenticación de Cloud SQL. Cambia el nombre del archivo a 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.18.2/cloud-sql-proxy.x86.exe y selecciona Guardar enlace como para descargar el proxy de autenticación de Cloud SQL. Cambia el nombre del archivo a cloud-sql-proxy.exe.

Imagen de Docker del proxy de autenticación 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 predeterminada del proxy de autenticación de Cloud SQL usa distroless, que no contiene ningún shell. Si necesitas un 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 imagen más reciente en tu máquina local con Docker mediante el siguiente comando:

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

Otros SO

En el caso de otros sistemas operativos que no se incluyan aquí, puedes compilar el proxy de autenticación de Cloud SQL a partir del código fuente.

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

En función del lenguaje y del entorno, puedes iniciar el proxy de autenticación de Cloud SQL mediante sockets TCP, sockets Unix o la imagen Docker del proxy de autenticación de Cloud SQL. El archivo binario del proxy de autenticación de Cloud SQL se conecta a una o varias instancias de Cloud SQL especificadas en la línea de comandos y abre una conexión local como TCP o como socket Unix. Otras aplicaciones y servicios, como el código de tu aplicación o las herramientas de cliente de gestión de bases de datos, pueden conectarse a instancias de Cloud SQL a través de esas conexiones TCP o de socket Unix.

Sockets TCP

En el caso de las conexiones TCP, el proxy de autenticación de Cloud SQL escucha en localhost(127.0.0.1) de forma predeterminada. Por lo tanto, si especificas --port PORT_NUMBER para una instancia, la conexión local será 127.0.0.1:PORT_NUMBER.

También puedes especificar otra dirección para la conexión local. Por ejemplo, así se configura el proxy de autenticación de Cloud SQL para que escuche en 0.0.0.0:1234 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 Resumen de tu instancia en la Google Cloud consola o ejecutando el siguiente comando:

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

    Por ejemplo: myproject:myregion:myinstance.

  2. Si la instancia tiene configuradas tanto la IP pública como la privada y quieres que el proxy de autenticación de Cloud SQL use la dirección IP privada, debes proporcionar la siguiente opción al iniciar el proxy de autenticación de Cloud SQL: 
    --private-ip
  3. Si utilizas una cuenta de servicio para autenticar el proxy de autenticación de Cloud SQL, anota la ubicación en tu máquina cliente del archivo de clave privada que se creó cuando creaste la cuenta de servicio.
  4. Inicia el proxy de autenticación de Cloud SQL.

    Estas son algunas cadenas de invocación del proxy de autenticación de Cloud SQL:

    • Con la autenticación del SDK de Google Cloud: 
      ./cloud-sql-proxy --port 5432 INSTANCE_CONNECTION_NAME
       El puerto especificado no debe estar en uso. Por ejemplo, no debe estarlo por un servidor de base de datos local.
    • Usar una cuenta de servicio e incluir explícitamente 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 Unix, que es un mecanismo estándar de Posix para usar una carpeta con el fin de gestionar la comunicación entre dos procesos que se ejecutan en el mismo host. Las ventajas de usar sockets Unix son una mayor seguridad y una 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 tanto el proxy de autenticación de Cloud SQL como la aplicación deben tener acceso de lectura y escritura a él.

  1. Copia tu INSTANCE_CONNECTION_NAME. Puedes encontrarlo en la página Resumen de tu instancia en la Google Cloud consola o ejecutando el siguiente comando:

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

    Por ejemplo: myproject:myregion:myinstance.

  2. Crea el directorio en el que se ubicarán los sockets del proxy de autenticación de Cloud SQL: 
    sudo mkdir /cloudsql; sudo chmod 777 /cloudsql
  3. Si utilizas una cuenta de servicio para autenticar el proxy de autenticación de Cloud SQL, anota la ubicación en tu máquina cliente del archivo de clave privada que se creó cuando creaste la cuenta de servicio.
  4. Abre una nueva ventana de terminal de Cloud Shell e inicia el proxy de autenticación de Cloud SQL.

    Estas son algunas cadenas de invocación del proxy de autenticación de Cloud SQL:

    • Usar la autenticación del SDK de Google Cloud: 
      ./cloud-sql-proxy --unix-socket /cloudsql INSTANCE_CONNECTION_NAME &
    • Usar 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 propio terminal de Cloud Shell para poder monitorizar su salida sin que se mezcle con la 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 Docker, usa la imagen Docker del proxy de autenticación de Cloud SQL, disponible en Google Container Registry.

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

gcloud sql instances describe INSTANCE_NAME
.

Por ejemplo: myproject:myregion:myinstance.

En función del lenguaje y del entorno, puedes iniciar el proxy de autenticación de Cloud SQL mediante sockets TCP o sockets Unix. Los sockets Unix no son compatibles con las aplicaciones escritas en lenguaje de programación Java o pensadas para el entorno Windows.

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

Si usas las credenciales proporcionadas por 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. En el parámetro de instancias se requiere el valor "0.0.0.0" para que sea posible acceder al puerto desde fuera del contenedor Docker.

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

Si usas las credenciales proporcionadas por 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, utiliza un directorio en el que se pueda escribir en lugar de /cloudsql. Por ejemplo: 

-v /mnt/stateful_partition/cloudsql:/cloudsql

Puedes especificar más de una instancia si las separas por comas. También puedes usar los metadatos de Compute Engine para determinar de forma dinámica las instancias a las que conectarte. Consulta más información sobre los parámetros del proxy de autenticación de Cloud SQL.

7. Inicia la sesión de psql.

La cadena de conexión que utilices dependerá de si has iniciado el proxy de autenticación de Cloud SQL mediante un socket TCP, 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 esté definido como disable, el proxy de autenticación de Cloud SQL proporciona una conexión cifrada.

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

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

Usar 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 esté definido como disable, el proxy de autenticación de Cloud SQL proporciona una conexión cifrada.

  2. Introduce la contraseña.
  3. Aparecerá el prompt de psql.

¿Necesitas ayuda? Para obtener ayuda para solucionar problemas con el proxy, consulta el artículo Solucionar problemas de conexiones del proxy de autenticación de Cloud SQL o visita nuestra página de asistencia de Cloud SQL.

Siguientes pasos