Crea un clúster y su instancia principal

Para implementar un entorno de base de datos para tus aplicaciones en AlloyDB para PostgreSQL, crea un clúster y su instancia principal. El clúster administra la configuración y el almacenamiento regionales, mientras que la instancia principal proporciona los recursos de procesamiento para las operaciones de lectura y escritura. Puedes crear un clúster y su instancia principal con la consola de Google Cloud , Google Cloud CLI, la API de REST o Terraform.

Antes de comenzar

Roles obligatorios

Antes de crear tu primer clúster de AlloyDB, debes tener los roles de Identity and Access Management (IAM) correctos.

  • Debes tener uno de estos roles de IAM en el proyecto de Google Cloud que estás usando:
    • roles/alloydb.admin (el rol de IAM predefinido de administrador de AlloyDB)
    • roles/owner (el rol básico de IAM de propietario)
    • roles/editor (el rol básico de IAM de editor)
  • Si no tienes ninguno de estos roles, comunícate con el administrador de la organización para solicitar acceso.
  • También debes tener el permiso compute.networks.list en el proyecto de Google Cloud que usas. Para obtener este permiso y, al mismo tiempo, seguir el principio de privilegio mínimo, pídele a tu administrador que te otorgue el rol de usuario de red de Compute (roles/compute.networkUser).

Crea un clúster y una instancia principal nuevos

Console

  1. Ve a la página Clústeres.

    Ir a los clústeres

  2. Haga clic en Crear clúster.

  3. Elige una configuración de clúster. Para obtener más información sobre la diferencia entre las configuraciones básicas y de alta disponibilidad, consulta ¿Qué es una instancia de AlloyDB?.

    Si no tienes certeza de si tu clúster nuevo necesita instancias de grupos de lectura, elige una de las opciones de configuración sin grupos de lectura. Puedes agregar instancias de grupo de lectura al clúster más adelante, cuando sea necesario.

  4. Haz clic en Continuar.

  5. En la sección Configura tu clúster, en el campo ID del clúster, ingresa un ID para tu clúster.

  6. En el campo Contraseña, ingresa una contraseña inicial para el clúster nuevo. AlloyDB asigna la contraseña proporcionada al usuario de la base de datos postgres mientras se crea el clúster.

  7. Opcional: Para configurar la marca alloydb.iam_authentication de forma manual, anula la selección de Crear un usuario de base de datos de IAM. Para obtener más información, consulta Configura marcas de bases de datos.

    De forma predeterminada, se selecciona Crear un usuario de base de datos de IAM, que hace lo siguiente:

    • Habilita la marca alloydb.iam_authentication en la instancia principal.

    • Crea un usuario de base de datos de IAM para ti.

  8. En el campo Versión de la base de datos, selecciona la versión principal de PostgreSQL para tu nuevo clúster de AlloyDB.

  9. Selecciona una región. Para las cargas de trabajo de desarrollo y de zona de pruebas, considera la forma de 1 CPU virtual, que está disponible en regiones seleccionadas. Para obtener más información, consulta Consideraciones cuando se usa 1 CPU virtual.

  10. Selecciona una ruta de red.

  11. Opcional: Para aplicar un rango de direcciones IP específico a este clúster, en lugar de permitir que AlloyDB elija un rango de direcciones IP, sigue estos pasos:

    1. Haz clic en Mostrar la opción de rango de IP asignado.

    2. En la lista Rango de IP asignado, selecciona un rango de direcciones IP.

    Para obtener más información sobre esta opción, consulta Crea un clúster con un rango de direcciones IP específico.

  12. Opcional: Para encriptar este clúster con una clave de encriptación administrada por el cliente (CMEK) en lugar de la encriptación administrada por Google, sigue estos pasos adicionales:

    1. Haz clic en Opciones de encriptación avanzada.

    2. Selecciona Clave de encriptación administrada por el cliente (CMEK).

    3. En el menú que aparece, selecciona una clave administrada por el cliente.

      La consola de Google Cloud limita esta lista a las claves que se encuentran en el mismo proyecto y la misma región de Google Cloud que el clúster nuevo. Para usar una clave que no está en esta lista, haz clic en ¿No ves tu clave? Escribe el nombre del recurso de la clave y, luego, el nombre del recurso de la clave en el cuadro de diálogo que aparece.

      Ten en cuenta que el uso de CMEK con AlloyDB requiere una configuración adicional. Para obtener más información, consulta Usa CMEK con AlloyDB.

    4. Haz clic en Continuar.

  13. Configura tu instancia principal:

    1. En el campo ID de instancia, ingresa un ID para tu instancia principal.
    2. Selecciona una de las siguientes series de máquinas:

      • C4A (serie de máquinas basadas en Google Axion)
      • N2 (serie de máquinas basadas en x86) Esta es la serie de máquinas predeterminada.
      • C4 (serie de máquinas basadas en x86)
      • Z3 (serie de máquinas basadas en Intel Xeon)
    3. Selecciona un tipo de máquina. Para obtener más información, consulta Elige un tipo de máquina.

      • C4A admite 1, 2, 4, 8, 16, 32, 48, 64 y 72 CPUs virtuales.
      • N2 admite 2, 4, 8, 16, 32, 64, 96 y 128 CPUs virtuales.
      • C4 admite 4, 8, 16, 24, 32, 48, 96, 144, 192 y 288 CPUs virtuales.
      • Z3 admite 8, 14, 16, 22, 32, 44 y 88 CPUs virtuales.

      Para obtener más información sobre el uso de la serie de máquinas C4A basadas en Axion, incluido el tipo de máquina con 1 CPU virtual, consulta Consideraciones cuando se usa la serie de máquinas C4A basadas en Axion.

    4. Opcional: Configura marcas personalizadas para tu instancia. Para cada parámetro, sigue estos pasos:

      1. Haz clic en Agregar marca.
      2. En la lista Nueva marca de base de datos, selecciona una marca.
      3. Proporciona un valor para la marca.
      4. Haz clic en Listo.
  14. Haga clic en Crear clúster.

