Create a cluster and its primary instance

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

Before you begin

• The Google Cloud project you are using must have been enabled to access AlloyDB.
• A VPC network in the Google 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 Google 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 Google 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

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. In the Configure your cluster section, in the Cluster ID field, enter an ID for your cluster.

6. In the Password field, enter a password for the postgres user.

7. Select a region.

8. Select a network path.

9. If you want to encrypt this cluster using a customer-managed encryption key (CMEK) instead of Google-managed encryption, then follow these additional steps:

   1. Click Advanced encryption options.

   2. Select Customer-managed encryption key (CMEK).

   3. In the menu that appears, select a customer-managed key.

      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.

10. 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, follow these steps:
       1. Click Add flag.
       2. In the New database flag list, select a flag.
       3. Provide a value for the flag.
       4. Click Done.

11. If you chose a cluster type without read pools, click Create cluster. Otherwise, continue to the next step.

12. If you chose a cluster type with read pools, complete the following steps:

    1. Click Continue to add one or more read pool instances.

    2. 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.

          Note: You can have a maximum of 10 nodes across all the read pool instances in a cluster.

          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.

    3. 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. To create the cluster, use the gcloud alloydb clusters create command.

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

   • CLUSTER_ID: The ID of the cluster that 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 that you 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 want 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.
   Note: Using CMEK requires some additional setup. For more information, see Using CMEK with AlloyDB.

   This command initiates a long-running operation, returning an operation ID.

2. Confirm that the operation was successful.

   gcloud 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.

3. To create the primary instance, use the gcloud alloydb instances create command.

   gcloud 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 the following:
     • 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.

Clone a cluster

To create a clone of an active cluster, containing a copy of all the source cluster's data and running in the same region, perform a point-in-time recovery on that cluster. You can specify a very recent point in time when doing so—for example, the first second of the current minute.

This process copies only the source cluster's data into the clone—not any of the source cluster's configuration. To encrypt the clone's data using CMEK, you need to specify CMEK details as part of the point-in-time recovery command, even if the source cluster's data is already CMEK-encrypted. After the new cluster is created, you need to add instances, database flags, backup schedules, and any other configuration necessary to suit your needs.

A cluster created this way exists independently of its source, with its data having no relationship to the source cluster's data after the initial duplication has completed. If you want to create secondary clusters that automatically track and replicate data changes made in their source clusters, see About cross-region replication.

Note: You cannot clone secondary clusters, because they they do not support point-in-time recovery.