Create a cluster and its primary instance

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.

          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 with either private service access or Private Service Connect enabled, use the gcloud alloydb clusters create command.

   Private services access

   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 

   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

     • 16, for compatibility with PostgreSQL 16

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

   • --enable-private-service-connect (Optional): set to enable Private Service Connect as the connectivity method for the cluster and its instances.

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

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.

After creating the primary cluster, you must create a primary instance.

Create a primary instance

To create a 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 \
        --allowed-psc-projects=ALLOWED_PROJECT_LIST

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
• ALLOWED_PROJECT_LIST (Optional): the comma separated list of project IDs or project number that you want to allow access the instance, if using Private Service Connect.