Aerospike Cloud Quickstart

This quickstart walks you through:

• creating an Aerospike Cloud account.
• provisioning a database cluster.
• configuring VPC peering to connect from your AWS environment.

Before you begin

This quickstart assumes familiarity with AWS networking concepts (VPCs, subnets, route tables, security groups) and basic AWS CLI usage.

Before you begin, you need:

• an Aerospike Cloud account (you can create one in the first step).
• an AWS account.
• AWS CLI installed and configured with credentials for your AWS account.

Connection requirements are covered in Connect to your cluster from AWS.

Create an account

To create an Aerospike Cloud account with your email address and password, go to the Cloud console, click Register now and fill out the form.

You can also:

• Sign up with Google OIDC using an existing Google account.
• Accept an invitation from an existing user and join their Aerospike Cloud organization.

Note

New accounts do not have enterprise contracts by default. If you are setting up a new account, contact your sales specialist to get an enterprise billing plan for the Aerospike Cloud database clusters you need.

The Service Level Agreements (SLAs) of your new cluster depend on the number of zones and node count; consider your use case and what guarantees you need.

Provision your first cluster

Follow these steps to provision and launch your first Aerospike Cloud database cluster.

About node entitlements

New Aerospike Cloud accounts start with 0 node entitlements. To launch clusters, request node entitlements from Aerospike and provide your Organization ID (not just your user ID). See Entitlements.

1. In the Aerospike Cloud console, click Clusters, then click Provision cluster.

2. On the Provision a new cluster screen:

   1. Cluster name: Enter a name for your cluster.

   2. Namespace: Enter a namespace name.

   3. Cloud provider: Leave as AWS (default).

   Click Continue.

   Note

   AWS is preselected as the cloud provider.

3. On the Set deployment location and layout screen:

   1. Region: Select the region closest to your applications. For best performance and cost, deploy the cluster in the same region (and availability zone, if possible) as your application.

   2. CIDR block: Leave as auto-generated (default).

   3. Number of availability zones: Leave as 1 (default).

   4. Zone ID assignment: Leave as auto-assigned (default).

   Click Continue.

4. On the Configure availability and storage screen:

   1. Replication factor: Select 2 (recommended minimum).

   2. Consistency mode: Leave as default.

   3. Data storage: Choose In-memory or Hybrid memory based on your use case.

   Click Continue.

5. On the Select node size and count screen:

   1. Instance type: Select i4g.large.

   2. Cluster size: Leave as default.

   Note

   If you selected the ap-southeast-7 region, i4g instance types are unavailable. Select i4i.large instead.

   Click Continue.

6. On the Server configuration screen, click Review cluster. No changes are needed for this quickstart.

7. On the Review and launch cluster screen, verify your selections and click Launch cluster.

   Note

   Cluster provisioning typically takes ~20 minutes, depending on configuration. You can start the VPC peering setup (steps 1-3 in the next section) while the cluster launches, but you must wait for provisioning to complete before the peering request appears in AWS.

Connect to your cluster from AWS

To connect your applications to Aerospike Cloud, you must establish a VPC peering connection between your AWS VPC and the Aerospike Cloud VPC. This keeps traffic off the public internet, reducing latency and improving security.

Set up the connection

1. Open the networking settings in the Aerospike Cloud console.

   1. Go to your cluster in the Aerospike Cloud console.

   2. Click Finish setup → Set up network access, or go to the Networking tab.

2. Get your AWS VPC details.

   In the AWS Console:

   1. Go to VPC → Your VPCs.

   2. Select your VPC, or create one if needed.

   3. Verify the IPv4 CIDR does not overlap with 10.128.0.0/19 or 10.129.0.0/24.

   4. Record these values from the VPC details page. You need them in the next step:

      Value	Where to find it
      VPC ID	VPC details page (for example vpc-0abcd1234efgh5678)
      IPv4 CIDR	VPC details page (for example 10.0.0.0/16)
      AWS Account ID	Click your account name (top right) → copy the 12-digit Account ID
      Region	Region selector (top right), for example us-east-1

      Tip

      Use the region (for example us-east-1) in CLI commands, not the Availability Zone (for example us-east-1a).

   5. Go to VPC → Subnets and confirm at least one subnet exists for this VPC. If no subnets exist, click Create subnet, select your VPC, and choose an Availability Zone.

3. Initiate VPC peering.

   In the Aerospike Cloud console:

   1. Navigate to your cluster and go to Network connectivity → VPC peering.

   2. Click Create VPC Peering.

   3. Fill in the details of your AWS VPC:

      • AWS account ID: The 12-digit ID of your AWS account where your VPC resides.
      • VPC ID: The identifier of your VPC.
      • VPC region: Auto-filled from your cluster’s region.
      • VPC CIDR block: Your VPC’s IPv4 CIDR block.

   4. Under TLS connection, accept the default Accept only TLS connections (recommended).

   5. Click Create configuration. The Aerospike Cloud service initiates a VPC peering connection from the Aerospike VPC to your VPC.

   Aerospike’s AWS account creates a peering connection request. The connection status shows Pending Acceptance until you accept it in your AWS account.

   If peering fails

   Double-check that the AWS Account ID, VPC ID, and CIDR block are entered correctly and that your VPC CIDR does not overlap with Aerospike’s CIDR ranges.

