mirror of
https://github.com/traefik/traefik.git
synced 2025-11-04 10:21:15 +01:00
356 lines
9.1 KiB
Markdown
356 lines
9.1 KiB
Markdown
---
|
|
title: "Traefik WebSocket Documentation"
|
|
description: "How to configure WebSocket and WebSocket Secure (WSS) connections with Traefik Proxy."
|
|
---
|
|
|
|
# WebSocket
|
|
|
|
Configuring Traefik to handle WebSocket and WebSocket Secure (WSS) connections.
|
|
{: .subtitle }
|
|
|
|
## Overview
|
|
|
|
WebSocket is a communication protocol that provides full-duplex communication channels over a single TCP connection.
|
|
WebSocket Secure (WSS) is the encrypted version of WebSocket, using TLS/SSL encryption.
|
|
|
|
Traefik supports WebSocket and WebSocket Secure (WSS) out of the box. This guide will walk through examples of how to configure Traefik for different WebSocket scenarios.
|
|
|
|
## Basic WebSocket Configuration
|
|
|
|
A basic WebSocket configuration only requires defining a router and a service that points to your WebSocket server.
|
|
|
|
```yaml tab="Docker & Swarm"
|
|
labels:
|
|
- "traefik.http.routers.my-websocket.rule=Host(`ws.example.com`)"
|
|
- "traefik.http.routers.my-websocket.service=my-websocket-service"
|
|
- "traefik.http.services.my-websocket-service.loadbalancer.server.port=8000"
|
|
```
|
|
|
|
```yaml tab="Kubernetes"
|
|
apiVersion: traefik.io/v1alpha1
|
|
kind: IngressRoute
|
|
metadata:
|
|
name: my-websocket-route
|
|
spec:
|
|
entryPoints:
|
|
- web
|
|
routes:
|
|
- match: Host(`ws.example.com`)
|
|
kind: Rule
|
|
services:
|
|
- name: my-websocket-service
|
|
port: 8000
|
|
```
|
|
|
|
```yaml tab="File (YAML)"
|
|
http:
|
|
routers:
|
|
my-websocket:
|
|
rule: "Host(`ws.example.com`)"
|
|
service: my-websocket-service
|
|
|
|
services:
|
|
my-websocket-service:
|
|
loadBalancer:
|
|
servers:
|
|
- url: "http://my-websocket-server:8000"
|
|
```
|
|
|
|
```toml tab="File (TOML)"
|
|
[http.routers]
|
|
[http.routers.my-websocket]
|
|
rule = "Host(`ws.example.com`)"
|
|
service = "my-websocket-service"
|
|
|
|
[http.services]
|
|
[http.services.my-websocket-service]
|
|
[http.services.my-websocket-service.loadBalancer]
|
|
[[http.services.my-websocket-service.loadBalancer.servers]]
|
|
url = "http://my-websocket-server:8000"
|
|
```
|
|
|
|
## WebSocket Secure (WSS) Configuration
|
|
|
|
WebSocket Secure (WSS) requires TLS configuration.
|
|
The client connects using the `wss://` protocol instead of `ws://`.
|
|
|
|
```yaml tab="Docker & Swarm"
|
|
labels:
|
|
- "traefik.http.routers.my-websocket-secure.rule=Host(`wss.example.com`)"
|
|
- "traefik.http.routers.my-websocket-secure.service=my-websocket-service"
|
|
- "traefik.http.routers.my-websocket-secure.tls=true"
|
|
- "traefik.http.services.my-websocket-service.loadbalancer.server.port=8000"
|
|
```
|
|
|
|
```yaml tab="Kubernetes"
|
|
apiVersion: traefik.io/v1alpha1
|
|
kind: IngressRoute
|
|
metadata:
|
|
name: my-websocket-secure-route
|
|
spec:
|
|
entryPoints:
|
|
- websecure
|
|
routes:
|
|
- match: Host(`wss.example.com`)
|
|
kind: Rule
|
|
services:
|
|
- name: my-websocket-service
|
|
port: 8000
|
|
tls: {}
|
|
```
|
|
|
|
```yaml tab="File (YAML)"
|
|
http:
|
|
routers:
|
|
my-websocket-secure:
|
|
rule: "Host(`wss.example.com`)"
|
|
service: my-websocket-service
|
|
tls: {}
|
|
|
|
services:
|
|
my-websocket-service:
|
|
loadBalancer:
|
|
servers:
|
|
- url: "http://my-websocket-server:8000"
|
|
```
|
|
|
|
```toml tab="File (TOML)"
|
|
[http.routers]
|
|
[http.routers.my-websocket-secure]
|
|
rule = "Host(`wss.example.com`)"
|
|
service = "my-websocket-service"
|
|
[http.routers.my-websocket-secure.tls]
|
|
|
|
[http.services]
|
|
[http.services.my-websocket-service]
|
|
[http.services.my-websocket-service.loadBalancer]
|
|
[[http.services.my-websocket-service.loadBalancer.servers]]
|
|
url = "http://my-websocket-server:8000"
|
|
```
|
|
|
|
## SSL Termination for WebSockets
|
|
|
|
In this scenario, clients connect to Traefik using WSS (encrypted), but Traefik connects to your backend server using WS (unencrypted).
|
|
This is called SSL termination.
|
|
|
|
```yaml tab="Docker & Swarm"
|
|
labels:
|
|
- "traefik.http.routers.my-wss-termination.rule=Host(`wss.example.com`)"
|
|
- "traefik.http.routers.my-wss-termination.service=my-ws-service"
|
|
- "traefik.http.routers.my-wss-termination.tls=true"
|
|
- "traefik.http.services.my-ws-service.loadbalancer.server.port=8000"
|
|
```
|
|
|
|
```yaml tab="Kubernetes"
|
|
apiVersion: traefik.io/v1alpha1
|
|
kind: IngressRoute
|
|
metadata:
|
|
name: my-wss-termination-route
|
|
spec:
|
|
entryPoints:
|
|
- websecure
|
|
routes:
|
|
- match: Host(`wss.example.com`)
|
|
kind: Rule
|
|
services:
|
|
- name: my-ws-service
|
|
port: 8000
|
|
tls: {}
|
|
```
|
|
|
|
```yaml tab="File (YAML)"
|
|
http:
|
|
routers:
|
|
my-wss-termination:
|
|
rule: "Host(`wss.example.com`)"
|
|
service: my-ws-service
|
|
tls: {}
|
|
|
|
services:
|
|
my-ws-service:
|
|
loadBalancer:
|
|
servers:
|
|
- url: "http://my-ws-server:8000"
|
|
```
|
|
|
|
```toml tab="File (TOML)"
|
|
[http.routers]
|
|
[http.routers.my-wss-termination]
|
|
rule = "Host(`wss.example.com`)"
|
|
service = "my-ws-service"
|
|
[http.routers.my-wss-termination.tls]
|
|
|
|
[http.services]
|
|
[http.services.my-ws-service]
|
|
[http.services.my-ws-service.loadBalancer]
|
|
[[http.services.my-ws-service.loadBalancer.servers]]
|
|
url = "http://my-ws-server:8000"
|
|
```
|
|
|
|
## End-to-End WebSocket Secure (WSS)
|
|
|
|
For end-to-end encryption, Traefik can be configured to connect to your backend using HTTPS.
|
|
|
|
```yaml tab="Docker & Swarm"
|
|
labels:
|
|
- "traefik.http.routers.my-wss-e2e.rule=Host(`wss.example.com`)"
|
|
- "traefik.http.routers.my-wss-e2e.service=my-wss-service"
|
|
- "traefik.http.routers.my-wss-e2e.tls=true"
|
|
- "traefik.http.services.my-wss-service.loadbalancer.server.port=8443"
|
|
# If the backend uses a self-signed certificate
|
|
- "traefik.http.serversTransports.insecureTransport.insecureSkipVerify=true"
|
|
- "traefik.http.services.my-wss-service.loadBalancer.serversTransport=insecureTransport"
|
|
```
|
|
|
|
```yaml tab="Kubernetes"
|
|
apiVersion: traefik.io/v1alpha1
|
|
kind: ServersTransport
|
|
metadata:
|
|
name: insecure-transport
|
|
spec:
|
|
insecureSkipVerify: true
|
|
|
|
---
|
|
apiVersion: traefik.io/v1alpha1
|
|
kind: IngressRoute
|
|
metadata:
|
|
name: my-wss-e2e-route
|
|
spec:
|
|
entryPoints:
|
|
- websecure
|
|
routes:
|
|
- match: Host(`wss.example.com`)
|
|
kind: Rule
|
|
services:
|
|
- name: my-wss-service
|
|
port: 8443
|
|
serversTransport: insecure-transport
|
|
tls: {}
|
|
```
|
|
|
|
```yaml tab="File (YAML)"
|
|
http:
|
|
serversTransports:
|
|
insecureTransport:
|
|
insecureSkipVerify: true
|
|
|
|
routers:
|
|
my-wss-e2e:
|
|
rule: "Host(`wss.example.com`)"
|
|
service: my-wss-service
|
|
tls: {}
|
|
|
|
services:
|
|
my-wss-service:
|
|
loadBalancer:
|
|
serversTransport: insecureTransport
|
|
servers:
|
|
- url: "https://my-wss-server:8443"
|
|
```
|
|
|
|
```toml tab="File (TOML)"
|
|
[http.serversTransports]
|
|
[http.serversTransports.insecureTransport]
|
|
insecureSkipVerify = true
|
|
|
|
[http.routers]
|
|
[http.routers.my-wss-e2e]
|
|
rule = "Host(`wss.example.com`)"
|
|
service = "my-wss-service"
|
|
[http.routers.my-wss-e2e.tls]
|
|
|
|
[http.services]
|
|
[http.services.my-wss-service]
|
|
[http.services.my-wss-service.loadBalancer]
|
|
serversTransport = "insecureTransport"
|
|
[[http.services.my-wss-service.loadBalancer.servers]]
|
|
url = "https://my-wss-server:8443"
|
|
```
|
|
|
|
## EntryPoints Configuration for WebSockets
|
|
|
|
In your Traefik static configuration, you'll need to define entryPoints for both WS and WSS:
|
|
|
|
```yaml tab="File (YAML)"
|
|
entryPoints:
|
|
web:
|
|
address: ":80"
|
|
websecure:
|
|
address: ":443"
|
|
```
|
|
|
|
```toml tab="File (TOML)"
|
|
[entryPoints]
|
|
[entryPoints.web]
|
|
address = ":80"
|
|
[entryPoints.websecure]
|
|
address = ":443"
|
|
```
|
|
|
|
## Testing WebSocket Connections
|
|
|
|
You can test your WebSocket configuration using various tools:
|
|
|
|
1. Browser Developer Tools: Most modern browsers include WebSocket debugging in their developer tools.
|
|
2. WebSocket client tools like [wscat](https://github.com/websockets/wscat) or online tools like [Piesocket's WebSocket Tester](https://www.piesocket.com/websocket-tester).
|
|
|
|
Example wscat commands:
|
|
|
|
```bash
|
|
# Test standard WebSocket
|
|
wscat -c ws://ws.example.com
|
|
|
|
# Test WebSocket Secure
|
|
wscat -c wss://wss.example.com
|
|
```
|
|
|
|
## Common Issues and Solutions
|
|
|
|
### Headers and Origin Checks
|
|
|
|
Some WebSocket servers implement origin checking. Traefik passes the original headers to your backend, including the `Origin` header.
|
|
|
|
If you need to manipulate headers for WebSocket connections, you can use Traefik's Headers middleware:
|
|
|
|
```yaml tab="Docker & Swarm"
|
|
labels:
|
|
- "traefik.http.middlewares.my-headers.headers.customrequestheaders.Origin=https://allowed-origin.com"
|
|
- "traefik.http.routers.my-websocket.middlewares=my-headers"
|
|
```
|
|
|
|
```yaml tab="Kubernetes"
|
|
apiVersion: traefik.io/v1alpha1
|
|
kind: Middleware
|
|
metadata:
|
|
name: my-headers
|
|
spec:
|
|
headers:
|
|
customRequestHeaders:
|
|
Origin: "https://allowed-origin.com"
|
|
|
|
---
|
|
apiVersion: traefik.io/v1alpha1
|
|
kind: IngressRoute
|
|
metadata:
|
|
name: my-websocket-route
|
|
spec:
|
|
routes:
|
|
- match: Host(`ws.example.com`)
|
|
kind: Rule
|
|
middlewares:
|
|
- name: my-headers
|
|
services:
|
|
- name: my-websocket-service
|
|
port: 8000
|
|
```
|
|
|
|
### Certificate Issues with WSS
|
|
|
|
If you're experiencing certificate issues with WSS:
|
|
|
|
1. Ensure your certificates are valid and not expired
|
|
2. For testing with self-signed certificates, configure your clients to accept them
|
|
3. When using Let's Encrypt, ensure your domain is properly configured
|
|
|
|
For backends with self-signed certificates, use the `insecureSkipVerify` option in the ServersTransport configuration as shown in the examples above.
|