Connect to an instance using Private Service Connect

Console

1. In the Google Cloud console, go to the Private Service Connect page.

   Go to Private Service Connect

2. Click the Connection Policies tab.

3. Click Create connection policy.

4. Enter a Name for the connection policy.

5. Specify the service class by doing the following:

   1. For Source service class, select Google services.
   2. From the Service class menu, select google-cloud-alloydb because AlloyDB is the managed service for the connection policy.

6. In the Target endpoints scope section, select a Network and Region this policy applies to.

7. In the Policy section, select one or more subnets from the Subnetworks menu. The subnets are used to allocate IP addresses for endpoints.

8. Optional: Specify a Connection limit for the policy. The limit determines how many endpoints AlloyDB can create for this connection policy. If you don't specify a connection limit, then there's no limit.

9. Click Create policy.

gcloud

To create a service connection policy, use the service-connection-policies create command.

gcloud network-connectivity service-connection-policies create POLICY_NAME \
    --network=NETWORK \
    --project=PROJECT_ID \
    --region=REGION \
    --service-class=SERVICE_CLASS \
    --subnets=https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETS \
    --psc-connection-limit=LIMIT \
    --description="DESCRIPTION" \
    --producer-instance-location=PRODUCER_INSTANCE_LOCATION \
    --allowed-google-producers-resource-hierarchy-level=LIST_OF_NODES

Replace the following:

• POLICY_NAME: the name of your service connection policy.
• NETWORK: the network this policy applies to.
• PROJECT_ID: the project ID or number of the VPC network's project. For Shared VPC networks, you must deploy service connection policies in the host project because these policies aren't supported in service projects.
• REGION: the region this policy applies to. The same policy must exist for every region where you want to automate service connectivity.
• SERVICE_CLASS: the producer-supplied resource identifier of the service class. For AlloyDB, the service class is google-cloud-alloydb.
• SUBNETS: one or more regular consumer subnets that are used to allocate IP addresses for Private Service Connect endpoints. These IP addresses are allocated automatically and returned to the subnet's pool as managed service instances are created and deleted. The subnets must be in the same region as the service connection policy. If multiple connection policies share the same region, then you can reuse the same subnetwork in these policies. You can enter multiple subnets in a comma-separated list.
• LIMIT: the maximum number of endpoints that you can create with this policy. If you don't specify a limit, then there's no limit.
• DESCRIPTION: an optional description of the service connection policy.

• PRODUCER_INSTANCE_LOCATION: specifies whether the policy automates connections to AlloyDB instances. You can set this value one of the following:

  • none (default): the AlloyDB instance is in the same project as the service connection policy (or in the case of Shared VPC, in connected projects).
  • custom-resource-hierarchy-levels: requires that you set the Resource Manager location path for the projects that you want to automate connectivity for through the allowed-google-producers-resource-hierarchy-level parameter.

• LIST_OF_NODES: set this parameter if your producer instance location is set to custom-resource-hierarchy-levels. This parameter is a list of projects, folders, and organizations where the instances for which you want to automate connectivity reside. The list is in the form of projects/PROJECT_ID, folders/FOLDER_ID, or organizations/ORGANIZATION_ID.

For example, the following command creates a service connection policy for the
google-cloud-alloydb service class that allocates IP addresses from the managed-services subnet. A maximum of 10 Private Service Connect endpoints can be created with this policy. The endpoints must be created in projects that are in the same organization as the managed service instance. The AlloyDB instance is located in the myproject project.

gcloud network-connectivity service-connection-policies create alloydb-policy \
    --network=default \
    --project=my-project \
    --region=us-central1 \
    --service-class=google-cloud-alloydb \
    --subnets=managed-service-subnet \
    --psc-connection-limit=10 \
    --producer-instance-location=custom-resource-hierarchy-levels \
    --allowed-google-producers-resource-hierarchy-level=projects/myproject

Console

1. In the Google Cloud console, go to the Clusters page.

   Go to Clusters

2. Click Create cluster.

3. In Cluster ID, enter my-cluster.

4. Enter a password. Take note of this password because you use it in this quickstart.

5. Retain the default database version.

6. Select the us-central1 (Iowa) region.

7. Retain the default instance ID, my-cluster-primary.

8. In Zonal availability, retain Single zone as the selected option. While we don't recommend a single zone instance for production, you use a single zone in this quickstart to minimize costs. For more information, see Reduce costs using basic instances.

