Managing with DevOps API

The DevOps API allows you to manage your databases, users, and tokens.

For more, see the DevOps API reference.

Managing your database lifecycle

Manage your databases with the DevOps API, which can be used to create, terminate, resize, park, and unpark your database.

You can use the DevOps API to perform the actions which are available to you through your role permissions.

The following roles can use the application token to use the DevOps API:

  • Organization Administrator

  • Database Administrator

  • Custom roles with create, terminate, and expand database permissions

If you were on a Free or serverless (Beta) tier before 4 March 2021, you were migrated to the pay as you go plan. You will need to reconnect to your database using your application token.

Use the DevOps API to perform lifecycle actions for DataStax Astra DB databases.

  1. To use the DevOps API, create an application token to authenticate your service account in the DevOps API.

  2. Once you have authenticated your service account, you can create, terminate, resize, park, and unpark databases using the DevOps API.

Example

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/availableRegions' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'

You cannot resize, park, or unpark serverless databases. The commands will work with only classic databases.

Managing roles

Use the DevOps API to create, modify, and delete roles for your organization.

You can use the DevOps API to perform the actions your role permissions allow.

The following roles use the application token to execute DevOps API queries:

  • Organization Administrator

  • Database Administrator

Prerequisites

  1. Create an application token to authenticate your service account in the DevOps API.

  2. Once you have authenticated your service account, you can create, update, and delete roles in the DevOps API.

Creating a new role

  1. Submit a GET query to check existing roles within the organization to ensure you don’t duplicate roles:

    • cURL command (/v2)

    • Result

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/organizations/roles' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
    [
    	{"ID":"3fb93abd-7abe-4a3d-9f71-9ded80070a4a”,
    	"Name":"API Admin Svc Acct”,
    	"Type":"default","policy”:”
    		{\"description\":\"API Admin Svc Acct\”,
    		\"actions\”:[
    			\"accesslist-read\”,
    			\"org-billing-read\”,
    			\"org-billing-write\”,
    			\"org-user-read\”,
    			\"org-user-write\”,
    			\"org-db-create\”,
    			\"org-db-passwordreset\”,
    			\"org-db-view\”,
    			\"org-db-terminate\”,
    			\"org-db-suspend\”,
    			\"org-db-addpeering\”,
    			\"org-db-managemigratorproxy\”,
    			\"org-db-expand\”,
    			\"db-all-keyspace-create\”,
    			\"db-all-keyspace-describe\”,
    			\"db-keyspace-grant\”,
    			\"db-keyspace-modify\”,
    			\"db-keyspace-describe\”,
    			\"db-keyspace-create\”,
    			\"db-keyspace-authorize\”,
    			\"db-keyspace-alter\”,
    			\"db-keyspace-drop\”,
    			\"db-table-select\”,
    			\"db-table-grant\”,
    			\"db-table-modify\”,
    			\"db-table-describe\”,
    			\"db-table-create\”,
    			\"db-table-authorize\”,
    			\"db-table-alter\”,
    			\"db-table-drop\”,
    			\"db-graphql\",\"db-rest\”],
    		\"effect\":\"allow\”,
    		\"resources\":
    			[\"drn:astra:org:__ORG_ID__\”,
    			\"drn:astra:org:__ORG_ID__:db:*\”,
    			\"drn:astra:org:__ORG_ID__:db:*:keyspace:*\”,
    			\"drn:astra:org:__ORG_ID__:db:*:keyspace:*:table:*\"]}”}
    	}
    ]
  2. Create a new role for your organization:

    • cURL command (/v2)

    • Result

    curl --request POST \
      --url 'https://api.astra.datastax.com/v2/organizations/roles' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
        	"name":"<roleName>",
        	"policy": {
        	  "description": "Create and describe keyspaces",
        	  "resources": ["drn:astra:org:<organizationId>"],
        	  "actions": ["db-all-keyspace-create", "db-all-keyspace-describe"],
        	  "effect": "allow"}
        }'
    {
    	"OrgID":"dccb8c32-cc2a-4bea-bd95-47ab8eb20510",
    	"ID":"b125f9ab-675e-4bc7-9306-5e50a05b7c56",
    	"Name":"keyspaceRole",
    	"Policy":"{
    		\"description\":\"keyspaces\",
    		\"resources\":[\"drn:astra:org:dccb8c32-cc2a-4bea-bd95-47ab8eb20510\"],
    		\"actions\":[\"db-all-keyspace-create\",\"db-all-keyspace-describe\"],
    		\"effect\":\"allow\"
    		}",
    	"LastUpdateDateTime":"",
    	"LastUpdateUserID":"wsbCtHyXCfuSHkiKbYWHsYZa"
    }

    If a role with the same name already exists, you’ll get an error when trying to create the new role: "unable to create role".

    You can assign actions to the following resources to determine the available permissions for the custom role you create:

    Group of permissions Resource assignment options Applicable actions

    For organization permissions (org-)

    • drn:astra:org:<organizationId>

    • org-audits-read

    • org-billing-read

    • org-billing-write

    • org-external-auth-read

    • org-external-auth-write

    • org-notification-write

    • org-read

    • org-role-delete

    • org-role-read

    • org-role-write

    • org-token-read

    • org-token-write

    • org-user-read

    • org-user-write

    • org-write

    • accesslist-read

    • accesslist-write

    For database permissions (org-db)

    • drn:astra:org:<organizationId>:db:*

    • drn:astra:org:<organizationId>:db:<databaseId>

    • db-cql

    • db-graphql

    • db-rest

    • org-db-addpeering

    • org-db-create

    • org-db-expand

    • org-db-managemigratorproxy

    • org-db-passwordreset

    • org-db-suspend

    • org-db-terminate

    • org-db-view

    For keyspace permissions (db-keyspace)

    • drn:astra:org:<organizationId>:db:*:keyspace:*

    • drn:astra:org:<organizationId>:db:<databaseId>:keyspace:*

    • drn:astra:org:<organizationId>:db:<databaseId>:keyspace:<keyspaceName>

    • db-all-keyspace-create

    • db-all-keyspace-describe

    • db-keyspace-alter

    • db-keyspace-authorize

    • db-keyspace-create

    • db-keyspace-describe

    • db-keyspace-drop

    • db-keyspace-grant

    • db-keyspace-modify

    For table permissions (db-table)

    • drn:astra:org:<organizationId>:db:*:keyspace:*:table:*

    • drn:astra:org:<organizationId>:db:<databaseId>:keyspace:*:table:*

    • drn:astra:org:<organizationId>:db:<databaseId>:keyspace:<keyspaceName>:table:*

    • db-table-alter

    • db-table-authorize

    • db-table-create

    • db-table-describe

    • db-table-drop

    • db-table-grant

    • db-table-modify

    • db-table-select

    If you grant access to a specified keyspace, the following permissions are allowed:

    • All actions for database access (org-db or db actions) are granted for the entire database, even if access is granted to only a single keyspace in the database.

    • Keyspace-specific access is granted for all db-keyspace actions.

    • Table-specific access is granted for all tables belonging to the specified keyspace.

    For example, if you wanted to create a custom role that allows the users to use the REST and GraphQL APIs and also allow the role to modify tables, use the following call:

    curl --request POST \
      --url 'https://api.astra.datastax.com/v2/organizations/roles' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
      	"name":"apiRole",
      	"policy": {
      	  "description": "Access to REST and GraphQL APIs, modify tables",
      	  "resources": ["drn:astra:org:<organizationId>", "drn:astra:org:<organizationId>:db:<databaseId>:keyspace:<keyspaceName>:table:*"],
      	  "actions": ["db-graphql", "db-rest", "db-table-modify"],
      	  "effect": "allow"}
        }'

    By using the *, the role will be able to modify all tables within the specified keyspace. If you want to grant the modify permission to a specified table, include the <tableName> in the resource.

  3. Confirm role was created with the necessary permissions:

    • cURL command (/v2)

    • Result

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/organizations/roles/<roleId>' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
    {
    	"ID":"b125f9ab-675e-4bc7-9306-5e50a05b7c56",
    	"Name":"keyspaceRole",
    	"policy":"{
    		\"description\":\"keyspaces\",
    		\"resources\":[\"drn:astra:org:dccb8c32-cc2a-4bea-bd95-47ab8eb20510\"],
    		\"actions\":[\"db-all-keyspace-create\",\"db-all-keyspace-describe\"],
    		\"effect\":\"allow\"
    	}"
    }

For more, see Create a role in an organization in the DevOps API.