gcloud

Para usar gcloud CLI, puedes instalar e inicializar Google Cloud CLI, o bien puedes usar Cloud Shell.

Debes crear un clúster de AlloyDB y una instancia principal antes de comenzar a usar AlloyDB.

Crea un clúster

  1. Para crear el clúster con el acceso privado a servicios o Private Service Connect habilitado, usa el comando gcloud alloydb clusters create.

    Acceso privado a servicios

    gcloud alloydb clusters create CLUSTER_ID \
        --database-version=POSTGRES_VERSION \
        --password=PASSWORD \
        --region=REGION_ID \
        --project=PROJECT_ID \
        --network=NETWORK

    Private Service Connect

    gcloud alloydb clusters create CLUSTER_ID \
        --database-version=POSTGRES_VERSION \
        --password=PASSWORD \
        --region=REGION_ID \
        --project=PROJECT_ID \
        --enable-private-service-connect

    Reemplaza lo siguiente:

    • CLUSTER_ID: Es el ID del clúster que estás creando. Debe comenzar con una letra minúscula y puede contener letras minúsculas, números y guiones.

    • VERSION: Es la versión principal de PostgreSQL con la que deseas que sean compatibles los servidores de bases de datos del clúster. Elige una de estas opciones:

      • 14, para compatibilidad con PostgreSQL 14

      • 15, para compatibilidad con PostgreSQL 15

      • 16, para compatibilidad con PostgreSQL 16

      • 17, para que sea compatible con PostgreSQL 17, que es la versión predeterminada de PostgreSQL admitida

      • 18, para compatibilidad con PostgreSQL 18

    • PASSWORD: Es la contraseña que se usará para el usuario postgres predeterminado.

    • NETWORK (opcional): Es el nombre de la red de VPC que configuraste para el acceso privado a servicios a AlloyDB. Si omites la marca --network, AlloyDB usa la red default.

      Si usas una red de VPC compartida, configúrala en la ruta de acceso completamente calificada de la red de VPC, por ejemplo, projects/cymbal-project/global/networks/shared-vpc-network.

    • --enable-private-service-connect (opcional): Se configura para habilitar Private Service Connect como el método de conectividad para el clúster y sus instancias.

    • REGION_ID: Es la región en la que deseas que se coloque el clúster.

    • PROJECT_ID: Es el ID del proyecto en el que deseas colocar el clúster.

    Este comando inicia una operación de larga duración y, luego, muestra un ID de operación.

  2. Opcional: Para aplicar un rango de direcciones IP específico a este clúster, en lugar de permitir que AlloyDB elija un rango de direcciones IP, proporciona el siguiente argumento:

    --allocated-ip-range-name=RANGE
    

    Reemplaza RANGE por el nombre del rango de direcciones IP que deseas que este clúster use para el acceso privado a servicios.

    Para obtener más información sobre esta opción, consulta Crea un clúster con un rango de direcciones IP específico.

  3. Opcional: Para encriptar este clúster con una clave de encriptación administrada por el cliente (CMEK) en lugar de la encriptación predeterminada administrada por Google, proporciona los siguientes argumentos:

    --kms-key=KEY_ID \
    --kms-keyring=KEYRING_ID \
    --kms-location=LOCATION_ID \
    --kms-project=PROJECT_ID
    

    Reemplaza lo siguiente:

    • KEY_ID: Es el ID de la clave de CMEK que se usará.

    • KEYRING_ID: Es el ID del llavero de claves de la clave.

    • LOCATION_ID: Es el ID de la región del llavero de claves, que debe ser la misma que la región del clúster.

    • PROJECT_ID: Es el ID del proyecto del llavero de claves.

  4. Confirma que la operación se haya realizado correctamente.

    gcloud alloydb operations describe OPERATION_ID \
        --region=REGION_ID \
        --project=PROJECT_ID

    Reemplaza OPERATION_ID por el ID de la operación que se devolvió en el paso anterior.

