Using Custom DNS on an external system

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

Currently when you create a database, DataStax automatically sets up a Domain Name System (DNS) entry so that applications can connect to the database. This DNS entry is used in the Secure Connect Bundle (SCB), and plays a part in the cryptography ensuring both parties are communicating to the intended target.

As an Astra administrator setting up a private endpoint, you must create a local version of the *.astra.datastax.com domain to override the name resolution to the public IP address advertised by DataStax.

Now, you can set up your custom DNS with a private endpoint and use your DNS entry to send traffic to the private endpoint.

Benefits

This option works with an Astra database with a 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 said zone and its resolution. It also ensures you do not have to create and manage a local astra.datastax.com zone.

Prerequisites

Configure an application token to interact with the Astra APIs. For more, see Manage application tokens.

If you have any type of traffic over private links, you must prepare any client application to accept a self-signed certificate. This means you must use the ca.crt from the SCB. DataStax must have self-signed certificates for custom domains. If the client application uses a common Astra domain name, that application must still be prepared to accept our self-signed certificate.

Update any client that is over private links—even if that client NOT is planning to be used with custom domains.

Configure your Astra Organization with the custom domains

Retrieve list of existing custom domains

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

cURL command (/v2)
Results

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

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

The endpoint returns the list of custom domain names. If no domains are configured, the endpoint returns an empty response.

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 custom domain list is a "desired state" list. Adding, removing, or changing domains requires that you send the complete list of desired domains. For example, if you have a list of domains, then send only a single domain, you will unconfigure the previous domains.

cURL command (/v2)

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

If there are no errors, the request is complete. You can retrieve the list of configured domains to verify the configuration is in place.

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 so that the database is only accessible through private endpoints. You do not 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.

Retrieve modified list of custom domains

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

cURL command (/v2)
Results

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

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

The endpoint returns the list of custom domain names.

Retrieve the Secure Connect Bundle for a custom domain

About downloading SCB

Private link and the custom domain are required before the SCB for that custom domain can be downloaded.
With a configured private endpoint for the database after the custom domain is added, you can download the SCB for custom domains.

Obtain SCB for a database in an organization

This example returns the SCBs for Astra and all added custom domains for your organization.

cURL command (/v2)
Results

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

{
  "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": "dde308f5-a8b0-474d-afd6-81e5689e3e25-1",
  "region": "us-east-1",
  "cloudProvider": "AWS",
  "customDomainBundles": [
    {
      "domain": "example.domain.com",
      "cqlFQDN": "dde308f5-a8b0-474d-afd6-81e5689e3e25-us-east-1.db.example.domain.com",
      "apiFQDN": "dde308f5-a8b0-474d-afd6-81e5689e3e25-us-east-1.apps.example.domain.com",
      "dashboardFQDN": "dde308f5-a8b0-474d-afd6-81e5689e3e25-us-east-1.dashboard.example.domain.com",
      "downloadURL": "nifty.cloud.datastax.com:9092"
    }
    {
      "domain": "example.domain2.com",
      "cqlFQDN": "dde308f5-a8b0-474d-afd6-81e5689e3e25-us-east-1.db.example.domain2.com",
      "apiFQDN": "dde308f5-a8b0-474d-afd6-81e5689e3e25-us-east-1.apps.example.domain2.com",
      "dashboardFQDN": "dde308f5-a8b0-474d-afd6-81e5689e3e25-us-east-1.dashboard.example.domain2.com",
      "downloadURL": "nifty.cloud.datastax.com:9092"
    }
  ]
}

In the stanza for the appropriate database ID, the customDomainBundles section of the response will contain a sub-stanza for each custom domain in which there will be a downloadURL parameter for the respective Secure Connect Bundle. The downloadURL is the link to downloading the Secure Connect Bundle. For more on generating a Secure Bundle, see Obtain zip for connecting to the database.

From these results, get the host key for your custom domain:

cqlFQDN: for CQL queriers
apiFQDN: for http (REST API) requests to your database
dashboardFQDN: review the dashboard using the private endpoint

Each FQDN here is captured in the Secure Connect Bundle to ensure you are utilizing the selected private endpoint. You need to add DNS entries for each FQDN in the domains you want to utilize and point them at your private endpoint.

Create a DNS entry for your private endpoint

You can alias your private endpoint with a DNS entry to use as your hostname in the Astra DB secure connect bundle. To configure your specific endpoint, see the instructions for your cloud provider:

Adding custom domains

Once all configuration is complete, you can add more custom domains as needed. To complete this action,

Open Astra and go to Settings and select Security Settings.
Go to Custom Domains and click Add Domains.

Remember to set your custom domain with a private link.

Add your custom domain name to the Domain field.
Click Add Domain add one custom domain. Click + Add another domain one time to add another domain or several times to add several custom domains.

Removing custom domains

Open Astra and go to Settings and select Security Settings.
Go to Custom Domains and click the trash icon.
Read the information in the Delete Custom Domain box. This information explains how deleting a custom domain affects any application dependencies.
Type delete to confirm and then click Delete.