Skip to content

Load balancer configuration#

If you're deploying Neptune on your own hardware with ingress_controller set to embedded (the default) and service_exposition_type set to NodePort, Neptune will be exposed on port 30080 on each node of the cluster.

An external load balancer has to be configured to terminate the SSL/TLS connection and forward traffic to all nodes to port 30080.

In the case of deployment on a single VM, there's only a single node.

Any SSL-stripping load balancer should work, provided it adds x-forwarded-for, x-forwarded-port, x-forwarded-proto, and x-forwarded-host headers properly and allows for long-lasting WebSocket connections.


Because the Neptune client may send large HTTP request bodies, setting client_max_body_size 30m; (for Nginx) is required to ensure that the client works properly.

We recommend using Nginx. You can use the sample configuration below as a template:

Sample Nginx configuration
server {
  listen 80;
  return 302 https://$host$request_uri;

upstream kubernetes-nodes {

server {
  listen 80;
  return 302 https://$host$request_uri;

map $http_upgrade $connection_upgrade {
  default upgrade;
  '' close;

map $http_x_forwarded_proto $new_x_forwarded_proto {
  default $http_x_forwarded_proto;
  "" $scheme;

map $http_x_forwarded_host $new_http_x_forwarded_host {
  default $http_x_forwarded_host;
  "" $host;

map $http_x_forwarded_port $new_http_x_forwarded_port {
  default $http_x_forwarded_port;
  "" $server_port;

server {
  listen 443;
  server_name _;

  ssl_certificate /etc/nginx/certs/cert.crt;
  ssl_certificate_key /etc/nginx/certs/cert.key;
  ssl on;
  ssl_session_cache builtin:1000 shared:SSL:10m;
  ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
  ssl_prefer_server_ciphers on;

  access_log /var/log/nginx/access.log;

  location / {

    client_max_body_size 10G; # prevents 413 header too large for proxy

    # Enables websockets. Needs all three to work. # (1)!
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;

    proxy_set_header X-Real-IP $remote_addr;

    # Needed for keycloak and backend to read client side address of Neptune
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $new_x_forwarded_proto;
    proxy_set_header X-Forwarded-Host $new_http_x_forwarded_host;
    proxy_set_header X-Forwarded-Port $new_http_x_forwarded_port;

    proxy_pass http://kubernetes-nodes$request_uri;

    # websocket/upload connection kill prevention
    proxy_read_timeout 86400;
    proxy_send_timeout 86400;

    proxy_http_version 1.1;
  1. Missing variables causes headers to not be set, so non-ws connections won't have Upgrade and Connection headers set.