Updating a role

  1. If you need to make changes to the permissions for an existing role, you can change the policy:

    curl --request PUT \
      --url 'https://api.astra.datastax.com/v2/organizations/roles/<roleId>' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
      	"name":"<roleName>",
      	"policy": {
      	  "description": "Create and describe keyspaces",
      	  "resources": ["drn:astra:org:<organizationId>"],
      	  "actions": ["db-all-keyspace-create", "db-all-keyspace-describe"],
      	  "effect": "allow"}
        }'
  2. Confirm role was created with the necessary permissions:

    • cURL command (/v2)

    • Result

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/organizations/roles/<roleId>' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
    {
    	"OrgID":"dccb8c32-cc2a-4bea-bd95-47ab8eb20510",
    	"ID":"b125f9ab-675e-4bc7-9306-5e50a05b7c56",
    	"Name":"newRoleName",
    	"Policy":"{
    		\"description\":\"keyspaces\",
    		\"resources\":[\"drn:astra:org:dccb8c32-cc2a-4bea-bd95-47ab8eb20510\"],
    		\"actions\":[\"db-all-keyspace-create\",\"db-all-keyspace-describe\"],
    		\"effect\":\"allow\"
    		}",
    	"LastUpdateDateTime":"",
    	"LastUpdateUserID":"wsbCtHyXCfuSHkiKbYWHsYZa"
    }

For more, see Update a role within an organization in the DevOps API.

Deleting a custom role

When you delete a custom role, all users and tokens assigned to that role will no longer have access.

  1. Delete a custom role to revoke access based on that role:

    curl --request DELETE \
      --url 'https://api.astra.datastax.com/v2/organizations/roles/<roleId>' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
  2. Confirm role no longer exists:

    • cURL command (/v2)

    • Result

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/organizations/roles/<roleId>' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
    "unable to get role for organization"

For more, see Delete a role by ID in the DevOps API.

Managing users

Use the DevOps API to create, modify, and delete users for your organization.

The following roles use the application token to execute DevOps API queries:

  • Organization Administrator

  • Database Administrator

Prerequisites

  1. Create an application token to authenticate your service account in the DevOps API.

  2. Once you have authenticated your service account, you can create and delete users in the DevOps API.

Inviting a user

  1. Check existing users within the organization:

    • cURL command (/v2)

    • Result

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/organizations/users' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
    {
    "OrgID":"dacb3c32-cc2a-4bea-bd95-47ab8eb20410”,
    "OrgName":"DataStax”,
    "Users”:[
    	{"UserID":"388def78-0040-4dge-b235-d67806929c8f”,
    	"Email":"john.smith@datastax.com”,
    	"Status":"active”,
    	"Roles”:[{"ID":"704fc2af-9c11-4c57-b9e5-5667b8889b3e”, "Name":"Admin User”}]
    	},
    	{"UserID":"d8bb706b-95a0-499b-aadc-5a43b4f9042d”,
    	"Email":"jane.doe@datastax.com”,
    	"Status":"active”,
    	"Roles”:[{"ID":"21ef3576-0197-415a-b167-d510af12ecf0”,"Name":"Organization Administrator”}]
    	}]
    }
  2. Inviting a new user to your organization:

    curl --request PUT \
     --url 'https://api.astra.datastax.com/v2/organizations/users' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>' \
     --data '{
         "email":"<userEmail>",
         "orgID":"<organizationId>",
         "roles": ["<roleId1>", "<roleId2>", "<roleId3>"]
       }'

For roles, use the id UUID value by Getting existing roles in your organization. The API results will show the UUID for each role id.

Your invited user must validate their email address in their invitation before they can log in to Astra.

For more, see Invite a user to an organization in the DevOps API.

Getting user information

  1. Check for a specified user’s information within the organization:

    • cURL command (/v2)

    • Result

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/organizations/users/<userId>' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
    {
    	"UserID":"388def78-0040-4dfe-b235-d67806939c8f",
    	"Email":"sebastian.estevez@datastax.com",
    	"Status":"active",
    	"Roles":[{"ID":"704fc2af-9c11-4c57-b9e5-5667b8889b3e","Name":"Admin User"}]
    }

For more, see Get an organization’s user in the DevOps API.

Removing a user

  1. Delete a user by their ID:

    curl --request DELETE \
     --url 'https://api.astra.datastax.com/v2/organizations/users/<userId>' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
  2. Confirm user no longer exists:

    • cURL command (/v2)

    • Result

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/organizations/users/<userId>' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
    {
    	"OrgID":"dccb8c32-cc2a-4bea-bd95-47ab8eb20510",
    	"ID":"b125f9ab-675e-4bc7-9306-5e50a05b7c56",
    	"Name":"newRoleName",
    	"Policy":"{
    		\"description\":\"keyspaces\",
    		\"resources\":[\"drn:astra:org:dccb8c32-cc2a-4bea-bd95-47ab8eb20510\"],
    		\"actions\":[\"db-all-keyspace-create\",\"db-all-keyspace-describe\"],
    		\"effect\":\"allow\"
    		}",
    	"LastUpdateDateTime":"",
    	"LastUpdateUserID":"wsbCtHyXCfuSHkiKbYWHsYZa"
    }

For more, see Remove or uninvite a user from an organization in the DevOps API.

Managing tokens

Use the DevOps API to generate or revoke an application token for specific roles.

You can use the DevOps API to perform the actions which are available to you through your role permissions.

The following roles can use the application token to use the DevOps API:

  • Organization Administrator

  • Database Administrator

Prerequisites

  1. Create an application token to authenticate your service account in the DevOps API.

  2. Once you have authenticated your service account, you can create and revoke tokens the DevOps API.

Generating a token for client

  1. Get all clients within the organization:

    • cURL command (/v2)

    • Result

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/clientIdSecrets' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
    {"clients":[
    	{"clientId":"DkFtHKMhDQDuQtlExkSzwbya",
    		"roles":["21ef3576-0197-415a-b167-d510af12ecf0"],
    		"generatedOn":"2021-02-22T17:09:58.668Z"},
    	{"clientId":"eYSboCJaESiblJZnKZWMxROv",
    		"roles":["21ef3576-0197-415a-b167-d510af12ecf0"],
    		"generatedOn":"2021-04-28T18:49:11.323Z"}
    ]}
  2. Create an application token for a specific client:

    • cURL command (/v2)

    • Result

    curl --request POST \
     --url 'https://api.astra.datastax.com/v2/clientIdSecrets' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>' \
     --data '{"roles": ["<roleId>"]}'
    {
      "clientId":"zjCEYwRGWocLfQJHBNQxvorr",
      "secret":"SLR.cllL1YzfJDnl+YhUv5DMKlx8HaeMFTKjIJ4I6YdKB7w-K7U_+j-a9daWbbcp0uugXW,hb.3J2S0PPqDNhT6+oUiPYYaI+,xuwm2O97.ZpHcYvCsnlrTyl8w1pH-0",
      "orgId":"dccb8c32-cc2a-4bea-bd95-47ab8eb20510",
      "roles":["21ef3576-0197-415a-b167-d510af12ecf0"],
      "token":"AstraCS:zjCEYwRGWocLfQJHBNQxvorr:8709074baaf63e746cc5de52891e3a5ca88c73ae1fb7336652e9b59b9e69eff2",
      "generatedOn":"2021-04-30T19:38:26.147847107Z"
    }

For the roleId, provide the relevant role’s id UUID value from a prior GET query, as shown in Getting existing roles in your organization. The API results will show the UUID for each role id.

Also refer to Generate token for client in the DevOps API.

Removing a token

When you remove a token, all users and roles assigned to that role will no longer have access.

  1. Get a list of the available client IDs and secrets for your organization:

    • cURL command (/v2)

    • Result

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/clientIdSecrets' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
    {"clients":[
    	{"clientId":"DkFtHKMhDQDuQtlExkSzwbya",
    		"roles":["21ef3576-0197-415a-b167-d510af12ecf0"],
    		"generatedOn":"2021-02-22T17:09:58.668Z"},
    	{"clientId":"eYSboCJaESiblJZnKZWMxROv",
    		"roles":["21ef3576-0197-415a-b167-d510af12ecf0"],
    		"generatedOn":"2021-04-28T18:49:11.323Z"}
    ]}
  2. Remove a token for a specific client ID:

    curl --request DELETE \
     --url 'https://api.astra.datastax.com/v2/clientIdSecrets/<clientID>' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
  3. Get a list of the available client IDs and secrets for your organization to confirm it was removed:

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/clientIdSecrets' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'

For more, see Revoke a token in the DevOps API.

What’s next?

You can now use your token to connect to the Astra DB APIs. See more about the available APIs:

BYOK AWS with DevOps API

Encryption is a widely accepted mechanism to secure data against breaches. By default, DataStax Astra DB encrypts data, and cloud providers such as AWS or Google Cloud offer encryption solutions. However, you may want to further limit data access, because cloud providers have access to the keys and ultimately to the data.

To address this security concern, DataStax Astra DB allows you to associate a Customer Managed Key (one per region) that you defined in the AWS Key Management Service (KMS) with a Customer Key that you create in Astra DB.

In this topic, we’ll use these terms:

  • Bring Your Own Key (BYOK) refers to the overall capability.

  • Customer Managed Key (CMK) refers to a particular key type in AWS KMS.

  • Customer Key refers to the corresponding key association in Astra DB.

