Connect to an instance using Private Service Connect

Stay organized with collections Save and categorize content based on your preferences.

This page describes how to use Private Service Connect to connect to an AlloyDB for PostgreSQL instance.

You can use Private Service Connect to connect to either a primary AlloyDB instance or any of its read replicas, or a secondary AlloyDB instance from multiple Virtual Private Cloud (VPC) networks that belong to different groups, teams, projects, or organizations.

Required roles

You must grant all the following roles to a user in your VPC network to be able to connect to an AlloyDB instance.

Enable Private Service Connect

To enable inbound connectivity, create a AlloyDB cluster with Private Service Connect enabled. When you create a primary instance, specify the projects permitted for connectivity. For outbound connectivity, provide the network attachment URI.

Create an AlloyDB primary cluster

The following example uses the gcloud alloydb clusters create command with the --enable-private-service-connect flag that creates an AlloyDB cluster with Private Service Connect enabled.

The process of creating a cluster remains the same with the exception of passing the --enable-private-service-connect flag. For detailed information about creating a cluster, see Create cluster and its primary instance.

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.

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.

Create an AlloyDB instance

The following example shows how to create a primary instance with a list of allowed projects configured. The process of creating an instance remains the same with the exception of passing the list of allowed projects using the --allowed-psc-projects flag for a Private Service Connect-enabled primary cluster.

For more information about creating other instance types, see Create a read pool instance and Create a secondary 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 \
    --allowed-psc-projects=ALLOWED_PROJECT_LIST
    --psc-network-attachment-uri=NETWORK_ATTACHMENT_URI

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" {}

Configure inbound connectivity

After you enable PSC for an AlloyDB instance, you can get the service attachment URL and configure an endpoint in your consume VPC to connect securely to the AlloyDB instance.

Get the service attachment

After creating an AlloyDB instance with Private Service Connect enabled, get the service attachment URL and use it to create the Private Service Connect endpoint.

Use the gcloud alloydb instances describe command to view details about an instance.

gcloud alloydb instances describe INSTANCE_ID \
 --cluster=CLUSTER_ID --region=REGION_ID

Replace the following:

• INSTANCE_ID: the ID of the instance.
• CLUSTER_ID: the ID of the cluster.
• REGION_ID: the region in which the AlloyDB cluster is deployed.

A sample response for the command is as follows:

  "pscInstanceConfig": {
    "serviceAttachmentLink:": "https://www.googleapis.com/compute/v1/projects/my-project/regions/my-region/serviceAttachments/my-service-attachment-id"
        "allowedConsumerProjects": {
          "45678",
          "12345",
              "67890",
            },
            "pscDnsName": "11111111-1111-1111-1111-111111111111.22222222-2222-2222-2222-222222222222.alloydb-psc.goog."
          }

The serviceAttachmentLink parameter holds the value of the service attachment URL.

Create a Private Service Connect endpoint

To create a Private Service Connect endpoint, pass the service attachment URL along with a unique endpoint name. For more information about creating a Private Service Connect endpoint, see Create an endpoint.

You can also reserve an internal IP address for the Private Service Connect endpoint using the gcloud compute addresses create command, and then use the reserved IP address when creating the endpoint.

Configure outbound connectivity

To enable outbound connectivity, set the network attachment URI when you create or update an AlloyDB instance. This URI allows secure connectivity between your project and the AlloyDB instance during outbound operations such as migrations.

Create the network attachment

You can create a network attachment that can accept connections automatically(ACCEPT_AUTOMATIC) or manually (ACCEPT_MANUAL). For more information about creating a network attachment, see Create and manage network attachments.

If you choose to create a network attachment that accepts connections automatically, then you don't need to set a list of accepted projects explicitly. For accepting connections manually, you must add the service-owned project number of the project where your AlloyDB instance is located to the list of accepted projects.

To find the service-owned project number, run the following command:

gcloud alpha alloydb clusters describe CLUSTER_ID --region=REGION_ID

The following is a sample response:

pscConfig:
pscEnabled: true
serviceOwnedProjectNumber: 123456789012

After you identify the service-owned project number, add the project to list of accepted projects and then create the network attachment.

Mae sure that the region of the network attachment is the same as the region of the AlloyDB instance. In addition, the subnet used to create the network attachment must belong to the RFC 1918 IP ranges, which are 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16.

Update an instance for outbound connectivity

To enable outbound connectivity for an existing AlloyDB instance with Private Service Connect enabled, pass the --psc-network-attachment-uri parameter to the gcloud alloydb instances update command.

Deactivate outbound connectivity

To deactivate outbound connectivity for an existing AlloyDB instance, pass the --clear-psc-network-attachment-uri parameter to the gcloud alloydb instances update command.

Connect to an AlloyDB instance

You can connect to an AlloyDB instance with Private Service Connect enabled by using one of the following options:

• an internal IP address,
• a DNS record
• AlloyDB Auth Proxy
• AlloyDB Language Connectors

Connecting using DNS records requires creating a DNS record in a private DNS zone in the corresponding VPC network. After you create a DNS record, you can use this record to connect to a Private Service Connect enabled instance directly using a DNS record, using AlloyDB Auth Proxy, or using AlloyDB Language Connectors.

Configure a DNS managed zone and a DNS record

