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
Go to the Clusters page.
Click a cluster in the Resource Name column.
In the Overview page, go to Instances in your cluster, and click Create primary instance.
Configure your primary instance:
- In the Instance ID field, enter an ID for your primary instance.
- Under Zonal availability, select one of the following options:
- To create a highly available production instance with automated failover, select Multiple zones (Highly available).
- To create a basic instance that does not need to be highly available, select Single zone.
Select one of the following machine series:
- C4A (Google Axion-based machine series)
- N2 (x86-based machine series). This is the default machine series.
Select a machine type.
- C4A supports 1, 4, 8, 16, 32, 48, 64, and 72 machine types or shapes.
- N2 supports 2, 4, 8, 16, 32, 64, 96, and 128 machine types or shapes.
For more information about using the C4A Axion-based machine series, including the 1 vCPU machine type, see Considerations when using the C4A Axion-based machine series.
Optional: To connect your applications and clients over the public internet, check the box Enable Public IP under Public IP Connectivity. Enabling public IP might require additional configuration to make sure that you have a secure connection. For more information, see Connect using public IP.
By default, private IP is always enabled. For more information, see Enable private services access.
Optional: To enable and use managed connection pooling, check the box Enable managed connection pool under Managed connection pool. For more information, see Configure managed connection pooling.
Optional: To set custom flags for your instance, expand Advanced configuration options, then do the following for each flag:
- Click Add flag.
- Select a flag from the New database flag list.
- Provide a value for the flag.
- Click Done.
Optional: To configure SSL or connector requirements on the instance, expand Advanced configuration options, then do the following:
- By default, AlloyDB instances require all connections to use SSL encryption. To allow non-SSL connections, clear the Only allow SSL connections checkbox.
- 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.
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 \
--availability-type=AVAILABILITY \
--region=REGION_ID \
--cluster=CLUSTER_ID \
--cpu-count=CPU_COUNT \
--machine-type=MACHINE_TYPE \
--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.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.
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.CPU_COUNT
: the number of vCPUs that you want for the instance.- You must specify either
cpu_count
ormachine_type
. - If only
cpu_count
is provided, an N2 instance is created with the following specifications:- 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
- If both
machine_type
andcpu_count
are provided, thecpu_count
value must align with the number of vCPUs specified in themachine_type
. For example, ifmachine_type
isn2-highmem-4
, then you must setcpu_count
to4
.
- You must specify either
MACHINE_TYPE
: the machine type of the instance.For the C4A Axion-based machine series, the following are valid values:
c4a-highmem-1
c4a-highmem-4-lssd
c4a-highmem-8-lssd
c4a-highmem-16-lssd
c4a-highmem-32-lssd
c4a-highmem-48-lssd
c4a-highmem-64-lssd
c4a-highmem-72-lssd
For N2 machine series, the following are valid values:
n2-highmem-2
n2-highmem-4
n2-highmem-8
n2-highmem-16
n2-highmem-32
n2-highmem-64
n2-highmem-96
n2-highmem-128
When you use
machine_type
andcpu_count
together, the values incpu_count
andmachine_type
must match. For example, ifmachine_type
isn2-highmem-4
, then you must setcpu_count
to4
.
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 \
--region=REGION_ID \
--cluster=CLUSTER_ID \
--project=PROJECT_ID \
--cpu-count=CPU_COUNT \
--machine-type=MACHINE_TYPE \
--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 \
--region=REGION_ID \
--cluster=CLUSTER_ID \
--cpu-count=CPU_COUNT \
--machine-type=MACHINE_TYPE \
--project=PROJECT_ID \
--require-connectors
To enable managed connection pooling in your AlloyDB
instance, add the --enable-connection-pooling
flag to the
gcloud alloydb instances create
command:
gcloud alloydb instances create INSTANCE_ID \
--instance-type=PRIMARY \
--region=REGION_ID \
--cluster=CLUSTER_ID \
--cpu-count=CPU_COUNT \
--machine-type=MACHINE_TYPE \
--project=PROJECT_ID \
--enable-connection-pooling
You can also create an AlloyDB instance with Private Service Connect-enabled. For information about creating a primary instance for a Private Service Connect-enabled cluster, see Create an AlloyDB instance.
Terraform
Create an instance
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] }
An N2 instance is created in the preceding example. To create a C4A instance,
use the machine_type
field within the machine_config
structure, shown
in the following example:
machine_config { machine_type = "c4a-highmem-4-lssd" }
Prepare Cloud Shell
To apply your Terraform configuration in a Google Cloud project, prepare Cloud Shell as follows:
- Launch Cloud Shell.
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.
- 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 asmain.tf
.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
- 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
- In the
terraform-docs-samples
directory, navigate to thealloydb
directory.cd terraform-docs-samples/alloydb
- Copy the sample code into the newly created
main.tf
. Replacecp SAMPLE_FILE
<var>SAMPLE_FILE</var>
with the name of the sample file to copy—for example,main.tf
. - Review and modify the sample parameters to apply to your environment.
- Save your changes.
- Initialize Terraform. You only need to do this once per directory.
Optional: To use the latest Google provider version, include theterraform init
-upgrade
option:terraform init -upgrade
Apply the changes
- Review the configuration to confirm that the Terraform updates match your expectations:
Make corrections to the configuration as necessary.terraform plan
- Apply the Terraform configuration by running the following command and entering
yes
at the prompt: Wait until Terraform displays theterraform apply
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.
REST v1
Create an instance
This example creates a primary instance. For a complete list of parameters for this call, see Method: projects.locations.clusters.instances.create. For information about cluster settings, see View cluster and instance settings.
Don't include sensitive or personally identifiable information in your cluster ID, because it's externally visible. You don't need to include the project ID in the cluster name because this is done automatically where appropriate—for example, in the log files.
To send your request, save the request body in a file named instance_request.json
.
{ "instance_type": "PRIMARY", "machine_config": { "cpu_count": "vCPU_COUNT", }, }
Make the following replacement:
CPU_COUNT
: the number of visible CPU cores on the instance that you want to create.
The preceding example creates an N2 instance with the following specifications:
- 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
To create a C4A instance, use the machine_type
field instead of cpu_count
in the machine_config
structure, as shown in the following example:
machine_config: { machine_type : MACHINE_TYPE, },
For the C4A Axion-based machine series, use the following are valid values:
c4a-highmem-1
c4a-highmem-4-lssd
c4a-highmem-8-lssd
c4a-highmem-16-lssd
c4a-highmem-32-lssd
c4a-highmem-48-lssd
c4a-highmem-64-lssd
c4a-highmem-72-lssd
For the N2 machine series, use the following are valid values:
n2-highmem-2
n2-highmem-4
n2-highmem-8
n2-highmem-16
n2-highmem-32
n2-highmem-64
n2-highmem-96
n2-highmem-128
Use the following HTTP method and URL:
POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID/instances?instance_id=INSTANCE_ID
Make the following replacements:
PROJECT_ID
: the ID of the project where you want the cluster located.LOCATION_ID
: the ID of the cluster's region.CLUSTER_ID
: the ID of the cluster that you create. The ID must begin with a lowercase letter and can contain lowercase letters, numbers, and hyphens.INSTANCE_ID
: the name of the primary instance that you want to create.
You can use curl to execute the request, as shown in the following example:
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://alloydb.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID/instances?instance_id=INSTANCE_ID -d @instance_request.json