Después de crear el clúster principal, debes crear una instancia principal.

Crea una instancia principal

Para crear una instancia principal, usa el comando gcloud alloydb instances create.

    gcloud alloydb instances create INSTANCE_ID \
        --instance-type=PRIMARY \
        --region=REGION_ID \
        --cluster=CLUSTER_ID \
        --project=PROJECT_ID \
        --cpu-count=CPU_COUNT \
        --machine-type=MACHINE_TYPE \
        --allowed-psc-projects=ALLOWED_PROJECT_LIST

Reemplaza lo siguiente:

  • INSTANCE_ID: Es el ID de la instancia que estás creando. Debe comenzar con una letra minúscula y puede contener letras minúsculas, números y guiones.

  • REGION_ID: la región en la que deseas que se ubique la instancia.

  • CLUSTER_ID: Es el ID del clúster que creaste antes.

  • PROJECT_ID: Es el ID del proyecto en el que se creó el clúster.

  • CPU_COUNT: Es la cantidad de CPUs virtuales que deseas para la instancia.

    • Debes especificar cpu_count o machine_type.
    • Si solo se proporciona cpu_count, se crea una instancia N2 con las siguientes especificaciones:

      • 2: 2 CPU virtuales, 16 GB de RAM
      • 4: 4 CPU virtuales, 32 GB de RAM
      • 8: 8 CPU virtuales, 64 GB de RAM
      • 16: 16 CPU virtuales, 128 GB de RAM
      • 32: 32 CPU virtuales, 256 GB de RAM
      • 64: 64 CPUs virtuales, 512 GB de RAM
      • 96: 96 CPUs virtuales, 768 GB de RAM
      • 128: 128 CPU virtuales, 864 GB de RAM
    • Si se proporcionan machine_type y cpu_count, el valor de cpu_count debe alinearse con la cantidad de CPU virtuales especificadas en machine_type. Por ejemplo, si machine_type es n2-highmem-4, debes establecer cpu_count en 4.

  • MACHINE_TYPE: Selecciona de una lista de tipos de máquinas compatibles, como n2-highmem-4, c4-highmem-4-lssd o c4a-highmem-4-lssd. Para obtener más información, consulta Elige un tipo de máquina de AlloyDB.

    Cuando usas machine_type y cpu_count juntos, los valores de cpu_count y machine_type deben coincidir. Por ejemplo, si machine_type es n2-highmem-4, debes establecer cpu_count en 4.

  • ALLOWED_PROJECT_LIST: (Opcional) Si usas Private Service Connect, ALLOWED_PROJECT_LIST es la lista separada por comas de los IDs de proyecto o el número de proyecto al que deseas permitir el acceso a la instancia.

