Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.9.x (latest)
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • 2.5.x
  • 2.4.x
  • 2.3.x
  • 2.2.x
  • 2.1.x
  • 2.0.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
    • FAQ
    • Changelog
    • Architecture
    • Custom Resources
    • Deployment Methods
    • Kong for Kubernetes with Kong Enterprise
    • High-Availability and Scaling
    • Resource Classes
    • Security
    • Ingress Resource API Versions
    • Kong Ingress on Minikube
    • Kong for Kubernetes
    • Kong for Kubernetes Enterprise
    • Kong for Kubernetes with Kong Enterprise
    • Kong Ingress on AKS
    • Kong Ingress on EKS
    • Kong Ingress on GKE
    • Admission Controller
    • Getting Started with KIC
    • Upgrading from KIC 1.3.x
    • Getting Started using Istio
      • Using the KongPlugin Resource
      • Using the KongIngress Resource
      • Using KongConsumer and Credential Resources
      • Using the KongClusterPlugin Resource
      • Using the TCPIngress Resource
      • Using the UDPIngress Resource
    • Using the ACL and JWT Plugins
    • Using cert-manager with Kong
    • Configuring a Fallback Service
    • Using an External Service
    • Configuring HTTPS Redirects for Services
    • Using Redis for Rate Limiting
    • Integrate KIC with Prometheus/Grafana
    • Configuring Circuit-Breaker and Health-Checking
    • Setting up a Custom Plugin
    • Using Ingress with gRPC
    • Setting up Upstream mTLS
    • Exposing a TCP-based Service
    • Exposing a UDP-based Service
    • Using the mTLS Auth Plugin
    • Configuring Custom Entities
    • Using the OpenID Connect Plugin
    • Rewriting Hosts and Paths
    • Preserving Client IP Address
    • KIC Annotations
    • CLI Arguments
    • Custom Resource Definitions
    • Plugin Compatibility
    • Version Compatibility
    • Troubleshooting
    • Prometheus Metrics

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • ExternalTrafficPolicy: Local
  • Proxy Protocol
  • HTTP headers
  • Cloud-provider specific details
    • GKE
    • AKS
    • EKS
Kubernetes Ingress Controller
2.0.x
  • Home
  • Kubernetes Ingress Controller
  • Guides
  • Preserving Client IP Address
You are browsing documentation for an outdated version. See the latest documentation here.

Preserving Client IP Address

Kong is usually deployed behind a Load Balancer (using a Kubernetes Service of type LoadBalancer). This can result in loss of actual Client IP address and Kong observing the IP address of the Load Balancer as the client IP address. This guide lays out different methods of solving this problem.

Preserving the Client IP address in cloud behind Load-Balancers requires configuration that is be specific to your use-case, cloud provider and other architecture details. This document provides details on how networking works inside Kubernetes and explains in detail of how various methods describe later in this document work. It is recommended that you give this a read.

Following methods are possible to preserve Client IP address:

ExternalTrafficPolicy: Local

As explained in Kubernetes docs, setting service.spec.externalTrafficPolicy to Local preserves the Client IP address. You don’t need to change any configuration in Kong if you are using this method to preserve Client IP address.

Please note that this is not supported by all of the public Cloud providers.

Proxy Protocol

If you have an L4 Load Balancer that supports Proxy Protocol, and you’re terminating TCP connections at the Load Balancer before passing traffic onward to Kong, then you can configure Kong to pick up the Client IP address via this protocol.

Once you have configured the Load Balancer to use Proxy Protocol, you need to set the following environment variables in Kong for Kong to receive the Client IP from the Proxy Protocol header.

  • KONG_TRUSTED_IPS
  • KONG_PROXY_LISTEN
  • KONG_REAL_IP_HEADER

For example:

KONG_TRUSTED_IPS=0.0.0.0/0,::/0  # This trusts all IPs
KONG_PROXY_LISTEN="0.0.0.0:8000 proxy_protocol, 0.0.0.0:8443 ssl proxy_protocol"
KONG_REAL_IP_HEADER=proxy_protocol

HTTP headers

If you are using an L7 Load Balancer, i.e. HTTP requests are being terminated at the Load Balancer, then you need to use x-forwarded-for or x-real-ip header to preserve details of the connection between the Client and Load Balancer.

You should configure the Load Balancer to inject these headers, and then you need to set the following environment variables in Kong for Kong to pick up the Client IP address from HTTP headers:

  • KONG_TRUSTED_IPS
  • KONG_REAL_IP_HEADER
  • Optional KONG_REAL_IP_RECURSIVE

Please note that if you are using an L7 Load Balancer with Kong, you cannot use the certificates feature in Kong as the TLS session is already established between the Client and Load Balancer.

Cloud-provider specific details

For the major public clouds, follow are some additional details that can help you preserve the client IP address:

GKE

You can use ExternalTrafficPolicy: Local to preserve the Client IP address.

AKS

You can use ExternalTrafficPolicy: Local to preserve the Client IP address.

EKS

You have two options:

  • L4 Load Balancer In this case, you need to use the Proxy Protocol method to preserve Client IP address.
  • L7 Load Balancer In this case, you need to use the HTTP headers method to preserve the Client IP address.

The recommend Load Balancer type for AWS is NLB. You can choose the type of Load Balancer using the following annotation:

service.beta.kubernetes.io/aws-load-balancer-type: nlb

Other useful annotations for AWS are:

service.beta.kubernetes.io/aws-load-balancer-backend-protocol: tcp
service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: '*'

A complete list can be found here.

Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023