Last updated February 07, 2025

This article describes how to use AWS PrivateLink to create a secure connection between an AWS VPC and a Heroku Key-Value Store (KVS) instance running in a Private Space or a Shield Private Space. This process involves three high-level steps:

1. Creating an endpoint service on your Private or Shield Heroku Key-Value Store instance
2. Creating an endpoint network interface in your AWS VPC
3. Establishing the secure connection between the two endpoints

As part of setting up the connection, you can specify a list of approved accounts to limit access to your KVS instance from the VPC.

Heroku Prerequisites

The following Heroku resources are required to set up a PrivateLink endpoint:

• A Private Space or Shield Private Space. Create a Private Space or a Shield Private Space using either the Heroku Dashboard or the Heroku CLI.
• A Heroku app running in the Private Space or Shield Private Space with an attached Heroku Key-Value Store instance. All Heroku Key-Value Store instances running in a Private Space or a Shield Private Space use one of the private or shield plan types, respectively. See Heroku Key-Value Store on how to create an instance.

Provisioning the Heroku Endpoint

Step 1: Install the Heroku Data via PrivateLink CLI plugin

To install the CLI plugin, run the command:

$ heroku plugins:install data-privatelink

Step 2: Obtain your AWS Account ID

You can obtain your AWS account ID with the AWS CLI:

$ aws sts get-caller-identity --output text --query 'Account'

123456789101

The example command returns an account ID of 123456789101.

You can also obtain your account ID from the Account page of your AWS account. The Account ID is shown in the Account Settings section:

Step 3: Create a PrivateLink Endpoint

Create a PrivateLink endpoint using the following Heroku CLI command and substitute the values:

$ heroku data:privatelink:create REDIS_ADDON_NAME --aws-account-id ACCOUNT_ID --app APP_NAME

• Replace REDIS_ADDON_NAME with the name of your KVS add-on, for example, redis-kvs-12345.
• Replace APP_NAME with your app’s name.
• Replace ACCOUNT_ID with the AWS account that should receive access to your KVS add-on. This ID can match any of the following patterns:
  • account-id
  • account-id:user/username
  • account-id:role/rolename

Here’s an example command with the output:

$ heroku data:privatelink:create redis-kvs-12345 --aws-account-id 123456789101:user/abc.xyz --app privatelink-vpc-endpoint-demo
Creating privatelink... done

Service Name: Provisioning
Status:       Provisioning

The PrivateLink is now being provisioned for redis-kvs-12345.
Run heroku data:privatelink:wait REDIS_URL -a APP to check the creation process.

Step 4: Obtain Your Endpoint’s Service Name

When the PrivateLink endpoint finishes provisioning, use the command to view its details:

$ heroku data:privatelink KVS_ADDON_NAME --app APP_NAME

Replace KVS_ADDON_NAME with the name of your private KVS add-on, and replace APP_NAME with your app’s name.

Here’s an example command with the output:

$ heroku data:privatelink redis-kvs-12345 --app privatelink-vpc-endpoint-demo
=== privatelinks for redis-kvs-12345
Service Name:         com.amazonaws.vpce.us-east-1.vpce-svc-0410a2e25933fe8ec
Status:               Operational

=== Allowed Accounts
ARN                                    Status
arn:aws:iam::123456789101:user/abc.xyz Active

Your privatelink is now operational.
You must now copy the Service Name and follow the rest of the steps listed in https://devcenter.heroku.com/articles/heroku-redis-via-privatelink.

Copy the value of the Service Name field from the command’s output. In the previous example, the service name is com.amazonaws.vpce.us-east-1.vpce-svc-0410a2e25933fe8ec. You need this value to provision the Amazon VPC endpoint.

Provisioning the Amazon VPC Endpoint

You perform the steps in this section from your Amazon VPC dashboard.

Step 1: Create and Configure a Security Group

Your endpoint requires a security group with appropriate ingress security rules. To create a security group:

1. Click Create security group in the Security Groups tab of your VPC dashboard.
2. In the Basic details section, specify a security group name and description, and select your desired VPC.
3. In the Inbound rules section, click to Add rule.
4. Enable TCP access to ports 6379 from any valid IP address.
5. Click Create security group.

Step 2: Create the Endpoint

To create an endpoint:

1. Navigate to the Endpoints tab of your VPC dashboard and click Create Endpoint.
2. Give a name for your endpoint in the Name tag field.
3. In the Type section, select the PrivateLink Ready partner services category.
4. In the Service settings section, paste the Service name value you obtained earlier.

5. Click Verify service to display the list of available subnets.

   

6. In the Network Settings section, select the VPC you specified when creating the Security Group.

7. In the Subnets section, select the subnets to enable and the Subnet ID, and select the IP address type to use.

8. In the Security group section, select the security group you created in the previous step, and click Create endpoint.

   

You see the endpoint you created with an initial status of pending acceptance, which transitions to available after 5-10 minutes.

Connecting the Heroku and Amazon VPC Endpoints

After the Amazon VPC endpoint becomes available, you can obtain the URL that allows your VPC to communicate with your Heroku Key-Value Store add-on.

First, obtain your PrivateLink endpoint’s endpoint ID and extract the 17-character string that appears at the end of it. Convert that string to upper case and use it in the following command. For example, if the endpoint ID vpce-01c87ae3c05563935, the endpoint ID is 01C87AE3C05563935.

Run the command, substituting the the string in ENDPOINT_ID_HERE:

$ heroku config --app your_app_name | grep ENDPOINT_ID_HERE

This command displays the AWS VPC Endpoint connection URL and the corresponding connection string for your KVS instance. The connection string has the following format:

redis://user:password@vpc-endpoint-dns-name:6379

You can now use this connection string to connect the applications in your AWS VPC to your private Heroku Key-Value Store instance. Here’s an example command with the output:

$ heroku config --app privatelink-vpc-endpoint-demo | grep 01C87AE3C05563935

REDIS_ENDPOINT_01C87AE3C05563935_URL:           redis://user:password@vpc-endpoint-dns-name:6379

Connecting to Heroku Key-Value Store from EC2 via VPC Endpoints

After you configure your VPC endpoints, you can create an EC2 instance in your AWS VPC to connect to Heroku Postgres.

In your EC2 dashboard, click Launch an instance. Give your instance a name and select the AMI type.

Then, select the instance type and key pair name. The example creates an Ubuntu t2.micro instance.

When configuring the network settings, select the VPC network with the security group you created earlier and pick an appropriate subnet. Review the summary of your instance and click Launch instance.

After the instance’s status transitions to running and all status checks have passed, connect to the instance using the SSH key pair you specified during instance creation.

After connecting to the instance, use the connection string to connect to KVS securely. The port number is 6379 not 6380 as it is when connecting via stunnel.

The following output shows the connection string used to connect to a Heroku Key-Value Store instance from within a sample EC2 instance with Ruby:

ᐅ ssh ubuntu@ec2-1-2-3-4.compute-1.amazonaws.com
Welcome to Ubuntu 18.04.1 LTS (GNU/Linux 4.15.0-1021-aws x86_64)
...<snip>...
ubuntu@ip:~$ sudo apt install ruby && sudo gem install redis
...<snip>...
ubuntu@ip:~$ irb
irb(main)> require "redis"
=> true
irb(main)> url = URI.parse("redis://password@vpce-id-secret.vpce-svc-id.us-east-1.vpce.amazonaws.com:6379")
irb(main)> url.scheme = "rediss"
irb(main)> $redis = Redis.new(url: url, driver: :ruby, ssl_params: { verify_mode: OpenSSL::SSL::VERIFY_NONE })
irb(main)> $redis.ping
=> "PONG"

Limitations

• You must provision the Amazon VPC endpoint you create in a subnet that’s in the same region as your Heroku Key-Value Store instance.
• You can only connect to your private KVS instance in availability zones that are common between your own VPC and the Heroku Data VPC.
• It’s your responsibility to verify the security of your VPC to ensure fully secure access to your Heroku Key-Value Store instance.