To configure a DNS managed zone and a DNS record in your network, follow these steps:

1. To view summary information about a AlloyDB instance, including the DNS name of the instance, use the gcloud alloydb instances describe command:

   gcloud alloydb instances describe INSTANCE_ID \
   --cluster=CLUSTER_ID --region=REGION_ID

   Replace the following:

   • INSTANCE_ID: The ID of the instance.
   • CLUSTER_ID: The ID of the cluster.

   In the response, verify that the DNS name appears. The DNS name has the INSTANCE_UID.PROJECT_UID.REGION_NAME.alloydb-psc.goog. pattern.

2. To create a private DNS zone, use the gcloud dns managed-zones create command. This zone is associated with the VPC network that's used to connect to the AlloyDB instance through the Private Service Connect endpoint.

   gcloud dns managed-zones create ZONE_NAME \
   --project=PROJECT_ID \
   --description=DESCRIPTION \
   --dns-name=DNS_NAME \
   --networks=NETWORK_NAME \
   --visibility=private

   Replace the following:

   • ZONE_NAME: the name of the DNS zone.
   • PROJECT_ID: the ID or project number of the Google Cloud project that contains the zone.
   • DESCRIPTION: a description of the zone (for example, a DNS zone for the AlloyDB instance).
   • DNS_NAME: the DNS name for the zone, such as INSTANCE_UID.PROJECT_UID.REGION_NAME.alloydb-psc.goog..
   • NETWORK_NAME: the name of the VPC network.

3. After you create the Private Service Connect endpoint, to create a DNS record in the zone, use the gcloud dns record-sets create command:

   gcloud dns record-sets create DNS_NAME \
   --project=PROJECT_ID \
   --type=RRSET_TYPE \
   --rrdatas=RR_DATA \
   --zone=ZONE_NAME

   Replace the following:

   • DNS_NAME: the DNS name that you retrieved earlier in this procedure.
   • RRSET_TYPE: the resource record type of the DNS record set (for example, A).
   • RR_DATA: the IP address allocated for the Private Service Connect endpoint (for example, 198.51.100.5). You can also enter multiple values such as rrdata1 rrdata2 rrdata3 (for example, 10.1.2.3 10.2.3.4 10.3.4.5).

Connect directly using a DNS record

After you create a Private Service Connect endpoint, and create a DNS record, you can connect directly using the DNS record.

1. To retrieve the DNS record of the Private Service Connect endpoint, use the gcloud compute addresses describe command:

   gcloud compute addresses describe DNS_RECORD \
   --project=PROJECT_ID \
   --region=REGION_NAME

   Replace the following:

   • DNS_RECORD: the DNS record for the endpoint.
   • PROJECT_ID: the ID or project number of the Google Cloud project that contains the endpoint.
   • REGION_NAME: the region name for the endpoint.

2. To connect to the AlloyDB instance, use the DNS record.

   psql -U USERNAME -h DNS_RECORD

   Replace the following:

   • USERNAME: the name of the user that's connecting to the instance.
   • DNS_RECORD: the endpoint's DNS record.

Connect using AlloyDB Auth Proxy

The AlloyDB Auth Proxy is a connector that lets you make authorized, encrypted connections to AlloyDB databases. The AlloyDB Auth Proxy works by having a local client running in the local environment. Your application communicates with the AlloyDB Auth Proxy with the standard database protocol used by your database.

When you set the --psc flag while starting the Auth Proxy client, the AlloyDB Auth Proxy uses the DNS record that you created to connect to the Private Service Connect enabled instance.

Make sure that you start the Auth Proxy client by passing the instance URI that you retrieve using the gcloud alloydb instances list command, and set the --psc flag.

For more information about connecting to an instance using Auth Proxy, see Connect using the Auth Proxy.

Connect using AlloyDB Language Connectors

AlloyDB Language Connectors are libraries that provide automated mTLS with TLS 1.3 and Identity and Access Management (IAM) authorization when connecting to an AlloyDB instance.

After the Language Connector determines the instance supports Private Service Connect, it uses the DNS record that you created to connect to the instance.

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

  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

  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

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

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

Connect directly through an internal IP address

After you create a Private Service Connect endpoint, you can directly connect to an AlloyDB instance using the IP address that you configured.

1. To retrieve the IP address of the Private Service Connect endpoint, use the gcloud compute addresses describe command:

   gcloud compute addresses describe ADDRESS_NAME \
   --project=PROJECT_ID \
   --region=REGION_NAME

   Replace the following:

   • ADDRESS_NAME: the name of the endpoint's IP address.
   • PROJECT_ID: the ID or project number of the Google Cloud project that contains the endpoint.
   • REGION_NAME: the region name for the endpoint.

2. To connect to the AlloyDB instance, use the internal IP address.

   psql -U USERNAME -h IP_ADDRESS"

   Replace the following:

   • USERNAME: the name of the user that's connecting to the instance.
   • IP_ADDRESS: the endpoint's IP address.

Limitations

• You can set up to 20 Private Service Connect endpoints that connect to the service attachment of an AlloyDB instance with Private Service Connect enabled.
• You can't use the --network flag when you create a Private Service Connect-enabled cluster because it's associated with private services access.
• You can't activate or deactivate Private Service Connect on an existing instance.
• You can't configure an instance that has Private Service Connect enabled to use private services access.