mirror of
https://github.com/traefik/traefik
synced 2026-02-03 12:20:33 +00:00
Clean Up Menu Entries & Update Expose Overview
This commit is contained in:
Sheddy
@@ -20,3 +20,97 @@ For detailed steps tailored to your environment, follow the guide for your platf
|
|||||||
- [Kubernetes](./kubernetes/basic.md)
|
- [Kubernetes](./kubernetes/basic.md)
|
||||||
- [Docker](./docker/basic.md)
|
- [Docker](./docker/basic.md)
|
||||||
- [Docker Swarm](./swarm/basic.md)
|
- [Docker Swarm](./swarm/basic.md)
|
||||||
|
|
||||||
|
## Advanced Use Cases
|
||||||
|
|
||||||
|
### Exposing gRPC Services
|
||||||
|
|
||||||
|
Traefik Proxy supports gRPC applications without requiring specific configuration. You can expose gRPC services using either HTTP (h2c) or HTTPS.
|
||||||
|
|
||||||
|
??? example "Using HTTP (h2c)"
|
||||||
|
|
||||||
|
For unencrypted gRPC communication, configure your service to use the `h2c://` protocol scheme:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
http:
|
||||||
|
routers:
|
||||||
|
grpc-router:
|
||||||
|
service: grpc-service
|
||||||
|
rule: Host(`grpc.example.com`)
|
||||||
|
|
||||||
|
services:
|
||||||
|
grpc-service:
|
||||||
|
loadBalancer:
|
||||||
|
servers:
|
||||||
|
- url: h2c://backend:8080
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
For providers with labels (Docker, Kubernetes), specify the scheme using:
|
||||||
|
`traefik.http.services.<service-name>.loadbalancer.server.scheme=h2c`
|
||||||
|
|
||||||
|
??? example "Using HTTPS"
|
||||||
|
|
||||||
|
For encrypted gRPC communication, use standard HTTPS URLs. Traefik will use HTTP/2 over TLS to communicate with your gRPC backend:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
http:
|
||||||
|
routers:
|
||||||
|
grpc-router:
|
||||||
|
service: grpc-service
|
||||||
|
rule: Host(`grpc.example.com`)
|
||||||
|
tls: {}
|
||||||
|
|
||||||
|
services:
|
||||||
|
grpc-service:
|
||||||
|
loadBalancer:
|
||||||
|
servers:
|
||||||
|
- url: https://backend:8080
|
||||||
|
```
|
||||||
|
|
||||||
|
Traefik handles the protocol negotiation automatically. Configure TLS certificates for your backends using [ServersTransport](../reference/routing-configuration/http/load-balancing/serverstransport.md) if needed.
|
||||||
|
|
||||||
|
### Exposing WebSocket Services
|
||||||
|
|
||||||
|
Traefik Proxy supports WebSocket (WS) and WebSocket Secure (WSS) connections out of the box. No special configuration is required beyond standard HTTP routing.
|
||||||
|
|
||||||
|
??? example "Basic WebSocket"
|
||||||
|
|
||||||
|
Configure a router and service pointing to your WebSocket server. Traefik automatically detects and handles the WebSocket upgrade:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
http:
|
||||||
|
routers:
|
||||||
|
websocket-router:
|
||||||
|
rule: Host(`ws.example.com`)
|
||||||
|
service: websocket-service
|
||||||
|
|
||||||
|
services:
|
||||||
|
websocket-service:
|
||||||
|
loadBalancer:
|
||||||
|
servers:
|
||||||
|
- url: http://websocket-backend:8000
|
||||||
|
```
|
||||||
|
|
||||||
|
??? example "WebSocket Secure (WSS)"
|
||||||
|
|
||||||
|
For encrypted WebSocket connections, enable TLS on your router. Clients connect using `wss://` while you can choose whether backends use encrypted or unencrypted connections:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
http:
|
||||||
|
routers:
|
||||||
|
websocket-secure-router:
|
||||||
|
rule: Host(`wss.example.com`)
|
||||||
|
service: websocket-service
|
||||||
|
tls: {}
|
||||||
|
|
||||||
|
services:
|
||||||
|
websocket-service:
|
||||||
|
loadBalancer:
|
||||||
|
servers:
|
||||||
|
- url: http://websocket-backend:8000 # SSL termination at Traefik
|
||||||
|
# OR
|
||||||
|
# - url: https://websocket-backend:8443 # End-to-end encryption
|
||||||
|
```
|
||||||
|
|
||||||
|
Traefik preserves WebSocket headers including `Origin`, `Sec-WebSocket-Key`, and `Sec-WebSocket-Version`. Use the [Headers middleware](../reference/routing-configuration/http/middlewares/headers.md) if you need to modify headers for origin checking or other requirements.
|
||||||
|
|||||||
@@ -13,7 +13,7 @@ The GrpcWeb middleware converts gRPC Web requests to HTTP/2 gRPC requests before
|
|||||||
!!! tip
|
!!! tip
|
||||||
|
|
||||||
Please note, that Traefik needs to communicate using gRPC with the backends (h2c or HTTP/2 over TLS).
|
Please note, that Traefik needs to communicate using gRPC with the backends (h2c or HTTP/2 over TLS).
|
||||||
Check out the [gRPC](../../user-guides/grpc.md) user guide for more details.
|
Check out [Exposing gRPC Services](../../expose/overview.md#exposing-grpc-services) for more details.
|
||||||
|
|
||||||
## Configuration Examples
|
## Configuration Examples
|
||||||
|
|
||||||
|
|||||||
@@ -363,6 +363,6 @@ providers:
|
|||||||
|
|
||||||
## Full Example
|
## Full Example
|
||||||
|
|
||||||
For additional information, refer to the [full example](../user-guides/crd-acme/index.md) with Let's Encrypt.
|
For additional information on exposing services with Kubernetes, refer to the [Kubernetes guide](../expose/kubernetes/basic.md).
|
||||||
|
|
||||||
{% include-markdown "includes/traefik-for-business-applications.md" %}
|
{% include-markdown "includes/traefik-for-business-applications.md" %}
|
||||||
|
|||||||
+6
-7
@@ -1,19 +1,18 @@
|
|||||||
---
|
---
|
||||||
title: "Traefik FastProxy Experimental Configuration"
|
title: "Traefik FastProxy Experimental Configuration"
|
||||||
description: "This section of the Traefik Proxy documentation explains how to use the new FastProxy option."
|
description: "This section of the Traefik Proxy documentation explains how to use the new FastProxy install configuration option."
|
||||||
---
|
---
|
||||||
|
|
||||||
# Traefik FastProxy Experimental Configuration
|
# Traefik FastProxy Experimental Configuration
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
This guide provides instructions on how to configure and use the new experimental `fastProxy` static configuration option in Traefik.
|
This guide provides instructions on how to configure and use the new experimental `fastProxy` install configuration option in Traefik. The `fastProxy` option introduces a high-performance reverse proxy designed to enhance the performance of routing.
|
||||||
The `fastProxy` option introduces a high-performance reverse proxy designed to enhance the performance of routing.
|
|
||||||
|
|
||||||
!!! info "Limitations"
|
!!! info "Limitations"
|
||||||
|
|
||||||
Please note that the new fast proxy implementation does not work with HTTP/2.
|
Please note that the new fast proxy implementation does not work with HTTP/2.
|
||||||
This means that when a H2C or HTTPS request with [HTTP2 enabled](../routing/services/index.md#disablehttp2) is sent to a backend, the fallback proxy is the regular one.
|
This means that when a H2C or HTTPS request with [HTTP2 enabled](../../routing-configuration/http/load-balancing/service.md#disablehttp2) is sent to a backend, the fallback proxy is the regular one.
|
||||||
|
|
||||||
Additionnaly, observability features like tracing and OTEL semconv metrics are not supported for the moment.
|
Additionnaly, observability features like tracing and OTEL semconv metrics are not supported for the moment.
|
||||||
|
|
||||||
@@ -22,10 +21,10 @@ The `fastProxy` option introduces a high-performance reverse proxy designed to e
|
|||||||
The `fastProxy` option is currently experimental and subject to change in future releases.
|
The `fastProxy` option is currently experimental and subject to change in future releases.
|
||||||
Use with caution in production environments.
|
Use with caution in production environments.
|
||||||
|
|
||||||
### Enabling FastProxy
|
## Enabling FastProxy
|
||||||
|
|
||||||
The fastProxy option is a static configuration parameter.
|
The fastProxy option is an install configuration parameter.
|
||||||
To enable it, you need to configure it in your Traefik static configuration
|
To enable it, you need to configure it in your Traefik install configuration
|
||||||
|
|
||||||
```yaml tab="File (YAML)"
|
```yaml tab="File (YAML)"
|
||||||
experimental:
|
experimental:
|
||||||
@@ -0,0 +1,43 @@
|
|||||||
|
---
|
||||||
|
title: "Traefik Plugins Experimental Configuration"
|
||||||
|
description: "This section of the Traefik Proxy documentation explains how to use the new Plugins install configuration option."
|
||||||
|
---
|
||||||
|
|
||||||
|
# Traefik Plugins Experimental Configuration
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This guide provides instructions on how to configure and use the new experimental `plugins` install configuration option in Traefik. The `plugins` option introduces a system to extend Traefik capabilities with custom middlewares and providers.
|
||||||
|
|
||||||
|
!!! warning "Experimental"
|
||||||
|
|
||||||
|
The `plugins` option is currently experimental and subject to change in future releases.
|
||||||
|
Use with caution in production environments.
|
||||||
|
|
||||||
|
## Enabling Plugins
|
||||||
|
|
||||||
|
The plugins option is an install configuration parameter.
|
||||||
|
To enable a plugin, you need to define it in your Traefik install configuration
|
||||||
|
|
||||||
|
```yaml tab="File (YAML)"
|
||||||
|
experimental:
|
||||||
|
plugins:
|
||||||
|
plugin-name: # The name of the plugin in the routing configuration
|
||||||
|
moduleName: "github.com/github-organization/github-repository" # The plugin module name
|
||||||
|
version: "vX.XX.X" # The version to use
|
||||||
|
```
|
||||||
|
|
||||||
|
```toml tab="File (TOML)"
|
||||||
|
[experimental.plugins.plugin-name]
|
||||||
|
moduleName = "github.com/github-organization/github-repository" # The plugin module name
|
||||||
|
version = "vX.XX.X" # The version to use
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab="CLI"
|
||||||
|
# The plugin module name
|
||||||
|
# With plugin-name the name of the plugin in the routing configuration
|
||||||
|
--experimental.plugins.plugin-name.modulename=github.com/github-organization/github-repository
|
||||||
|
--experimental.plugins.plugin-name.version=vX.XX.X # The version to use
|
||||||
|
```
|
||||||
|
|
||||||
|
To learn more about how to add a new plugin to a Traefik instance, please refer to the [developer documentation](https://plugins.traefik.io/install).
|
||||||
@@ -128,6 +128,6 @@ See the dedicated section in [routing](../../../../routing/providers/kubernetes-
|
|||||||
|
|
||||||
## Full Example
|
## Full Example
|
||||||
|
|
||||||
For additional information, refer to the [full example](../../../../user-guides/crd-acme/index.md) with Let's Encrypt.
|
For additional information on exposing services with Kubernetes, refer to the [Kubernetes guide](../../../../expose/kubernetes/basic.md).
|
||||||
|
|
||||||
{% include-markdown "includes/traefik-for-business-applications.md" %}
|
{% include-markdown "includes/traefik-for-business-applications.md" %}
|
||||||
|
|||||||
@@ -8,7 +8,7 @@ The `grpcWeb` middleware converts gRPC Web requests to HTTP/2 gRPC requests befo
|
|||||||
!!! tip
|
!!! tip
|
||||||
|
|
||||||
Please note, that Traefik needs to communicate using gRPC with the backends (h2c or HTTP/2 over TLS).
|
Please note, that Traefik needs to communicate using gRPC with the backends (h2c or HTTP/2 over TLS).
|
||||||
Check out the [gRPC](../../../../user-guides/grpc.md) user guide for more details.
|
Check out [Exposing gRPC Services](../../../../expose/overview.md#exposing-grpc-services) for more details.
|
||||||
|
|
||||||
## Configuration Examples
|
## Configuration Examples
|
||||||
|
|
||||||
|
|||||||
@@ -2037,6 +2037,6 @@ If the ServersTransportTCP CRD is defined in another provider the cross-provider
|
|||||||
|
|
||||||
## Further
|
## Further
|
||||||
|
|
||||||
Also see the [full example](../../user-guides/crd-acme/index.md) with Let's Encrypt.
|
For additional information on exposing services with Kubernetes, see the [Kubernetes guide](../../expose/kubernetes/basic.md).
|
||||||
|
|
||||||
{% include-markdown "includes/traefik-for-business-applications.md" %}
|
{% include-markdown "includes/traefik-for-business-applications.md" %}
|
||||||
|
|||||||
@@ -1,183 +0,0 @@
|
|||||||
---
|
|
||||||
title: "Integration with cert-manager"
|
|
||||||
description: "Learn how to use cert-manager certificates with Traefik Proxy for your routers. Read the technical documentation."
|
|
||||||
---
|
|
||||||
|
|
||||||
# cert-manager
|
|
||||||
|
|
||||||
Provision TLS Certificate for Traefik Proxy with cert-manager on Kubernetes
|
|
||||||
{: .subtitle }
|
|
||||||
|
|
||||||
## Pre-requisites
|
|
||||||
|
|
||||||
To obtain certificates from cert-manager that can be used in Traefik Proxy, you will need to:
|
|
||||||
|
|
||||||
1. Have cert-manager properly configured
|
|
||||||
2. Have Traefik Proxy configured
|
|
||||||
|
|
||||||
The certificates can then be used in an Ingress / IngressRoute / HTTPRoute.
|
|
||||||
|
|
||||||
## Example with ACME and HTTP challenge
|
|
||||||
|
|
||||||
!!! example "ACME issuer for HTTP challenge"
|
|
||||||
|
|
||||||
```yaml tab="Issuer"
|
|
||||||
apiVersion: cert-manager.io/v1
|
|
||||||
kind: Issuer
|
|
||||||
metadata:
|
|
||||||
name: acme
|
|
||||||
|
|
||||||
spec:
|
|
||||||
acme:
|
|
||||||
# Production server is on https://acme-v02.api.letsencrypt.org/directory
|
|
||||||
# Use staging by default.
|
|
||||||
server: https://acme-staging-v02.api.letsencrypt.org/directory
|
|
||||||
privateKeySecretRef:
|
|
||||||
name: acme
|
|
||||||
solvers:
|
|
||||||
- http01:
|
|
||||||
ingress:
|
|
||||||
ingressClassName: traefik
|
|
||||||
```
|
|
||||||
|
|
||||||
```yaml tab="Certificate"
|
|
||||||
apiVersion: cert-manager.io/v1
|
|
||||||
kind: Certificate
|
|
||||||
metadata:
|
|
||||||
name: whoami
|
|
||||||
namespace: traefik
|
|
||||||
spec:
|
|
||||||
secretName: domain-tls # <=== Name of secret where the generated certificate will be stored.
|
|
||||||
dnsNames:
|
|
||||||
- "domain.example.com"
|
|
||||||
issuerRef:
|
|
||||||
name: acme
|
|
||||||
kind: Issuer
|
|
||||||
```
|
|
||||||
|
|
||||||
Let's see now how to use it with the various Kubernetes providers of Traefik Proxy.
|
|
||||||
The enabled providers can be seen on the [dashboard](../reference/install-configuration/api-dashboard.md) of Traefik Proxy and also in the INFO logs when Traefik Proxy starts.
|
|
||||||
|
|
||||||
### With an Ingress
|
|
||||||
|
|
||||||
To use this certificate with an Ingress, the [Kubernetes Ingress](../providers/kubernetes-ingress.md) provider has to be enabled.
|
|
||||||
|
|
||||||
!!! info Traefik Helm Chart
|
|
||||||
|
|
||||||
This provider is enabled by default in the Traefik Helm Chart.
|
|
||||||
|
|
||||||
!!! example "Route with this Certificate"
|
|
||||||
|
|
||||||
```yaml tab="Ingress"
|
|
||||||
apiVersion: networking.k8s.io/v1
|
|
||||||
kind: Ingress
|
|
||||||
metadata:
|
|
||||||
name: domain
|
|
||||||
annotations:
|
|
||||||
traefik.ingress.kubernetes.io/router.entrypoints: websecure
|
|
||||||
|
|
||||||
spec:
|
|
||||||
rules:
|
|
||||||
- host: domain.example.com
|
|
||||||
http:
|
|
||||||
paths:
|
|
||||||
- path: /
|
|
||||||
pathType: Exact
|
|
||||||
backend:
|
|
||||||
service:
|
|
||||||
name: domain-service
|
|
||||||
port:
|
|
||||||
number: 80
|
|
||||||
tls:
|
|
||||||
- secretName: domain-tls # <=== Use the name defined in Certificate resource.
|
|
||||||
```
|
|
||||||
|
|
||||||
### With an IngressRoute
|
|
||||||
|
|
||||||
To use this certificate with an IngressRoute, the [Kubernetes CRD](../providers/kubernetes-crd.md) provider has to be enabled.
|
|
||||||
|
|
||||||
!!! info Traefik Helm Chart
|
|
||||||
|
|
||||||
This provider is enabled by default in the Traefik Helm Chart.
|
|
||||||
|
|
||||||
!!! example "Route with this Certificate"
|
|
||||||
|
|
||||||
```yaml tab="IngressRoute"
|
|
||||||
apiVersion: traefik.io/v1alpha1
|
|
||||||
kind: IngressRoute
|
|
||||||
metadata:
|
|
||||||
name: domain
|
|
||||||
|
|
||||||
spec:
|
|
||||||
entryPoints:
|
|
||||||
- websecure
|
|
||||||
|
|
||||||
routes:
|
|
||||||
- match: Host(`domain.example.com`)
|
|
||||||
kind: Rule
|
|
||||||
services:
|
|
||||||
- name: domain-service
|
|
||||||
port: 80
|
|
||||||
tls:
|
|
||||||
secretName: domain-tls # <=== Use the name defined in Certificate resource.
|
|
||||||
```
|
|
||||||
|
|
||||||
### With an HTTPRoute
|
|
||||||
|
|
||||||
To use this certificate with an HTTPRoute, the [Kubernetes Gateway](../routing/providers/kubernetes-gateway.md) provider has to be enabled.
|
|
||||||
|
|
||||||
!!! info Traefik Helm Chart
|
|
||||||
|
|
||||||
This provider is disabled by default in the Traefik Helm Chart.
|
|
||||||
|
|
||||||
!!! example "Route with this Certificate"
|
|
||||||
|
|
||||||
```yaml tab="HTTPRoute"
|
|
||||||
---
|
|
||||||
apiVersion: gateway.networking.k8s.io/v1
|
|
||||||
kind: Gateway
|
|
||||||
metadata:
|
|
||||||
name: domain-gateway
|
|
||||||
spec:
|
|
||||||
gatewayClassName: traefik
|
|
||||||
listeners:
|
|
||||||
- name: websecure
|
|
||||||
port: 8443
|
|
||||||
protocol: HTTPS
|
|
||||||
hostname: domain.example.com
|
|
||||||
tls:
|
|
||||||
certificateRefs:
|
|
||||||
- name: domain-tls # <==== Use the name defined in Certificate resource.
|
|
||||||
---
|
|
||||||
apiVersion: gateway.networking.k8s.io/v1
|
|
||||||
kind: HTTPRoute
|
|
||||||
metadata:
|
|
||||||
name: domain
|
|
||||||
spec:
|
|
||||||
parentRefs:
|
|
||||||
- name: domain-gateway
|
|
||||||
hostnames:
|
|
||||||
- domain.example.com
|
|
||||||
rules:
|
|
||||||
- matches:
|
|
||||||
- path:
|
|
||||||
type: Exact
|
|
||||||
value: /
|
|
||||||
|
|
||||||
backendRefs:
|
|
||||||
- name: domain-service
|
|
||||||
port: 80
|
|
||||||
weight: 1
|
|
||||||
```
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
There are multiple event sources available to investigate when using cert-manager:
|
|
||||||
|
|
||||||
1. Kubernetes events in `Certificate` and `CertificateRequest` resources
|
|
||||||
2. cert-manager logs
|
|
||||||
3. Dashboard and/or (debug) logs from Traefik Proxy
|
|
||||||
|
|
||||||
cert-manager documentation provides a [detailed guide](https://cert-manager.io/docs/troubleshooting/) on how to troubleshoot a certificate request.
|
|
||||||
|
|
||||||
{% include-markdown "includes/traefik-for-business-applications.md" %}
|
|
||||||
@@ -1,32 +0,0 @@
|
|||||||
apiVersion: v1
|
|
||||||
kind: Service
|
|
||||||
metadata:
|
|
||||||
name: traefik
|
|
||||||
|
|
||||||
spec:
|
|
||||||
ports:
|
|
||||||
- protocol: TCP
|
|
||||||
name: web
|
|
||||||
port: 8000
|
|
||||||
- protocol: TCP
|
|
||||||
name: admin
|
|
||||||
port: 8080
|
|
||||||
- protocol: TCP
|
|
||||||
name: websecure
|
|
||||||
port: 4443
|
|
||||||
selector:
|
|
||||||
app: traefik
|
|
||||||
|
|
||||||
---
|
|
||||||
apiVersion: v1
|
|
||||||
kind: Service
|
|
||||||
metadata:
|
|
||||||
name: whoami
|
|
||||||
|
|
||||||
spec:
|
|
||||||
ports:
|
|
||||||
- protocol: TCP
|
|
||||||
name: web
|
|
||||||
port: 80
|
|
||||||
selector:
|
|
||||||
app: whoami
|
|
||||||
@@ -1,74 +0,0 @@
|
|||||||
apiVersion: v1
|
|
||||||
kind: ServiceAccount
|
|
||||||
metadata:
|
|
||||||
namespace: default
|
|
||||||
name: traefik-ingress-controller
|
|
||||||
|
|
||||||
---
|
|
||||||
kind: Deployment
|
|
||||||
apiVersion: apps/v1
|
|
||||||
metadata:
|
|
||||||
namespace: default
|
|
||||||
name: traefik
|
|
||||||
labels:
|
|
||||||
app: traefik
|
|
||||||
|
|
||||||
spec:
|
|
||||||
replicas: 1
|
|
||||||
selector:
|
|
||||||
matchLabels:
|
|
||||||
app: traefik
|
|
||||||
template:
|
|
||||||
metadata:
|
|
||||||
labels:
|
|
||||||
app: traefik
|
|
||||||
spec:
|
|
||||||
serviceAccountName: traefik-ingress-controller
|
|
||||||
containers:
|
|
||||||
- name: traefik
|
|
||||||
image: traefik:v3.6
|
|
||||||
args:
|
|
||||||
- --api.insecure
|
|
||||||
- --accesslog
|
|
||||||
- --entryPoints.web.Address=:8000
|
|
||||||
- --entryPoints.websecure.Address=:4443
|
|
||||||
- --providers.kubernetescrd
|
|
||||||
- --certificatesresolvers.myresolver.acme.tlschallenge
|
|
||||||
- --certificatesresolvers.myresolver.acme.email=foo@you.com
|
|
||||||
- --certificatesresolvers.myresolver.acme.storage=acme.json
|
|
||||||
# Please note that this is the staging Let's Encrypt server.
|
|
||||||
# Once you get things working, you should remove that whole line altogether.
|
|
||||||
- --certificatesresolvers.myresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory
|
|
||||||
ports:
|
|
||||||
- name: web
|
|
||||||
containerPort: 8000
|
|
||||||
- name: websecure
|
|
||||||
containerPort: 4443
|
|
||||||
- name: admin
|
|
||||||
containerPort: 8080
|
|
||||||
|
|
||||||
---
|
|
||||||
kind: Deployment
|
|
||||||
apiVersion: apps/v1
|
|
||||||
metadata:
|
|
||||||
namespace: default
|
|
||||||
name: whoami
|
|
||||||
labels:
|
|
||||||
app: whoami
|
|
||||||
|
|
||||||
spec:
|
|
||||||
replicas: 2
|
|
||||||
selector:
|
|
||||||
matchLabels:
|
|
||||||
app: whoami
|
|
||||||
template:
|
|
||||||
metadata:
|
|
||||||
labels:
|
|
||||||
app: whoami
|
|
||||||
spec:
|
|
||||||
containers:
|
|
||||||
- name: whoami
|
|
||||||
image: traefik/whoami
|
|
||||||
ports:
|
|
||||||
- name: web
|
|
||||||
containerPort: 80
|
|
||||||
@@ -1,32 +0,0 @@
|
|||||||
apiVersion: traefik.io/v1alpha1
|
|
||||||
kind: IngressRoute
|
|
||||||
metadata:
|
|
||||||
name: simpleingressroute
|
|
||||||
namespace: default
|
|
||||||
spec:
|
|
||||||
entryPoints:
|
|
||||||
- web
|
|
||||||
routes:
|
|
||||||
- match: Host(`your.example.com`) && PathPrefix(`/notls`)
|
|
||||||
kind: Rule
|
|
||||||
services:
|
|
||||||
- name: whoami
|
|
||||||
port: 80
|
|
||||||
|
|
||||||
---
|
|
||||||
apiVersion: traefik.io/v1alpha1
|
|
||||||
kind: IngressRoute
|
|
||||||
metadata:
|
|
||||||
name: ingressroutetls
|
|
||||||
namespace: default
|
|
||||||
spec:
|
|
||||||
entryPoints:
|
|
||||||
- websecure
|
|
||||||
routes:
|
|
||||||
- match: Host(`your.example.com`) && PathPrefix(`/tls`)
|
|
||||||
kind: Rule
|
|
||||||
services:
|
|
||||||
- name: whoami
|
|
||||||
port: 80
|
|
||||||
tls:
|
|
||||||
certResolver: myresolver
|
|
||||||
@@ -1,17 +0,0 @@
|
|||||||
---
|
|
||||||
apiVersion: traefik.io/v1alpha1
|
|
||||||
kind: TLSOption
|
|
||||||
metadata:
|
|
||||||
name: default
|
|
||||||
namespace: default
|
|
||||||
spec:
|
|
||||||
minVersion: VersionTLS12
|
|
||||||
cipherSuites:
|
|
||||||
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 # TLS 1.2
|
|
||||||
- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 # TLS 1.2
|
|
||||||
- TLS_AES_256_GCM_SHA384 # TLS 1.3
|
|
||||||
- TLS_CHACHA20_POLY1305_SHA256 # TLS 1.3
|
|
||||||
curvePreferences:
|
|
||||||
- CurveP521
|
|
||||||
- CurveP384
|
|
||||||
sniStrict: true
|
|
||||||
@@ -1,134 +0,0 @@
|
|||||||
---
|
|
||||||
title: "Traefik CRD TLS Documentation"
|
|
||||||
description: "Learn how to use Traefik Proxy w/ an IngressRoute Custom Resource Definition (CRD) for Kubernetes, and TLS with Let's Encrypt. Read the technical documentation."
|
|
||||||
---
|
|
||||||
|
|
||||||
# Traefik & CRD & Let's Encrypt
|
|
||||||
|
|
||||||
Traefik with an IngressRoute Custom Resource Definition for Kubernetes, and TLS Through Let's Encrypt.
|
|
||||||
{: .subtitle }
|
|
||||||
|
|
||||||
This document is intended to be a fully working example demonstrating how to set up Traefik in [Kubernetes](https://kubernetes.io),
|
|
||||||
with the dynamic configuration coming from the [IngressRoute Custom Resource](../../providers/kubernetes-crd.md),
|
|
||||||
and TLS setup with [Let's Encrypt](https://letsencrypt.org).
|
|
||||||
However, for the sake of simplicity, we're using [k3s](https://github.com/rancher/k3s) docker image for the Kubernetes cluster setup.
|
|
||||||
|
|
||||||
Please note that for this setup, given that we're going to use ACME's TLS-ALPN-01 challenge, the host you'll be running it on must be able to receive connections from the outside on port 443.
|
|
||||||
And of course its internet facing IP address must match the domain name you intend to use.
|
|
||||||
|
|
||||||
In the following, the Kubernetes resources defined in YAML configuration files can be applied to the setup in two different ways:
|
|
||||||
|
|
||||||
- the first, and usual way, is simply with the `kubectl apply` command.
|
|
||||||
- the second, which can be used for this tutorial, is to directly place the files in the directory used by the k3s docker image for such inputs (`/var/lib/rancher/k3s/server/manifests`).
|
|
||||||
|
|
||||||
!!! important "Kubectl Version"
|
|
||||||
|
|
||||||
With the `rancher/k3s` version used in this guide (`0.8.0`), the kubectl version needs to be >= `1.11`.
|
|
||||||
|
|
||||||
## k3s Docker-compose Configuration
|
|
||||||
|
|
||||||
Our starting point is the docker-compose configuration file, to start the k3s cluster.
|
|
||||||
You can start it with:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker compose -f k3s.yml up
|
|
||||||
```
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
--8<-- "content/user-guides/crd-acme/k3s.yml"
|
|
||||||
```
|
|
||||||
|
|
||||||
## Cluster Resources
|
|
||||||
|
|
||||||
Let's now have a look (in the order they should be applied, if using `kubectl apply`) at all the required resources for the full setup.
|
|
||||||
|
|
||||||
### IngressRoute Definition
|
|
||||||
|
|
||||||
First, you will need to install Traefik CRDs containing the definition of the `IngressRoute` and the `Middleware` kinds,
|
|
||||||
and the RBAC authorization resources which will be referenced through the `serviceAccountName` of the deployment.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Install Traefik Resource Definitions:
|
|
||||||
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml
|
|
||||||
|
|
||||||
# Install RBAC for Traefik:
|
|
||||||
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/reference/dynamic-configuration/kubernetes-crd-rbac.yml
|
|
||||||
```
|
|
||||||
|
|
||||||
### Services
|
|
||||||
|
|
||||||
Then, the services. One for Traefik itself, and one for the app it routes for, i.e. in this case our demo HTTP server: [whoami](https://github.com/traefik/whoami).
|
|
||||||
|
|
||||||
```bash
|
|
||||||
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/user-guides/crd-acme/02-services.yml
|
|
||||||
```
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
--8<-- "content/user-guides/crd-acme/02-services.yml"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Deployments
|
|
||||||
|
|
||||||
Next, the deployments, i.e. the actual pods behind the services.
|
|
||||||
Again, one pod for Traefik, and one for the whoami app.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/user-guides/crd-acme/03-deployments.yml
|
|
||||||
```
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
--8<-- "content/user-guides/crd-acme/03-deployments.yml"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Port Forwarding
|
|
||||||
|
|
||||||
Now, as an exception to what we said above, please note that you should not let the ingressRoute resources below be applied automatically to your cluster.
|
|
||||||
The reason is, as soon as the ACME provider of Traefik detects we have TLS routers, it will try to generate the certificates for the corresponding domains.
|
|
||||||
And this will not work, because as it is, our Traefik pod is not reachable from the outside, which will make the ACME TLS challenge fail.
|
|
||||||
Therefore, for the whole thing to work, we must delay applying the ingressRoute resources until we have port-forwarding set up properly, which is the next step.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
kubectl port-forward --address 0.0.0.0 service/traefik 8000:8000 8080:8080 443:4443 -n default
|
|
||||||
```
|
|
||||||
|
|
||||||
Also, and this is out of the scope of this guide, please note that because of the privileged ports limitation on Linux, the above command might fail to listen on port 443.
|
|
||||||
In which case you can use tricks such as elevating caps of `kubectl` with `setcaps`, or using `authbind`, or setting up a NAT between your host and the WAN.
|
|
||||||
Look it up.
|
|
||||||
|
|
||||||
### Traefik Routers
|
|
||||||
|
|
||||||
We can now finally apply the actual ingressRoutes, with:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/user-guides/crd-acme/04-ingressroutes.yml
|
|
||||||
```
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
--8<-- "content/user-guides/crd-acme/04-ingressroutes.yml"
|
|
||||||
```
|
|
||||||
|
|
||||||
Give it a few seconds for the ACME TLS challenge to complete, and you should then be able to access your whoami pod (routed through Traefik), from the outside.
|
|
||||||
Both with or (just for fun, do not do that in production) without TLS:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl [-k] https://your.example.com/tls
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl http://your.example.com:8000/notls
|
|
||||||
```
|
|
||||||
|
|
||||||
Note that you'll have to use `-k` as long as you're using the staging server of Let's Encrypt, since it is not an authorized certificate authority on systems where it hasn't been manually added.
|
|
||||||
|
|
||||||
### Force TLS v1.2+
|
|
||||||
|
|
||||||
Nowadays, TLS v1.0 and v1.1 are deprecated.
|
|
||||||
In order to force TLS v1.2 or later on all your IngressRoute, you can define the `default` TLSOption:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/user-guides/crd-acme/05-tlsoption.yml
|
|
||||||
```
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
--8<-- "content/user-guides/crd-acme/05-tlsoption.yml"
|
|
||||||
```
|
|
||||||
@@ -1,30 +0,0 @@
|
|||||||
server:
|
|
||||||
image: rancher/k3s:v1.34.2-k3s1
|
|
||||||
command: server --disable-agent --no-deploy traefik
|
|
||||||
environment:
|
|
||||||
- K3S_CLUSTER_SECRET=somethingtotallyrandom
|
|
||||||
- K3S_KUBECONFIG_OUTPUT=/output/kubeconfig.yaml
|
|
||||||
- K3S_KUBECONFIG_MODE=666
|
|
||||||
volumes:
|
|
||||||
# k3s will generate a kubeconfig.yaml in this directory. This volume is mounted
|
|
||||||
# on your host, so you can then 'export KUBECONFIG=/somewhere/on/your/host/out/kubeconfig.yaml',
|
|
||||||
# in order for your kubectl commands to work.
|
|
||||||
- /somewhere/on/your/host/out:/output
|
|
||||||
# This directory is where you put all the (yaml) configuration files of
|
|
||||||
# the Kubernetes resources.
|
|
||||||
- /somewhere/on/your/host/in:/var/lib/rancher/k3s/server/manifests
|
|
||||||
ports:
|
|
||||||
- 6443:6443
|
|
||||||
|
|
||||||
node:
|
|
||||||
image: rancher/k3s:v1.34.2-k3s1
|
|
||||||
privileged: true
|
|
||||||
links:
|
|
||||||
- server
|
|
||||||
environment:
|
|
||||||
- K3S_URL=https://server:6443
|
|
||||||
- K3S_CLUSTER_SECRET=somethingtotallyrandom
|
|
||||||
volumes:
|
|
||||||
# this is where you would place a alternative traefik image (saved as a .tar file with
|
|
||||||
# 'docker save'), if you want to use it, instead of the traefik:v3.6 image.
|
|
||||||
- /somewhere/on/your/host/custom-image:/var/lib/rancher/k3s/agent/images
|
|
||||||
@@ -1,283 +0,0 @@
|
|||||||
---
|
|
||||||
title: "Traefik Proxy gRPC Examples"
|
|
||||||
description: "This section of the Traefik Proxy documentation explains how to use Traefik as reverse proxy for gRPC applications."
|
|
||||||
---
|
|
||||||
|
|
||||||
# gRPC Examples
|
|
||||||
|
|
||||||
## With HTTP (h2c)
|
|
||||||
|
|
||||||
This section explains how to use Traefik as reverse proxy for gRPC application.
|
|
||||||
|
|
||||||
### Traefik Configuration
|
|
||||||
|
|
||||||
Static configuration:
|
|
||||||
|
|
||||||
```yaml tab="File (YAML)"
|
|
||||||
entryPoints:
|
|
||||||
web:
|
|
||||||
address: :80
|
|
||||||
|
|
||||||
providers:
|
|
||||||
file:
|
|
||||||
directory: /path/to/dynamic/config
|
|
||||||
|
|
||||||
api: {}
|
|
||||||
```
|
|
||||||
|
|
||||||
```toml tab="File (TOML)"
|
|
||||||
[entryPoints]
|
|
||||||
[entryPoints.web]
|
|
||||||
address = ":80"
|
|
||||||
|
|
||||||
[api]
|
|
||||||
|
|
||||||
[providers.file]
|
|
||||||
directory = "/path/to/dynamic/config"
|
|
||||||
```
|
|
||||||
|
|
||||||
```yaml tab="CLI"
|
|
||||||
--entryPoints.web.address=:80
|
|
||||||
--providers.file.directory=/path/to/dynamic/config
|
|
||||||
--api.insecure=true
|
|
||||||
```
|
|
||||||
|
|
||||||
`/path/to/dynamic/config/dynamic_conf.{yml,toml}`:
|
|
||||||
|
|
||||||
```yaml tab="YAML"
|
|
||||||
## dynamic configuration ##
|
|
||||||
|
|
||||||
http:
|
|
||||||
routers:
|
|
||||||
routerTest:
|
|
||||||
service: srv-grpc
|
|
||||||
rule: Host(`frontend.local`)
|
|
||||||
|
|
||||||
services:
|
|
||||||
srv-grpc:
|
|
||||||
loadBalancer:
|
|
||||||
servers:
|
|
||||||
- url: h2c://backend.local:8080
|
|
||||||
```
|
|
||||||
|
|
||||||
```toml tab="TOML"
|
|
||||||
## dynamic configuration ##
|
|
||||||
|
|
||||||
[http]
|
|
||||||
|
|
||||||
[http.routers]
|
|
||||||
[http.routers.routerTest]
|
|
||||||
service = "srv-grpc"
|
|
||||||
rule = "Host(`frontend.local`)"
|
|
||||||
|
|
||||||
[http.services]
|
|
||||||
[http.services.srv-grpc]
|
|
||||||
[http.services.srv-grpc.loadBalancer]
|
|
||||||
[[http.services.srv-grpc.loadBalancer.servers]]
|
|
||||||
url = "h2c://backend.local:8080"
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
For providers with labels, you will have to specify the `traefik.http.services.<my-service-name>.loadbalancer.server.scheme=h2c`
|
|
||||||
|
|
||||||
### Conclusion
|
|
||||||
|
|
||||||
We don't need specific configuration to use gRPC in Traefik, we just need to use `h2c` protocol, or use HTTPS communications to have HTTP2 with the backend.
|
|
||||||
|
|
||||||
## With HTTPS
|
|
||||||
|
|
||||||
This section explains how to use Traefik as reverse proxy for gRPC application with self-signed certificates.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### gRPC Server Certificate
|
|
||||||
|
|
||||||
In order to secure the gRPC server, we generate a self-signed certificate for service url:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./backend.key -out ./backend.cert
|
|
||||||
```
|
|
||||||
|
|
||||||
That will prompt for information, the important answer is:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
Common Name (e.g. server FQDN or YOUR name) []: backend.local
|
|
||||||
```
|
|
||||||
|
|
||||||
### gRPC Client Certificate
|
|
||||||
|
|
||||||
Generate your self-signed certificate for router url:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./frontend.key -out ./frontend.cert
|
|
||||||
```
|
|
||||||
|
|
||||||
with
|
|
||||||
|
|
||||||
```txt
|
|
||||||
Common Name (e.g. server FQDN or YOUR name) []: frontend.local
|
|
||||||
```
|
|
||||||
|
|
||||||
### Traefik Configuration
|
|
||||||
|
|
||||||
At last, we configure our Traefik instance to use both self-signed certificates.
|
|
||||||
|
|
||||||
Static configuration:
|
|
||||||
|
|
||||||
```yaml tab="File (YAML)"
|
|
||||||
entryPoints:
|
|
||||||
websecure:
|
|
||||||
address: :4443
|
|
||||||
|
|
||||||
serversTransport:
|
|
||||||
# For secure connection on backend.local
|
|
||||||
rootCAs:
|
|
||||||
- ./backend.cert
|
|
||||||
|
|
||||||
providers:
|
|
||||||
file:
|
|
||||||
directory: /path/to/dynamic/config
|
|
||||||
|
|
||||||
api: {}
|
|
||||||
```
|
|
||||||
|
|
||||||
```toml tab="File (TOML)"
|
|
||||||
[entryPoints]
|
|
||||||
[entryPoints.websecure]
|
|
||||||
address = ":4443"
|
|
||||||
|
|
||||||
|
|
||||||
[serversTransport]
|
|
||||||
# For secure connection on backend.local
|
|
||||||
rootCAs = [ "./backend.cert" ]
|
|
||||||
|
|
||||||
[api]
|
|
||||||
|
|
||||||
[provider.file]
|
|
||||||
directory = "/path/to/dynamic/config"
|
|
||||||
```
|
|
||||||
|
|
||||||
```yaml tab="CLI"
|
|
||||||
--entryPoints.websecure.address=:4443
|
|
||||||
# For secure connection on backend.local
|
|
||||||
--serversTransport.rootCAs=./backend.cert
|
|
||||||
--providers.file.directory=/path/to/dynamic/config
|
|
||||||
--api.insecure=true
|
|
||||||
```
|
|
||||||
|
|
||||||
`/path/to/dynamic/config/dynamic_conf.{yml,toml}`:
|
|
||||||
|
|
||||||
```yaml tab="YAML"
|
|
||||||
## dynamic configuration ##
|
|
||||||
|
|
||||||
http:
|
|
||||||
routers:
|
|
||||||
routerTest:
|
|
||||||
service: srv-grpc
|
|
||||||
rule: Host(`frontend.local`)
|
|
||||||
services:
|
|
||||||
srv-grpc:
|
|
||||||
loadBalancer:
|
|
||||||
servers:
|
|
||||||
# Access on backend with HTTPS
|
|
||||||
- url: https://backend.local:8080
|
|
||||||
tls:
|
|
||||||
# For secure connection on frontend.local
|
|
||||||
certificates:
|
|
||||||
- certfile: ./frontend.cert
|
|
||||||
keyfile: ./frontend.key
|
|
||||||
```
|
|
||||||
|
|
||||||
```toml tab="TOML"
|
|
||||||
## dynamic configuration ##
|
|
||||||
|
|
||||||
[http]
|
|
||||||
|
|
||||||
[http.routers]
|
|
||||||
[http.routers.routerTest]
|
|
||||||
service = "srv-grpc"
|
|
||||||
rule = "Host(`frontend.local`)"
|
|
||||||
|
|
||||||
[http.services]
|
|
||||||
[http.services.srv-grpc]
|
|
||||||
[http.services.srv-grpc.loadBalancer]
|
|
||||||
[[http.services.srv-grpc.loadBalancer.servers]]
|
|
||||||
# Access on backend with HTTPS
|
|
||||||
url = "https://backend.local:8080"
|
|
||||||
|
|
||||||
[tls]
|
|
||||||
|
|
||||||
# For secure connection on frontend.local
|
|
||||||
[[tls.certificates]]
|
|
||||||
certFile = "./frontend.cert"
|
|
||||||
keyFile = "./frontend.key"
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
With some services, the server URLs use the IP, so you may need to configure `insecureSkipVerify` instead of the `rootCAs` to activate HTTPS without hostname verification.
|
|
||||||
|
|
||||||
### A gRPC example in go (modify for https)
|
|
||||||
|
|
||||||
We use the gRPC greeter example in [grpc-go](https://github.com/grpc/grpc-go/tree/master/examples/helloworld)
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
In order to use this gRPC example, we need to modify it to use HTTPS
|
|
||||||
|
|
||||||
So we modify the "gRPC server example" to use our own self-signed certificate:
|
|
||||||
|
|
||||||
```go
|
|
||||||
// ...
|
|
||||||
|
|
||||||
// Read cert and key file
|
|
||||||
backendCert, _ := os.ReadFile("./backend.cert")
|
|
||||||
backendKey, _ := os.ReadFile("./backend.key")
|
|
||||||
|
|
||||||
// Generate Certificate struct
|
|
||||||
cert, err := tls.X509KeyPair(backendCert, backendKey)
|
|
||||||
if err != nil {
|
|
||||||
log.Fatalf("failed to parse certificate: %v", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
// Create credentials
|
|
||||||
creds := credentials.NewServerTLSFromCert(&cert)
|
|
||||||
|
|
||||||
// Use Credentials in gRPC server options
|
|
||||||
serverOption := grpc.Creds(creds)
|
|
||||||
var s *grpc.Server = grpc.NewServer(serverOption)
|
|
||||||
defer s.Stop()
|
|
||||||
|
|
||||||
pb.RegisterGreeterServer(s, &server{})
|
|
||||||
err := s.Serve(lis)
|
|
||||||
|
|
||||||
// ...
|
|
||||||
```
|
|
||||||
|
|
||||||
Next we will modify gRPC Client to use our Traefik self-signed certificate:
|
|
||||||
|
|
||||||
```go
|
|
||||||
// ...
|
|
||||||
|
|
||||||
// Read cert file
|
|
||||||
frontendCert, _ := os.ReadFile("./frontend.cert")
|
|
||||||
|
|
||||||
// Create CertPool
|
|
||||||
roots := x509.NewCertPool()
|
|
||||||
roots.AppendCertsFromPEM(frontendCert)
|
|
||||||
|
|
||||||
// Create credentials
|
|
||||||
credsClient := credentials.NewClientTLSFromCert(roots, "")
|
|
||||||
|
|
||||||
// Dial with specific Transport (with credentials)
|
|
||||||
conn, err := grpc.Dial("frontend.local:4443", grpc.WithTransportCredentials(credsClient))
|
|
||||||
if err != nil {
|
|
||||||
log.Fatalf("did not connect: %v", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
defer conn.Close()
|
|
||||||
client := pb.NewGreeterClient(conn)
|
|
||||||
|
|
||||||
name := "World"
|
|
||||||
r, err := client.SayHello(context.Background(), &pb.HelloRequest{Name: name})
|
|
||||||
|
|
||||||
// ...
|
|
||||||
```
|
|
||||||
@@ -1,355 +0,0 @@
|
|||||||
---
|
|
||||||
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.
|
|
||||||
+9
-13
@@ -139,13 +139,12 @@ plugins:
|
|||||||
'user-guides/crd-acme/index.md': 'expose/kubernetes/basic.md'
|
'user-guides/crd-acme/index.md': 'expose/kubernetes/basic.md'
|
||||||
'user-guides/cert-manager.md': 'expose/kubernetes/advanced.md'
|
'user-guides/cert-manager.md': 'expose/kubernetes/advanced.md'
|
||||||
'user-guides/docker-compose/basic-example/index.md': 'expose/docker/basic.md'
|
'user-guides/docker-compose/basic-example/index.md': 'expose/docker/basic.md'
|
||||||
'user-guides/docker-compose/acme-tls/index.md': 'expose/docker/advanced.md'
|
'user-guides/docker-compose/acme-tls/index.md': 'expose/docker/basic.md'
|
||||||
'user-guides/docker-compose/acme-http/index.md': 'expose/docker/advanced.md'
|
'user-guides/docker-compose/acme-http/index.md': 'expose/docker/basic.md'
|
||||||
'user-guides/docker-compose/acme-dns/index.md': 'expose/docker/advanced.md'
|
'user-guides/docker-compose/acme-dns/index.md': 'expose/docker/basic.md'
|
||||||
## Expose pages (redirect old URLs to new structure)
|
'user-guides/fastproxy.md': 'reference/install-configuration/experimental/fastproxy.md'
|
||||||
'expose/kubernetes.md': 'expose/kubernetes/basic.md'
|
'user-guides/grpc.md': 'expose/overview.md#exposing-grpc-services'
|
||||||
'expose/docker.md': 'expose/docker/basic.md'
|
'user-guides/websocket.md': 'expose/overview.md#exposing-websocket-services'
|
||||||
'expose/swarm.md': 'expose/swarm/basic.md'
|
|
||||||
# References
|
# References
|
||||||
# Static Configuration
|
# Static Configuration
|
||||||
'reference/static-configuration/overview.md': 'reference/install-configuration/configuration-options.md'
|
'reference/static-configuration/overview.md': 'reference/install-configuration/configuration-options.md'
|
||||||
@@ -273,6 +272,9 @@ nav:
|
|||||||
- 'Tracing': 'reference/install-configuration/observability/tracing.md'
|
- 'Tracing': 'reference/install-configuration/observability/tracing.md'
|
||||||
- 'Logs & AccessLogs': 'reference/install-configuration/observability/logs-and-accesslogs.md'
|
- 'Logs & AccessLogs': 'reference/install-configuration/observability/logs-and-accesslogs.md'
|
||||||
- 'Health Check (CLI & Ping)': 'reference/install-configuration/observability/healthcheck.md'
|
- 'Health Check (CLI & Ping)': 'reference/install-configuration/observability/healthcheck.md'
|
||||||
|
- 'Experimental':
|
||||||
|
- 'FastProxy': 'reference/install-configuration/experimental/fastproxy.md'
|
||||||
|
- 'Plugins': 'reference/install-configuration/experimental/plugins.md'
|
||||||
- 'Options List': 'reference/install-configuration/configuration-options.md'
|
- 'Options List': 'reference/install-configuration/configuration-options.md'
|
||||||
- 'Routing Configuration':
|
- 'Routing Configuration':
|
||||||
- 'Common Configuration' :
|
- 'Common Configuration' :
|
||||||
@@ -378,12 +380,6 @@ nav:
|
|||||||
- 'Deprecation Notices':
|
- 'Deprecation Notices':
|
||||||
- 'Releases': 'deprecation/releases.md'
|
- 'Releases': 'deprecation/releases.md'
|
||||||
- 'Features': 'deprecation/features.md'
|
- 'Features': 'deprecation/features.md'
|
||||||
- 'User Guides':
|
|
||||||
- 'FastProxy': 'user-guides/fastproxy.md'
|
|
||||||
- 'Kubernetes and Let''s Encrypt': 'user-guides/crd-acme/index.md'
|
|
||||||
- 'Kubernetes and cert-manager': 'user-guides/cert-manager.md'
|
|
||||||
- 'gRPC Examples': 'user-guides/grpc.md'
|
|
||||||
- 'WebSocket Examples': 'user-guides/websocket.md'
|
|
||||||
- 'Contributing':
|
- 'Contributing':
|
||||||
- 'Thank You!': 'contributing/thank-you.md'
|
- 'Thank You!': 'contributing/thank-you.md'
|
||||||
- 'Submitting Issues': 'contributing/submitting-issues.md'
|
- 'Submitting Issues': 'contributing/submitting-issues.md'
|
||||||
|
|||||||
Reference in New Issue
Block a user