Configure AWS VPC peering

With VPC peering, your app running in your AWS VPC can communicate privately with an Aerospike Cloud database in the Aerospike Cloud VPC without traversing the public internet. VPC peering reduces latency and exposure, ensuring a more secure connection for your applications.

Prerequisites

• The AWS CLI is installed and configured.

• An existing AWS VPC with an IPv4 CIDR block that does not overlap with any of the following:

  • The CIDR block of the specific cluster you are peering with. Aerospike Cloud assigns this at provisioning as either an auto-generated value or a custom value you specify. Find it on the cluster Details tab → Infrastructure section → CIDR block field.

  • The internal services CIDR 10.129.0.0/24.

  • The CIDR block of any other VPC peering connection to the same Aerospike Cloud cluster that is active, pending, or being created.

• Basic familiarity with AWS VPC peering.

• DNS hostnames and DNS resolution are enabled in your VPC attributes.

Tip

Have your AWS VPC ID, AWS VPC CIDR, AWS Account ID, and AWS Region ready. Aerospike Cloud automates its side of the connection. You use these values to initiate and configure the connection from your AWS account.

Configure VPC peering

Complete these steps to peer your AWS VPC with Aerospike Cloud and configure routing, DNS, security groups, and connectivity.

Step 1: Create or identify your AWS VPC

Prepare your AWS VPC and collect the identifiers you need for the peering request.

1. Create a new VPC in AWS or verify your existing VPC.

2. Verify that the CIDR block does not overlap with the Aerospike Cloud CIDR blocks listed in the prerequisites.

3. Record the following details for your VPC:

   • VPC ID (for example, vpc-0abcd1234efgh5678)
   • CIDR block (for example, 10.0.0.0/16)
   • AWS account ID (for example, 123456789012)
   • AWS Region (for example, us-east-1)

Step 2: Initiate VPC peering

Request a peering connection from the Aerospike Cloud Console or API.

Aerospike Cloud Console

1. Open your cluster and go to the Networking tab → 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.
   • AWS Region: The AWS region of your VPC.
   • VPC ID: The identifier of your VPC (for example, vpc-0abcd1234efgh5678).
   • VPC CIDR: Your VPC’s IPv4 CIDR block (for example, 10.0.0.0/16).

4. Submit the peering request.

Aerospike Cloud API

1. Create a VPC peering request:

   curl -X POST "https://api.aerospike.com/v1/database/clusters/{clusterId}/vpc-peerings" \
     -H "Authorization: Bearer <YOUR_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "vpcId": "<YOUR_AWS_VPC_ID>",
       "cidrBlock": "<YOUR_AWS_VPC_CIDR>",
       "accountId": "<YOUR_AWS_ACCOUNT_ID>",
       "region": "<YOUR_AWS_REGION>",
       "isSecureConnection": true
     }'

2. Check the peering status:

   curl -X GET "https://api.aerospike.com/v1/database/clusters/{clusterId}/vpc-peerings" \
     -H "Authorization: Bearer <YOUR_TOKEN>"

   The response is a paginated collection. Each item in vpcPeerings describes one connection. Note the status field, for example initiating-request, pending-acceptance, or active.

   {
     "count": 1,
     "meta": null,
     "vpcPeerings": [
       {
         "id": "902aafd0-b46c-4f7b-a622-80e447c439ad",
         "accountId": "123456789012",
         "vpcId": "vpc-0abcd1234efgh5678",
         "cidrBlock": "10.0.0.0/16",
         "region": "us-east-1",
         "status": "initiating-request",
         "peeringId": "pcx-1410263943e464f4a",
         "isSecureConnection": true,
         "isRequester": true
       }
     ]
   }

What happens next?

Aerospike Cloud creates a peering connection request. The connection status reads Pending Acceptance until you accept it in your AWS account.

Step 3: Accept the peering request

Since Aerospike Cloud initiated the peering request, you must accept it in your AWS account.

AWS Console

1. Navigate to VPC → Peering Connections.

2. Select the pending peering connection containing your peering connection ID.

3. Select Actions → Accept request.

AWS CLI

Accept the peering connection:

aws ec2 accept-vpc-peering-connection \
  --vpc-peering-connection-id <YOUR_VPC_PEERING_CONNECTION_ID> \
  --region <YOUR_AWS_REGION>

