Cómo conectarse a AlloyDB para PostgreSQL

Como administrador de BigQuery, puedes crear una conexión para acceder a los datos de AlloyDB. Esta conexión permite que los analistas de datos consulten datos en AlloyDB.

Para conectarte a AlloyDB, debes seguir estos pasos:

  1. Crea una conexión de AlloyDB.

  2. Otorga acceso a la cuenta de servicio.

Antes de comenzar

  1. Habilita la API de conexión de BigQuery.

    Habilita la API

  2. Para obtener los permisos que necesitas para crear una conexión de AlloyDB, pídele a tu administrador que te otorgue el rol de IAM administrador de conexión de BigQuery (roles/bigquery.connectionAdmin) en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

    También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Crea una conexión de AlloyDB

Como práctica recomendada, usa conexiones para controlar las credenciales de la base de datos cuando te conectes a AlloyDB. Las conexiones se encriptan y almacenan de forma segura en el servicio de conexión de BigQuery. Si las credenciales del usuario son válidas para otros datos en el origen, puedes volver a usar la conexión. Por ejemplo, puedes usar una conexión para consultar la misma base de datos en una instancia de AlloyDB varias veces.

Selecciona una de las siguientes opciones para crear una conexión de AlloyDB:

Console

  1. Ve a la página de BigQuery.

    Ir a BigQuery

  2. En el panel Explorador, haz clic en Agregar.

  3. En el diálogo Agregar, haz clic en Conexiones a fuentes de datos externas:

  4. En el diálogo Fuente de datos externa, ingresa la siguiente información:

    • En Tipo de conexión, selecciona AlloyDB.
    • En ID de conexión, ingresa un identificador para el recurso de conexión. Se permiten letras, números y guiones bajos. Por ejemplo, bq_alloydb_connection
    • En Ubicación de los datos, selecciona una ubicación (o región) de BigQuery que sea compatible con la región de la fuente de datos externa.
    • En Nombre descriptivo, ingresa un nombre fácil de usar para la conexión, como My connection resource (opcional). El nombre descriptivo puede ser cualquier valor que te ayude a identificar el recurso de conexión si necesitas modificarlo más adelante.
    • En Descripción, ingresa una descripción para este recurso de conexión (opcional).
    • Opcional: Encriptación Si deseas usar una clave de encriptación administrada por el cliente (CMEK) para encriptar tus credenciales, selecciona Clave de encriptación administrada por el cliente (CMEK) y, luego, selecciona una clave administrada por el cliente. De lo contrario, tus credenciales están protegidas con la clave predeterminada que es propiedad de Google y está administrada por Google.
    • En Nombre de la base de datos (Database name), ingresa el nombre de la base de datos.
    • En Nombre de usuario de la base de datos, ingresa el nombre de usuario para la base de datos.
    • En Contraseña de la base de datos, ingresa la contraseña para la base de datos.
      • Opcional: Para ver la contraseña, haz clic en Mostrar contraseña.

    • En Instancia de AlloyDB, ingresa el URI de conexión de la instancia principal o de lectura de AlloyDB con el prefijo //alloydb.googleapis.com.

      • URI de muestra: //alloydb.googleapis.com/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_NAME/instances/INSTANCE_ID

  5. Haga clic en Crear conexión.

  6. Haz clic en Ir a la conexión.

  7. En el panel Información de conexión, copia el ID de la cuenta de servicio para usarlo en el próximo paso y otorgar los permisos de IAM correctos.

bq

Ingresa el comando bq mk con las siguientes marcas:

  bq mk \
  --connection \
  --location=LOCATION \
  --project_id=PROJECT_ID \
  --connector_configuration '{
    "connector_id": "google-alloydb",
    "asset": {
      "database": "DATABASE",
      "google_cloud_resource": "RESOURCE_PATH"
    },
    "authentication": {
      "username_password": {
        "username": "USERNAME",
        "password": {
          "plaintext": "PASSWORD"
        }
      }
    }
  }' \
  CONNECTION_ID

