How To Add The Whitelist for Your Ingress-Nginx Controller of K8S?

Introduction

Access control is a critical aspect of securing your Kubernetes applications. One way to enhance security is by implementing a whitelist to allow only specific IP addresses to access your services. In this post, I’ll show you how to configure IP whitelisting for your Ingress-Nginx Controller in Kubernetes.

This guide is for anyone using Kubernetes and managing external or internal traffic to their services, such as DevOps engineers and Kubernetes enthusiasts.

Prerequisites

Before we start, ensure you have the following:

• A working Kubernetes cluster.
• kubectl installed and configured.
• Ingress-Nginx Controller already installed.

Understanding Whitelisting in Ingress-Nginx

Whitelisting allows you to restrict access to your application based on IP addresses or CIDR ranges. This is particularly useful for:

• Securing internal applications that only certain teams or locations should access.
• Protecting sensitive data by limiting external access.

Ingress-Nginx supports whitelisting via annotations, making it straightforward to set up.

Steps to Add a Whitelist

Step 1: Verify Ingress-Nginx Installation

First, check that the Ingress-Nginx Controller is running in your cluster. Use the following command:

kubectl get pods -n ingress-nginx

Look for a pod with a name like ingress-nginx-controller. If it’s not running, install it using Ingress-Nginx installation guides.

Step 2: Identify the IPs to Whitelist

Determine the IP addresses or CIDR ranges you want to allow access. For example:

• Internal IPs: 192.168.1.0/24
• External static IP: 203.0.113.0/24

Step 3: Configure the Ingress Nginx Controller(!IMPORTANT)

Before we add the whitelist into the ingress resource, we HAVE TO change the externalTrafficPolicy field to Local like below example or the whitelist will not be applied correctly.

The comparison between Local and Cluster for externalTrafficPolicy

Attribute/Behavior	Local	Cluster
Traffic Routing	Routes only to Pods on the node receiving traffic	Distributes traffic to any Pod in the cluster
Client Original IP	Preserved	Replaced by the node’s IP
Traffic Balancing	Requires Load Balancer to balance external traffic	Handled internally by Kubernetes
Network Hops	Few (direct to the target Pod)	More (may forward to other nodes)
Latency	Low	May be slightly higher
Fault Tolerance	Requires Pods to be evenly distributed across nodes	High, as traffic can reach any available Pod
Use Case	When client IP is needed (e.g., for logging or IP-based access control)	For high availability and balanced distribution without needing client IP

...

spec:
  allocateLoadBalancerNodePorts: true
  clusterIP: 10.109.177.97
  clusterIPs:
  - 10.109.177.97
  externalTrafficPolicy: Local # <--- Change it to Local, default is Cluster
  healthCheckNodePort: 32459
  internalTrafficPolicy: Cluster

...

Step 4: Configure the Ingress Resource

To implement the whitelist, add the annotation nginx.ingress.kubernetes.io/whitelist-source-range to your Ingress resource. Below is a sample YAML configuration:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/whitelist-source-range: "192.168.1.0/24,203.0.113.0/24"
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

Save this configuration as ingress.yaml.

Step 5: Apply the Configuration

Apply the YAML configuration using kubectl:

kubectl apply -f ingress.yaml

Verify the configuration:

kubectl describe ingress example-ingress

Check for the annotation and ensure it’s applied correctly.

Step 6: Testing the Whitelist

To confirm the whitelist works as expected, test access from:

• Whitelisted IPs: Access the service using a browser or curl:

curl -H "Host: example.com" http://<INGRESS_IP>

• Non-Whitelisted IPs: Try accessing from an unlisted IP. You should receive a 403 Forbidden response.

Common Issues and Troubleshooting

1. Access Denied Despite Proper Configuration:
   • Double-check the IP ranges in the annotation.
   • Ensure you’re testing from the correct source IP.
2. Misconfigured CIDR Ranges:
   • Validate your CIDR format using online tools like CIDR Calculator.
3. Ingress Logs:
   • Check the logs of your Ingress-Nginx Controller for clues:

kubectl logs -n ingress-nginx <ingress-nginx-controller-pod>

Best Practices

• Combine whitelisting with HTTPS to encrypt traffic.
• Use ConfigMaps or Secrets to store sensitive configurations.
• Regularly review and update the whitelist as network requirements evolve.

Conclusion

Adding a whitelist to your Ingress-Nginx Controller is a simple yet effective way to secure your Kubernetes applications. By restricting access to trusted IPs, you reduce the risk of unauthorized access. Give it a try, and feel free to share your feedback or challenges in the comments below!

References and Further Reading

• Ingress-Nginx Official Documentation
• Kubernetes Networking Concepts
• CIDR Notation Explained