Connecting to AWS Neptune From Local Environment

I have recently started a new project in which we decided to give AWS Neptune a try. To make sure our developers had a decent development experience, I wanted to give them the ability to connect to a Neptune instance within their local development environment.

The challenge with connecting to an AWS Neptune instance is that they are only reachable within the VPC in which they are set up. The workaround is to have a bastion server in that same VPC that can be reachable from your local environment, and use ssh local port forwarding from your computer to connect to the Neptune instance.

Setup

1- Create Bastion Server

The first step of the setup is to create the bastion server. Since all it’s doing is forwarding network traffic, you can probably get away with a t2.nano. There’s really nothing needed to be set up in that instance other than making sure:

• it’s in the same VPC as the Neptune instance
• it’s in a subnet that can reach the Neptune subnet
• the security group allows inbound connection from your local environment and outbound to the Neptune instance (port 8182 is the default)
• you start the instance with a key you have access to

2- Configure Your SSH Agent

Next step is to set up your ssh agent configuration to connect to the bastion server. You should be able to find your config file on ~/.ssh/config, or create one if it doesn’t exist. Append the following to the file:

Host <bastion server ip here>
  Hostname <bastion server ip here>
  Port 22
  User ec2-user
  IdentifyFile ~/.ssh/<key name>.pem

After you do that, you might need to reload your ssh agent:

killall ssh-agent; eval "$(ssh-agent -s)"

ps. - remember that this might cause you to have to re-add ssh keys.

3- Start Local Port Forward

Last step, which is required to repeat everytime you want to start the connection, is to open a terminal window and run the following ssh command, substituting with your neptune and bastion server ip:

ssh -L 8182:<neptune endpoint>:8182 <bastion server ip>

If the command is successful, it will connect to the bastion server just like any other ssh connection, but as long as you keep that ssh session open, all requests to your localhost:8182 will be forwarded to the Neptune instance. You should be able to confirm the setup is working by pointing your browser to http://localhost:8182 and seeing a JSON response.