This page describes how to set up a custom domain name system(DNS) name for your Cloud SQL instance.

Overview

You can configure a Cloud SQL instance so that your applications canconnect using a custom DNS name managed by your organization.If you want to use a custom DNS name to connect to a Cloud SQLinstance instead of using an IP address, then configure a customsubject alternative name (SAN). You can configure a custom SANwhen you create or update an instance.

When you add a custom DNS name as a custom SAN configuration to your instance,Cloud SQL inserts the custom DNS nameto the SAN field of the server certificate of the instance. This customizationlets you use the custom DNS name withhostname validation securely.You can add a comma-separated list of up to three custom DNS names to thecustom SAN configuration. For security reasons, you can use a custom SAN configurationonly for instances that youconfigure withCUSTOMER_MANAGED_CAS_CAas the server CA mode.

After you configure the custom DNS name for your instance, you can use thatcustom DNS name to connect your database clients or applications, includingCloud SQL Language Connectors andtheCloud SQL Auth Proxy.

Workflow

To set up a custom DNS name for an instance, do the following:

1. Create an instance configured with customer-managed CA.
2. Add custom SAN values to the instance. The custom SAN values are insertedinto the SAN field of the server certificate of the instance.
3. Determine the IP address of the instance.
4. Create custom DNS records for your instance.
5. Connect to the instance using the custom DNS name.

Before you begin

Before you set up a custom DNS name for your instance, make sure you havetherequired roles and permissions.

If you are creating a new Cloud SQL instance, then to use custom SAN,your instance must also use acustomer-managed certificate authority (CA) for itsserver CA mode.

Create an instance with custom SAN values

To create an instance with custom SAN values, use the followinggcloud sql instances create command:

gcloudsqlinstancescreate"INSTANCE_NAME"\--database-version=DATABASE_VERSION\--project=PROJECT_ID\--region=REGION\--server-ca-mode=CUSTOMER_MANAGED_CAS_CA\--server-ca-pool=projects/PROJECT_ID_CAS/locations/REGION/caPools/CA_POOL_ID--custom-subject-alternative-names=CUSTOM_DNS_NAME

Add or update custom SAN values for an instance

To add or update custom SAN values for an existing instance,do the following:

gcloudsqlinstancespatchINSTANCE_NAME\--custom-subject-alternative-names=CUSTOM_DNS_NAME

Clear all custom SAN values from an instance

To clear all custom SAN values from an instance,do the following:

gcloudsqlinstancespatchINSTANCE_NAME\--clear-custom-subject-alternative-names

Create custom DNS records

Before you can connect to the instance using the custom DNS name withyour clients and applications, set up the mapping between the DNS nameand the IP address. This mappingis known as DNS resolution. If you are connecting privately, thencreate the DNS record in a private DNS zonein the corresponding Virtual Private Cloud (VPC)network.

To create custom DNS records for your instance, do the following:

1. Retrieve the IP address for your instance. Run the following command:

   gcloudsqlinstancesdescribeINSTANCE_NAME\--project=PROJECT_ID

   Make the following replacements:

   • INSTANCE_NAME: the name of the Cloud SQL instance
   • PROJECT_ID: the ID orproject numberof the Google Cloud project that contains the instance

2. In the response, look for theipAddresses: field.

   For example:

   ipAddresses:- ipAddress: 192.0.2.4  type: PRIVATE

   You can retrieve the private IP address for an instance configured forprivate services access,Private Service Connect, orboth.

   Warning: For security reasons, we don't recommend setting up custom DNS records for the public IP address of an instance.

3. Add two DNS records to a DNS zone used by your application.You can use a DNS server that you manage yourself ortheCloud DNS private zone used by your application.

   • Create anA record for the IP address of the instance
   • Create aTXT record containing the instance connection name.

   Standard database clients use theA record to look up the IP addressto make the connection. Cloud SQL Language Connectors and the Cloud SQL Auth Proxyuse theTXT record to look up the instance connection name.

   For example, the connection string for your instance ismy-project:region:my-instance,but you want to connect using the DNS nameprod-db.mycompany.example.com.If the IP address of the instance on your company network is192.0.2.4,then create the following DNS records:

   Record type: AName: prod-db.mycompany.example.comValue: 192.0.2.4TTL: 600Record type: TXTName: prod-db.mycompany.example.comValue: my-project:region:my-instanceTTL: 600

Connect to an instance using a custom DNS name

For example, when using thepsql client, specify the flagsslmode=verify-full. Other PostgreSQL client drivers have similarconfiguration flags.

If you're connecting to a private Cloud SQL instancefrom an external network, then you must configure your Cloud SQL instanceand its Virtual Private Cloud (VPC) network to permit externalconnections and to let Cloud DNS communicate with on-premisessystems. For more information about this configuration, seeConnect from an external source andConfigure DNS for on-premises systems.

Limitations

• You can't add more than three DNS names as custom SAN values to the servercertificate of a Cloud SQL instance.
• The maximum length of a DNS name that you can add to the certificate as acustom SAN value for an instance is 253 characters.
• The DNS names that you add to the certificate for an instance can't havewildcard characters (*) or trailing dots. For example,test.example.com. isn't allowed.
• The DNS names must be valid, as specified byRFC 1034.
• You can specify custom SAN values forCUSTOMER_MANAGED_CAS_CA instances only.

What's next

• Manage SSL/TLS certificates on your Cloud SQL instance.
• Learn more abouthow encryption is handled in Google Cloud.
• Connect to your Cloud SQL instance using SSL/TLS certificates.
• Learn more abouthow PostgreSQL uses SSL/TLS certificates.