This BYOK feature:

  • Is available for serverless Astra DB databases with these cloud providers:

  • Is not available in the Astra DB Free Tier.

  • Free Tier users: instead of submitting a Support ticket, click the Chat icon in the Astra DB console’s lower-right corner. Ask the DataStax onboarding representative about options to upgrade your organization and use BYOK.

Introduction

Data encryption is defined as a process that transforms data into an encoded format. Once encoded, the data is incomprehensible without being decrypted. Data encryption is essential for organizations in all industries because it protects data from unauthorized access. When thinking of data encryption, two main scenarios are often considered:

  • Data at rest

    Encrypting data while it is stored in the file storage in use.

  • Data in transit

    Encrypting data while it travels through private or public networks.

BYOK allows customers to manage encryption for data at rest.

Benefits

BYOK allows you to take full control of the encryption keys when storing data in the cloud. AWS KMS provides protection against data breaches by alerting you when tampering occurs. In KMS, you can configure specific policies to adhere to compliance guidelines, such as auditing, key rotation, and access.

Setting up a corresponding Customer Key for an Astra DB database hosted in an AWS region enables the separation of:

  • The encrypted lock

  • The key that encrypts/decrypts data

This separation of lock and key is considered a best practice to secure data via encryption.

After setting up a Customer Managed Key (CMK) in your AWS account’s Key Management Service, use the Astra DB console, or the DataStax DevOps API, to associate an existing AWS CMK with a Customer Key in Astra DB.

In Astra DB console, under Organization Settings, see the Key Encryption section of Security Settings.

In addition to the console UI, BYOK provides DevOps API calls that allow you to programmatically:

  • Create a new association between a CMK (created in AWS KMS) and your Astra DB data, in a specific region.

  • List all Customer Keys that are associated with protecting the AWS-based Astra DB data for your organization.

  • List a specific Customer Key for an organization, based on the specified cloud provider (aws) & region combination.

Please contact DataStax Support if you need to delete Customer Keys from your Astra DB organization. If you agree, the DataStax Support team may perform the key deletion on your behalf. Once a registered association with an AWS KMS Customer Managed Key is deleted from your Astra DB organization, the default data encryption provided by Astra DB is used.

Prerequisites

  1. Create your Astra DB database using the Astra DB console. In the case of this BYOK feature, create an AWS-based database, and choose one of the available regions to start.

  2. Before submitting the DataStax DevOps API calls, set up a Customer Managed Key (one per region, as needed) in the AWS KMS, as outlined in this topic.

  3. Create an application token to authenticate your service account in the DevOps API.

  4. Ensure you have permission to create and view Customer Keys. See Roles and permissions.

  5. Ensure that you know your Astra DB organization ID. When you log into the Astra DB console, your organization ID is in the generated URL. For example, in the URL https://astra.datastax.com/org/a99999c7-b934-436c-9999-9999999a3b5d/manage, the organization ID is a99999c7-b934-436c-9999-9999999a3b5d.

Multi-region support

The BYOK feature is supported in multi-region Astra DB environments; however, each region is encrypted using its own key. Keys cannot be shared across regions. For a given organization:

  • if you have an Astra DB database that spans multiple regions,

  • and if you’ve defined a Customer Managed Key in AWS or Google Cloud,

  • create a Customer Key in each (provider + region) combination.

Pricing

There is no additional cost to using BYOK with Astra DB. As noted previously, BYOK is not available in the Astra DB Free Tier.

Customer Managed Keys in AWS may incur a monthly fee, and a fee for use in excess of the AWS free tier. The fees are counted against the AWS KMS quotas for your AWS account. For details, see:

Roles and permissions

The following Astra DB roles can manage Customer Keys.

  • Organization Administrator

  • Database Administrator

To manage Customer Keys, your Astra DB account must have these permissions enabled.

  • org-cmk-read

  • org-cmk-write

AWS KMS console

Before you create a Customer Managed Key in the AWS Key Management Service (KMS), submit the following REST API call:

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/kms/provider/<provider>/region/<region>/accounts' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'

The GET’s response includes the provider_id of the AWS account where DataStax will store your S3 buckets. Copy the ID number returned in the GET’s response. Then, when you configure your AWS KMS Customer Managed Key (see the steps below), you’ll specify this account number, and grant DataStax permission to access this account.

  1. After authenticating into your AWS organization and account, search for, or navigate to, the Key Management Service (KMS).

  2. On the KMS page, click the left sidebar link for Customer managed keys.

  3. Click Create key.

  4. Choose the Symmetric option for a single key, which will be used to encrypt and decrypt data for your Astra DB database in an Amazon S3 bucket. Click Next.

  5. On Add labels, enter a memorable alias for your CMK, such as datastax-byok-cmk, and optionally provide a brief Description and user-defined Tags. Click Next.

  6. On Define key administrative permissions, decide if you want to keep the option to Allow key administrators to delete this key. Also on this dialog, expand the down arrow in Key administrators section and select the relevant AWS accounts. Click Next.

  7. On Define key usage permissions, decide which AWS accounts you want to authorize for the CMK’s usage. For now, skip the Other AWS Accounts option; there’s an option on the next screen to edit the in-progress Key policy definition. Click Next.

  8. On the Review page, check the selected options, and then scroll through the generated Key policy. There are a couple manual edits to perform. Add the full section (see below) that starts with:

            {
                "Sid": "Allow an external account to use this KMS key",
                .
                .
                .
            }
  9. Ensure that you have actions defined that are shown in the following example. Of course, your arn:aws:iam::…​ values will be different. The first sample ARN shown below is the account owner’s ID, and the second ARN in this sample is the ID of the AWS S3 storage account.

    Again, to get the appropriate storage account ID value, if you haven’t already, use the following GET to retrieve the provider_id of the account that DataStax will use, and for which you’ll grant access permission.

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/kms/provider/<provider>/region/<region>/accounts' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'

    Make sure that your Key policy here in KMS, again in the section under "Allow an external account to use this KMS key", is using the intended S3 storage account ID’s arn:aws:iam::<storage-account-id>:role/creator value.

    {
        "Version": "2012-10-17",
        "Id": "key-consolepolicy-3",
        "Statement": [
            {
                "Sid": "Enable IAM User Permissions",
                "Effect": "Allow",
                "Principal": {
                    "AWS": "arn:aws:iam::111111111111:root"
                },
                "Action": "kms:*",
                "Resource": "*"
            },
            {
                "Sid": "Allow an external account to use this KMS key",
                "Effect": "Allow",
                "Principal": {
                    "AWS": "arn:aws:iam::222222222222:role/creator"
                },
                "Action": [
                    "kms:EnableKey",
                    "kms:Encrypt",
                    "kms:Decrypt",
                    "kms:GenerateDataKey",
                    "kms:GenerateDataKeyWithoutPlaintext",
                    "kms:ReEncryptTo",
                    "kms:ReEncryptFrom",
                    "kms:DescribeKey"
                ],
                "Resource": "*"
            },
            {
                "Sid": "Allow attachment of persistent resources",
                "Effect": "Allow",
                "Principal": {
                    "AWS": "arn:aws:iam::222222222222:role/creator"
                },
                "Action": [
                    "kms:CreateGrant",
                    "kms:ListGrants",
                    "kms:RevokeGrant"
                ],
                "Resource": "*"
            }
        ]
    }

    In your edits, match the kms:…​ values in the Action:…​ section, under the Sid label that begins with "Allow an external account to use this KMS key". Ensure that your Key policy has the following actions defined. To use the KMS CMK with your Astra DB data, DataStax requires these eight actions:

                "Action": [
                    "kms:EnableKey",
                    "kms:Encrypt",
                    "kms:Decrypt",
                    "kms:GenerateDataKey",
                    "kms:GenerateDataKeyWithoutPlaintext",
                    "kms:ReEncryptTo",
                    "kms:ReEncryptFrom",
                    "kms:DescribeKey"
                ]

    You can copy/paste in those values (if not present already) into your KMS CMK’s Key policy textbox.

    If you have questions, please contact us at Astra DB Product Management.

  10. Also, in the Key policy section that starts with:

                "Sid": "Allow attachment of persistent resources",

    Be sure to use the three actions shown in the sample below:

    "Action": [
                    "kms:CreateGrant",
                    "kms:ListGrants",
                    "kms:RevokeGrant"
                ],
  11. When you are ready, click Finish.

  12. On the AWS KMS Customer managed keys page, notice the alias name that you defined for your newly created CMK and its ID value.

Copy the ARN of the key you just created. That ARN can serve as the keyID that you’ll provide in:

  • Astra DB console’s Add Keys UI of your organization’s Security Settings

  • Or in the DevOps API /v2/kms POST request payload

DevOps v2 API to manage Customer Keys

Submit DevOps API calls to create and view Customer Keys in your Astra DB organization.