4. Accept the peering request.

   Note

   The peering request only appears in AWS after your Aerospike cluster is fully provisioned. Wait for the cluster status to show as Active in the Aerospike Cloud console before proceeding.

   1. In the AWS Console: VPC → Peering Connections → select the pending peering → Actions → Accept request.
      • Or use the CLI:

        aws ec2 accept-vpc-peering-connection \
          --vpc-peering-connection-id pcx-1410263943e464f4a \
          --region us-east-1

5. Update route tables.

   1. In the AWS Console, go to VPC → Subnets.

   2. Select the subnet you identified earlier when getting your AWS VPC details (for example subnet-0abc1234def56789).

   3. Click the route table ID link (for example rtb-0e20f7173e8792fa0) to open the route table details page.

   4. Click your route table ID to get to the route table ID details page. Click Edit routes, then click Add route and enter:

      • Destination: 10.128.0.0/19
      • Target: Select Peering Connection, then select your peering connection (for example pcx-0577cf61346e2dd32)
      • Or use the CLI:

        aws ec2 create-route \
          --region <YOUR_REGION> \
          --route-table-id <YOUR_ROUTE_TABLE_ID> \
          --destination-cidr-block 10.128.0.0/19 \
          --vpc-peering-connection-id <YOUR_PEERING_CONNECTION_ID>

      The destination CIDR 10.128.0.0/19 is the Aerospike Cloud VPC CIDR, not your VPC’s CIDR. This route directs traffic destined for Aerospike through the peering connection.

   5. Click Save changes.

   Aerospike Cloud updates its VPC routes automatically on their side.

   Using EKS?

   If you use EKS, repeat this for each worker subnet to ensure all nodes can reach the Aerospike CIDR.

6. Associate private hosted zone (DNS).

   DNS association is required to resolve Aerospike cluster endpoints. Verify that Enable DNS resolution and Enable DNS hostnames are enabled in your VPC settings.

   1. After the peering connection is accepted, get the Hosted Zone ID (Zone ID, for example Z0123456789ABCDEFGHIJ) from the Networking tab in the Aerospike Cloud console.

   2. Associate your VPC with Aerospike’s private hosted zone:

      aws route53 associate-vpc-with-hosted-zone \
        --hosted-zone-id <HOSTED_ZONE_ID_FROM_CLOUD_CONSOLE> \
        --vpc VPCRegion=<YOUR_VPC_REGION>,VPCId=<YOUR_VPC_ID>

   Notes about Hosted Zones

   • The hosted zone is owned by Aerospike’s AWS account. You may not see it in your Route 53 console.
   • Use the region in VPCRegion (example us-west-2), not the Availability Zone (example us-west-2a).
   Verify the association

   You can validate association with:

   aws route53 list-hosted-zones-by-vpc \
     --vpc-id <YOUR_VPC_ID> \
     --vpc-region <YOUR_VPC_REGION>

   If your AWS permissions restrict Route 53 change lookups, verify with DNS resolution from inside the VPC (Step 8).

7. Configure a security group.

   1. In the AWS Console, go to VPC → Security Groups.

   2. Select an existing security group for your VPC, or click Create security group and enter:

      • Security group name: aerospike-client-sg
      • Description: Security group for Aerospike Cloud client access
      • VPC: Select your VPC

   3. Click Create security group.

   4. With your security group selected, click the Outbound rules tab, then click Edit outbound rules.

   5. Click Add rule and enter:

      • Type: Custom TCP
      • Port range: 4000
      • Destination: 10.128.0.0/19 (Aerospike VPC CIDR)
      • Description: Aerospike Cloud

   6. Click Save rules.

   You do not need to add inbound rules. Security groups are stateful, so return traffic from Aerospike is automatically allowed.

   Note

   The Aerospike VPC is automatically configured to allow inbound traffic from peered VPCs.

8. (Optional) Launch a test client in your VPC.

   If you already have an application host in your VPC, skip to step 9. Otherwise, launch a small EC2 instance to validate connectivity.

   In the AWS Console, go to EC2 → Instances → Launch instances. Select Amazon Linux 2023, t2.micro, a key pair (create one if needed), your VPC, a public subnet (with the route table from step 5), the security group from step 7, and enable Auto-assign public IP. Launch the instance and connect via SSH.

