Private Networks

GrapheneDB Private Networks are dedicated virtual networks into which multiple hosted GrapheneDB databases can be provisioned.

For every Private Network, a VPC is created in GrapheneDB’s AWS account. Databases can then be deployed within the Private Network, which can be secured via:

• public routing and IP Whitelisting and/or
• private routing and AWS VPC peering

All GrapheneDB databases are deployed in Private Networks, and then you can decide if you want to secure the database network or not.

📘

Note:

Private Networks are free of charge.

Creating a new Private Network

To create a new Private Network, navigate to GrapheneDB’s home page and click on the Create Private Network button:

A new modal window will be displayed, where you’ll need to enter the following information:

• Display name: This is a required field.
• AWS region: If you are going to establish a VPC peering connection, the Private Network has to be in the same AWS region as the application’s VPC you wish to peer to. This is a required field.
• IP Address range: An IPv4 CIDR block (of size /16 or smaller). This is a required field. Databases deployed within the Private Network will be automatically assigned private IP addresses from this subnet. If you plan to use VPC peering, the address space should be carefully chosen to avoid collisions with other address ranges in your peered deployments. If you don’t plan to use VPC peering, the private IP address will not be used to route your traffic and it’s recommended to use the default address space (172.30.0.0/16). For guidance on choosing an IP address range, please refer to the section on this page.

Please review this information carefully and click on the Create Private Network button to proceed. Once created, you’ll be redirected to the Network’s settings page, where you’ll be able to further configure it.

Choosing an IP address range

📘

Note:

Picking the right IP address range correctly is of vital importance for private routing when doing VPC peering. If you don’t plan to do private routing with VPC peering, we recommend to use our default value (172.30.0.0/16).

Databases deployed within a Private Network will be assigned a private IP address from the IP address range configured.

When accessing from a properly configured peered VPC, traffic is routed to this private IP address. When not accessing from a peered VPC, traffic is routed to the public IP address, so that the private IP address of the database server becomes irrelevant.

Thus, if you are planning to do private networking using VPC peering, it is important that you choose an IP address range that doesn’t overlap with any other address range in your deployments.

The IP address range is a range of IPv4 addresses in the form of a Classless Inter-Domain Routing (CIDR) block. IPv6 is currently not supported.

The available IP address ranges are in the 172.x.y.z/n address space, where:

• 16 ≤ x ≤ 31
• 16 ≤ n ≤ 25

Not allowed:

• 172.28.0.0/16
• 10.100.0.0/16

Good options are:

• 172.19.0.0/16, 172.21.0.0/16, 172.23.0.0/16, 172.25.0.0/16, 172.27.0.0/16, 172.29.0.0/16, 172.31.0.0/16

Bad options are:

• 172.16.0.0/16 - heavily used
• 172.17.0.0/16 - Docker’s default

Configuring a Private Network

You can configure an existing Private Network from the Private Network’s homepage, by clicking on the Configure link for the corresponding Private Network:

You’ll be taken to the Private Network’s homepage, where the following options will be available:

• Access mode
• IP whitelist
• VPC peering
• Deletion

Access modes and network routing

For every database hosted with GrapheneDB, a DNS record is created pointing the public IP address of the server hosting the database.

For databases that are on the default public network and not within any Private Network, connections always rely on the public hostname resolution to the public IP address. Inbound connections to the databases are always allowed, regardless of their origin.

With Private Networks, the databases that are deployed inside of it can be protected by restricting inbound traffic. Private Networks have 2 access modes: Private and Public.

In private access mode, the Private Network will only allow connections from the public IP addresses in the IP Whitelist and reject incoming traffic from any other source, except GrapheneDB’s internal infrastructure.

In public mode, inbound traffic is allowed, regardless of its origin.

Please note that the terms Public and Private used for the access mode refer as to whether inbound connections from any source will be allowed or not. It is not related in any way with using public or private IP addresses for networking. You can find more information on this topic below in Understanding network routing.

Private mode

This is the default access mode and protects all databases in the Private Network from unwanted network connections.

In Private access mode, no inbound network connections will be allowed, except when originating from:

• public IP addresses in the IP Whitelist of the Private Network
• VPCs with the Private Network
• GrapheneDB’s internal infrastructure

In order to connect to a database inside a Private Network configured in Private mode, you have the following options:

• add public IP addresses to the IP Whitelist: traffic from these IPs will be explicitly allowed
• add VPC peering connections and access the databases using their private IP addresses from the peered VPCs

Public mode

In Public mode, all traffic to the database is allowed and the IP Whitelist is ignored. Be very careful when setting your network to Public mode!

Peered VPCs will continue to route traffic to the Private Network using the private IP address space.

🚧

Important:

Since Public mode makes your network available to all traffic, we recommend only using Public mode sparingly. For example, you can temporarily enable public mode on your Private Network to test you are not locking out your own traffic.

Understanding network routing

VPC peering connections rely on the private IP address space for networking. This means connections from peered VPCs will always work, regardless of the access mode set.

Private routing from peered VPCs is achieved with the DNS resolution built into VPC peering, which will resolve public hostnames to private IP addresses for peered VPCs.

All connections that are not originating from peered VPCs will rely on public hostnames and public IP addresses. To protect such connections, the Private access mode can be used alongside an IP Whitelist.

Please note that the IP Whitelist and VPC peering connections can be used simultaneously to allow access to the databases inside a Private Network.

Example: 2 servers access a database hosted inside a Private Network configured in Private mode.

• Server A is hosted in the customers’ VPC and connects to the database using VPC peering and DNS resolution.
• Server B is hosted in another AWS region or cloud provider. Its public IP address is added to the IP Whitelist of the Private Network.

Change from Private mode to Public

To change the access mode from Private to Public, please navigate to the Private Network homepage. In the Access mode section, click on the Public radio button.

A warning dialog will be displayed. To proceed, click on the button Switch access mode to Public.

📘

Note:

Please use Public mode carefully. It is not recommended to leave your Private Network on Public mode. Only use Public mode temporarily and for testing purposes only.

❗️

Important:

DNS host resolution should be disabled in the AWS console when switching the Private Network mode to Public in case public traffic is desired. Public mode means only that all connections are allowed, while the DNS resolves to private IPs unless DNS host resolution is disabled.

Change from Public mode to Private

To change the access mode from Public to Private, please navigate to the Private Network homepage. In the Access mode section, click on the Private radio button.

A warning dialog will be displayed. To proceed, click on the button Switch access mode to Private.

IP Whitelisting

The IP Whitelist provides a way to allow access for a certain group of public IP addresses to all databases inside a Private Network.

📘

Note:

The IP Whitelist will be ignored if the Private Network is set to Public access mode.

Adding an IP address to the IP Whitelist

🚧

Important:

Until they are removed again, IP addresses in the IP Whitelist will have be able to access any database inside the Private Network.

You should only use public IP addresses which are static and shared only with trustworthy peers.

To add a new address to the IP Whitelist:

1. Navigate to the Private Network homepage and click on the Add IP address button.
2. Enter the requested information:

• Display name
• IP address: A unique public IPv4 address (IPv6 not supported) that will be allowed to access the databases inside the Private Network

3. Click on the Add IP address button. You should now see the IP address you just added listed in the Whitelist

Adding your current public IP address to the IP Whitelist

🚧

Important: Public IP addresses are commonly shared

Your current public IP address is the same address that you are currently using with your internet browser.

Since public IP addresses are often shared, this can be especially dangerous when you are accessing from a public network, such as wifi from café or a network from a large organization (university, big corporation).

By allowing access from this IP address, you are allowing access for anyone else using the same public IP address until it is removed from the IP Whitelist. Be careful when adding your current public IP address to your whitelist.

For your convenience, we’ve added a way to retrieve your current public IP address, so you can easily add it to the IP Whitelist. To do this:

• Navigate to the Private Network homepage and click on the Add IP address button.
• Click on Retrieve current public IP address to insert the IP address into the corresponding field
• Click on the Add IP address button. You should now see the IP address you just added listed in the Whitelist

🚧

Important:

There is a max limit of 18 total whitelisted IPs and VPC peering connections that can be added into a Private Network.

• The sum of whitelisted IPs + VPC peers yield the total.

Once you hit the maximum for a Private Network, attempting to add additional entries will result in an error message. In order to add new entries, you must first remove an existing VPC peering connection or IP.

Removing an IP address from the IP Whitelist

To remove an IP address from the IP Whitelist, navigate to the Private Network homepage, and click on the Remove IP address link for the corresponding IP address you wish to remove.

A confirmation dialog will be displayed. To proceed and remove the IP address from the IP Whitelist click on Remove IP address.