If you are using Postman for your API calls, ensure you use the raw option to enter the body of your API call.

For descriptions of the /v2/kms calls, see the sections below. For more, see the DevOps v2 API reference details.

Create a Customer Key for Astra DB

Use the following POST to create a Customer Key in Astra DB that will be associated with an existing Customer Managed Key in the AWS Key Management Service (KMS).

In the request payload, specify your Astra DB organizationID, and the keyID of the Customer Managed Key that you created in AWS KMS, and the region. In each Astra DB organization, there can be one Customer Key for a given cloud provider and region combination. A successful Customer Key creation returns 200 OK in the response.

When you log into the Astra DB console, your organization ID is in the generated URL. For example, in the URL https://astra.datastax.com/org/a99999c7-b934-436c-9999-9999999a3b5d/manage, the organization ID is a99999c7-b934-436c-9999-9999999a3b5d.

  • cURL command (/v2/kms)

  • Result

curl --request POST \
  --url 'https://api.astra.datastax.com/v2/kms' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
  "orgId": "<organization-id>",
  "<cloud-provider>": {
    "keyID": "String - Resource name of the key",
    "region": "String - Region in which the key exists"
  }
}'
200 OK

Or one of the following:

400 Bad request.
403 The user is forbidden to perform the operation.
404 The specified resource was not found.
500 A server error occurred.

{
  "errors": [
    {
      "description": "string",
      "internalCode": "string",
      "internalTxId": "string"
    }
  ]
}

Get all Customer Keys in an Astra DB organization

Retrieve all existing Customer Keys of an Astra DB organization.

  • cURL command (/v2/kms)

  • Result

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/kms/' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'
When one or more keys are found for the organization, 
the 200 OK response contains, for each key:

{
    "OrganizationID": "String - The ID of your organization",
    "CloudProvider": "String - The cloud provider, such as aws or gcp",
    "KeyID": "String - The ID of the Customer Key",
    "Region": "String - The region in which the Customer Key is used"
}
   .
   .
   .

If there are no keys setup for the organization, 
the 404 response contains:

{
  "description": "Organization: <orgID> does not have 
                  any CMKs associated with it."
}

Other potential response codes:

400 Bad request.
403 The user is forbidden to perform the operation.
500 A server error occurred.

Get a single Customer Key in an Astra DB organization

Retrieves a Customer Key in an Astra DB organization for a given cloud provider & region combination. The provider value in this case should be aws.

The GET response also returns the provider ID of the storage account where your Amazon S3 buckets exist. If not done already, you can use this information to configure or modify (back in the AWS Key Management Service) your KMS Customer Managed Key, so that Astra DB has access to the key.

  • cURL command (/v2/kms)

  • Result

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/kms/provider/<provider>/region/<region>/accounts' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'
When the key is found for the given provider and region, 
the 200 OK response contains:

{
  "organization_id": "String - The ID of your organization",
  "provider_id": "String - The ID of the provider account
                   where DataStax stores your data buckets",
  "provider": "String - aws or gcp"
}

If there are no keys setup for the organization's provider 
and region combination, the 404 response contains:

{
  "description": "Could not find <provider> data in 
                  region <region> for organization <orgID>."
}

Other potential response codes:

400 Bad request.
403 The user is forbidden to perform the operation.
500 A server error occurred.

BYOK GCP with DevOps API

Encryption is a widely accepted mechanism to secure data against breaches. By default, DataStax Astra DB encrypts data, and cloud providers such as Google Cloud offer encryption solutions. However, you may want to further limit data access, because cloud providers have access to the keys and ultimately to the data.

To address this security concern, DataStax Astra DB allows you to associate a Customer Managed Encryption Key (one per region) that you defined in Google Cloud’s Key Management Service (KMS) with a Customer Key that you create in Astra DB.

In this topic, we’ll use these terms:

  • Bring Your Own Key (BYOK) refers to the overall capability.

  • Customer Managed Encryption Key (CMEK) refers to a particular key type in Google Cloud KMS.

  • Customer Key refers to the corresponding key association in Astra DB.

This BYOK feature:

  • Is available for serverless Astra DB databases with these cloud providers:

  • Is not available in the Astra DB Free Tier.

  • Free Tier users: instead of submitting a Support ticket, click the Chat icon in the Astra DB console’s lower-right corner. Ask the DataStax onboarding representative about options to upgrade your organization and use BYOK.

Introduction

Data encryption is defined as a process that transforms data into an encoded format. Once encoded, the data is incomprehensible without being decrypted. Data encryption is essential for organizations in all industries because it protects data from unauthorized access. When thinking of data encryption, two main scenarios are often considered:

  • Data at rest

    Encrypting data while it is stored in the file storage in use.

  • Data in transit

    Encrypting data while it travels through private or public networks.

BYOK allows customers to manage encryption for data at rest.

Benefits

BYOK allows you to take full control of the encryption keys when storing data in the cloud. Google Cloud KMS provides protection against data breaches by alerting you when tampering occurs. In KMS, you can configure specific policies to adhere to compliance guidelines, such as auditing, key rotation, and access.

Setting up a corresponding Customer Key for an Astra DB database hosted in a Google Cloud region enables the separation of:

  • The encrypted lock

  • The key that encrypts/decrypts data

This separation of lock and key is considered a best practice to secure data via encryption.

After setting up a Customer Managed Encryption Key (CMEK) in your Google Cloud project’s Key Management Service, use the DataStax DevOps API to associate an existing Google Cloud CMEK with a Customer Key in Astra DB:

  • Create a new association between the Google Cloud CMEK and your Astra DB data, in a specific region.

  • List all Customer Keys that are associated with protecting the Google Cloud based Astra DB data for your organization.

  • List a specific Customer Key for an organization, based on the specified cloud provider (gcp) & region combination.

Please contact DataStax Support if you need to delete Customer Keys from your Astra DB organization. If you agree, the DataStax Support team may perform the key deletion on your behalf. Once a registered association with a Google Cloud CMEK is deleted from your Astra DB organization, the default data encryption provided by Astra DB is used.

Prerequisites

  1. Create your Astra DB database using the Astra DB console. For the examples in this topic, in the case of this BYOK feature, create a Google Cloud based database, and choose one of the available regions to start.

  2. Before submitting the DataStax DevOps API calls, set up a Customer Managed Encryption Key (one per region, as needed) in the Google Cloud KMS, as outlined in this topic.

  3. Create an application token to authenticate your service account in the DevOps API.

  4. Ensure you have permission to create and view Customer Keys. See Roles and permissions.

  5. Ensure that you know your Astra DB organization ID. When you log into the Astra DB console, your organization ID is in the generated URL. For example, in the URL https://astra.datastax.com/org/a99999c7-b934-436c-9999-9999999a3b5d/manage, the organization ID is a99999c7-b934-436c-9999-9999999a3b5d.

Multi-region support

The BYOK feature is supported in multi-region Astra DB environments; however, each region is encrypted using its own key. Keys cannot be shared across regions. For a given organization:

  • if you have an Astra DB database that spans multiple regions,

  • and if you’ve defined a Customer Managed Key in AWS or Google Cloud,

  • create a Customer Key in each (provider + region) combination.

Pricing

There is no additional cost to using BYOK with Astra DB. As noted previously, BYOK is not available in the Astra DB Free Tier.

Customer Managed Encryption Keys in Google Cloud may incur a monthly fee, and a fee for use in excess of the Google Cloud free tier. The fees are counted against the Google Cloud KMS quotas for your project. For details, see Customer Managed Encryption Key in the Google Cloud documentation.

Roles and permissions

The following Astra DB roles can manage Customer Keys.

  • Organization Administrator

  • Database Administrator

To manage Customer Keys, your Astra DB account must have these permissions enabled.

  • org-cmk-read

  • org-cmk-write

Google Cloud console

This section describes steps you’ll perform in Google Cloud console to:

  • Create a custom role with specific permissions needed by Astra DB

  • Create a Customer Managed Encryption Key

Once your CMEK with assigned role and permissions are setup, you can use the DevOps API to submit calls that create and view associated Customer Keys for your Astra DB data.

Prerequisite API step to determine account for GCS buckets

Before you create a custom role and a Customer Managed Encryption Key (CMEK) in Google Cloud console, determine (for a given region) in which project does Astra DB store your Google Cloud Storage (GCS) buckets. To find that information, use cURl or Postman to submit a GET on /v2/kms/provider/gcp/region/<region-name>/accounts. Example:

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/kms/provider/<provider>/region/<region>/accounts' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'

The GET’s response includes the ID of the Google Cloud Storage (GCS) account, into which Astra DB will store your database’s encrypted data. Copy the ID number returned in the GET’s response. Then, when you configure your Google Cloud CMEK (see the steps below), you’ll specify this account number, and grant DataStax permission to access this account.

Create a custom role and grant permissions