Reemplaza lo siguiente:

  • LOCATION: Especifica una región del conjunto de datos de BigQuery que se combinará con los datos de AlloyDB. Las consultas que usan esta conexión deben ejecutarse desde esta región.
  • PROJECT_ID: ingresa el ID del proyecto de Google Cloud.
  • DATABASE: Ingresa el nombre de la base de datos.
  • RESOURCE_PATH: Ingresa el URI de conexión de la instancia principal o de lectura de AlloyDB con el prefijo //alloydb.googleapis.com.
    • URI de muestra: //alloydb.googleapis.com/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_NAME/instances/INSTANCE_ID
  • USERNAME: Ingresa el nombre del usuario de la base de datos.
  • PASSWORD: Ingresa la contraseña del usuario de la base de datos.
  • CONNECTION_ID: Ingresa un ID de conexión para identificar esta conexión.

API

Dentro de la API de conexión de BigQuery, puedes invocar CreateConnection dentro de ConnectionService para crear una instancia de conexión. Consulta la página de la biblioteca cliente para obtener más detalles.

Otorga acceso a la cuenta de servicio

Una cuenta de servicio se crea automáticamente cuando creas la primera conexión dentro de un proyecto. El nombre de la cuenta de servicio es BigQuery Connection Service Agent. El ID de la cuenta de servicio tiene el siguiente formato:

service-PROJECT_NUMBER@gcp-sa-bigqueryconnection.iam.gserviceaccount.com

Para conectarte a AlloyDB, debes otorgar a la nueva conexión acceso a AlloyDB para que BigQuery pueda acceder a los datos en nombre de los usuarios. La cuenta de servicio debe tener el siguiente permiso:

  • alloydb.instances.connect

Puedes otorgar a la cuenta de servicio asociada con la conexión el rol de IAM de cliente de AlloyDB, que ya tiene asignado este permiso. Puedes omitir este paso si la cuenta de servicio ya tiene el permiso necesario.

Console

  1. Ir a la página IAM y administración

    Ir a IAM y administración

  2. Haz clic en Otorgar acceso.

    Se abre el cuadro de diálogo Agregar principales.

  3. En el campo Principales nuevas, escribe el nombre de la cuenta de servicio BigQuery Connection Service Agent o el ID de la cuenta de servicio que se tomó de la información de conexión.

  4. En el campo Selecciona un rol, selecciona AlloyDB y, luego, Cliente de AlloyDB.

  5. Haz clic en Guardar.

gcloud

Usa el comando de gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:SERVICE_ACCOUNT_ID --role=roles/alloydb.client

Ingresa los siguientes valores:

  • PROJECT_ID es el ID del proyecto de Google Cloud.
  • SERVICE_ACCOUNT_ID: Reemplaza el número de proyecto en service-PROJECT_NUMBER@gcp-sa-bigqueryconnection.iam.gserviceaccount.com y úsalo.

Comparte conexiones con usuarios

Puedes otorgar los siguientes roles para permitir que los usuarios consulten datos y administren conexiones:

  • roles/bigquery.connectionUser: Permite que los usuarios usen conexiones para conectarse con fuentes de datos externas y ejecutar consultas en ellas.

  • roles/bigquery.connectionAdmin: Permite que los usuarios administren conexiones.

Para obtener más información sobre los roles y los permisos de IAM en BigQuery, consulta Roles y permisos predefinidos.

Selecciona una de las opciones siguientes:

Console

  1. Ve a la página de BigQuery.

    Ir a BigQuery

    Las conexiones se enumeran en tu proyecto, en un grupo llamado Conexiones externas.

  2. En el panel Explorador, haz clic en el nombre de tu proyecto > Conexiones externas > conexión.

  3. En el panel Detalles, haz clic en Compartir para compartir una conexión. A continuación, sigue estos pasos:

    1. En el cuadro de diálogo Permisos de conexión, agrega o edita las principales para compartir la conexión con otros principales.

    2. Haz clic en Guardar.

bq

Usa el siguiente comando set-iam-policy:

  bq set-iam-policy RESOURCE FILE_NAME

Reemplaza lo siguiente:

  • RESOURCE: Ingresa el nombre del recurso en el formato project_id.region.connection_id o region.connection_id.
  • FILE_NAME: Ingresa el nombre del archivo que contiene la política de IAM en formato JSON.

Para obtener más información sobre el comando set-iam-policy, consulta Controla el acceso a los recursos con IAM.

API

Consulta el método projects.locations.connections.setIAM en la sección de referencia de la API de REST de las conexiones de BigQuery y proporciona una instancia del recurso policy.

¿Qué sigue?