Step 4: Update route tables

To route traffic from your VPC to the Aerospike Cloud database VPC, add route table entries in your VPC route tables.

Locate the route tables for each subnet that requires Aerospike access and add a route table entry to each one.

Each route table entry should include the following:

• Destination (Aerospike cluster CIDR): The cluster CIDR block from the Details tab → Infrastructure section.
• Target: The VPC peering connection ID, for example pcx-1410263943e464f4a

AWS Console

1. In VPC → Route Tables, locate the route tables for subnets that require Aerospike access.

2. Add a route to each required route table with:

   • Destination (Aerospike cluster CIDR): Enter the cluster CIDR block from the Details tab → Infrastructure section.
   • Target: The VPC peering connection ID, for example pcx-1410263943e464f4a

AWS CLI

Create the route table entry:

aws ec2 create-route \
  --region <YOUR_AWS_REGION> \
  --route-table-id <YOUR_ROUTE_TABLE_ID> \
  --destination-cidr-block <YOUR_AEROSPIKE_CLUSTER_CIDR> \
  --vpc-peering-connection-id <YOUR_VPC_PEERING_CONNECTION_ID>

Step 5: Associate private hosted zone (DNS)

Associate your VPC with Aerospike’s private hosted zone so database endpoints resolve to private IPs inside your network.

Mandatory step

DNS association is required to resolve Aerospike database endpoints. Verify that enableDnsSupport and enableDnsHostnames are set to true in your VPC settings. These settings appear as DNS hostnames and DNS resolution in the AWS VPC Console.

1. After the peering connection is accepted, get the hosted zone ID associated with your Aerospike Cloud database.

   Aerospike Cloud Console

   The hosted zone ID, for example Z04089311NGVVH0FO3QGG, is shown in the Infrastructure section of the Details tab of your Aerospike Cloud database.

   Aerospike Cloud API

   Get the hosted zone ID from the cluster’s infrastructure.hostedZoneId field:

   curl -X GET "https://api.aerospike.com/v1/database/clusters/{clusterId}" \
     -H "Authorization: Bearer <YOUR_TOKEN>"

   The response includes a hostedZoneId field nested under infrastructure, for example:

   {
     "infrastructure": {
       "hostedZoneId": "Z04089311NGVVH0FO3QGG",
       ...
     },
     ...
   }

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

   Note

   You can only perform this action with the AWS CLI, as the hosted zone is owned by an Aerospike Cloud AWS Account.

   aws route53 associate-vpc-with-hosted-zone \
     --hosted-zone-id <HOSTED_ZONE_ID> \
     --vpc VPCRegion=<YOUR_AWS_REGION>,VPCId=<YOUR_AWS_VPC_ID>

3. After a few minutes, DNS queries in your VPC, for example fcd8461a-49ee-42ea-ae08-7366a94e7654.aerospike.internal, resolve to Aerospike’s private IP addresses.

Step 6: Configure security groups

Follow these guidelines for configuring security groups in your VPC:

1. Add outbound rules that allow traffic on the following ports to the cluster CIDR block (from the Details tab → Infrastructure section):

   • TCP port 4000 for TLS client connections
   • (Optional) TCP port 9145 to the Aerospike Prometheus Exporter metrics port

2. Do not add an inbound rule that explicitly allows traffic from the Aerospike VPC block. Since security groups are stateful, if an instance in your VPC initiates a connection to the Aerospike VPC, the return traffic is automatically allowed back in.

Note

The Aerospike Cloud VPC is automatically configured to allow inbound traffic from peered VPCs and has outbound rules configured to ensure proper return traffic to your VPC.

Step 7: Test connectivity

Run the following from a host in your peered AWS VPC (for example, an EC2 instance or a pod). Commands do not work from your laptop unless it has network access to that VPC.

1. In the Aerospike Cloud console, open Clusters, select your cluster, and open the Details tab. In the Connection section, copy Hostname.

   Use the full value (for example, a1b2c3d4-e5f6-7890-abcd-ef1234567890.aerospike.internal) as HOSTNAME in the following steps. TLS port in the same section is 4000.

   For --tls-name, use the full Hostname value, not the bare Cluster ID from the General section.

