Create a primary instance

This page describes how to create the primary instance in an AlloyDB cluster.

Before you begin

• The Google Cloud project you are using must have been enabled to access 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.

Create an AlloyDB primary instance

Console

1. Go to the Clusters page.

   Go to Clusters

2. Click a cluster in the Resource Name column.

3. In the Overview page, go to Instances in your cluster, and click Create primary instance.

4. Configure your primary instance:

   1. In the Instance ID field, enter an ID for your primary instance.

   2. Under Zonal availability, select one of the following options:

      1. To create a highly available production instance with automated failover, select Multiple zones (Highly available).

         Note: The Mexico, Montreal, and Osaka regions have three zones within one or two physical data centers. These regions are in the process of expanding to at least three physical data centers. For more information, see Cloud locations and Google Cloud Platform SLAs. To help improve the reliability of your workloads, consider a multi-regional deployment.

      2. To create a basic instance that does not need to be highly available, select Single zone.

   3. Select a machine type.

   4. Optional: To set custom flags for your instance, expand Advanced configuration options, then do the following 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.

   5. Optional: To configure SSL or connector requirements on the instance, expand Advanced configuration options, then do the following:

      1. By default, AlloyDB instances require all connections to use SSL encryption. To allow non-SSL connections, clear the Only allow SSL connections checkbox.
      2. To require that all database connections to the instance use the AlloyDB Auth Proxy or the secure connector libraries provided by Google, select Require connectors.

   6. Click Create instance.

gcloud

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

Use the gcloud alloydb instances create command to create a primary instance.

gcloud alloydb instances create INSTANCE_ID \
    --instance-type=PRIMARY \
    --cpu-count=CPU_COUNT \
    --availability-type=AVAILABILITY \
    --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
  • 96: 96 vCPUs, 768 GB RAM
  • 128: 128 vCPUs, 864 GB RAM

• AVAILABILITY: Whether or not this instance should be highly available (HA), with nodes in multiple zones. Valid values include:

  • REGIONAL: Creates an HA instance with separate active and standby nodes, and automated failover between them. This is the default value, suitable for production environments.

  • ZONAL: Creates a basic instance, containing only one node, and no automated failover.

    Note: The Mexico, Montreal, and Osaka regions have three zones within one or two physical data centers. These regions are in the process of expanding to at least three physical data centers. For more information, see Cloud locations and Google Cloud Platform SLAs. To help improve the reliability of your workloads, consider a multi-regional deployment.

• REGION_ID: The region where you want the instance placed. For example, us-central1.

• CLUSTER_ID: The ID of the cluster where you want the instance placed.

• PROJECT_ID: The ID of the project where the cluster is placed.

By default, new instances require all connections to use SSL encryption. To allow non-SSL connections to the instance, add the --ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED flag to the command:

gcloud alloydb instances create INSTANCE_ID \
  --instance-type=PRIMARY \
  --cpu-count=CPU_COUNT \
  --region=REGION_ID \
  --cluster=CLUSTER_ID \
  --project=PROJECT_ID \
  --ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED

To enforce a secure connection between the client and an AlloyDB instance through the Auth Proxy or other applications that use Google-provided connector libraries, add the --require-connectors flag to the command:

gcloud alloydb instances create INSTANCE_ID \
  --instance-type=PRIMARY \
  --cpu-count=CPU_COUNT \
  --region=REGION_ID \
  --cluster=CLUSTER_ID \
  --project=PROJECT_ID \
  --require-connectors

To create a primary instance for a Private Service Connect-enabled cluster, add the --allowed-psc-projects flag to set a comma separated list of project IDs or project numbers that you want to allow access to the instance—for example, my-project-1, 12345,my-project-n.

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:

• ALLOWED_PROJECT_LIST (Optional): The comma separated list of project IDs or project numbers that you want to allow access to the instance—for example,my-project-1, 12345,my-project-n. You must set a list of allowed projects or numbers, if your cluster is using Private Service Connect as the method of connecting to the instance.

Terraform

To create an instance within your database cluster, use a Terraform resource.

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
  }

  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]
}

Prepare Cloud Shell

To apply your Terraform configuration in a Google Cloud project, prepare Cloud Shell as follows:

1. Launch Cloud Shell.

2. Set the default Google Cloud projectwhere you want to apply your Terraform configurations.

   You only need to run this command once per project, and you can run it in any directory.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory, also called a root module.

1. In Cloud Shell, create a directory and a new file within that directory. The filename must be a TF file—for example, main.tf. In this document, the file is referred to as main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Copy the sample code into the newly created main.tf. Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

   git clone https://github.com/terraform-google-modules/terraform-docs-samples

3. In the terraform-docs-samples directory, navigate to the alloydb directory.

   cd terraform-docs-samples/alloydb

4. Copy the sample code into the newly created main.tf.

   cp SAMPLE_FILE

   Replace <var>SAMPLE_FILE</var> with the name of the sample file to copy—for example, main.tf.
5. Review and modify the sample parameters to apply to your environment.
6. Save your changes.
7. Initialize Terraform. You only need to do this once per directory.

   terraform init

   Optional: To use the latest Google provider version, include the -upgradeoption:

   terraform init -upgrade

Apply the changes

Note: Terraform samples typically assume that the required APIs are enabled in your Google Cloud project.

1. Review the configuration to confirm that the Terraform updates match your expectations:

   terraform plan

   Make corrections to the configuration as necessary.
2. Apply the Terraform configuration by running the following command and entering yes at the prompt:

   terraform apply

   Wait until Terraform displays the Apply complete! message.

Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.

What's next

• Create a read pool instance

• Reduce costs using basic instances

• Learn about sizing recommendations