9. Select the 2 vCPU, 16 GB machine type.

10. Retain private IP connectivity.

    1. Select Private Service Connect (PSC).
    2. Click Add an endpoint.
    3. Select the project where you want to create the endpoint.
    4. Select the network.
    5. Click Check policy for service connection policy information.

11. Retain the default settings under Network security.

12. Don't make changes in Show advanced options.

13. Click Create cluster. It might take several minutes for AlloyDB to create the cluster and display it on the primary cluster Overview page.

gcloud

To create the cluster, use the gcloud alloydb clusters create command.

gcloud alloydb clusters create CLUSTER_ID \
  --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.

• PASSWORD: the password to use for the default postgres user.

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

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 \
    --availability-type=AVAILABILITY \
    --region=REGION_ID \
    --cluster=CLUSTER_ID \
    --project=PROJECT_ID \
    --allowed-psc-projects=ALLOWED_PROJECT_LIST \
    --psc-network-attachment-uri=NETWORK_ATTACHMENT_URI \
    --psc-auto-connections=network=CONSUMER_NETWORK,project=CONSUMER_PROJECT

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
• AVAILABILITY: indicates 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.
• CLUSTER_ID: the ID of the cluster you created earlier.
• ALLOWED_PROJECT_LIST: the comma-separated list of project IDs or project numbers that you want to allow access the instance—for example, my-project-1, 12345,my-project-n.
• NETWORK_ATTACHMENT_URI (Optional): the full resource name of the network attachment URI that you create for outbound connectivity. For example: projects/PROJECT_ID/regions/REGION_ID/networkAttachments/NETWORK_ATTACHMENT_ID.
• CONSUMER_NETWORK: the path to the VPC network where Private Service Connect endpoints need are to be created. For example: projects/my-host-project/global/networks/default. This option applies when you are creating endpoints automatically. Ensure that the service connection policy is created. You can create the policy before or after creating the instance.
• CONSUMER_PROJECT: the project where the Private Service Connect endpoint is created. If you're using a Shared VPC network, then this can be either the host project or the service project. Any projects that you specify in the auto-connection parameters are added to your allowed projects automatically. Optionally, for any projects where you want to create Private Service Connect endpoints manually, you can add these projects to your list of allowed projects.

A secondary cluster created for a Private Service Connect enabled primary cluster automatically inherits the Private Service Connect configuration. For more information, see Create a secondary cluster.

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
  }
  psc_instance_config {
  allowed_consumer_projects = ["123456789"]
  psc_interface_configs {
    network_attachment_resource = google_compute_network_attachment.default.id
  }
  }
}

resource "google_compute_network" "default" {
    name = "alloydb-network"
    auto_create_subnetworks = false
}

resource "google_compute_subnetwork" "default" {
    name = "alloydb-subnetwork"
    region = "us-central1"
    network = google_compute_network.default.id
    ip_cidr_range = "10.0.0.0/16"
}

resource "google_compute_network_attachment" "default" {
  name                  = "alloydb-network-attachment"
  region                = "us-central1"
  connection_preference = "ACCEPT_AUTOMATIC"
  subnetworks = [
    google_compute_subnetwork.default.self_link
  ]
}

data "google_project" "project" {}

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

Console

1. In the Google Cloud console, go to the Clusters page.

   Go to Clusters

2. Click Create cluster.

3. In Cluster ID, enter my-cluster.

4. Enter a password. Take note of this password because you use it in this quickstart.

5. Retain the default database version.

6. Select the us-central1 (Iowa) region.

7. Retain the default instance ID, my-cluster-primary.

8. In Zonal availability, retain Single zone as the selected option. While we don't recommend a single zone instance for production, you use a single zone in this quickstart to minimize costs. For more information, see Reduce costs using basic instances.

9. Select the 2 vCPU, 16 GB machine type.

10. Retain private IP connectivity.

    1. Select Private Service Connect(PSC).
    2. Click Add an endpoint.
    3. Select the project where you want to create the endpoint.
    4. Select the network.
    5. Click Check policy for service connection policy information.

11. Retain the default settings under Network security.

12. Don't make changes in Show advanced options.

13. Click Create cluster. It might take several minutes for AlloyDB to create the cluster and display it on the primary cluster Overview page.

gcloud

To create the cluster, use the gcloud alloydb clusters create command.