2. Test DNS resolution. The following commands should return a list of private IPs, one for each Aerospike node:

   dig +short <HOSTNAME>

   Or:

   getent hosts <HOSTNAME>

   Use one of the returned addresses as NODE_IP for the TCP connectivity test.

3. Test TCP connectivity to the TLS port on a node IP from the previous step:

   nc -zv <NODE_IP> 4000

   If nc is unavailable:

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

   If port 4000 is closed, double-check route tables, peering acceptance, and security group outbound rules from step 6.

4. (Optional) Connect with Aerospike Quick Look (AQL).

   Before running AQL:

   • Install Aerospike Tools on the test host.
   • Create a database user with the roles you need.
   • On the Details tab, in the Certificates section, download or copy TLS certificate (save as a .pem file).

   Connect with TLS (port 4000). Use the same HOSTNAME for -h, --tls-name, and the host in the connection string:

   aql --tls-enable \
     --tls-name <HOSTNAME> \
     --tls-cafile <PATH_TO_CA_PEM> \
     -h <HOSTNAME>:4000 \
     -U <DB_USERNAME> \
     -P

   Enter the database user password when prompted. For more command options, see Run Aerospike Quick Look.

   Note

   If you see “Peers not reachable”, run AQL from inside the peered VPC. AQL discovers cluster peers and connects to node private IPs directly.

VPC peering status definitions

Throughout the VPC peering process, Aerospike Cloud and AWS indicate the status of the peering connection. Following are common statuses and their meanings:

• Pending Acceptance: The peering connection request has been created by Aerospike and is awaiting your acceptance in AWS. You must accept the request within seven days or it expires.
• Active: The peering connection is fully established. An active status on both sides means the link is ready for use (though you may still need to configure routing and DNS as described in step 4 and step 5).
• 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 few minutes 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. You would need to create a new request if you rejected by mistake.
• Expired: The request wasn’t accepted within the allowed time (seven days). The connection is not made and the request must be recreated if still needed.

In the Aerospike Cloud Console, these statuses may be labeled slightly differently (for example, Pending instead of Pending Acceptance) but the status is unchanged. 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 configured correctly as those steps are outside the raw peering status.

Troubleshooting

Use the following checks based on where the peering or connectivity process stopped.

If a failure occurs during provisioning

If the VPC peering connection fails to provision or shows a Failed status, verify the following:

• You entered the account ID for your VPC (Accepter) correctly.
• You have selected the correct ID for your VPC (Accepter).
• You entered the correct region for your VPC (Accepter).
• None of the primary or secondary CIDR blocks in your VPC overlap the cluster CIDR block or the internal services CIDR 10.129.0.0/24.

If any of these values are incorrect, delete the failed peering request and create a new one with the correct values.

If provisioning succeeded but you cannot connect

If the VPC peering status is Active, but you cannot connect to the database, check the following:

• Routing: Your subnet uses the correct route table, with a route to the cluster CIDR block pointing to the peering connection. Confirm that route entries exist in the route tables attached to your application subnets.
• DNS: DNS resolution returns Aerospike private IPs. Verify that the hosted zone association completed successfully, and that enableDnsSupport and enableDnsHostnames are set to true in your VPC settings. These settings appear as DNS hostnames and DNS resolution in the VPC Console UI.
• Ports: Client and AQL tests use TLS port 4000.
• Security groups: Your security groups allow outbound TCP 4000 to the cluster CIDR block. See AWS Security Group Rules documentation for more details.
• Network ACLs: No network ACLs are blocking the traffic.
• Propagation time: You waited at least 10 minutes after applying route changes for them to propagate.

The AWS Network Reachability Analyzer tool is helpful for debugging network connectivity issues.

Tip

If writes fail with FAIL_FORBIDDEN, the issue may be unrelated to connectivity or permissions. See FAIL_FORBIDDEN on writes for details.

Conclusion

After peering is active and routes are properly configured, your AWS resources (EC2, EKS, and similar compute services) communicate privately with Aerospike Cloud. This approach eliminates internet exposure and generally yields lower latency.

If you experience any issues connecting, see the Troubleshooting section.

What’s next

After VPC peering is configured, create database users and connect your applications:

• Create your first database user
• Configure Aerospike clients for application connectivity