In Google Cloud console, create a custom role and grant the minimum required permissions needed by Astra DB to access your Google Cloud Storage (GCS) buckets. Custom roles let you group permissions and assign them to principals in your project or organization. You can manually select permissions or import permissions from another role.

  1. After authenticating into your Google Cloud project, search for "IAM & Admin".

  2. On the "IAM & Admin" page, from the left-side navigation panel, choose Roles.

  3. Click Create Role.

  4. Click ADD PERMISSIONS and filter on kms.

  5. From among the filtered results, further narrow down by enabling Cloud KMS Viewer and Cloud KMS CryptoKey Encrypter/decrypter.

  6. Scroll down the refreshed results list, and at a minimum, enable the following permissions for your custom role:

    cloudkms.cryptoKeyVersions.useToDecrypt
    cloudkms.cryptoKeyVersions.useToEncrypt
    cloudkms.cryptoKeys.get

    Example:

    Google Cloud Key Management Add Permissions By Role to ensure DataStax access to CMEK.

  7. Click ADD.

  8. Modify values such as the custom role’s Title and ID string.

  9. Click CREATE.

You’ll specify this custom role during the CMEK steps outlined below.

Create a Customer Managed Encryption Key

  1. While authenticated into your Google Cloud project, search for, or navigate to, the "Key Management" service. The Cloud Key Management Service (Cloud KMS) lets you create, use, rotate, and manage cryptographic keys. A cryptographic key is a resource that is used for encrypting and decrypting data or for producing and verifying digital signatures.

  2. On the Cloud KMS page, if you haven’t already, click ENABLE.

  3. Click Create Key Ring, or open an existing Key Ring if already defined. Key rings group keys together to keep them organized.

    1. If new, provide a name for your Key Ring, such as testkeyring.

    2. For Location type, choose Region.

    3. Select the same region of your Astra DB database(s).

  4. On the "Create Key" page:

    1. Enter a Name for your key.

    2. For Key type, choose Generated Key.

    3. For Protection level, choose Software.

    4. For Purpose, choose Symmetric encrypt/decrypt.

    5. Decide on the key Rotation cadence to match your preference. The default is 90 days.

    6. When ready, click CREATE.

  5. On the "Keys for <your-key-ring-name> key ring" page, click the link for your newly created key’s name.

  6. On the "Key: <your-key-name>" page, click the PERMISSIONS tab.

  7. In this step, you’ll provide:

    • The storage account ID returned in the GET /v2/kms/provider/gcp/region/<region-name>/accounts API call. See Prerequisite API step to determine account for GCS buckets.

    • The custom role you created earlier. See Create a custom role and grant permissions.

      Provide those values so you can properly setup, with the necessary role and permissions, the following principles:

      <projectNumber>-compute@developer.gserviceaccount.com
      service-<projectNumber>@gs-project-accounts.iam.gserviceaccount.com

      Where <projectNumber> is the output of GET /v2/kms/provider/gcp/region/<region-name>/accounts.

      1. On this PERMISSIONS tab, click ADD.

      2. Paste into the New principals textbox the account ID that you copied from the response of the GET /v2/kms/provider/gcp/region/<region-name>/accounts. (Again, refer to Prerequisite API step to determine account for GCS buckets).

      3. Select the name of the custom role that you created earlier. As a reminder, in an earlier step, we applied the following permissions to the custom role:

        cloudkms.cryptoKeyVersions.useToDecrypt
        cloudkms.cryptoKeyVersions.useToEncrypt
        cloudkms.cryptoKeys.get

        Those are the minimum permissions needed in the role that’s assigned to your CMEK.

      4. When you’re ready, click SAVE.

  8. On the "Key: <your-key-name>" page, click the VERSIONS tab.

  9. Under Actions, expand the three vertical dots and select Copy resource name. Example:

    Google Cloud Key Management menu selecting Copy Resource Name option for a newly created key.

    The format of the copied resource name is:

    projects/<id>/locations/<region-name>/keyRings/<your-key-ring-name>/cryptoKeys/<your-key-name>/cryptoKeyVersions/<version>

    Optionally, you can remove the /cryptoKeyVersions/<version> portion at the end of the copied resource name. Copy the rest. Example:

    projects/this-that-999999/locations/us-east1/keyRings/testkeyring/cryptoKeys/mydefaultkey

Save the copied resource name of your Customer Managed Encryption Key. You’ll provide its value while adding a Customer Key association in Astra DB console. For those steps, see the next section.

DevOps v2 API to manage Customer Keys

Submit DevOps API calls to create and view Customer Keys in your Astra DB organization. In effect, you’ll register a Customer Key in Astra DB that is associated with an already created (see above) Customer Managed Encryption Key (CMEK) in Google Cloud.

If you are using Postman for your API calls, ensure you use the raw option to enter the body of your API call.

For descriptions of the /v2/kms calls, see the sections below. For more, see the DevOps v2 API reference details.

Create a Customer Key for Astra DB

Use the following POST to create a Customer Key in Astra DB that will be associated with an existing Customer Managed Encryption Key (CMEK) that was created in Google Cloud.

In the request payload, specify your Astra DB organizationID, the keyID, and the region.

Recall that keyID for the POST payload is the CMEK’s resource name, as generated in the Google Cloud console. See that step to copy the CMEK’s resource name, in Create a Customer Managed Encryption Key above.

In each Astra DB organization, there can be one Customer Key for a given cloud provider and region combination. A successful Customer Key creation returns 200 OK in the response.

When you log into the Astra DB console, your organization ID is in the generated URL. For example, in the URL https://astra.datastax.com/org/a99999c7-b934-436c-9999-9999999a3b5d/manage, the organization ID is a99999c7-b934-436c-9999-9999999a3b5d.

  • cURL command (/v2/kms)

  • Result

curl --request POST \
  --url 'https://api.astra.datastax.com/v2/kms' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <application_token>' \
  --data '{
  "orgId": "<organization-id>",
  "<cloud-provider>": {
    "keyID": "String - Resource name of the key",
    "region": "String - Region in which the key exists"
  }
}'
200 OK

Or one of the following:

400 Bad request.
403 The user is forbidden to perform the operation.
404 The specified resource was not found.
500 A server error occurred.

{
  "errors": [
    {
      "description": "string",
      "internalCode": "string",
      "internalTxId": "string"
    }
  ]
}

Get all Customer Keys in an Astra DB organization

Retrieve all existing Customer Keys of an Astra DB organization.

  • cURL command (/v2/kms)

  • Result

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/kms/' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'
When one or more keys are found for the organization, 
the 200 OK response contains, for each key:

{
    "OrganizationID": "String - The ID of your organization",
    "CloudProvider": "String - The cloud provider, such as aws or gcp",
    "KeyID": "String - The ID of the Customer Key",
    "Region": "String - The region in which the Customer Key is used"
}
   .
   .
   .

If there are no keys setup for the organization, 
the 404 response contains:

{
  "description": "Organization: <orgID> does not have 
                  any CMKs associated with it."
}

Other potential response codes:

400 Bad request.
403 The user is forbidden to perform the operation.
500 A server error occurred.

Get a single Customer Key in an Astra DB organization

Retrieves a Customer Key in an Astra DB organization for a given cloud provider & region combination. The provider value in this example should be gcp.

The GET response also returns the provider ID of the storage account where your Google Cloud Storage (GCS) buckets exist. If not done already, you can use this information to configure or modify (back in the Google Cloud console) your CMEK, so that Astra DB has access to the key.

  • cURL command (/v2/kms)

  • Result

curl --request GET \
 --url 'https://api.astra.datastax.com/v2/kms/provider/<provider>/region/<region>/accounts' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <application_token>'
When the key is found for the given provider and region, 
the 200 OK response contains:

{
  "organization_id": "String - The ID of your organization",
  "provider_id": "String - The ID of the provider account
                   where DataStax stores your data buckets",
  "provider": "String - aws or gcp"
}

If there are no keys setup for the organization's provider 
and region combination, the 404 response contains:

{
  "description": "Could not find <provider> data in 
                  region <region> for organization <orgID>."
}

Other potential response codes:

400 Bad request.
403 The user is forbidden to perform the operation.
500 A server error occurred.

Managing access list

Use the DevOps API to add and remove addresses for your database access list. You can also enable and disable your access list.

You can use the DevOps API to perform the actions your role permissions allow.

The following roles use the application token to execute DevOps API queries:

  • Organization Administrator

  • Database Administrator

The access list feature will be rolled out for classic databases over a few weeks. If you do not see the access list feature in your database settings, please open a support ticket.

Prerequisites

  1. Create an application token to authenticate your service account in the DevOps API.

  2. Once you have authenticated your service account, you can add and remove IP addresses and CIDRs for your access list in the DevOps API.

  3. You must have your access list on to be able to manage your access list via the DevOps API.