gcloud alloydb clusters create CLUSTER_ID \
  --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.

• PASSWORD: the password to use for the default postgres user.

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

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 \
    --availability-type=AVAILABILITY \
    --region=REGION_ID \
    --cluster=CLUSTER_ID \
    --project=PROJECT_ID \
    --allowed-psc-projects=ALLOWED_PROJECT_LIST \
    --psc-network-attachment-uri=NETWORK_ATTACHMENT_URI \

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
• AVAILABILITY: indicates 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.
• CLUSTER_ID: the ID of the cluster you created earlier.
• ALLOWED_PROJECT_LIST: the comma separated list of project IDs or project number that you want to allow access the instance—for example, my-project-1, 12345,my-project-n.
• NETWORK_ATTACHMENT_URI (Optional): the full resource name of the network attachment URI that you create for outbound connectivity. For example: projects/PROJECT_ID/regions/REGION_ID/networkAttachments/NETWORK_ATTACHMENT_ID.
• CONSUMER_NETWORK: the path to the VPC network from where Private Service Connect endpoints need to be created. For example: projects/my-host-project/global/networks/default. This option applies when you are creating endpoints automatically. Ensure that the service connection policy is created. You can create the policy before or after creating the instance.
• CONSUMER_PROJECT: the project where the Private Service Connect endpoint is created. If you're using a Shared VPC network, then this can be either the host project or the service project. Any projects that you specify in the auto-connection parameters are added to your allowed projects automatically. Optionally, for any projects where you want to create Private Service Connect endpoints manually, you can add these projects to your list of allowed projects.

A secondary cluster created for a Private Service Connect enabled primary cluster automatically inherits the Private Service Connect configuration. For more information, see Create a secondary cluster.

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
  }
  psc_instance_config {
  allowed_consumer_projects = ["123456789"]
  psc_interface_configs {
    network_attachment_resource = google_compute_network_attachment.default.id
  }
  }
}

resource "google_compute_network" "default" {
    name = "alloydb-network"
    auto_create_subnetworks = false
}

resource "google_compute_subnetwork" "default" {
    name = "alloydb-subnetwork"
    region = "us-central1"
    network = google_compute_network.default.id
    ip_cidr_range = "10.0.0.0/16"
}

resource "google_compute_network_attachment" "default" {
  name                  = "alloydb-network-attachment"
  region                = "us-central1"
  connection_preference = "ACCEPT_AUTOMATIC"
  subnetworks = [
    google_compute_subnetwork.default.self_link
  ]
}

data "google_project" "project" {}

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

Java

If you're using Private Service Connect to connect to your AlloyDB instance, include the following:

config.addDataSourceProperty("alloydbIpType", "PSC");

For more information about using Private Service Connect endpoint in Java Language Connectors, see the GitHub repository.

Python (pg8000)

If you're using Private Service Connect to connect to your AlloyDB instance, include the following:

  def getconn() -> pg8000.dbapi.Connection:
      conn: pg8000.dbapi.Connection = connector.connect(
          inst_uri,
          "pg8000",
          user=user,
          password=password,
          db=db,
          # use ip_type to specify PSC
          ip_type=IPTypes.PSC,
      )
      return conn

For more information about using Private Service Connect endpoint in Python Language Connectors, see the GitHub repository.

Python (asyncpg)

If you're using Private Service Connect to connect to your AlloyDB instance, include the following:

  async def getconn() -> asyncpg.Connection:
    conn: asyncpg.Connection = await connector.connect(
        inst_uri,
        "asyncpg",
        user=user,
        password=password,
        db=db,
        # use ip_type to specify PSC
        ip_type=IPTypes.PSC,
    )
    return conn

For more information about using Private Service Connect endpoint in Python Language Connectors, see the GitHub repository.

Go (pgx)

If you're using Private Service Connect to connect to your AlloyDB instance, include the following:

d.Dial(ctx, instURI, alloydbconn.WithPSC())

For more information about using Private Service Connect endpoint in Go Language Connectors, see the GitHub repository.

Go (database/sql)

If you're using Private Service Connect to connect to your AlloyDB instance, include the following:

  cleanup, err := pgxv5.RegisterDriver(
    "alloydb",
    alloydbconn.WithDefaultDialOptions(alloydbconn.WithPSC())
)

For more information about using Private Service Connect endpoint in Go Language Connectors, see the GitHub repository.