Manage the database IP access list
By default, Astra DB databases don’t restrict public access. This means databases allow connection attempts from any public IP address. However, you can use the database’s IP access list to allow only client connections from trusted IP addresses. If configured, your database automatically denies any connection attempts to and from an IP not included in the list.
Restricting public access doesn’t affect private endpoint connections. However, DataStax recommends restricting public access to ensure that your database is available only through private endpoints and allowed IPs.
Prerequisites
-
An active Astra account
-
An active Astra DB Serverless database
-
An application token or user role with permission to manage a database’s access list, such as the Database Administrator role or the Write IP Access List and Read IP Access List permissions
Restrict public access to a database
When you restrict public access, your database becomes inaccessible to all internet traffic. This can disrupt any applications that depend on a connection to your database, including viewing the database from your own machine. To prevent downtime, promptly add approved IP addresses or CIDR blocks to the access list. Until you add entries to the access list, no external connections to your database are allowed. |
To restrict public access to a database, do the following:
-
In the Astra Portal navigation menu, select your database.
Each database has one IP access list. For multi-region databases, this access list applies to every region for that database.
-
Click the Settings tab.
-
In the IP Access List section, enable Restrict public access.
-
In the confirmation dialog, click Restrict Public Access.
Next, add IP access list entries.
Add IP access list entries
After you Restrict public access to a database, create a list of allowed IP addresses or CIDR blocks that can access the database. Each entry can be a single IPv4 address, address space, or a CIDR block.
Using CIDR notation
A CIDR range indicates a range of IP addresses.
For example, the CIDR range 192.168.0.0/16
represents the first IP address of 192.168.0.0
through the last IP address of 192.168.255.255
.
The /16
mask indicates that the first 16 bits of the IP address are static.
The addresses in the CIDR range are represented by all the permutations of the last 16 bits.
Multiple tools are available online to help you convert a range of IP addresses to CIDR.
Each database has its own IP access list. When you add entries, make sure you add them to all applicable databases. For a multi-region database, all of the database’s regions share the same access list.
-
Astra Portal
-
DevOps API
In the Astra Portal, you can add individual access list entries, import multiple entries from a file, or copy entries from another database.
Importing entries from a file or another database overrides any existing access list entries. |
-
Add one entry
-
Import entries from a file
-
Copy entries from another database
-
In the Astra Portal navigation menu, select your database.
-
Click the Settings tab.
-
In the IP Access List section, click Add Access, and then select Add IP Address.
-
Enter the IP address or CIDR-notated range of IP addresses that you want to be able to access your database. The Current IP Address field shows the IP address you are currently using to access the Astra Portal. You can click
Copy to automatically paste this address into the IP Address or CIDR field. -
Optional: Enter a description for the access list entry.
-
Click Add Address.
You can import one or more IP access list entries from a JSON file.
-
In the Astra Portal navigation menu, select your database.
-
Click the Settings tab.
-
In the IP Access List section, click Add Access, and then select Upload from file.
-
Click Select File, and then select a file on your computer that contains a list of IP access list entries. You can use the following template to format your file:
template.json{ "addresses": [ { "address": "192.168.0.1/32", "description": "This CIDR allows datacenter B to connect to database A", "enabled": true }, { "address": "ADDRESS", "description": "DESCRIPTION", "enabled": false }, { "address": "ADDRESS", "description": "DESCRIPTION", "enabled": false } ], "configurations": { "accessListEnabled": true } }
When the file finishes uploading, a preview of the entries appears.
-
Click Import List.
You can import database IP access list entries from another serverless database in your organization.
-
In the Astra Portal navigation menu, select your database.
-
Click the Settings tab.
-
In the IP Access List section, click Add Access, and then select Import from database.
-
In the Import from database dialog, select another serverless database in your organization that has the IP access list entries that you want to apply to your current database.
After selecting a database, a preview of the entries appears.
-
Click Import List.
Use the DevOps API database access list endpoints to manage IP access list entries for Astra DB databases.
-
Get the database’s existing access list:
curl -sS --location -X GET "https://api.astra.datastax.com/v2/databases/DATABASE_ID/access-list" \ --header "Authorization: Bearer APPLICATION_TOKEN" \ --header "Content-Type: application/json"
Response
A successful response includes the IP access list entries for the specified database, if any exist:
[ { "organizationId": "303a3598-0905-4b5d-9db2-4bf2f9790973", "databaseId": "8fbcfe1d-56fa-4ed0-9aff-f57029feef1b", "addresses": [ { "address": "137.187.23.0/24", "enabled": true, "description": "This address allows the database connections from the production environment.", "lastUpdateDateTime": "2021-01-21T17:32:28Z" } ], "configurations": { "accessListEnabled": true } } ]
To get access lists for all databases in your organization, use
GET /v2/access-lists
. -
If the database doesn’t have an access list, get an access list template:
curl -sS --location -X GET "https://api.astra.datastax.com/v2/access-list/template" \ --header "Authorization: Bearer APPLICATION_TOKEN" \ --header "Content-Type: application/json"
Response
A successful response includes an example of an access list with one entry.
{ "addresses": [ { "address": "137.187.23.0/24", "enabled": true, "description": "This address allows the database connections from the prod environment" } ], "configurations": { "accessListEnabled": true } }
-
Add addresses to the database’s access list:
curl -sS --location -X POST "https://api.astra.datastax.com/v2/databases/DATABASE_ID/access-list" \ --header "Authorization: Bearer APPLICATION_TOKEN" \ --header "Content-Type: application/json" \ --data '{ [ { "address": "137.187.23.0/24", "enabled": true, "description": "This address allows the database connections from the prod environment" } ] }'
Each address is an object containing the following fields:
-
address
: An IP address or CIDR block -
enabled
: Eithertrue
(active, allowing traffic) orfalse
(inactive, not allowing traffic) -
description
: Optional string describing the entry
If you want to verify the structure of the access list, use
POST /v2/access-list/validate
. -
-
Optional: Send another request to
GET /v2/databases/DATABASE_ID/access-list
to confirm that the entries were added.
Test the connection and restart applications
After you add or edit IP access list entries, restart any applications, including clients and drivers, that depend on a connection to your database. DataStax recommends testing IP access list changes in a development environment before applying them in production.
The database might take a few minutes to recognize new IP access list entries. Wait a few minutes before you attempt to connect to your database from the new IP address.
Edit IP access list entries
-
Astra Portal
-
DevOps API
-
In the Astra Portal navigation menu, select your database.
-
Click the Settings tab.
-
In the IP Access List section, find the entry you want to edit, click
More Options, and then select Edit.If you want to overwrite all entries, see Add IP access list entries for import and copy options.
-
In the Add Access dialog, you can edit the Description.
-
Click Update Address to save your changes.
-
Test the connection and restart applications, if necessary.
-
Edit entries
-
Replace all entries
-
Get the database’s existing access list:
curl -sS --location -X GET "https://api.astra.datastax.com/v2/databases/DATABASE_ID/access-list" \ --header "Authorization: Bearer APPLICATION_TOKEN" \ --header "Content-Type: application/json"
Response
A successful response includes the IP access list entries for the specified database, if any exist:
[ { "organizationId": "303a3598-0905-4b5d-9db2-4bf2f9790973", "databaseId": "8fbcfe1d-56fa-4ed0-9aff-f57029feef1b", "addresses": [ { "address": "137.187.23.0/24", "enabled": true, "description": "This address allows the database connections from the production environment.", "lastUpdateDateTime": "2021-01-21T17:32:28Z" } ], "configurations": { "accessListEnabled": true } } ]
To get access lists for all databases in your organization, use
GET /v2/access-lists
. -
To update one entry, send a
PATCH
request containing the entries to update.The
address
is the unique identifier for each entry. If you need to modify theaddress
, you can either replace all entries or delete the existing entry and then add a new one.curl -sS --location -X PATCH "https://api.astra.datastax.com/v2/databases/DATABASE_ID/access-list" \ --header "Authorization: Bearer APPLICATION_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "addresses": [ { "address": "125.187.17.0/24", "enabled": true, "description": "Development" } ], "configurations": { "accessListEnabled": true } }'
The
configurations
object indicates the overall enforcement of the database’s IP access list. IfaccessListEnabled
isfalse
, the database doesn’t restrict public access. -
Test the connection and restart applications, if necessary.
To replace all access list entries for a database, you can upsert the access list:
-
Get the database’s existing access list:
curl -sS --location -X GET "https://api.astra.datastax.com/v2/databases/DATABASE_ID/access-list" \ --header "Authorization: Bearer APPLICATION_TOKEN" \ --header "Content-Type: application/json"
Response
A successful response includes the IP access list entries for the specified database, if any exist:
[ { "organizationId": "303a3598-0905-4b5d-9db2-4bf2f9790973", "databaseId": "8fbcfe1d-56fa-4ed0-9aff-f57029feef1b", "addresses": [ { "address": "137.187.23.0/24", "enabled": true, "description": "This address allows the database connections from the production environment.", "lastUpdateDateTime": "2021-01-21T17:32:28Z" } ], "configurations": { "accessListEnabled": true } } ]
To get access lists for all databases in your organization, use
GET /v2/access-lists
. -
Send a
PUT
request containing the entire desired access list:curl -sS --location -X PUT "https://api.astra.datastax.com/v2/databases/DATABASE_ID/access-list" \ --header "Authorization: Bearer APPLICATION_TOKEN" \ --header "Content-Type: application/json" \ --data `{ "addresses": [ { "address": "ADDRESS_1", "enabled": true, "description": "Development" }, { "address": "ADDRESS_2", "enabled": true, "description": "Test" }, { "address": "ADDRESS_3", "enabled": true, "description": "Production" } ], "configurations": { "accessListEnabled": true } }'
-
Test the connection and restart applications, if necessary.
Disable or delete IP access list entries
When you delete an IP access list entry, it can take a few minutes for your database to reject new traffic from that address. Existing connections can remain open for an indefinite amount of time, depending on application behavior and how the connection was established. |
-
Astra Portal
-
DevOps API
-
In the Astra Portal navigation menu, select your database.
-
Click the Settings tab.
-
In the IP Access List section, find the entry you want to disable or delete, click
More Options, and then select either Disable or Delete. -
In the confirmation dialog, click Disable or Delete.
-
Disable entries
-
Delete specific entries
-
Delete all entries
To disable an access list entry, send a PATCH
request that sets enabled
to false
.
-
Get the database’s existing access list:
curl -sS --location -X GET "https://api.astra.datastax.com/v2/databases/DATABASE_ID/access-list" \ --header "Authorization: Bearer APPLICATION_TOKEN" \ --header "Content-Type: application/json"
Response
A successful response includes the IP access list entries for the specified database, if any exist:
[ { "organizationId": "303a3598-0905-4b5d-9db2-4bf2f9790973", "databaseId": "8fbcfe1d-56fa-4ed0-9aff-f57029feef1b", "addresses": [ { "address": "137.187.23.0/24", "enabled": true, "description": "This address allows the database connections from the production environment.", "lastUpdateDateTime": "2021-01-21T17:32:28Z" } ], "configurations": { "accessListEnabled": true } } ]
To get access lists for all databases in your organization, use
GET /v2/access-lists
. -
Send a
DELETE
request containing the addresses to delete.If you don’t specify an address, the entire access list is deleted and public access is reenabled.
curl -sS --location -X DELETE "https://api.astra.datastax.com/v2/databases/DATABASE_ID/access-list" \ --header "Authorization: Bearer APPLICATION_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "addresses": [ { "address": "125.187.17.0/24" } ] }'
-
Test the connection and restart applications, if necessary.
-
To delete the entire access list for a database, send a
DELETE
request with no body.If you delete all entries, you reenable public access to the database.
curl -sS --location -X DELETE "https://api.astra.datastax.com/v2/databases/DATABASE_ID/access-list" \ --header "Authorization: Bearer APPLICATION_TOKEN" \ --header "Content-Type: application/json"
-
Test the connection and restart applications, if necessary.