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

Create a new cluster

Console

1. Go to the Clusters page.

   Go to Clusters

2. Click Create cluster.

3. Choose a cluster configuration. For more information about the difference between highly available and basic configurations, see Nodes and instances.

   If you're not sure whether your new cluster needs read pool instances, choose one of the configurations with no read pools. You can add read pool instances to the cluster later, whenever needed.

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 an initial password for the new cluster. AlloyDB assigns the provided password to the postgres database user while creating the cluster.

7. In the Database version field, select the major version of PostgreSQL that you want the cluster's database servers to be compatible with.

8. Select a region.

9. Select a network path.

10. Optional: To apply a specific IP address range to this cluster, instead of allowing AlloyDB to choose an IP address range, follow these steps:

    1. Click Show allocated IP range option.

    2. From the Allocated IP range list, select an IP address range.

    For more information about this option, see Create a cluster with a specific IP address range.

11. Optional: 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. 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.

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

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

14. 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 \
       --database-version=POSTGRES_VERSION \
       --password=PASSWORD \
       --network=NETWORK \
       --region=REGION_ID \
       --project=PROJECT_ID
   

   Replace the following:

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

   • VERSION: the major version of PostgreSQL that you want the cluster's database servers to be compatible with. Choose one of the following:

     • 14, for compatibility with PostgreSQL 14

     • 15, for compatibility with PostgreSQL 15, which is the default PostgreSQL version supported

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

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

2. Optional: To apply a specific IP address range to this cluster, instead of allowing AlloyDB to choose an IP address range, provide the following argument:

   --allocated-ip-range-name=RANGE
   

   Replace RANGE with the name of the IP address range that you want this cluster to use for private services access.

   For more information about this option, see Create a cluster with a specific IP address range.

3. Optional: To encrypt this cluster using a customer-managed encryption key (CMEK) instead of the default Google-managed encryption, provide the following arguments:

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

   Replace the following:

   • KEY_ID: the ID of the CMEK key to use.

   • KEYRING_ID: the ID of the key's key ring.

   • LOCATION_ID: the ID of the key ring's region, which must be the same as the cluster's region.

   • PROJECT_ID: the ID of the key ring's project.

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

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

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

   Replace the following:

   • 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
     • 96: 96 vCPUs, 768 GB RAM
     • 128: 128 vCPUs, 864 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 an active 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.

Create a cluster with a specific IP address range

AlloyDB uses private services access to allow a cluster's internal resources to communicate with each other. Before you can create a cluster, your VPC network must contain at least one IP address range configured with a private services access connection.

If your VPC network contains more than one IP address range that has been configured with private services access, then you have the option to specify the range that AlloyDB assigns to a new cluster.

To specify an IP address range, see the optional steps in Create a cluster.

If you do not specify a range, then AlloyDB takes one of the following actions while creating a cluster:

• If you have multiple IP address ranges with private services access available, then AlloyDB chooses one of those ranges.

• If you have set up exactly one IP address range in your VPC with private services access, then AlloyDB applies that range to the new cluster.

For more information about creating IP address ranges for use with AlloyDB, see Enable private services access.

What's next

• Create a read pool instance.

• Connect a psql client to an instance.

• Create a database.

• Upgrade a cluster's major server version.