Use custom domains

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

If you prefer, you can route traffic to your Astra DB databases through custom domains.

To configure custom domains in Astra DB, do the following:

  1. Complete the Prerequisites.

  2. Use the DevOps API to add custom domains to your Astra DB organization.

  3. Get the Secure Connect Bundle for the custom domains.

  4. Create DNS entries to route traffic to your custom domains.

  5. block public access to your databases.

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

Prerequisites

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

  • An active Astra account.

  • A paid subscription plan.

    Custom domains are a premium feature that requires a paid subscription plan. Use of custom domains incurs billed charges from both Astra DB and other providers, such as a custom domain host or private link service through a cloud provider. For information about private endpoint pricing, see the plan details on the Astra DB pricing page and your provider’s documentation.

  • 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, such as GoCQL, be aware that DataStax does not officially support connections over private links, with or without custom domains, through third-party open-source drivers. For more information, see the DataStax Support Policy.

Manage 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 -sS --location -X GET "https://api.astra.datastax.com/v2/organizations/customDomains" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
Response

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

[
  "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 --location -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.

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 (FQDN) for your DNS records and the ca.crt for your client applications' self-signed certificates.

  1. To get a temporary URL to download the SCB for a specific database, send a POST request to the Obtain zip for connecting to the database endpoint.

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

  2. 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.

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

  3. 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 Secure Connect Bundle.

Create DNS entries

To ensure proper name resolution for private endpoints and custom domains, you must configure private DNS mapping for the *.astra.datastax.com domain and subdomains. This overrides the default resolution to the public IP address provided by Astra DB.

If you use a custom domain for one database, then you must configure private DNS mapping for every database you create, whether it uses a private endpoint or not.

  • AWS

  • Microsoft Azure

  • Google Cloud

  1. In Amazon Route 53, create a private hosted zone to route the astra.datastax.com domain traffic to your AWS PrivateLink VPC ID.

  2. Create alias or CNAME records to route Astra DB subdomains to your Amazon VPC interface endpoint’s DNS name.

Use alias records if you use DataStax drivers. For more information, see Comparison of alias and CNAME records.

For each database, you must create records for the .db and .apps subdomains. You can get the subdomains from the secureBundleURL response body.

Hostname Format DNS entry Purpose

cqlFQDN

DATABASE_ID-REGION.db.CUSTOM_DOMAIN

Required

CQL queries.

apiFQDN

DATABASE_ID-REGION.apps.CUSTOM_DOMAIN

Required

HTTP (Data API) requests.

dashboardFQDN

DATABASE_ID-REGION.dashboard.CUSTOM_DOMAIN

Optional

The database’s Grafana dashboard, which can be inactive. For information about database metrics, see View and export metrics.

For multi-region databases, you must create records for every region where you use a custom domain and private endpoint.

  1. In the Azure Portal, create a private DNS zone.

  2. Create DNS entries to map Astra DB subdomains to your virtual network.

For each database, you must create records for the .db and .apps subdomains. You can get the subdomains from the secureBundleURL response body.

Hostname Format DNS entry Purpose

cqlFQDN

DATABASE_ID-REGION.db.CUSTOM_DOMAIN

Required

CQL queries.

apiFQDN

DATABASE_ID-REGION.apps.CUSTOM_DOMAIN

Required

HTTP (Data API) requests.

dashboardFQDN

DATABASE_ID-REGION.dashboard.CUSTOM_DOMAIN

Optional

The database’s Grafana dashboard, which can be inactive. For information about database metrics, see View and export metrics.

For multi-region databases, you must create records for every region where you use a custom domain and private endpoint.

  1. In the Google Cloud console, create a private zone to route traffic to your Private Service Connect endpoint IP.

  2. Create Type A standard records for Astra DB subdomains.

For each database, you must create records for the .db and .apps subdomains. You can get the subdomains from the secureBundleURL response body.

Hostname Format DNS entry Purpose

cqlFQDN

DATABASE_ID-REGION.db.CUSTOM_DOMAIN

Required

CQL queries.

apiFQDN

DATABASE_ID-REGION.apps.CUSTOM_DOMAIN

Required

HTTP (Data API) requests.

dashboardFQDN

DATABASE_ID-REGION.dashboard.CUSTOM_DOMAIN

Optional

The database’s Grafana dashboard, which can be inactive. For information about database metrics, see View and export metrics.

For multi-region databases, you must create records for every region where you use a custom domain and private endpoint.

Block public access

DataStax recommends that you use the IP Access List to block all public internet traffic to the database. This makes the database available only through private endpoints and allowed IPs.

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

  1. In the Astra Portal navigation menu, click Settings, and then click Security.

  2. In the Custom Domains section, click Add Domains.

  3. In the Domain field, enter your custom domain name.

  4. Click Add Domain to add your custom domain, or click Add another domain to add additional custom domains.

  5. Get Secure Connect Bundles and create DNS entries for your new custom domains.

Remove custom domains in the Astra Portal

  1. In the Astra Portal navigation menu, click Settings, and then click Security.

  2. In the Custom Domains section, locate the domain you want to delete, and then click delete Delete.

  3. In the Delete Custom Domain dialog, review the information about how custom domain deletion can impact application dependencies.

  4. To proceed with deletion, enter delete, and then click Delete.

  5. If applicable, remove private endpoints, private zones, and other resources associated with the removed domain in your cloud provider and other services.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com