The IP address will be removed and the IP address will no longer be visible in the IP Whitelist.

VPC peering

If your infrastructure is deployed on AWS, you can create VPC peering connections and benefit from private network between your VPCs on AWS and the underlying VPC of your Private Networks in which your GrapheneDB databases deployed.

By doing this, the traffic between your infrastructure and your databases can be routed through private IP addresses instead of public, while keeping the Private Network and its databases protected from public network traffic.

🚧

Important:

In order for VPC peering to work, please ensure that:

• the Private Network and the peering VPC are placed in the same AWS region
• the IP address range of your Private Network does not overlap with the subnets in use in your AWS VPCs

For every Private Network, GrapheneDB will create a VPC in GrapheneDB’s AWS account.
To establish secure connections between your VPCs follow the steps below to create a new VPC peering connection.

Creating a new VPC peering connection

Please follow these steps to create a new VPC peering connection:

1. Navigate to the VPC peering section within the Private Network’s homepage and click on the Add VPC peering connection button
2. Fill out the necessary information:

• Display name: This field is required.
• AWS Account ID: The ID of the AWS account where the VPC to peer with is hosted. This field is required. Read more on where to find your AWS ID here.
• VPC ID: The ID of the VPC to peer this Private Network with. This field is required. Learn where to find your VPC ID here.

3. Click on Start VPC peering process to initiate the peering request.
   You should see the newly created peering request in the VPC peering section.

4. Accept the peering request in your AWS console. You’ll find the request under the Peering Connections section on the VPC page. You can find out more on where to find this information here.

5. After accepting the request you should see Active in the VPC peering section of the Private Network.

📘

Note:

Please note that it can take a bit of time before the Private Network acknowledges the peering request was accepted. You can speed up the process by clicking on the Refresh button in the peering section.

After creating the VPC peering connection, please configure the peered VPC for private routing. Without taking these additional steps, it won’t be possible to connect across VPCs using private IP addresses.

How to find your AWS account ID

To establish a peering connection between a database in a Private Network and your own VPC, you’ll need to provide your AWS account ID. You’ll find it by clicking on Support in the navigation bar of your AWS Management console in the upper-right, and then clicking Support Center. Your account ID will appear in the upper right-hand corner below the Support menu.

How to find your VPC ID

To establish a peering connection between a database in a Private Network and your own VPC you’ll need to provide your VPC ID.

To get your VPC ID, navigate to your VPC Dashboard in your AWS Management console, and copy the ID under the VPC ID column.

How to accept a peering connection on AWS

Please navigate to VPC Dashboard on your AWS Console and click on Peering Connections on the left side menu.You should see the newly created request from GrapheneDB. Select the request and and then choose Accept Request from the Actions dropdown menu.

📘

Note:

The VPC peering connection request is awaiting acceptance from the owner of the accepter VPC. During this state, the owner of the requester VPC can delete the request, and the owner of the accepter VPC can accept or reject the request. If no action is taken on the request, it expires after 7 days.

Configuring the peered VPC for private routing

Once the VPC peering connection has been created, connecting the remote VPC with the underlying VPC of the Private Network will require further configuration in order to benefit from private routing.

🚧

Important:

When using a cluster within VPC peered connections, you should be adding private in the URI .
Example: db-private-12xc444sfnb7.graphenedb.com
This does not apply to singles.

The remote VPC’s network routing table needs to be updated to include a route to the Private Network’s subnet, and private DNS resolution needs to be enabled, so that network traffic relies on private instead of public IP addresses.

Please complete the following steps to configure the peered VPC for private networking:

1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/ and navigate to the VPCs
2. Next, go to the Routes table section on the left hand side of the AWS console and click on the Route table ID you're using for this VPC peering. Then, please click on Edit routes. Destination should be GrapheneDB Private Network IP address range (Requester VCP CIDR) and Target should be a peering ID. Click on Save changes.

Once that is done, when you select the desired Route table ID and click on the Routes tab, you should be able to see it in the targets list: pcx-xxxxxxxx (with the Destination of GrapheneDB Private Network IP address range)

3. Now, in the AWS navigation pane, choose Your VPCs > select the VPC ID you're using for this setup, and choose Actions, Edit VPC settings. Enable DNS resolution and DNS hostnames, so that any hostnames for databases in the Private Network resolve to their private IPs.

