Use custom domains for Astra

All Astra DB Serverless databases have default DNS entries, allowing applications to connect seamlessly and securely. For example, a database’s default Secure Connect Bundle (SCB) includes DNS entries for the default Astra domain.

If you prefer, you can route traffic to your Astra DB Serverless databases through custom domains. To configure custom domains for Astra, do the following:

Complete the Prerequisites.
Use the DevOps API to add custom domains to your Astra organization.

After completing the initial configuration, you can manage custom domains in the Astra Portal or the DevOps API.

Route database traffic through your custom domains:

Enable private endpoints for your databases.
Create DNS entries to route traffic to your custom domains.
Block public access to your databases.

If you enable custom domains, you must configure private endpoints for all current and future databases. This requires ongoing management of DNS entries and private endpoints in your cloud provider and Astra organization.

Connect your client applications through your custom domains.

Prerequisites

To use custom domains for Astra, you need the following:

A paid plan.

Custom domains are a premium feature that requires a paid plan. Use of custom domains incurs billed charges from both Astra and other providers, such as a custom domain host and private link service through a cloud provider.

An active Astra DB Serverless database.
An application token with the Organization Administrator role.
A custom domain configured with a private link and ready to receive traffic.
A DataStax-supported connection method that is compatible with private links and custom domains, such as a DataStax API, client, or driver.

If you use a third-party open-source driver, be aware that DataStax does not officially support connections over private links, with or without custom domains, through these drivers.

Manage custom domains with the DevOps API

To configure custom domains for your Astra 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 -sS -L -X GET "https://api.astra.datastax.com/v2/organizations/customDomains" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"

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

Result

[
  "example.domain1.com",
  "example.domain2.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 -sS -L -X POST "https://api.astra.datastax.com/v2/organizations/customDomains" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data-raw '[
  "example.domain1.com",
  "example.domain2.com",
  "example.domain3.com"
]'

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

Configure private endpoints and DNS entries

After you enable a custom domain in an Astra organization, you must configure private endpoints and DNS entries for every database that you create in that organization.

For multi-region databases, you must create records for every region.

When you create databases in the future, you must repeat this process for each new database.

To route database connections through your custom domains, you must enable private endpoints for your databases and configure DNS entries for the *.astra.datastax.com domain and subdomains. This ensures proper name resolution for private endpoints and custom domains, and it overrides the default resolution to the public IP address provided by Astra.

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

Configure private endpoints and DNS entries for all databases in your Astra organization:

Complete all steps to configure the private endpoints, including creating the DNS entries:

Recommended: Use the IP Access List to block all public internet traffic to each database.

This makes your databases available only through private endpoints and allowed IPs.

With custom domains enabled, you are still assigned a host name in the astra.datastax.com zone, which resolves the internet-facing IP. After you configure private endpoints and DNS routing, DataStax recommends that you block all public internet traffic to your databases, which makes your databases accessible through private endpoints only.

Connect to a database through a custom domain

After you enable custom domains and configure private endpoints for all databases, you use your custom domains to connect to your databases.

For HTTP requests, such as Data API requests, use the apps subdomain of your custom domain.

For Cassandra drivers and other integrations that use the SCB, you must download the custom domain SCB for each database. Don’t use the default SCB, which uses the default Astra domain.

The following steps explain how to download a custom domain SCB for a database using the DevOps API. To use the Astra Portal, see Download and use a Secure Connect Bundle (SCB) with an Astra DB Serverless database.

Send a POST request to the DevOps API secure bundle URL endpoint:
```
curl -sS -L -X POST "https://api.astra.datastax.com/v2/databases/DATABASE_ID/secureBundleURL?all=true" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
```
Provide the following:
- DATABASE_ID: The database ID. If you have multiple databases, you must send a separate request for each database.
- APPLICATION_TOKEN: An application token with the Organization Administrator role or Database Administrator role for the target database.
- all=true: For multi-region databases and custom domains, this query parameter is required to fetch SCB download links for all regions and domains.

Use the returned downloadURL to download the SCB for the specified database:

{
  "downloadURL": "nifty.cloud.datastax.com:9092",   // Downloads the default bundle
  "downloadURLInternal": "internal-nifty.cloud.datastax.com:9092",
  "downloadURLMigrationProxy": "proxy-nifty.cloud.datastax.com:9092",
  "downloadURLMigrationProxyInternal": "proxy-nifty.cloud.datastax.com:9092",
  "datacenterID": "DATABASE_ID-1",
  "region": "us-east-2",
  "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"   // Downloads a custom domain bundle
    },
    {
      "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"  // Downloads a custom domain bundle
    }
  ]
}

The response can contain multiple downloadURL keys:

Default bundles: The main response object contains a downloadURL for datastax.com. You can use this link to download the default bundle configured for the default Astra domain and the database’s primary region (identified by datacenterID: "DATABASE_ID-1").
Regional bundles: For multi-region databases, the response includes separate objects and download URLs for each region. Regions are identified by the datacenterID key where the primary region is "DATABASE_ID-1" and each secondary region is numbered sequentially as "DATABASE_ID-2", "DATABASE_ID-3", and so on.
Custom domain bundles: Within each regional object, the customDomainBundles array contains a nested object for each custom domain, if any are configured. You can use the downloadURL in each domain’s object to download the SCB for that domain. You must configure private endpoints for the database before you can download the SCB for a custom domain.

From the SCB, 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.

For more information about the SCB contents, see Download and use a Secure Connect Bundle (SCB) with an Astra DB Serverless database.

Manage custom domains in the Astra Portal

After you add an initial custom domain configuration with the DevOps API, you can manage custom domains in the Astra Portal.

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

Add custom domains in the Astra Portal

In the Astra Portal header, click Settings.
In the Settings navigation menu, make sure the enterprise/organization filter is set to the organization that you want to manage.

If the organization belongs to an enterprise, you must filter on the enterprise, and then click the organization name in the Organizations list.
In the Settings navigation menu, click Security.
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.
Enable private endpoints and create DNS entries for each new custom domain.
Connect to each database through the custom domain using the database’s apps domain or custom domain SCB.

Remove custom domains in the Astra Portal

In the Astra Portal header, click Settings.
In the Settings navigation menu, make sure the enterprise/organization filter is set to the organization that you want to manage.

If the organization belongs to an enterprise, you must filter on the enterprise, and then click the organization name in the Organizations list.
In the Settings navigation menu, click Security.
In the Custom Domains section, find the domain you want to delete, and then click 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.
If applicable, remove private endpoints, private zones, and other resources associated with the removed domain in your cloud provider, Astra, client applications, and other services.