Serverless databases: Connect via a private endpoint

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

Private endpoints available on only serverless databases.

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.

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.

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.

What’s next?

For more about adding private endpoints with the DevOps API, see the DevOps API reference.