Adding addresses to your database access list

  1. Check existing access lists within your organization or database to see which addresses are already on your access list(s):

    Access lists are configured for each database within an organization. You must add each address to every database access list for which you want the address to have access.

    • cURL command (/v2): Get all access lists in organization

    • cURL command (/v2): Get access list in database

    • Result

    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/access-lists' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    [
      {
        "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
        }
      }
    ]
  2. Get a template for your access list:

    • cURL command (/v2)

    • Result

    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/access-list/template' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    [
      {
        "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
        }
      }
    ]

    For more, see Get template of access list in the DevOps API.

  3. Complete your access list to submit.

  4. Add your access list addresses:

    curl --request POST \
      --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
          [
            "address": "125.187.17.0/24",
            "enabled": true,
            "description": "Development"
          ]
        }'

    For more, see Add addresses to access list for a database in the DevOps API.

  5. Confirm the new addresses have been added to your access list:

    • cURL command (/v2)

    • Result

    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    [
      {
        "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"
          },
          {
            "address": "125.187.17.0/24",
            "enabled": true,
            "description": "Development"
          },
        ],
        "configurations": {
          "accessListEnabled": true
        }
      }
    ]

Replacing your existing access list

  1. Check existing access lists within your organization or database to see which addresses are already on your access list:

    • cURL command (/v2): Get all access lists in organization

    • cURL command (/v2): Get access list in database

    • Result

    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/access-lists' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    [
      {
        "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
        }
      }
    ]
  2. Submit your revised access list:

    • cURL command (/v2): Replace access list

    • cURL command (/v2): Update access list

    curl --request PUT \
      --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
          "addresses": [
              {
                "address": "125.187.17.0/24",
                "enabled": true,
                "description": "Development"
                "lastUpdateDateTime": "2021-01-21T17:32:28Z"
              }
            ],
            "configurations": {
              "accessListEnabled": true
            }
        }'
    curl --request PATCH \
      --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
          "addresses": [
              {
                "address": "125.187.17.0/24",
                "enabled": true,
                "description": "Development"
              }
            ],
            "configurations": {
              "accessListEnabled": true
            }
        }'
  3. Confirm the new addresses have been added to your access list:

    • cURL command (/v2)

    • Result

    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    [
      {
        "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"
          },
          {
            "address": "125.187.17.0/24",
            "enabled": true,
            "description": "Development"
          },
        ],
        "configurations": {
          "accessListEnabled": true
        }
      }
    ]

Deleting address or access lists

If you do not specify which addresses to delete, the entire access list is deleted.

When the entire access list is deleted, public access is no longer restricted.

  1. Check existing access lists within your organization or database to see which addresses are already on your access list:

    • cURL command (/v2): Get all access lists in organization

    • cURL command (/v2): Get access list in database

    • Result

    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/access-lists' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    [
      {
        "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"
          },
          {
            "address": "125.187.17.0/24",
            "enabled": true,
            "description": "Development"
          },
        ],
        "configurations": {
          "accessListEnabled": true
        }
      }
    ]
  2. Delete an address from your access list:

    • cURL command (/v2): Delete addresses from access list

    • cURL command (/v2): Delete entire access list

    curl --request DELETE \
      --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
          "addresses": [
              {
                "address": "125.187.17.0/24"
              }
            ]
        }'
    curl --request DELETE \
      --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
  3. Confirm the address no longer exists:

    • cURL command (/v2): Get all access lists in organization

    • cURL command (/v2): Get access list in database

    • Result

    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/access-lists' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/databases/<databaseId>/access-list' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    [
      {
        "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
        }
      }
    ]

For more, see Delete addresses or access list for database in the DevOps API.

What’s next?

Explore the DevOps API.

Managing multiple regions

Use the DevOps API to add or remove regions for your database.

The following roles use the application token to execute DevOps API queries:

  • Organization Administrator

  • Database Administrator

Prerequisites

  1. Create an application token to authenticate your service account in the DevOps API.

  2. Once you have authenticated your service account, you can add and removes regions in the DevOps API.

Adding a region to your database

You must have an existing database and payment method before you can add a new region. If you do not have a payment method for your database, you can add a payment method.

  1. Check existing regions for your database:

    • cURL command (/v2)

    • Result

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/databases/<databaseID>/datacenters' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
    {
    	"id": "1234-5678-91011121-3141",
    	"name": "dc-1234-5678-91011121-3141",
    	"tier": "Serverless",
    	"cloudProvider": "GCP",
    	"region": "europe-west1",
    	"regionZone": "emea",
    	"regionClassification": "standard",
    	"capacityUnits": 1,
    	"studioUrl": "http://path-to-studio:port",
    	"grafanaUrl": "http://path-to-grafana:port",
    	"cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
    	"graphqlUrl": "http://path-to-graqphl:port/api/graphql",
    	"dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
    	"secureBundleUrl": "http://s3-signed-bundle-url",
    	"secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
    	"secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
    	"secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
    }
  2. Add a new region to your database:

    • cURL command (/v2)

    curl --request POST \
      --url 'https://api.astra.datastax.com/v2/databases/<databaseID>/datacenters' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
          "tier": "Serverless",
          "cloudProvider": "<cloudProvider>",
          "region": "<region>",
        }'
  3. Confirm your region was added to the database:

    • cURL command (/v2)

    • Result

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/databases/<databaseID>/datacenters' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
    [
    	{
    		"id": "1234-5678-91011121-3141",
    		"name": "dc-1234-5678-91011121-3141",
    		"tier": "Serverless",
    		"cloudProvider": "GCP",
    		"region": "europe-west1",
    		"regionZone": "emea",
    		"regionClassification": "standard",
    		"capacityUnits": 1,
    		"studioUrl": "http://path-to-studio:port",
    		"grafanaUrl": "http://path-to-grafana:port",
    		"cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
    		"graphqlUrl": "http://path-to-graqphl:port/api/graphql",
    		"dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
    		"secureBundleUrl": "http://s3-signed-bundle-url",
    		"secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
    		"secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
    		"secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
    	}
    	{
    		"id": "9364-1208-04716476-8536",
    		"name": "dc-9364-1208-04716476-8536",
    		"tier": "Serverless",
    		"cloudProvider": "GCP",
    		"region": "us-east1",
    		"regionZone": "na",
    		"regionClassification": "standard",
    		"capacityUnits": 1,
    		"studioUrl": "http://path-to-studio:port",
    		"grafanaUrl": "http://path-to-grafana:port",
    		"cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
    		"graphqlUrl": "http://path-to-graqphl:port/api/graphql",
    		"dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
    		"secureBundleUrl": "http://s3-signed-bundle-url",
    		"secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
    		"secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
    		"secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
    	}
    
    ]

For more, see Invite a user to an organization in the DevOps API.

Delete a region from your database

The information displayed on the Connect page for your database is region specific.

Removing a region is not reversible. Proceed with caution.

  1. Check existing regions for your database:

    • cURL command (/v2)

    • Result

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/databases/<databaseID>/datacenters' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
    [
    	{
    		"id": "1234-5678-91011121-3141",
    		"name": "dc-1234-5678-91011121-3141",
    		"tier": "Serverless",
    		"cloudProvider": "GCP",
    		"region": "europe-west1",
    		"regionZone": "emea",
    		"regionClassification": "standard",
    		"capacityUnits": 1,
    		"studioUrl": "http://path-to-studio:port",
    		"grafanaUrl": "http://path-to-grafana:port",
    		"cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
    		"graphqlUrl": "http://path-to-graqphl:port/api/graphql",
    		"dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
    		"secureBundleUrl": "http://s3-signed-bundle-url",
    		"secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
    		"secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
    		"secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
    	}
    	{
    		"id": "9364-1208-04716476-8536",
    		"name": "dc-9364-1208-04716476-8536",
    		"tier": "Serverless",
    		"cloudProvider": "GCP",
    		"region": "us-east1",
    		"regionZone": "na",
    		"regionClassification": "standard",
    		"capacityUnits": 1,
    		"studioUrl": "http://path-to-studio:port",
    		"grafanaUrl": "http://path-to-grafana:port",
    		"cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
    		"graphqlUrl": "http://path-to-graqphl:port/api/graphql",
    		"dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
    		"secureBundleUrl": "http://s3-signed-bundle-url",
    		"secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
    		"secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
    		"secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
    	}
    
    ]
  2. Delete a region from your database:

    • cURL command (/v2)

    curl --request DELETE \
      --url 'https://api.astra.datastax.com/v2/databases/<databaseID>/datacenters/<datacenterID>/terminate' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
  3. Confirm your region was removed from your database:

    • cURL command (/v2)

    • Result

    curl --request GET \
     --url 'https://api.astra.datastax.com/v2/databases/<databaseID>/datacenters' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer <application_token>'
    {
    	"id": "1234-5678-91011121-3141",
    	"name": "dc-1234-5678-91011121-3141",
    	"tier": "Serverless",
    	"cloudProvider": "GCP",
    	"region": "europe-west1",
    	"regionZone": "emea",
    	"regionClassification": "standard",
    	"capacityUnits": 1,
    	"studioUrl": "http://path-to-studio:port",
    	"grafanaUrl": "http://path-to-grafana:port",
    	"cqlshUrl": "http://path-to-cqlsh:port/cqlsh",
    	"graphqlUrl": "http://path-to-graqphl:port/api/graphql",
    	"dataEndpointUrl": "http://path-to-dataendpoint:port/api/rest",
    	"secureBundleUrl": "http://s3-signed-bundle-url",
    	"secureBundleInternalUrl": "http://s3-signed-internal-bundle-url",
    	"secureBundleMigrationProxyUrl": "http://s3-signed-proxy-bundle-url",
    	"secureBundleMigrationProxyInternalUrl": "http://s3-signed-proxy-internal-bundle-url"
    }

