Client Applications

There are three ways for client applications to connect to a running Datomic system:

Each of these options is described in detail below. 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.

Running in the Datomic Cloud VPC

Clients can run in the VPC provided by Datomic Cloud. This requires no additional setup, and is the recommended way to run client applications.

The storage stack creates a Virtual Private Cloud , named datomic-$(SystemName) in which to run a Datomic system. Inside this VPC, the stack creates 3 subnets named datomic-$(SystemName)-subnet-0, datomic-$(SystemName)-subnet-1, and datomic-$(SystemName)-subnet-2.

Simply launch your client application instances into any of these subnets, which are preconfigured for access to the Datomic system.

Separate VPC with VPC Endpoint

If your clients run in a VPC that you manage, and you are running Datomic storage version 397 or later, you can use a VPC Endpoint Datomic Network Load Balancer (NLB) to provide access to Datomic from your VPC. (For older versions of Datomic, use VPC Peering as described in the next section.)

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 VPC Service and Endpoint

  • In the CloudFormation Console browse to the Output tab of your Datomic compute or Query group stack
  • Find and record the Load Balancer Name reported under the key "LoadBalancerName"
  • Open the Endpoint Services Console
  • Click "Create Endpoint Service"
  • Choose the Network Load Balancer corresponding to the name you recorded from the CloudFormation Output
  • Click "Create Service"
  • Record the Endpoint Service address of the new service
  • Open the VPC Endpoints Console
  • Click "Create Endpoint"
  • Select "Find Service By Name"
  • Paste the VPC Endpoint Service address recorded in the prior step in the "Service Name" field
  • Click "Verify" to ensure the address is correct
  • Click "Create Endpoint"

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.

Deleting VPC Endpoint and Service:

You can delete a VPC Endpoint and Endpoint Service if you no longer need to access client applications from a separate VPC, or if you want to instead connect a VPC Link for HTTP Direct.

To delete an Endpoint and Endpoint Service:

  • First, delete the endpoint that is using the Endpoint Service. Generally this will be the API Gateway entry you are using for your Lambda Ions
  • In the CloudFormation Console browse to the Output tab of your Datomic compute or Query group stack
  • Find and record the Service Endpoint ID under the key "VpcEndpointServiceId"
  • Open the Endpoint Service Page
  • Find the Datomic Endpoint Service via the ID you recorded from the CloudFormation Output
  • Highlight the Service, click "Action" and "Delete Service"

Separate VPC with VPC Peering (Legacy)

If your clients to run in a VPC that you manage, and you are running an older version of Datomic storage (388 or earlier), you must create a VPC Peering Connection (For newer versions of Datomic, use a VPC Endpoint as described above.)

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.