Client Applications

Throughout this page, the following metavariables are used:

  • SystemName is the Datomic system name
  • GroupName is a Datomic compute group name. For the primary compute group, this is the SystemName. For a query group, this is the name of the query group.
  • Region is the AWS region in which the Datomic system is running.

Connecting Client Applications

The Storage CloudFormation stack creates a Virtual Private Cloud , named datomic-$(SystemName) in which to run the Datomic system. Inside this VPC, the stack also creates an applications security group named $(SystemName)-apps that you can use for client applications running in the Datomic system VPC. The security group that the Datomic system instances run in allows access from the applications security group.

Client Application in Separate VPC

We recommend client applications use the $(SystemName)-apps security group in the Datomic Cloud VPC.

However, if you have a pre-existing VPC in which your application runs, you can use a VPC Endpoint to the Datomic Network Load Balancer (NLB) to provide access to Datomic from your VPC.

Prerequisites

  • Your application VPC must be in the same AWS region as your Datomic Cloud system
  • Your VPC must contain at least one subnet in the same Availability Zone (AZ) as one of the Datomic subnets
  • VPC Endpoints are only supported in a Production Topology.

Verifying Subnet AZs

Find your Datomic System subnets and your application VPC subnets in the subnet list of the VPC Dashboard, taking note of the Availability Zones.

If at least one of your application VPC subnets is in the same AZ as one of the Datomic system subnets, you can proceed to create your VPC endpoint.

If your application VPC does not contain any AZ-matching subnets, you will need to create an additional subnet (or subnets) in your VPC in one of the AZs used by your Datomic system subnets.

Creating a VPC Endpoint

You can use this CloudFormation Template as a reference for creating and configuring a VPC Endpoint. This CloudFormation Template queries a running production Datomic system in the same account using parameters you specify when you launch it. Launch the template via the Create Stack dialog. You can modify this template to meet the needs of your use case.

Note: This template does not support Update stack. You need to delete and recreate the stack to make changes.

"Select Template" Screen

  1. Under "Choose a Template", select the "Specify an Amazon S3 template URL" option. Paste the URL (https://s3.amazonaws.com/datomic-cloud-1/cft/vpc-endpoint/vpc-endpoint-template.json) of the VPC Endpoint Template in the input field.
  2. Click the Next button

"Specify Details" Screen

Fill in the template's parameter values as specified below.

Stack name
Choose a name for the VPC Endpoint Stack.
Group Name
The name of your Datomic compute group.
VPC Id
The ID of the VPC you will use for your application.
Subnet Ids
Up to 3 subnets in your VPC that you will use for your application. Note: These subnets must be in the same AZs as the subnets in the Datomic Cloud VPC.

Click the Next button.

"Options" Screen

  1. Leave the default settings
  2. Click the Next button.

"Review" Screen

  1. Under "Capabilities", click the checkbox stating "I acknowledge that AWS CloudFormation might create IAM resources with custom names." ../images/check-iam-capabilities.png
  2. Click "Create" to launch the stack.

The endpoint will be given an automatically-generated name, and we recommend that you create a Route53 Record for the endpoint to provide a permanent application-friendly name for the entry.

Configuring Endpoint

Once the CloudFormation Stack is created successfully, look in the Outputs tab and take note of the VpcEndpointServiceId and VpcEndpoint value.

Select the entry in the endpoint service list. whose ID is equal to your VpcEndpointServiceId.

In the bottom panel of the screen, switch to the Endpoint Connections tab, and select the entry whose EndpointId is equal to your VpcEndpoint.

Select Actions and click "Accept Endpoint Connection Request".

After accepting the connection, the endpoint status will display "Pending". After a few minutes, it will transition to "Available".

Open Security Group

Application code in your VPC needs permission to access the VPC Endpoint security group. Find (or create) a security group that you will associate with your application instances/lambdas.

  1. Navigate to the Security Groups section of the AWS EC2 Management Console
  2. Click on the VPC Endpoint security group, named <group-name>-endpoint.
  3. Click the Inbound tab in the Security Group details at the bottom of the console.
  4. Click Edit to display the Edit inbound rules dialog box.
  5. Add an entry with the following parameters:
    • Type: Custom TCP Rule
    • Protocol: TCP
    • Port Range: 8182
    • Source: <Your application security group>
  6. Accept the defaults for the other entries, and click Save

Using the VPC Endpoint

You must use the VPC Endpoint DNS (or Route53 entry if you created one) and port 8182 for the :endpoint parameter in your Datomic client configuration when connecting from your VPC:

(def cfg {:server-type :ion
          :region "<your AWS Region>" ;; e.g. us-east-1
          :system "<system-name>"
          :endpoint "http://<VpcEndpointDns>:8182"})

The endpoint DNS name can be found in the Outputs of the VPC Endpoint CloudFormation Stack under the VpcEndpointDns key.

VPC Peering for Older Versions of Datomic Cloud

NOTE Versions of Datomic Cloud prior to 397 use an Application Load Balancer instead of an NLB and can't be targeted with a VPC Endpoint. Accessing Datomic from a separate VPC in versions older than 388 only can be achieved with VPC Peering:

If you run your applications in a different VPC than the one the Datomic system stack created, you must create a VPC Peering Connection between your VPC and the VPC the Datomic system stack creates.

See the AWS documentation for

If you want to allow applications in your existing VPC to refer to the Datomic system entry point using its DNS name, entry.$(SystemName).$(Region).datomic.net:8182, you must follow the last step above, "Associating a VPC with a Private Hosted Zone." In this step, associate your existing VPC with the Datomic system Route 53 Hosted Zone, named $(SystemName).$(Region).datomic.net. This allows the Datomic system VPC to handle private DNS resolution of the datomic.net domain for your VPC.

Note: If your application does not run in the provided datomic-$(SystemName)-apps security group, you must configure the datomic-$(SystemName)-entry security group to allow ingress from your application's security group.