Terraform

Crea un clúster y una instancia principal

Para crear un clúster y su instancia principal, usa un recurso de Terraform.

A continuación, se muestra un fragmento de código para crear un clúster y una instancia principal según el ejemplo de instancia completa de AlloyDB:

resource "google_alloydb_instance" "default" {
  cluster       = google_alloydb_cluster.default.name
  instance_id   = "alloydb-instance"
  instance_type = "PRIMARY"
  machine_config {
    cpu_count = 2
  }
  depends_on = [google_service_networking_connection.vpc_connection]
}

resource "google_alloydb_cluster" "default" {
  cluster_id       = "alloydb-cluster"
  location         = "us-central1"
  network_config {
    network = google_compute_network.default.id
  }
  database_version = "POSTGRES_17"
  initial_user {
    password = "alloydb-cluster"
  }
}

data "google_project" "project" {}

resource "google_compute_network" "default" {
  name = "alloydb-network"
}

resource "google_compute_global_address" "private_ip_alloc" {
  name          = "alloydb-cluster"
  address_type  = "INTERNAL"
  purpose       = "VPC_PEERING"
  prefix_length = 16
  network       = google_compute_network.default.id
}

resource "google_service_networking_connection" "vpc_connection" {
  network                 = google_compute_network.default.id
  service                 = "servicenetworking.googleapis.com"
  reserved_peering_ranges = [google_compute_global_address.private_ip_alloc.name]
}

En este ejemplo, se crea una instancia N2. Para obtener una lista de otros tipos de máquinas compatibles, como n2-highmem-4, c4-highmem-4-lssd o c4a-highmem-4-lssd, consulta Elige un tipo de máquina de AlloyDB.

Prepara Cloud Shell

Para aplicar tu configuración de Terraform en un proyecto de Google Cloud , prepara Cloud Shell de la siguiente manera:

  1. Inicia Cloud Shell
  2. Establece el proyecto de Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.

    Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Las variables de entorno se anulan si configuras valores explícitos en el archivo de configuración de Terraform.

Prepara el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio, también llamado módulo raíz.

  1. En Cloud Shell, crea un directorio y un archivo nuevo dentro de ese directorio. El nombre del archivo debe ser un archivo TF, por ejemplo, main.tf. En este documento, el archivo se denomina main.tf.
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf
  2. Copia el código de muestra en el main.tf recién creado. De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.
  3. Revisa el archivo main.tf y modifica los parámetros de muestra que se aplicarán a tu entorno.
  4. Guarda los cambios.
  5. Inicializa Terraform. Solo debes hacerlo una vez por directorio.
    terraform init
    De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google:
    terraform init -upgrade

Aplique los cambios

  1. Revisa la configuración para confirmar que las actualizaciones de Terraform coincidan con tus expectativas:
    terraform plan
    Corrige la configuración según sea necesario.
  2. Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite:
    terraform apply
    Espera hasta que Terraform muestre el mensaje Apply complete!.
  3. Abre tu proyecto de Google Cloud para ver los resultados. En la consola de Google Cloud , navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.

REST v1

Crea un clúster

En este ejemplo, se crea un clúster. Para obtener una lista completa de los parámetros de esta llamada, consulta Método: projects.locations.clusters.create. Para obtener información sobre la configuración del clúster, consulta Visualiza la configuración del clúster y de la instancia.