9. Test DNS resolution.

   Find the Hostname on the cluster Details tab in the Aerospike Cloud console. Run these commands from a host inside the consumer VPC (your EC2 test client or EKS pod).

   This dig command should return a list of private IPs, one for each Aerospike node:

   dig +short <AEROSPIKE_HOSTNAME>

   dig +short fcd8461a-49ee-42ea-ae08-7366a94e7654.aerospike.internal

   Example response

   10.128.1.8
   10.128.1.142

   If DNS does not resolve

   Confirm the private hosted zone association completed successfully and that Enable DNS resolution and Enable DNS hostnames are enabled in your VPC settings.

10. Test TCP connectivity to port 4000 using one of the IPs from step 9.

    If nc is available:

    nc -zv <IP_FROM_DIG> 4000

    If nc is not available, use bash TCP checks:

    timeout 3 bash -c 'cat < /dev/null > /dev/tcp/<IP_FROM_DIG>/4000' \
      && echo "4000 open" || echo "4000 closed"

    If port 4000 is open, your VPC peering, routing, and security group configuration is complete. Your application can now connect to Aerospike Cloud.

    If port 4000 is closed

    • In the AWS Console, go to VPC → Route tables, select your route table, and confirm a route to 10.128.0.0/19 targets the peering connection.
    • Go to VPC → Security groups, select your security group, and confirm an outbound rule allows TCP 4000 to 10.128.0.0/19.
    • Confirm the peering connection status is Active in both the AWS Console (VPC → Peering connections) and the Aerospike Cloud Console (Networking tab).

11. Connect to Aerospike using Aerospike Quick Look (AQL).

    1. Install Aerospike Tools on your EC2 instance.

       Follow the instructions at Install Aerospike Tools on Linux. After installation, verify with:

       aql --version

    2. Create a database user in the Aerospike Cloud console.

       Go to Access manager → Create database user. Enter a username and password, and select Read-Write access. This is separate from your Cloud console login. See Database users for details on access levels.

    3. Download the TLS certificate.

       In the Cloud console, go to Access manager → click Download CA certificate. This downloads a certificate.pem file to your local machine.

    4. Upload the certificate to your EC2 instance.

       Open a new terminal on your local machine (not the EC2 SSH session) and run:

       scp -i <PATH_TO_KEY_FILE> <PATH_TO_CERTIFICATE_PEM> ec2-user@<EC2_PUBLIC_IP>:~/certificate.pem

       Find your EC2 public IP in the AWS Console under EC2 → Instances → select your instance → copy the Public IPv4 address.

    5. Get the hostname from the cluster Details tab in the Cloud console (under Connection → Hostname).

    6. Connect with AQL.

       aql --tls-enable \
         --tls-name <HOSTNAME> \
         --tls-cafile ~/certificate.pem \
         -h <HOSTNAME>:4000 \
         -U <DB_USERNAME> \
         -P

       Enter your database password when prompted. When you see the aql> prompt, you are connected to your Aerospike Cloud cluster and can run queries.

    If you see “Peers not reachable”

    Ensure you’re running AQL from inside the VPC. AQL discovers cluster peers and tries to connect to node IPs directly.

Clean up resources

Tip

If you’re continuing to another Aerospike Cloud tutorial, skip this section. You can reuse your cluster, VPC peering, and EC2 instance.

If you created temporary resources to validate connectivity, clean them up when you’re done:

• Terminate the EC2 test instance you created in step 8.
• Delete the security group you created in step 7 (if no longer needed).
• Remove the database user you created in step 11.
• Delete your Aerospike Cloud cluster if you no longer need it.

Connection status reference

Throughout this process, you see status indicators for the peering connection in both the Aerospike Cloud console and the AWS Console. Here are common statuses and their meaning:

• Pending Acceptance: The peering connection request has been created by Aerospike and is awaiting your acceptance in AWS. In this state, you need to take action to accept the request. (If not accepted within 7 days, the request will expire.)
• Active: The peering connection is fully established. An active status on both sides means the link is ready for use (though routing/DNS may still need to be configured as described above).
• Provisioning: (Transient state) The request was accepted and AWS is in the process of making it active. This status usually changes to Active within a short time without further action.
• Failed: The peering request failed to establish. This can happen due to invalid parameters or network overlaps. A failed connection cannot be accepted or used. You may need to delete it and create a new request.
• Rejected: The peering request was explicitly declined by the accepter (your side). No connection is made. Create a new request if you rejected by mistake.
• Expired: The request wasn’t accepted within the allowed time (7 days). The connection is not made and the request must be recreated if still needed.

In the Aerospike Cloud console these statuses might be labeled slightly differently. For example, you may see “Pending” instead of “Pending Acceptance”. “Active” is the desired end state. If your connection shows “Active” but you cannot connect to the database, double-check that routes and DNS are set up correctly.

Next steps

You have now provisioned your first Aerospike Cloud database cluster and established connectivity from your own AWS VPC. Next, create a database user, set up observability, and build a client application you can connect to your new cluster.