Connect to an instance using Private Service Connect

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.

Role	Description
compute.networkAdmin	Grants full control over the VPC network that initiates a connection to an AlloyDB instance. If you use Private Service Connect to connect to an AlloyDB instance from multiple VPC networks, then each network has its own administrator.
dns.admin	Grants full control over Cloud DNS resources, including DNS zones and records.
alloydb.admin	Provides full control of an AlloyDB instance and controls the instance over its lifecycle.
alloydb.databaseUser (Optional)	Provides access to the AlloyDB instance. If you connect through the AlloyDB Auth Proxy client, then you must have the AlloyDB Client role. If you connect directly, then you don't need any Identity and Access Management (IAM) roles and permissions.

Enable Private Service Connect

Enabling Private Service Connect involves creating an AlloyDB cluster with Private Service Connect configured, and then creating an AlloyDB instance with a list of allowed projects.

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.

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

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 \
 --project=PROJECT_ID

Replace the following:

• INSTANCE_ID: The ID of the instance.
• PROJECT_ID: The ID of the instance's project.

A sample response for the command is as follows:

  "pscInstanceConfig": {
    "pscServiceAttachmentLink": "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 pscServiceAttachmentLink 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.

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 \
   --project=CLUSTER_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.

   Note: For each VPC network, create a separate DNS zone.

   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 user=USERNAME host=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.

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.

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 user=USERNAME hostaddr=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.
• The pglogical, dblink, and postgres_fdw extensions that require outbound connectivity aren't supported.