No incluyas información sensible o de identificación personal en el ID del clúster, ya que es visible de forma externa. No debes incluir el ID del proyecto en el nombre del clúster. Esto se hace de manera automática cuando es apropiado (por ejemplo, en los archivos de registro).

Para enviar tu solicitud, guarda el cuerpo de la solicitud en un archivo llamado cluster_request.json:

{
  "databaseVersion": "<var>DATABASE_VERSION</var>",
  "initialUser": {
    "user": "<var>INITIAL_USERNAME</var>",
    "password": "<var>INITIAL_USER_PASSWORD</var>"
  },
  "labels": {
    "test": "alloydb-cluster-full"
  }
}

Realiza los siguientes reemplazos:

  • DATABASE_VERSION: Es la cadena de enumeración de la versión de la base de datos, por ejemplo, POSTGRES_17.
  • INITIAL_USERNAME: Es el nombre de usuario que usas para el usuario de postgres predeterminado.
  • INITIAL_USER_PASSWORD: Es la contraseña que usas para el usuario postgres predeterminado.

Usa el siguiente método HTTP y la siguiente URL:

POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters?cluster_id=CLUSTER_ID

Realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto en el que deseas que se ubique el clúster.
  • LOCATION_ID: Es el ID de la región del clúster.
  • CLUSTER_ID: Es el ID del clúster que creas. El ID del clúster debe comenzar con una letra minúscula y puede contener letras minúsculas, números y guiones.

Puedes usar el siguiente comando curl para ejecutar la solicitud anterior:

curl -X POST   -H "Authorization: Bearer $(gcloud auth print-access-token)"   -H "Content-Type: application/json"   https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters?cluster_id=CLUSTER_ID   -d @cluster_request.json

Crea una instancia principal

En este ejemplo, se crea una instancia principal. Para obtener una lista completa de los parámetros de esta llamada, consulta Método: projects.locations.clusters.instances.create. Para obtener información sobre la configuración del clúster, consulta Visualiza la configuración del clúster y de la instancia.

No incluyas información sensible o de identificación personal en el ID del clúster, ya que es visible de forma externa. No es necesario que incluyas el ID del proyecto en el nombre del clúster, ya que esto se hace de forma automática cuando es apropiado, por ejemplo, en los archivos de registro.

Para enviar tu solicitud, guarda el siguiente cuerpo de la solicitud en un archivo llamado instance_request.json.

{
  "instance_type": "PRIMARY",
  "machine_config": {
    "cpu_count": VCPU_COUNT
  }
}

Realiza el siguiente reemplazo:

  • VCPU_COUNT: Es la cantidad de núcleos de CPU visibles en la instancia que deseas crear.

En el ejemplo anterior, se crea una instancia N2 con las siguientes especificaciones:

  • 2: 2 CPU virtuales, 16 GB de RAM
  • 4: 4 CPU virtuales, 32 GB de RAM
  • 8: 8 CPU virtuales, 64 GB de RAM
  • 16: 16 CPU virtuales, 128 GB de RAM
  • 32: 32 CPU virtuales, 256 GB de RAM
  • 64: 64 CPUs virtuales, 512 GB de RAM
  • 96: 96 CPUs virtuales, 768 GB de RAM
  • 128: 128 CPU virtuales, 864 GB de RAM

En el siguiente ejemplo, se muestra cómo crear una instancia para un tipo de máquina:

"machine_config": {
  "machine_type": "MACHINE_TYPE"
}

Reemplaza MACHINE_TYPE por un tipo de máquina compatible, como n2-highmem-4, c4-highmem-4-lssd o c4a-highmem-4-lssd. Para obtener más información sobre los tipos de máquinas compatibles, consulta Elige un tipo de máquina de AlloyDB.

Usa el siguiente método HTTP y la URL:

POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID/instances?instance_id=INSTANCE_ID

Realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto en el que deseas que se ubique el clúster.
  • LOCATION_ID: Es el ID de la región del clúster.
  • CLUSTER_ID: Es el ID del clúster que creas. El ID debe comenzar con una letra minúscula y puede contener letras minúsculas, números y guiones.
  • INSTANCE_ID: Es el nombre de la instancia principal que deseas crear.

Puedes usar curl para ejecutar la solicitud, como se muestra en el siguiente ejemplo:

curl -X POST   -H "Authorization: Bearer $(gcloud auth print-access-token)"   -H "Content-Type: application/json"   https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID/instances?instance_id=INSTANCE_ID   -d @instance_request.json

Clona un clúster activo

Para crear una clonación de un clúster activo, que contenga una copia de todos los datos del clúster de origen y que se ejecute en la misma región, realiza una recuperación de un momento determinado en ese clúster. Cuando lo hagas, puedes especificar un momento muy reciente, por ejemplo, el primer segundo del minuto actual.

Este proceso copia solo los datos del clúster de origen en el clon, no la configuración del clúster de origen. Para encriptar los datos de la clonación con CMEK, debes especificar los detalles de CMEK como parte del comando de recuperación de un momento determinado, incluso si los datos del clúster de origen ya están encriptados con CMEK. Después de crear el clúster nuevo, debes agregar instancias, marcas de base de datos, programas de copia de seguridad y cualquier otra configuración necesaria para satisfacer tus necesidades.

Un clúster creado de esta manera existe de forma independiente de su fuente, y sus datos no tienen relación con los datos del clúster de origen después de que se completa la duplicación inicial. Si quieres crear clústeres secundarios que realicen un seguimiento y repliquen automáticamente los cambios de datos realizados en sus clústeres de origen, consulta Acerca de la replicación entre regiones.

Crea un clúster con un rango de direcciones IP específico

AlloyDB usa el acceso privado a servicios para permitir que los recursos internos de un clúster se comuniquen entre sí. Antes de crear un clúster, tu red de VPC debe contener al menos un rango de direcciones IP configurado con una conexión de acceso privado a servicios.

Consideraciones para usar la serie de máquinas C4A basadas en Axion

AlloyDB ofrece una serie de máquinas C4A basadas en Google Axion, el procesador personalizado basado en ARM de Google. Las máquinas virtuales (VM) C4A están disponibles como configuraciones predefinidas para 1, 2, 4, 8, 16, 32, 48, 64 y 72 CPUs virtuales, con hasta 576 GB de memoria de doble velocidad de datos 5 (DDR5).

Cuando elijas C4A, ten en cuenta lo siguiente:

  • Para cambiar una instancia N2 existente a una instancia C4A, modifica el machine_type de la instancia actual con la consola de Google Cloud , gcloud CLI, Terraform o la API.
  • No borres la instancia N2 ni crees una nueva instancia C4A en el mismo clúster.

C4A es compatible con las siguientes regiones:

  • asia-east1
  • asia-southeast1
  • europe-west1
  • europe-west2
  • europe-west3
  • europe-west4
  • us-central1
  • us-east1
  • us-east4

Consideraciones para usar el tipo de máquina con 1 CPU virtual

AlloyDB ofrece una forma de 1 CPU virtual con C4A y está destinada solo para fines de desarrollo y pruebas. Para las cargas de trabajo de producción, elige dos o más CPUs virtuales.

Cuando elijas 1 CPU virtual, ten en cuenta las siguientes limitaciones:

  • Se ofrece 1 CPU virtual con 8 GB de memoria sin compatibilidad con la caché ultrarrápida.
  • Se recomienda la configuración de 1 CPU virtual para entornos de desarrollo y de zona de pruebas con bases de datos más pequeñas de decenas de gigabytes. Para bases de datos más grandes y cargas de trabajo de producción, considera usar 2 CPU virtuales o más.
  • Puedes configurar con alta disponibilidad (HA), pero no se ofrecen ANS de tiempo de actividad.
  • Para saber dónde puedes implementar 1 CPU virtual, consulta Regiones admitidas por C4A.

¿Qué sigue?