For more, see Remove or uninvite a user from an organization in the DevOps API.

What’s next?

Learn more about using multiple regions.

Get private endpoints information with the DevOps API

Use the DevOps API to create, remove, and manage private endpoints.

You can use the DevOps API to perform the actions your role permissions allow.

The following roles can manage private endpoints:

  • Organization Administrator

  • Database Administrator

Alternatively, you can use a custom role with permissions to manage private endpoints.

Prerequisites

Ensure you have permission to manage private endpoints.

To increase your security, consider restricting public access to your database using the access list.

Getting a list of private endpoint configurations

  1. Check existing private endpoint configurations within your organization or database:

    • cURL command (/v2): Get all private endpoints in organization

    • cURL command (/v2): Get all private endpoints in database

    • Result

    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/organizations/<organizationID>/clusters/private-link' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseId>/private-link' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    {
      "provider": "aws",
      "region": "us-east-1",
      "description": "Private Endpoint B",
      "organizationId": "string",
      "datacenterID": "string",
      "endpoints": [
        {
          "id": "string",
          "dateActivation": "1997-12-09T02:03:33.57Z",
          "dateDeactivation": "1997-12-09T02:03:33.57Z"
        }
      ]
    }

Getting a list of private endpoint connections

  1. Check existing private endpoint connections within your organization or database:

    • cURL command (/v2): Get all private endpoint connections in organization

    • cURL command (/v2): Get all private endpoint connections in database

    • cURL command (/v2): Get all private endpoint connections in specified region

    • Result

    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/organizations/clusters/private-link' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/private-link' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
    curl --request GET \
      --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/private-link' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'

    If the database is only in a single region, datacenterID is your databaseID.

    {
      "clusters": [
        {
          "databaseID": "string",
          "datacenters": [
            {
            "serviceName": "com.amazonaws.vpce.us-east-1.vpce-svc-1148ea04af491da11",
            "allowedPrincipals": [
              "arn:aws:iam::123456789012:role/admin"
            ],
            "datacenterID": "string",
            "endpoints": [
              {
                "endpointID": "vpce-svc-1148ea04af491da11",
                "description": "ecomm-team-billing-app",
                "status": "Accepted",
                "createdDateTime": "2009-11-10T23:00:00"
              }
              ]
            }
          ]
        }
      ]
    }

What’s next?

Explore Private endpoints in the DevOps API.

Connecting to AWS PrivateLink

To better protect your database connection, you can connect to a private endpoint using the Astra DB private endpoint. Private endpoints are available for only intra-region use. The region for your private endpoint in the AWS console and your Astra DB database must match.

This information applies to only serverless databases.

For pricing related to using private endpoints, see Pricing and billing.

The following roles can manage private endpoints:

  • Organization Administrator

  • Database Administrator

Alternatively, you can use a custom role with permissions to manage private endpoints.

For more about AWS PrivateLink, see AWS PrivateLink.

Prerequisites

  1. Create your Astra DB database using the Astra DB console.

  2. Ensure you have permission to manage private endpoints.

  3. Get your application token.

Only VPC owners can create resources such as VPC endpoints, subnets, route tables, and NACLs. Participants cannot view, modify, or delete resources that belong to other participants or the VPC owner. Thus a user cannot create resources, including a private endpoint, in a shared VPC that is owned by a different AWS account. To see which account owns your VPC, look at the Owner ID in the AWS Console. Example:

Look at Owner ID in AWS Console

To increase your security, restrict public access to your database using the access list.

If you are using Postman for your API calls, ensure you use the raw option to enter the body of your API call.

  1. Get the allowed principal from your AWS account.

    1. In your AWS console on the Identify and Access Management (IAM) Users page, select your user name from the available users.

    2. Select the User ARN as your allowed principal. For example, arn:aws:iam::123456789012:root.

  2. Enter the allowed principal for your private endpoints to Astra DB:

    • cURL command (/v2)

    • Result

    curl --request POST \
      --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/private-link' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
          "allowedPrincipals": [
            "arn:aws:iam::123456789012:role/admin"
          ]
        }'

    To confirm your datacenter ID, see your database Dashboard or use the DevOps API to get all datacenter IDs within your database.

    {
      "serviceName": "com.amazonaws.vpce.us-east-1.vpce-svc-1148ea04af491da11",
      "allowedPrincipals": [
        "arn:aws:iam::123456789012:role/admin"
      ]
    }
  3. Use the serviceName to create an endpoint in your AWS Console.

    • CLI

    • AWS console

    Get a list of available services:

    aws ec2 describe-vpc-endpoint-services

    Results:

    {
        "VpcEndpoints": [
            {
                "VpcEndpointId": "vpce-08a979e28f97a9f7c",
                "VpcEndpointType": "Interface",
                "VpcId": "vpc-06e4ab6c6c3b23ae3",
                "ServiceName": "com.amazonaws.us-east-2.monitoring",
                "State": "available",
                "PolicyDocument": "{\n  \"Statement\": [\n    {\n      \"Action\": \"*\", \n      \"Effect\": \"Allow\", \n      \"Principal\": \"*\", \n      \"Resource\": \"*\"\n    }\n  ]\n}",
                "RouteTableIds": [],
                "SubnetIds": [
                    "subnet-0931fc2fa5f1cbe44"
                ],
                "Groups": [
                    {
                        "GroupId": "sg-06e1d57ab87d8f182",
                        "GroupName": "default"
                    }
                ],
                "PrivateDnsEnabled": false,
                "RequesterManaged": false,
                "NetworkInterfaceIds": [
                    "eni-019b0bb3ede80ebfd"
                ],
                "DnsEntries": [
                    {
                        "DnsName": "vpce-08a979e28f97a9f7c-4r5zme9n.monitoring.us-east-2.vpce.amazonaws.com",
                        "HostedZoneId": "ZC8PG0KIFKBRI"
                    },
                    {
                        "DnsName": "vpce-08a979e28f97a9f7c-4r5zme9n-us-east-2c.monitoring.us-east-2.vpce.amazonaws.com",
                        "HostedZoneId": "ZC8PG0KIFKBRI"
                    }
                ],
                "CreationTimestamp": "2019-06-04T19:10:37.000Z",
                "Tags": [],
                "OwnerId": "123456789012"
            }
        ]

    In the Amazon VPC console navigation pane, select Endpoints > Create Endpoint. The available serviceNames are listed in the Service Name section.

    The status for your private endpoint should show pending acceptance.

  4. Accept your AWS private endpoint connection with your serviceName:

    • cURL command (/v2)

    • Result

    curl --request POST \
      --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/endpoints' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
          "endpointID": "vpce-svc-1148ea04af491da11",
          "description": "project-desc-dev-app"
        }'
    {
      "datacenters": [
        {
          "serviceName": "com.amazonaws.vpce.us-east-1.vpce-svc-1148ea04af491da11",
          "allowedPrincipals": [
            "arn:aws:iam::123456789012:role/admin"
          ],
          "datacenterID": "string",
          "endpoints": [
            {
              "endpointID": "vpce-svc-1148ea04af491da11",
              "description": "project-desc-dev-app",
              "status": "Accepted",
              "createdDateTime": "2021-04-10T23:00:00"
            }
          ]
        }
      ]
    }

    Your AWS console will show that it is in the available state. For more, see Accept and reject endpoint connect requests.

  5. Create a DNS entry for your private endpoint.

    1. Download your secure connect bundle for the region of your choice. Get your latest secure connect bundle.

    2. Unzip the secure connect bundle.

    3. In config.json, copy the host key’s value.

    4. In the AWS Console, create a CNAME record that points to the DNS name found in your VPC Endpoint details.

    5. In the AWS Console, create a private zone to route traffic to your virtual IP using Amazon Route 53. Update the following domains to use REST and CQL:

      • REST

      • CQL

      efe451fe-709e-4700-9185-5cf0fd3474a7-2-us-east-1.apps.astra.datastax.com
      efe451fe-709e-4700-9185-5cf0fd3474a7-2-us-east-1.db.astra.datastax.com
    6. In the AWS Console, create a DNS entry for the key host value and map it to your virtual IP address.

