Use custom DNS
The use of custom domains is available only as a premium feature. |
By default, when you create a database, Astra DB Serverless automatically sets up a DNS entry so that applications can connect to the database. The DNS entry is part of the cryptography that ensures both parties communicate to the intended target. If you connect to your database with a driver, the Secure Connect Bundle (SCB) also uses the DNS entry.
If you use private endpoints, then 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 Serverless.
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 Serverless 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.
[
"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 |
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 '[
"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 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 |
Get the Secure Connect Bundle for a custom domain
The Secure Connect Bundle (SCB) provides the hostname
(FQDN) for your private endpoint DNS entries and the ca.crt
for your client applications' self-signed certificates.
Before you 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 tohttps://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, 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 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
: Access 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 you created 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. -
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.