Finally navigate to the Peering Connections on the left-hand side menu, select Peering connection you used, and go to Actions > Edit DNS resolution. Tick the checkbox Allow requester VPC (vpc-xxxxxx) to resolve DNS of accepter VPC (vpc-xxxxxx).

You can find more information on these topics in the AWS documentation:

• Route tables for VPC peering
• Enabling DNS resolution in VPC peering connections

Managing VPC peering connections

If there are any VPC peering connections, these will be displayed in the corresponding section of the Private Network’s homepage.

For every VPC peering connection, the following details are displayed:

• Name: The display name supplied for the VPC peering connection
• Peering Connection ID: The ID assigned by AWS for this peering connection. Use this reference to update the routing table of the peered VPC.
• Peered VPC: The ID of the peered VPC
• Peered Account ID: The ID of the remote AWS account
• Peered CIDR block: The IPv4 CIDR block of the peered VPC
• Status: This will reflect the current status of the VPC peering connection. Peering requests pending acceptance are refreshed regularly. If you have recently accepted the peering request but the status has not updated yet in the UI, please use the Refresh link.

VPC Peering Connection status

When a VPC Peering Connection is created, the status will be transition to Pending Acceptance or Failed.

Pending Acceptance status

If the VPC Peering Request is created successfully, it needs to be accepted on the peering side, in order for the connection to be finally established.

Once the VPC Peering Request has been accepted, the status will transition to Active.

Active status

If the VPC Peering Connection has been accepted on the peering side, the connection becomes active.

Please keep in mind that even when the status is displayed as Active, some configuration is needed on the peering side in order for private networking to function properly. For instructions on configuring the peered VPC for private networking please read this section.

Failed status

If AWS fails to create the VPC Peering Connection, its status will be displayed as Failed.
To view the error message provided by AWS, please click on the View error link next to the Failed status.

The VPC peering connection can fail for following reasons:

• the Private Network and the peering VPC have overlapping IPv4 CIDR blocks, or
• the AWS account ID and VPC ID are incorrect or do not correspond with each other

If the VPC peering connection fails, try resolving the issue and creating a new VPC peering connection again. Failed VPC peering connections are not automatically deleted. You can optionally do this manually by using the Delete VPC Peering Connection link.

Deleting a VPC peering connection

To remove a VPC peering connection, navigate to the VPC Peering Connections section of the Private Network’s homepage and click on the corresponding Remove link.

A confirmation dialog will be displayed. To permanently delete the VPC peering connection, click on the Delete VPC Peering Connection button.

Deleted VPC Peering Connections cannot be recovered. To connect to the same VPC, just create a new VPC Peering Connection.

Creating a database in a Private Network

Creating a database in an existing Private Network

If you’ve already created a Private Network, you can select the Private Network you want in the Select placement section when creating a new database.

When a Private Network is selected, the AWS region of the Private Network is displayed for verification, as well as the names and count of the databases that are hosted in it.

🚧

Important:

Please note that Private Networks are in Private access mode by default. In order to connect to the database, you will need add entries to the IP Whitelist, create VPC peering connections or switch the access mode to Public.

Creating a database in a new Private Network

When creating a new database, a message is be displayed in the Placement section of the New Database page if there is no Private Network available on your account:

The Private Network is created in the next step.

To proceed, please enter the database details (Neo4j version and database name) and click on the Create database button.

A modal window will be displayed prompting to enter the configuration details of the Private Network:

To proceed, click on the button Create Private Network and database. A Private Network will be created and the database will be provisioned inside.

🚧

Important:

Please note that Private Networks are in Private access mode by default. In order to connect to the database, you will need add entries to the IP Whitelist, create VPC peering connections or switch the access mode to Public.

Migrating an existing database to a Private Network

Databases cannot be moved from a Private Network to another. The only way to do it is to clone the desired database into a new one in the Private Network of your choice.

More information on the clone procedure can be found here.

Deleting a Private Network

You can delete a Private Network by navigating to the Private Network page and clicking on the Delete Network button.

🚧

Important:

You can only delete Private Networks that have no databases inside. If you want to delete a Network with one or more databases, you’ll need to either remove the databases first.

Troubleshooting

Peering connection active on AWS, but still pending on GrapheneDB

Peering requests pending acceptance are refreshed regularly. If you have recently accepted the peering request but the status has not updated yet in the UI, please use the Refresh link at the top of the VPC peering connections list. It will force looking into it and getting the needed information to finish the peering connection.