You can now connect to your private endpoint using your updated secure connect bundle. For more, see Drivers for Astra.

Remove a private endpoint

  1. Delete a private endpoint from your Astra DB:

    • cURL command (/v2)

    curl --request DELETE \
      --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/endpoints/<endpointID>' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
  2. Remove your connection from AWS PrivateLink:

    • CLI

    • AWS Console

    aws ec2 delete-vpc-endpoint-service-configurations --service-ids <serviceId>
    1. In the Amazon VPC console navigation pane, select Endpoint Services.

    2. For the service you want to delete, select Actions > Delete.

    3. Select Yes, Delete to remove the connection.

Connect to Azure Private Link with the DevOps API

To better protect your database connection, you can connect to a private endpoint using the Astra DB private endpoint.

This information applies to only serverless databases.

For pricing related to using private endpoints, see Pricing and billing.

The following roles can manage private endpoints:

  • Organization Administrator

  • Database Administrator

Alternatively, you can use a custom role with permissions to manage private endpoints.

Prerequisites

  1. Create your Azure private endpoint.

  2. Disable network policies.

  3. Ensure you have permission to manage private endpoints.

To increase your security, consider restricting public access to your database using the access list.

  1. Get the allowed principal from your Azure account. This is your Subscription ID.

  2. Enter your Subscription ID as the allowed principal for your private endpoints to Astra DB:

    • cURL command (/v2)

    • Result

    curl --request POST \
      --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/private-link' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
          "allowedPrincipals": [
            "9cbbd094-fa31-490f-863d-897d01661681"
          ]
        }'

    To confirm your datacenter ID, see your database Dashboard or use the DevOps API to get all datacenter IDs within your database.

    {
      "serviceName": "test.a51y2a51-f9j4-4ad2-l863-67e5ac6g10m.westus2.azure.privatelinkservice",
      "allowedPrincipals": [
        "9cbbd094-fa31-490f-863d-897d01661681"
      ]
    }
  3. In your Azure Private endpoints, select Add.

    1. Select your Subscription and then your Resource group for your project.

    2. Enter your private endpoint name.

    3. Select the region for your private endpoint. This region should match your Astra DB region.

    4. Select Next: Resource.

    5. Select Connect to an Azure resource by resource ID or alias as your Connection method.

    6. Enter your serviceName as your Resource ID or alias.

    7. Select Next: Configuration.

    8. Select your Virtual network and Subnet from the menus.

    9. Select Review + create and then select Create to finish creating your private endpoint.

  4. Connect your Azure private endpoint connection:

    Your endpointId is the Resource ID for your private link endpoint, which is available in your Azure console by selecting JSON View for your private link endpoint. For example, /subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP_NAME/providers/Microsoft.Network/privateEndpoints/$ENDPOINT_NAME.

    • cURL command (/v2)

    • Result

    curl --request POST \
      --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/endpoints' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
          "endpointID": "/subscriptions/a51y2a51-f9j4-4ad2-l863-67e5ac6g10m/resourceGroups/lab-resourceGroups/providers/Microsoft.Network/privateEndpoints/dev-poc",
          "description": "project-desc-dev-app"
        }'
    {
      "datacenters": [
        {
          "serviceName": "test.a51y2a51-f9j4-4ad2-l863-67e5ac6g10m.westus2.azure.privatelinkservice",
          "allowedPrincipals": [
            "9cbbd094-fa31-490f-863d-897d01661681"
          ],
          "datacenterID": "string",
          "endpoints": [
            {
              "endpointID": "/subscriptions/a51y2a51-f9j4-4ad2-l863-67e5ac6g10m/resourceGroups/lab-resourceGroups/providers/Microsoft.Network/privateEndpoints/dev-poc",
              "description": "project-desc-dev-app",
              "status": "Accepted",
              "createdDateTime": "2021-04-10T23:00:00"
            }
          ]
        }
      ]
    }
  5. Create a DNS entry for your private endpoint. For more, see:

Your Azure portal will show that it is in the approved state.

Remove a private endpoint

  1. Delete a private endpoint from your Astra DB:

    • cURL command (/v2)

    curl --request DELETE \
      --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/endpoints/<endpointID>' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
  2. Remove your connection from your Azure portal:

    • Azure console

    • CLI

    1. In the Azure VPC console, select Private Link Center > Private endpoints.

    2. Select the checkbox beside the private endpoint you want to remove.

    3. Select Remove.

    Remove-AzPrivateEndpointConnection -Name myPrivateEndpointConnection1 -ResourceGroupName myResourceGroup -ServiceName myPrivateLinkServiceName

Connect to Google Cloud Private Service Connect with the DevOps API

To better protect your database connection, you can connect to a private endpoint using the Astra DB private endpoint. Private endpoints are available for only intra-region use. The region for your private endpoint in the Google Cloud Console and your Astra DB database must match.

This information applies to only serverless databases.

For pricing related to using private endpoints, see Pricing and billing.

The following roles can manage private endpoints:

  • Organization Administrator

  • Database Administrator

Alternatively, you can use a custom role with permissions to manage private endpoints.

Prerequisites

  1. Create your Astra DB database using the Astra DB console.

  2. Ensure you have permission to manage private endpoints.

  3. Get your application token.

  4. From your Google Cloud Console, get your Project ID. For example, valiant-ocean-258751.

  5. Create a Google Cloud Console network, subnetwork, and IP address for your private endpoint. For more, see Creating neworks.

To increase your security, restrict public access to your database using the access list.

If you are using Postman for your API calls, ensure you use the raw option to enter the body of your API call.

Connect to your Google Cloud Private Service Connect endpoint

  1. Enter the Project ID as your allowed principal for your private endpoints to Astra DB:

    • cURL command (/v2)

    • Result

    curl --request POST \
      --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/private-link' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
          "allowedPrincipals": [
            "valiant-ocean-258751"
          ]
        }'

    To confirm your datacenter ID, see your database Dashboard or use the DevOps API to get all datacenter IDs within your database.

    {
      "serviceName": "projects/<projectID>/regions/<regionName>/serviceAttachments/<serviceAttachmentName>",
      "allowedPrincipals": [
        "valiant-ocean-258751"
      ]
    }
  2. Create the endpoint in your Google Cloud Console.

    1. In the Google Cloud Console, go to Private Service Connect.

    2. Select Connect endpoint.

    3. Select Published service as the Target.

    4. Enter the 'serviceName' from the DevOps API result as the Target service.

    5. Enter a name for the Endpoint name.

    6. Select your Network and Subnetwork for the endpoint.

    7. Select an IP address for the endpoint.

    8. Select Add endpoint.

    The status for the endpoint will show as Accepted. This does not mean that the endpoint is ready for use and must be accepted in the Astra DB DevOps API.

  3. Using the PSC Connection ID from your Google Cloud Console as your endpoint ID, accept your Google Cloud private endpoint connection:

    • cURL command (/v2)

    • Result

    curl --request POST \
      --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/endpoints' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>' \
      --data '{
          "endpointID": "2755639674399101",
          "description": "project-desc-dev-app"
        }'
    .sh[]
    {
      "datacenters": [
        {
          "serviceName": "projects/<projectID>/regions/<regionName>/serviceAttachments/<serviceAttachmentName>",
          "allowedPrincipals": [
            "valiant-ocean-258751"
          ],
          "datacenterID": "string",
          "endpoints": [
            {
              "endpointID": "2755639674399101",
              "description": "project-desc-dev-app",
              "status": "Accepted",
              "createdDateTime": "2021-04-10T23:00:00"
            }
          ]
        }
      ]
    }

    Your Google Private Service Connect menu will show the private endpoint.

  4. Create a DNS entry for your private endpoint.

    1. Download your secure connect bundle for the region of your choice. Get your latest secure connect bundle.

    2. Unzip the secure connect bundle.

    3. In config.json, copy the host key’s value.

    4. In the Google Cloud Console, create a private zone to route traffic to your endpoint IP. Update the following domains to use REST and CQL:

      • REST

      • CQL

      efe451fe-709e-4700-9185-5cf0fd3474a7-2-us-east-1.apps.astra.datastax.com
      efe451fe-709e-4700-9185-5cf0fd3474a7-2-us-east-1.db.astra.datastax.com

      For more, see Create a private zone.

You can now connect to your private endpoint using your updated secure connect bundle. For more, see Drivers for Astra.

Remove a private endpoint

  1. Delete a private endpoint from your Astra DB:

    • cURL command (/v2)

    curl --request DELETE \
      --url 'https://api.astra.datastax.com/v2/organizations/clusters/<databaseID>/datacenters/<datacenterID>/endpoints/<endpointID>' \
      --header 'Accept: application/json' \
      --header 'Authorization: Bearer <application_token>'
  2. In the Google Cloud Console, go to Private Service Connect.

  3. Select the endpoint you want to remove.

  4. Select Delete.