Use Custom DNS on an external system

The use of custom domains is available only as a premium feature.

By default, when you create a database, Astra DB Classic automatically sets up a DNS entry so that applications can connect to the database. The Secure Connect Bundle (SCB) uses the DNS entry, and it is part of the cryptography that ensures both parties communicate to the intended target.

If you use private endpoints, you must create a local version of the *.astra.datastax.com domain to override the name resolution to the public IP address advertised by Astra DB Classic. Then, you must manage this configuration for every database you create, whether it uses a private endpoint or not.

Alternatively, for your databases with private endpoints, you can use custom DNS entries to send traffic to the private endpoint. You can have a DNS name for the database in a DNS zone that belongs to your organization. This option allows you to have complete control over this zone and its resolution. This option also ensures that you don’t have to create and manage a local *.astra.datastax.com zone for every database.

Prerequisites

You have an Astra DB database.
You have an application token.
You set your custom domain with a private link, and it is ready to receive traffic.

Add custom domains with the DevOps API

To configure custom domains for your Astra DB organization, use the DevOps API to get the list of custom domains and modify the entries as needed.

Get the list of custom domains

To retrieve the list of custom domains for your organization, send a GET request to https://api.astra.datastax.com/v2/organizations/customDomains:

curl --location --request GET 'https://api.astra.datastax.com/v2/organizations/customDomains' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer *ASTRA_DB_APPLICATION_TOKEN*' \
--data-raw '[
  "string"
]'

Response

Returns a list of custom domain names. If no domains are configured, the response is empty.

[
  "likeness.com",
  "happy.com"
]

Modify the list of custom domains

To modify the list of custom domains, send a POST request to https://api.astra.datastax.com/v2/organizations/customDomains. The request body must contain the entire custom domains list. Use the response body from the GET /organizations/customDomains endpoint as a template.

The custom domain list is a desired state list. You must always send the list of all custom domains when you add, remove, or change any domains. For example, if you have five domains, but your POST body contains only one domain, then all domains are removed except the one included in your request body.

curl --location --request POST 'https://api.astra.datastax.com/v2/organizations/customDomains' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer *ASTRA_DB_APPLICATION_TOKEN*' \
--data-raw '[
    "likeness.com",
    "happy.com",
    "dataslice.com"
]'

A request with no errors returns a successful response. You can repeat the GET request to verify your changes.

You are still assigned a host name in the astra.datastax.com zone, which resolves the internet-facing IP.

You can block all public internet traffic to the database so that the database is only accessible through private endpoints.

You don’t have to create a copy of the astra.datastax.com DNS zone when using custom domains. Instead, you create a DNS entry in your desired domain.

Get the Secure Connect Bundle for a custom domain

The Secure Connect Bundle (SCB) provides the hostname for your private endpoint DNS entries and the ca.crt for your client applications' self-signed certificates.

Before you can download the SCB, you must set your custom domains with private links and add custom domains to your Astra DB organization.

To get a temporary URL to download the SCB for a specific database, send a POST request to https://api.astra.datastax.com/v2/databases/DATABASE_ID/secureBundleURL:

curl --location --request POST 'https://api.astra.datastax.com/v2/databases/*DATABASE_ID*/secureBundleURL' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer *ASTRA_DB_APPLICATION_TOKEN*' \
--data-raw '[
  "all": true
]'

Response

A successful response contains SCB download links for the database and its custom domains:

{
  "downloadURL": "nifty.cloud.datastax.com:9092",
  "downloadURLInternal": "internal-nifty.cloud.datastax.com:9092",
  "downloadURLMigrationProxy": "proxy-nifty.cloud.datastax.com:9092",
  "downloadURLMigrationProxyInternal": "proxy-nifty.cloud.datastax.com:9092",
  "datcenterID": "*DATABASE_ID*-1",
  "region": "us-east-1",
  "cloudProvider": "AWS",
  "customDomainBundles": [
    {
      "domain": "example.domain.com",
      "cqlFQDN": "*DATABASE_ID*-*REGION*.db.example.domain.com",
      "apiFQDN": "*DATABASE_ID*-*REGION*.apps.example.domain.com",
      "dashboardFQDN": "*DATABASE_ID*-*REGION*.dashboard.example.domain.com",
      "downloadURL": "nifty.cloud.datastax.com:9092"
    }
    {
      "domain": "example.domain2.com",
      "cqlFQDN": "*DATABASE_ID*-*REGION*.db.example.domain2.com",
      "apiFQDN": "*DATABASE_ID*-*REGION*.apps.example.domain2.com",
      "dashboardFQDN": "*DATABASE_ID*-*REGION*.dashboard.example.domain2.com",
      "downloadURL": "nifty.cloud.datastax.com:9092"
    }
  ]
}

For more information about this endpoint, see Obtain zip for connecting to the database in the DevOps API reference.

In the response body, locate the customDomainBundles array, which contains an object for each custom domain.
Use the downloadURL to download the SCB for each custom domain.
From the SCB, you can get the ca.crt for your client applications' self-signed certificates.

Configure your client applications to accept self-signed certificates, namely the ca.crt from the SCB, if they have any traffic over private links.

DataStax requires self-signed certificates for custom domains. If any of your client applications use a common Astra domain name, you must still prepare those applications to accept the DataStax self-signed certificate.

Create DNS entries for private endpoints

Create DNS entries for your private endpoints or VPC peering configurations that use the hostname from your Astra DB Secure Connect Bundle:

From the secureBundleURL response body, you can get the following host keys for your custom domains:

cqlFQDN: CQL queries
apiFQDN: HTTP (REST API) requests to your database
dashboardFQDN: View the database Overview page when using a private endpoint

Each FQDN in the SCB ensures that you use the designated private endpoint. You must add DNS entries for each FQDN in the domains that you want to use and point them at your private endpoint.

If you configure custom domains after creating private endpoints, you must update your existing private endpoints' DNS entries to use your custom domains.

Manage custom domains in the Astra Portal

After you complete the initial custom DNS configuration, you can manage custom domains in the Astra Portal.

You can also use the DevOps API, as explained in Add custom domains with the DevOps API.

Add custom domains in the Astra Portal

In the Astra Portal, go to Settings, and then click Security Settings.
In the Custom Domains section, click Add Domains.
In the Domain field, enter your custom domain name.
Click Add Domain to add your custom domain, or click Add another domain to add additional custom domains.

Remember to set new custom domains with private links and Create DNS entries for private endpoints.

Remove custom domains in the Astra Portal

In the Astra Portal, go to Settings, and then click Security Settings.
In the Custom Domains section, locate the domain you want to delete, and then click delete Delete.
In the Delete Custom Domain dialog, review the information about how custom domain deletion can impact application dependencies.
To proceed with deletion, enter delete, and then click Delete.

After removing a custom domain, remember to update private links and DNS entries for your private endpoints accordingly.