How to Get Your WebSocket Chat Service Working with Nginx Ingress in Kubernetes

WebSockets enable real-time, bidirectional communication between clients and servers, making them ideal for chat applications. However, when deploying a WebSocket-based chat service behind an Nginx Ingress Controller in Kubernetes, you may encounter issues such as unexpected disconnections or failed handshake requests.

This guide will walk you through the necessary Nginx Ingress annotations to ensure your WebSocket chat service functions correctly.

The Problem: WebSockets Not Working

If your WebSocket chat service is not working correctly behind an Nginx Ingress in Kubernetes, you may experience issues like:

• Connection drops after a short period
• Handshake failures (HTTP 400 or 502 errors)
• WebSocket messages not being received by the backend

These issues arise because Nginx treats WebSockets differently from normal HTTP traffic. Without proper configuration, it may not recognize the WebSocket connection and could close it prematurely.

The Solution: Add Nginx Ingress Annotations

To resolve these issues, you need to add specific annotations to your Ingress resource. Here’s an example of a properly configured Ingress YAML:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: chat-ingress
  annotations:
    nginx.org/websocket-services: chat-service-name
    nginx.org/proxy-read-timeout: '3600'
    enable-underscores-in-headers: 'true'
spec:
  rules:
    - host: chat.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: chat-service-name
                port:
                  number: ...
...
...

This ingress example is tested in Rancher Kubernetes Management System.

Explanation of Annotations:

1. nginx.org/websocket-services: chat-service-name
   • This tells the Nginx Ingress Controller that the specified service (chat-service-name) uses WebSockets.
   • Without this, WebSocket upgrade requests might be ignored or mishandled.
2. nginx.org/proxy-read-timeout: '3600'
   • Extends the timeout for reading responses from the backend to 1 hour (3600 seconds).
   • WebSocket connections are long-lived, and shorter timeouts (e.g., the default 60 seconds) may cause unexpected disconnections.
3. enable-underscores-in-headers: 'true'
   • Allows underscores in HTTP headers, which some WebSocket libraries use.
   • Without this, WebSocket handshake requests may fail if headers contain underscores.

Deploying the Ingress Resource

After updating your Ingress YAML file, apply the changes with:

kubectl apply -f chat-ingress.yaml

Then, verify that the Ingress is correctly configured:

kubectl get ingress chat-ingress -o yaml

Check if your chat service is now accessible and stable.

Conclusion

By adding these annotations, you ensure that your Kubernetes Ingress correctly handles WebSocket connections for your chat service. This simple configuration change can save hours of debugging and provide a seamless experience for users relying on real-time messaging.