Create a cluster and its primary instance

Stay organized with collections Save and categorize content based on your preferences.

This page describes how to create an AlloyDB cluster and its primary instance.

Prerequisites

  • The Cloud project you are using must have been enabled to access AlloyDB.
  • A VPC network in the Cloud project you are using must already be configured for private services access to AlloyDB.
  • You must have one of these IAM roles in the Cloud project you are using:
    • roles/alloydb.admin (the AlloyDB Admin predefined IAM role)
    • roles/owner (the Owner basic IAM role)
    • roles/editor (the Editor basic IAM role)

    If you don't have any of these roles, contact your Organization Administrator to request access.

  • You must also have the compute.networks.list permission in the Cloud project you are using. To gain this permission while following the principle of least privilege, ask your administrator to grant you the roles/compute.networkUser (Compute Network User) role.

Procedure

When you use the Google Cloud console to create a cluster, you can create its primary instance and read pool instances.

When you use gcloud to create a cluster, each step is a separate gcloud CLI command.

Console

  1. In the Google Cloud console, go to the Clusters page.

    Go to Clusters

  2. Click Create cluster.
  3. Select a cluster type.
  4. Click Continue.
  5. Configure your cluster:
    1. In the Cluster ID field, enter an ID for your cluster.
    2. In the Password field, enter a password for the postgres user.
    3. Select a region.
    4. Select a network path.
    5. If you wish to encrypt this cluster using a customer-managed encryption key (CMEK) instead of Google-managed encryption, follow these additional steps:

      1. Click Advanced encryption options.
      2. Select Customer-managed encryption key (CMEK).
      3. Select a customer-managed key from the menu that appears.

        The Google Cloud console limits this list to keys within the same Google Cloud project and region as the new cluster. To use a key that is not on this list, click Don't see your key? Enter key resource name, and then type the key's resource name into the resulting dialog.

        Note that using CMEK with AlloyDB requires some additional setup. For more information, see Using CMEK with AlloyDB.

      4. Click Continue.
    6. Configure your primary instance:
      1. In the Instance ID field, enter an ID for your primary instance.
      2. Select a machine type.
      3. Optional: Set custom flags for your instance. For each flag:
        1. Click Add flag.
        2. Select a flag from the New database flag list.
        3. Provide a value for the flag.
        4. Click Done.
    7. If you chose a cluster type without read pools, click Create cluster. If you chose a cluster type with read pools, click Continue to add one ore more read pool instances.
    8. To add a read pool instance:
      1. Click Add read pool.
      2. In the Read pool instance ID field, enter an ID for the read pool instance.
      3. In the Node count field, enter a node count.

        The number of nodes in a read pool instance determines the instance's overall computing capacity.

      4. Select a machine type.
      5. Optional: Set custom flags to your instance. For each flag:
        1. Click Add flag.
        2. Select a flag from the New database flag list.
        3. Provide a value for the flag.
        4. Click Done.
      6. Click Add read pool.
    9. Click Create cluster.

gcloud

To use the gcloud CLI, you can install and initialize the Google Cloud CLI, or you can use Cloud Shell.

  1. Use the gcloud beta alloydb clusters create command to create the cluster.

    gcloud beta alloydb clusters create CLUSTER_ID \
        --password=PASSWORD \
        --network=NETWORK \
        --region=REGION_ID \
        --project=PROJECT_ID
    • CLUSTER_ID: The ID of the cluster you are creating. It must begin with a lowercase letter and can contain lowercase letters, numbers, and hyphens.
    • PASSWORD: The password to use for the default postgres user.
    • NETWORK (Optional): The name of the VPC network configured for private services access to AlloyDB. If you omit the --network flag, AlloyDB uses the default network.
    • REGION_ID: The region where you want the cluster placed.
    • PROJECT_ID: The ID of the project where you want the cluster placed.

    If you wish to encrypt this cluster using a customer-managed encryption key (CMEK) instead of the default Google-managed encryption, then you must provide these additional arguments:

    • --kms-key=KEY_ID: The ID of the CMEK key to use.
    • --kms-keyring=KEYRING_ID: The ID of the key's keyring.
    • --kms-location=LOCATION_ID: The ID of that keyring's region. Note that it must match the cluster's region.
    • --kms-project=PROJECT_ID: The keyring's project ID.
  2. This command initiates a long-running operation, returning an operation ID.

  3. Confirm that the operation was successful.

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

    Replace OPERATION_ID with the operation ID that was returned from the previous step.

  4. Use the instances create command to create the primary instance.

    gcloud beta alloydb instances create INSTANCE_ID \
        --instance-type=PRIMARY \
        --cpu-count=CPU_COUNT \
        --region=REGION_ID \
        --cluster=CLUSTER_ID \
        --project=PROJECT_ID
    • INSTANCE_ID: The ID of the instance you are creating. It must begin with a lowercase letter and can contain lowercase letters, numbers, and hyphens.
    • CPU_COUNT: The number of vCPUs you want for the instance. Valid values include:
      • 2 (2 vCPUs, 16 GB RAM)
      • 4 (4 vCPUs, 32 GB RAM)
      • 8 (8 vCPUs, 64 GB RAM)
      • 16 (16 vCPUs, 128 GB RAM)
      • 32 (32 vCPUs, 256 GB RAM)
      • 64 (64 vCPUs, 512 GB RAM)
    • REGION_ID: The region where you want the instance placed.
    • CLUSTER_ID: The ID of the cluster you created earlier.
    • PROJECT_ID: The ID of the project where the cluster is placed.