mirrors/traefik
1
0
Fork 0
mirror of https://github.com/traefik/traefik.git synced 2025-08-06 06:37:09 +02:00
Code Issues Projects Releases Wiki Activity

Merge branch v3.4 into v3.5

Browse Source
This commit is contained in:
kevinpollet 2025-07-11 10:29:18 +02:00
commit ff992fb7f9
No known key found for this signature in database
GPG Key ID: 0C9A5DDD1B292453
41 changed files with 3830 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
CHANGELOG.md
View File

@ -1,3 +1,26 @@
## [v3.4.4](https://github.com/traefik/traefik/tree/v3.4.4) (2025-07-11)
[All Commits](https://github.com/traefik/traefik/compare/v3.4.3...v3.4.4)
**Bug fixes:**
- **[k8s/gatewayapi]** Respect service.nativelb=false annotation when nativeLBByDefault is enabled ([#11847](https://github.com/traefik/traefik/pull/11847) by [sdelicata](https://github.com/sdelicata))
- **[service]** Fix concurrent access to balancer status map in WRR and P2C strategies ([#11887](https://github.com/traefik/traefik/pull/11887) by [kevinpollet](https://github.com/kevinpollet))
**Documentation:**
- **[docker,k8s]** Add New Expose Guides ([#11760](https://github.com/traefik/traefik/pull/11760) by [sheddy-traefik](https://github.com/sheddy-traefik))
- **[docker,k8s]** Add New Setup Guides ([#11741](https://github.com/traefik/traefik/pull/11741) by [sheddy-traefik](https://github.com/sheddy-traefik))
- **[docker/swarm]** Fix label for overriding swarm network on container ([#11881](https://github.com/traefik/traefik/pull/11881) by [kevinpollet](https://github.com/kevinpollet))
- **[logs,accesslogs]** Update Logs and Accesslogs Reference documentation with OTLP Options ([#11845](https://github.com/traefik/traefik/pull/11845) by [sheddy-traefik](https://github.com/sheddy-traefik))
- Update what is Traefik page to include full Traefik Platform context ([#11885](https://github.com/traefik/traefik/pull/11885) by [tomatokoolaid](https://github.com/tomatokoolaid))
**Misc:**
- Merge branch v2.11 into v3.4 ([#11896](https://github.com/traefik/traefik/pull/11896) by [kevinpollet](https://github.com/kevinpollet))
## [v2.11.27](https://github.com/traefik/traefik/tree/v2.11.27) (2025-07-11)
[All Commits](https://github.com/traefik/traefik/compare/v2.11.26...v2.11.27)
**Bug fixes:**
- Bump github.com/go-viper/mapstructure/v2 to v2.3.0 ([#11880](https://github.com/traefik/traefik/pull/11880) by [kevinpollet](https://github.com/kevinpollet))
## [v3.5.0-rc1](https://github.com/traefik/traefik/tree/v3.5.0-rc1) (2025-06-26)
[All Commits](https://github.com/traefik/traefik/compare/v3.4.0-rc1...v3.5.0-rc1)

BIN
docs/content/assets/img/setup/route-in-dashboard.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 482 KiB

BIN
docs/content/assets/img/setup/traefik-dashboard-docker.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 731 KiB

BIN
docs/content/assets/img/setup/traefik-dashboard-swarm.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 715 KiB

BIN
docs/content/assets/img/setup/traefik-dashboard.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 733 KiB

BIN
docs/content/assets/img/setup/whoami-json-dump.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 358 KiB

462
docs/content/expose/docker.md Normal file
View File

@ -0,0 +1,462 @@
# Exposing Services with Traefik on Docker
This guide will help you expose your services securely through Traefik Proxy using Docker. We'll cover routing HTTP and HTTPS traffic, implementing TLS, adding middlewares, Let's Encrypt integration, and sticky sessions.
## Prerequisites
- Docker and Docker Compose installed
- Basic understanding of Docker concepts
- Traefik deployed using the Traefik Docker Setup guide
## Expose Your First HTTP Service
Let's expose a simple HTTP service using the [whoami](https://hub.docker.com/r/traefik/whoami) application. This will demonstrate basic routing to a backend service.
First, create a `docker-compose.yml` file:
```yaml
services:
traefik:
image: "traefik:v3.4"
container_name: "traefik"
restart: unless-stopped
security_opt:
- no-new-privileges:true
networks:
- proxy
command:
- "--providers.docker=true"
- "--providers.docker.exposedbydefault=false"
- "--providers.docker.network=proxy"
- "--entryPoints.web.address=:80"
ports:
- "80:80"
- "8080:8080"
volumes:
- "/var/run/docker.sock:/var/run/docker.sock:ro"
whoami:
image: "traefik/whoami"
restart: unless-stopped
networks:
- proxy
labels:
- "traefik.enable=true"
- "traefik.http.routers.whoami.rule=Host(`whoami.docker.localhost`)"
- "traefik.http.routers.whoami.entrypoints=web"
networks:
proxy:
name: proxy
```
Save this as `docker-compose.yml` and start the services:
```bash
docker compose up -d
```
### Verify Your Service
Your service is now available at http://whoami.docker.localhost/. Test that it works:
```bash
curl -H "Host: whoami.docker.localhost" http://localhost/
```
You should see output similar to:
```bash
Hostname: whoami
IP: 127.0.0.1
IP: ::1
IP: 172.18.0.3
IP: fe80::215:5dff:fe00:c9e
RemoteAddr: 172.18.0.2:55108
GET / HTTP/1.1
Host: whoami.docker.localhost
User-Agent: curl/7.68.0
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 172.18.0.1
X-Forwarded-Host: whoami.docker.localhost
X-Forwarded-Port: 80
X-Forwarded-Proto: http
X-Forwarded-Server: 5789f594e7d5
X-Real-Ip: 172.18.0.1
```
This confirms that Traefik is successfully routing requests to your whoami application.
## Add Routing Rules
Now we'll enhance our routing by directing traffic to different services based on [URL paths](../reference/routing-configuration/http/router/rules-and-priority.md#path-pathprefix-and-pathregexp). This is useful for API versioning, frontend/backend separation, or organizing microservices.
Update your `docker-compose.yml` to add another service:
```yaml
# ...
# New service
whoami-api:
image: "traefik/whoami"
networks:
- proxy
container_name: "whoami-api"
environment:
- WHOAMI_NAME=API Service
labels:
- "traefik.enable=true"
# Path-based routing
- "traefik.http.routers.whoami-api.rule=Host(`whoami.docker.localhost`) && PathPrefix(`/api`)"
- "traefik.http.routers.whoami-api.entrypoints=web"
```
Apply the changes:
```bash
docker compose up -d
```
### Test the Path-Based Routing
Verify that different paths route to different services:
```bash
# Root path should go to the main whoami service
curl -H "Host: whoami.docker.localhost" http://localhost/
# /api path should go to the whoami-api service
curl -H "Host: whoami.docker.localhost" http://localhost/api
```
For the `/api` requests, you should see the response showing "API Service" in the environment variables section, confirming that your path-based routing is working correctly.
## Enable TLS
Let's secure our service with HTTPS by adding TLS. We'll start with a self-signed certificate for local development.
### Create a Self-Signed Certificate
Generate a self-signed certificate:
```bash
mkdir -p certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout certs/local.key -out certs/local.crt \
-subj "/CN=*.docker.localhost"
```
Create a directory for dynamic configuration and add a TLS configuration file:
```bash
mkdir -p dynamic
cat > dynamic/tls.yml << EOF
tls:
certificates:
- certFile: /certs/local.crt
keyFile: /certs/local.key
EOF
```
Update your `docker-compose.yml` file with the following changes:
```yaml
services:
traefik:
image: "traefik:v3.4"
container_name: "traefik"
restart: unless-stopped
security_opt:
- no-new-privileges:true
networks:
- proxy
command:
- "--api.insecure=false"
- "--api.dashboard=true"
- "--providers.docker=true"
- "--providers.docker.exposedbydefault=false"
- "--providers.docker.network=proxy"
- "--providers.file.directory=/etc/traefik/dynamic"
- "--entryPoints.web.address=:80"
- "--entryPoints.websecure.address=:443"
- "--entryPoints.websecure.http.tls=true"
ports:
- "80:80"
- "443:443"
- "8080:8080"
volumes:
- "/var/run/docker.sock:/var/run/docker.sock:ro"
# Add the following volumes
- "./certs:/certs:ro"
- "./dynamic:/etc/traefik/dynamic:ro"
labels:
- "traefik.enable=true"
- "traefik.http.routers.dashboard.rule=Host(`dashboard.docker.localhost`)"
- "traefik.http.routers.dashboard.entrypoints=websecure"
- "traefik.http.routers.dashboard.service=api@internal"
# Add the following label
- "traefik.http.routers.dashboard.tls=true"
whoami:
image: "traefik/whoami"
restart: unless-stopped
networks:
- proxy
labels:
- "traefik.enable=true"
- "traefik.http.routers.whoami.rule=Host(`whoami.docker.localhost`)"
- "traefik.http.routers.whoami.entrypoints=websecure"
# Add the following label
- "traefik.http.routers.whoami.tls=true"
whoami-api:
image: "traefik/whoami"
container_name: "whoami-api"
restart: unless-stopped
networks:
- proxy
environment:
- WHOAMI_NAME=API Service
labels:
- "traefik.enable=true"
- "traefik.http.routers.whoami-api.rule=Host(`whoami.docker.localhost`) && PathPrefix(`/api`)"
- "traefik.http.routers.whoami-api.entrypoints=websecure"
# Add the following label
- "traefik.http.routers.whoami-api.tls=true"
networks:
proxy:
name: proxy
```
Apply the changes:
```bash
docker compose up -d
```
Your browser can access https://whoami.docker.localhost/ for the service. You'll need to accept the security warning for the self-signed certificate.
## Add Middlewares
Middlewares allow you to modify requests or responses as they pass through Traefik. Let's add two useful middlewares: [Headers](../reference/routing-configuration/http/middlewares/headers.md) for security and [IP allowlisting](../reference/routing-configuration/http/middlewares/ipallowlist.md) for access control.
Add the following labels to your whoami service in `docker-compose.yml`:
```yaml
labels:
# Secure Headers Middleware
- "traefik.http.middlewares.secure-headers.headers.frameDeny=true"
- "traefik.http.middlewares.secure-headers.headers.sslRedirect=true"
- "traefik.http.middlewares.secure-headers.headers.browserXssFilter=true"
- "traefik.http.middlewares.secure-headers.headers.contentTypeNosniff=true"
- "traefik.http.middlewares.secure-headers.headers.stsIncludeSubdomains=true"
- "traefik.http.middlewares.secure-headers.headers.stsPreload=true"
- "traefik.http.middlewares.secure-headers.headers.stsSeconds=31536000"
# IP Allowlist Middleware
- "traefik.http.middlewares.ip-allowlist.ipallowlist.sourceRange=127.0.0.1/32,192.168.0.0/16,10.0.0.0/8"
```
Add the same middleware to your whoami-api service:
```yaml
labels:
- "traefik.http.routers.whoami-api.middlewares=secure-headers,ip-allowlist"
```
Apply the changes:
```bash
docker compose up -d
```
### Test the Middlewares
Now let's verify that our middlewares are working correctly:
Test the Secure Headers middleware:
```bash
curl -k -I -H "Host: whoami.docker.localhost" https://localhost/
```
In the response headers, you should see security headers set by the middleware:
- `X-Frame-Options: DENY`
- `X-Content-Type-Options: nosniff`
- `X-XSS-Protection: 1; mode=block`
- `Strict-Transport-Security` with the appropriate settings
Test the IP Allowlist middleware:
If your request comes from an IP that's in the allow list (e.g., 127.0.0.1), it should succeed:
```bash
curl -k -I -H "Host: whoami.docker.localhost" https://localhost/
```
If you try to access from an IP not in the allow list, the request will be rejected with a `403` Forbidden response. To simulate this in a local environment, you can modify the middleware configuration temporarily to exclude your IP address, then test again.
## Generate Certificates with Let's Encrypt
Let's Encrypt provides free, automated TLS certificates. Let's configure Traefik to automatically obtain and renew certificates for our services.
Instead of using self-signed certificates, update your existing `docker-compose.yml` file with the following changes:
Add the Let's Encrypt certificate resolver to the Traefik service command section:
```yaml
command:
- "--api.insecure=false"
- "--api.dashboard=true"
- "--providers.docker=true"
- "--providers.docker.exposedbydefault=false"
- "--providers.docker.network=proxy"
- "--entryPoints.web.address=:80"
- "--entryPoints.websecure.address=:443"
- "--entryPoints.websecure.http.tls=true"
- "--entryPoints.web.http.redirections.entryPoint.to=websecure"
- "--entryPoints.web.http.redirections.entryPoint.scheme=https"
# Let's Encrypt configuration
- "--certificatesresolvers.le.acme.email=your-email@example.com" # replace with your actual email
- "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
- "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
```
Add a volume for Let's Encrypt certificates:
```yaml
volumes:
# ...Existing volumes...
- "./letsencrypt:/letsencrypt"
```
Update your service labels to use the certificate resolver:
```yaml
labels:
- "traefik.http.routers.whoami.tls.certresolver=le"
```
Do the same for any other services you want to secure:
```yaml
labels:
- "traefik.http.routers.whoami-api.tls.certresolver=le"
```
Create a directory for storing Let's Encrypt certificates:
```bash
mkdir -p letsencrypt
```
Apply the changes:
```bash
docker compose up -d
```
!!! important "Public DNS Required"
Let's Encrypt may require a publicly accessible domain to validate domain ownership. For testing with local domains like `whoami.docker.localhost`, the certificate will remain self-signed. In production, replace it with a real domain that has a publicly accessible DNS record pointing to your Traefik instance.
Once the certificate is issued, you can verify it:
```bash
# Verify the certificate chain
curl -v https://whoami.docker.localhost/ 2>&1 | grep -i "server certificate"
```
You should see that your certificate is issued by Let's Encrypt.
## Configure Sticky Sessions
Sticky sessions ensure that a user's requests always go to the same backend server, which is essential for applications that maintain session state. Let's implement sticky sessions for our whoami service.
### First, Add Sticky Session Labels
Add the following labels to your whoami service in the `docker-compose.yml` file:
```yaml
labels:
- "traefik.http.services.whoami.loadbalancer.sticky.cookie=true"
- "traefik.http.services.whoami.loadbalancer.sticky.cookie.name=sticky_cookie"
- "traefik.http.services.whoami.loadbalancer.sticky.cookie.secure=true"
- "traefik.http.services.whoami.loadbalancer.sticky.cookie.httpOnly=true"
```
Apply the changes:
```bash
docker compose up -d
```
### Then, Scale Up the Service
To demonstrate sticky sessions with Docker, use Docker Compose's scale feature:
```bash
docker compose up -d --scale whoami=3
```
This creates multiple instances of the whoami service.
!!! important "Scaling After Configuration Changes"
If you run `docker compose up -d` after scaling, it will reset the number of whoami instances back to 1. Always scale after applying configuration changes and starting the services.
### Test Sticky Sessions
You can test the sticky sessions by making multiple requests and observing that they all go to the same backend container:
```bash
# First request - save cookies to a file
curl -k -c cookies.txt -H "Host: whoami.docker.localhost" https://localhost/
# Subsequent requests - use the cookies
curl -k -b cookies.txt -H "Host: whoami.docker.localhost" https://localhost/
curl -k -b cookies.txt -H "Host: whoami.docker.localhost" https://localhost/
```
Pay attention to the `Hostname` field in each response - it should remain the same across all requests when using the cookie file, confirming that sticky sessions are working.
For comparison, try making requests without the cookie:
```bash
# Requests without cookies should be load-balanced across different containers
curl -k -H "Host: whoami.docker.localhost" https://localhost/
curl -k -H "Host: whoami.docker.localhost" https://localhost/
```
You should see different `Hostname` values in these responses, as each request is load-balanced to a different container.
!!! important "Browser Testing"
When testing in browsers, you need to use the same browser session to maintain the cookie. The cookie is set with `httpOnly` and `secure` flags for security, so it will only be sent over HTTPS connections and won't be accessible via JavaScript.
For more advanced configuration options, see the [reference documentation](../reference/routing-configuration/http/load-balancing/service.md).
## Conclusion
In this guide, you've learned how to:
- Expose HTTP services through Traefik in Docker
- Set up path-based routing to direct traffic to different backend services
- Secure your services with TLS using self-signed certificates
- Add security with middlewares like secure headers and IP allow listing
- Automate certificate management with Let's Encrypt
- Implement sticky sessions for stateful applications
These fundamental capabilities provide a solid foundation for exposing any application through Traefik Proxy in Docker. Each of these can be further customized to meet your specific requirements.
### Next Steps
Now that you understand the basics of exposing services with Traefik Proxy, you might want to explore:
- [Advanced routing options](../reference/routing-configuration/http/router/rules-and-priority.md) like query parameter matching, header-based routing, and more
- [Additional middlewares](../reference/routing-configuration/http/middlewares/overview.md) for authentication, rate limiting, and request modifications
- [Observability features](../reference/install-configuration/observability/metrics.md) for monitoring and debugging your Traefik deployment
- [TCP services](../reference/routing-configuration/tcp/service.md) for exposing TCP services
- [UDP services](../reference/routing-configuration/udp/service.md) for exposing UDP services
- [Docker provider documentation](../reference/install-configuration/providers/docker.md) for more details about the Docker integration

1012
docs/content/expose/kubernetes.md Normal file
View File

File diff suppressed because it is too large Load Diff

22
docs/content/expose/overview.md Normal file
View File

@ -0,0 +1,22 @@
# Exposing Services with Traefik Proxy
This section guides you through exposing services securely with Traefik Proxy. You'll learn how to route HTTP and HTTPS traffic to your services, add security features, and implement advanced load balancing.
## What You'll Accomplish
Following these guides, you'll learn how to:
- Route HTTP traffic to your services with [Gateway API](../reference/routing-configuration/kubernetes/gateway-api.md) and [IngressRoute](../reference/routing-configuration/kubernetes/crd/http/ingressroute.md)
- Configure routing rules to direct requests
- Enable HTTPS with TLS
- Add security middlewares
- Generate certificates automatically with Let's Encrypt
- Implement sticky sessions for session persistence
## Platform-Specific Guides
For detailed steps tailored to your environment, follow the guide for your platform:
- [Kubernetes](./kubernetes.md)
- [Docker](./docker.md)
- [Docker Swarm](./swarm.md)

401
docs/content/expose/swarm.md Normal file
View File

@ -0,0 +1,401 @@
# Exposing Services with Traefik on Docker Swarm
This guide will help you expose your services securely through Traefik Proxy using Docker Swarm. We'll cover routing HTTP and HTTPS traffic, implementing TLS, adding middlewares, Let's Encrypt integration, and sticky sessions.
## Prerequisites
- Docker Swarm cluster initialized
- Basic understanding of Docker Swarm concepts
- Traefik deployed using the Traefik Docker Swarm Setup guide
## Expose Your First HTTP Service
Let's expose a simple HTTP service using the [whoami](https://hub.docker.com/r/traefik/whoami) application. This will demonstrate basic routing to a backend service.
First, update your existing `docker-compose.yml` file if you haven't already:
```yaml
services:
whoami:
image: traefik/whoami
networks:
- traefik_proxy
deploy:
replicas: 3
labels:
- "traefik.enable=true"
- "traefik.http.routers.whoami.rule=Host(`whoami.swarm.localhost`)"
- "traefik.http.routers.whoami.entrypoints=web,websecure"
```
Save this as `docker-compose.yml` and deploy the stack:
```bash
docker stack deploy -c docker-compose.yml traefik
```
### Verify Your Service
Your service is now available at http://whoami.swarm.localhost/. Test that it works:
```bash
curl -H "Host: whoami.swarm.localhost" http://localhost/
```
You should see output similar to:
```bash
Hostname: whoami.1.7c8f7tr56q3p949rscxrkp80e
IP: 127.0.0.1
IP: ::1
IP: 10.0.1.8
IP: fe80::215:5dff:fe00:c9e
RemoteAddr: 10.0.1.2:45098
GET / HTTP/1.1
Host: whoami.swarm.localhost
User-Agent: curl/7.68.0
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 10.0.1.1
X-Forwarded-Host: whoami.swarm.localhost
X-Forwarded-Port: 80
X-Forwarded-Proto: http
X-Forwarded-Server: 5789f594e7d5
X-Real-Ip: 10.0.1.1
```
This confirms that Traefik is successfully routing requests to your whoami application.
## Add Routing Rules
Now we'll enhance our routing by directing traffic to different services based on [URL paths](../reference/routing-configuration/http/router/rules-and-priority.md#path-pathprefix-and-pathregexp). This is useful for API versioning, frontend/backend separation, or organizing microservices.
Update your `docker-compose.yml` to add another service:
```yaml
# ...
# New service
whoami-api:
image: traefik/whoami
networks:
- traefik_proxy
environment:
- WHOAMI_NAME=API Service
deploy:
replicas: 2
labels:
- "traefik.enable=true"
# Path-based routing
- "traefik.http.routers.whoami-api.rule=Host(`whoami.swarm.localhost`) && PathPrefix(`/api`)"
- "traefik.http.routers.whoami-api.entrypoints=web,websecure"
- "traefik.http.routers.whoami-api.service=whoami-api-svc"
- "traefik.http.services.whoami-api-svc.loadbalancer.server.port=80"
# ...
```
Apply the changes:
```bash
docker stack deploy -c docker-compose.yml traefik
```
### Test the Path-Based Routing
Verify that different paths route to different services:
```bash
# Root path should go to the main whoami service
curl -H "Host: whoami.swarm.localhost" http://localhost/
# /api path should go to the whoami-api service
curl -H "Host: whoami.swarm.localhost" http://localhost/api
```
For the `/api` requests, you should see the response showing "API Service" in the environment variables section, confirming that your path-based routing is working correctly.
## Enable TLS
Let's secure our service with HTTPS by adding TLS. We'll start with a self-signed certificate for local development.
### Create a Self-Signed Certificate
Generate a self-signed certificate and dynamic config file to tell Traefik where the cert lives:
```bash
mkdir -p certs
# key + cert (valid for one year)
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout certs/local.key -out certs/local.crt \
-subj "/CN=*.swarm.localhost"
# dynamic config that tells Traefik where the cert lives
cat > certs/tls.yml <<'EOF'
tls:
certificates:
- certFile: /certificates/local.crt
keyFile: /certificates/local.key
EOF
```
Create a Docker config for the certificate files:
```bash
docker config create swarm-cert.crt certs/local.crt
docker config create swarm-cert.key certs/local.key
docker config create swarm-tls.yml certs/tls.yml
```
Update your `docker-compose.yml` file with the following changes:
```yaml
# Add to the Traefik command section:
command:
# ... existing commands ...
- "--entryPoints.websecure.address=:443"
- "--entryPoints.websecure.http.tls=true"
- "--providers.file.directory=/etc/traefik/dynamic"
```
```yaml
# Add to the root of your docker-compose.yml file:
configs:
swarm-cert.crt:
file: ./certs/local.crt
swarm-cert.key:
file: ./certs/local.key
swarm-tls.yml:
file: ./certs/tls.yml
```
Deploy the stack:
```bash
docker stack deploy -c docker-compose.yml traefik
```
Your browser can access https://whoami.swarm.localhost/ for the service. You'll need to accept the security warning for the self-signed certificate.
## Add Middlewares
Middlewares allow you to modify requests or responses as they pass through Traefik. Let's add two useful middlewares: [Headers](../reference/routing-configuration/http/middlewares/headers.md) for security and [IP allowlisting](../reference/routing-configuration/http/middlewares/ipallowlist.md) for access control.
Add the following labels to your whoami service deployment section in `docker-compose.yml`:
```yaml
deploy:
# ... existing configuration ...
labels:
# ... existing labels ...
# Secure Headers Middleware
- "traefik.http.middlewares.secure-headers.headers.frameDeny=true"
- "traefik.http.middlewares.secure-headers.headers.sslRedirect=true"
- "traefik.http.middlewares.secure-headers.headers.browserXssFilter=true"
- "traefik.http.middlewares.secure-headers.headers.contentTypeNosniff=true"
- "traefik.http.middlewares.secure-headers.headers.stsIncludeSubdomains=true"
- "traefik.http.middlewares.secure-headers.headers.stsPreload=true"
- "traefik.http.middlewares.secure-headers.headers.stsSeconds=31536000"
# IP Allowlist Middleware
- "traefik.http.middlewares.ip-allowlist.ipallowlist.sourceRange=127.0.0.1/32,192.168.0.0/16,10.0.0.0/8"
# Apply the middlewares
- "traefik.http.routers.whoami.middlewares=secure-headers,ip-allowlist"
```
Add the same middleware to your whoami-api service:
```yaml
deploy:
# ... existing configuration ...
labels:
# ... existing labels ...
- "traefik.http.routers.whoami-api.middlewares=secure-headers,ip-allowlist"
```
Apply the changes:
```bash
docker stack deploy -c docker-compose.yml traefik
```
### Test the Middlewares
Now let's verify that our middlewares are working correctly:
Test the Secure Headers middleware:
```bash
curl -k -I -H "Host: whoami.swarm.localhost" https://localhost/
```
In the response headers, you should see security headers set by the middleware:
- `X-Frame-Options: DENY`
- `X-Content-Type-Options: nosniff`
- `X-XSS-Protection: 1; mode=block`
- `Strict-Transport-Security` with the appropriate settings
Test the IP Allowlist middleware:
If your request comes from an IP that's in the allow list (e.g., 127.0.0.1), it should succeed:
```bash
curl -k -I -H "Host: whoami.swarm.localhost" https://localhost/
```
If you try to access from an IP not in the allow list, the request will be rejected with a `403` Forbidden response. To simulate this in a local environment, you can modify the middleware configuration temporarily to exclude your IP address, then test again.
## Generate Certificates with Let's Encrypt
Let's Encrypt provides free, automated TLS certificates. Let's configure Traefik to automatically obtain and renew certificates for our services.
Instead of using self-signed certificates, update your existing `docker-compose.yml` file with the following changes:
Add the Let's Encrypt certificate resolver to the Traefik service command section:
```yaml
command:
# ... existing commands ...
# Let's Encrypt configuration
- "--certificatesresolvers.le.acme.email=your-email@example.com" # replace with your actual email
- "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
- "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
```
Add a volume for Let's Encrypt certificates:
```yaml
volumes:
# ...Existing volumes...
- letsencrypt:/letsencrypt
```
Update your service labels to use the certificate resolver:
```yaml
labels:
# ... existing labels ...
- "traefik.http.routers.whoami.tls.certresolver=le"
```
Do the same for any other services you want to secure:
```yaml
labels:
# ... existing labels ...
- "traefik.http.routers.whoami-api.tls.certresolver=le"
```
Create a named volume for storing Let's Encrypt certificates by adding to the volumes section:
```yaml
volumes:
# ... existing volumes ...
letsencrypt:
driver: local
```
Apply the changes:
```bash
docker stack deploy -c docker-compose.yml traefik
```
!!! important "Public DNS Required"
Let's Encrypt may require a publicly accessible domain to validate domain ownership. For testing with local domains like `whoami.swarm.localhost`, the certificate will remain self-signed. In production, replace it with a real domain that has a publicly accessible DNS record pointing to your Traefik instance.
Once the certificate is issued, you can verify it:
```bash
# Verify the certificate chain
curl -v https://whoami.swarm.localhost/ 2>&1 | grep -i "server certificate"
```
You should see that your certificate is issued by Let's Encrypt.
## Configure Sticky Sessions
Sticky sessions ensure that a user's requests always go to the same backend server, which is essential for applications that maintain session state. Let's implement sticky sessions for our whoami service.
Docker Swarm already has multiple replicas running; we'll now add sticky session configuration. Update your whoami service in the `docker-compose.yml` file:
### Add Sticky Session Configuration
Add the following labels to your whoami service in the `docker-compose.yml` file:
```yaml
deploy:
# ... existing configuration ...
labels:
# ... existing labels ...
# Sticky Sessions Configuration
- "traefik.http.services.whoami.loadbalancer.sticky.cookie=true"
- "traefik.http.services.whoami.loadbalancer.sticky.cookie.name=sticky_cookie"
- "traefik.http.services.whoami.loadbalancer.sticky.cookie.secure=true"
- "traefik.http.services.whoami.loadbalancer.sticky.cookie.httpOnly=true"
```
Apply the changes:
```bash
docker stack deploy -c docker-compose.yml traefik
```
### Test Sticky Sessions
You can test the sticky sessions by making multiple requests and observing that they all go to the same backend container:
```bash
# First request - save cookies to a file
curl -k -c cookies.txt -H "Host: whoami.swarm.localhost" https://localhost/
# Subsequent requests - use the cookies
curl -k -b cookies.txt -H "Host: whoami.swarm.localhost" https://localhost/
curl -k -b cookies.txt -H "Host: whoami.swarm.localhost" https://localhost/
```
Pay attention to the `Hostname` field in each response - it should remain the same across all requests when using the cookie file, confirming that sticky sessions are working.
For comparison, try making requests without the cookie:
```bash
# Requests without cookies should be load-balanced across different containers
curl -k -H "Host: whoami.swarm.localhost" https://localhost/
curl -k -H "Host: whoami.swarm.localhost" https://localhost/
```
You should see different `Hostname` values in these responses, as each request is load-balanced to a different container.
!!! important "Browser Testing"
When testing in browsers, you need to use the same browser session to maintain the cookie. The cookie is set with `httpOnly` and `secure` flags for security, so it will only be sent over HTTPS connections and won't be accessible via JavaScript.
For more advanced configuration options, see the [reference documentation](../reference/routing-configuration/http/load-balancing/service.md).
## Conclusion
In this guide, you've learned how to:
- Expose HTTP services through Traefik in Docker Swarm
- Set up path-based routing to direct traffic to different backend services
- Secure your services with TLS using self-signed certificates
- Add security with middlewares like secure headers and IP allow listing
- Automate certificate management with Let's Encrypt
- Implement sticky sessions for stateful applications
These fundamental capabilities provide a solid foundation for exposing any application through Traefik Proxy in Docker Swarm. Each of these can be further customized to meet your specific requirements.
### Next Steps
Now that you understand the basics of exposing services with Traefik Proxy, you might want to explore:
- [Advanced routing options](../reference/routing-configuration/http/router/rules-and-priority.md) like query parameter matching, header-based routing, and more
- [Additional middlewares](../reference/routing-configuration/http/middlewares/overview.md) for authentication, rate limiting, and request modifications
- [Observability features](../reference/install-configuration/observability/metrics.md) for monitoring and debugging your Traefik deployment
- [TCP services](../reference/routing-configuration/tcp/service.md) for exposing TCP services
- [UDP services](../reference/routing-configuration/udp/service.md) for exposing UDP services
- [Docker provider documentation](../reference/install-configuration/providers/docker.md) for more details about the Docker integration

19
docs/content/index.md
View File

@ -7,18 +7,15 @@ description: "Traefik Proxy, an open-source Edge Router, auto-discovers configur
![Architecture](assets/img/traefik-architecture.png)
Traefik is an [open-source](https://github.com/traefik/traefik) *Application Proxy* that makes publishing your services a fun and easy experience.
It receives requests on behalf of your system, identifies which components are responsible for handling them, and routes them securely.
Traefik is an [open-source](https://github.com/traefik/traefik) Application Proxy and the core of the Traefik Hub Runtime Platform.
What sets Traefik apart, besides its many features, is that it automatically discovers the right configuration for your services.
The magic happens when Traefik inspects your infrastructure, where it finds relevant information and discovers which service serves which request.
If you start with Traefik for service discovery and routing, you can seamlessly add [API management](https://traefik.io/solutions/api-management/), [API gateway](https://traefik.io/solutions/api-gateway/), [AI gateway](https://traefik.io/solutions/ai-gateway/), and [API mocking](https://traefik.io/solutions/api-mocking/) capabilities as needed.
Traefik is natively compliant with every major cluster technology, such as Kubernetes, Docker Swarm, AWS, and [the list goes on](./reference/install-configuration/providers/overview.md); and can handle many at the same time. (It even works for legacy software running on bare metal.)
With Traefik, there is no need to maintain and synchronize a separate configuration file: everything happens automatically, in real time (no restarts, no connection interruptions).
With Traefik, you spend time developing and deploying new features to your system, not on configuring and maintaining its working state.
With 3.3 billion downloads and over 55k stars on GitHub, Traefik is used globally across hybrid cloud, multi-cloud, on prem, and bare metal environments running Kuberentes, Docker Swarm, AWS, [the list goes on](https://doc.traefik.io/traefik/reference/install-configuration/providers/overview/).
And if your needs change, you can add API gateway and API management capabilities seamlessly to your existing Traefik deployments. It takes less than a minute, there’s no rip-and-replace, and all your configurations are preserved. See this in action in [our API gateway demo video](https://info.traefik.io/watch-traefik-api-gw-demo?cta=docs).
Here’s how it works—Traefik receives requests on behalf of your system, identifies which components are responsible for handling them, and routes them securely. It automatically discovers the right configuration for your services by inspecting your infrastructure to identify relevant information and which service serves which request.
Because everything happens automatically, in real time (no restarts, no connection interruptions), you can focus on developing and deploying new features to your system, instead of configuring and maintaining its working state.
!!! quote "From the Traefik Maintainer Team"
When developing Traefik, our main goal is to make it easy to use, and we're sure you'll enjoy it.
@ -53,6 +50,6 @@ Use the sidebar to navigate to the section that is most appropriate for your nee
Have a question? Join our [Community Forum](https://community.traefik.io "Link to Traefik Community Forum") to discuss, learn, and connect with the Traefik community.
Using Traefik OSS in Production? Consider our enterprise-grade [API Gateway](https://info.traefik.io/watch-traefik-api-gw-demo?cta=doc) or our [24/7/365 OSS Support](https://info.traefik.io/request-commercial-support?cta=doc).
Using Traefik OSS in production? Consider upgrading to our API gateway ([watch demo video](https://info.traefik.io/watch-traefik-api-gw-demo)) for better security, control, and 24/7 support.
Explore our API Gateway upgrade via [this short demo video](https://info.traefik.io/watch-traefik-api-gw-demo?cta=doc).
Just need support? Explore our [24/7/365 support for Traefik OSS](https://info.traefik.io/request-commercial-support?cta=doc).

5
docs/content/providers/swarm.md
View File

@ -450,10 +450,7 @@ _Optional, Default=""_
Defines a default docker network to use for connections to all containers.
This option can be overridden on a per-container basis with the `traefik.docker.network` [routing label](../routing/providers/swarm.md#traefikdockernetwork).
!!! warning
The Docker Swarm provider still uses the same per-container mechanism as the Docker provider, so therefore the label still uses the `docker` keyword intentionally.
This option can be overridden on a per-container basis with the `traefik.swarm.network` [routing label](../routing/providers/swarm.md#traefikswarmnetwork).
```yaml tab="File (YAML)"
providers:

161
docs/content/reference/install-configuration/observability/logs-and-accesslogs.md
View File

@ -44,8 +44,82 @@ The section below describe how to configure Traefik logs using the static config
| `log.maxBackups` | Maximum number of old log files to retain.<br />The default is to retain all old log files. | 0 | No |
| `log.compress` | Compress log files in gzip after rotation. | false | No |
### OpenTelemetry
Traefik supports OpenTelemetry for logging. To enable OpenTelemetry, you need to set the following in the static configuration:
```yaml tab="File (YAML)"
experimental:
otlpLogs: true
```
```toml tab="File (TOML)"
[experimental]
otlpLogs = true
```
```sh tab="CLI"
--experimental.otlpLogs=true
```
!!! warning
This is an experimental feature.
#### Configuration Example
```yaml tab="File (YAML)"
experimental:
otlpLogs: true
log:
otlp:
http:
endpoint: https://collector:4318/v1/logs
headers:
Authorization: Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL
```
```toml tab="File (TOML)"
[experimental]
otlpLogs = true
[log.otlp]
http.endpoint = "https://collector:4318/v1/logs"
http.headers.Authorization = "Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL"
```
```sh tab="CLI"
--experimental.otlpLogs=true
--log.otlp.http.endpoint=https://collector:4318/v1/logs
--log.otlp.http.headers.Authorization=Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL
```
#### Configuration Options
| Field | Description | Default | Required |
|:-----------|:-----------------------------------------------------------------------------|:--------|:---------|
| `log.otlp.http` | This instructs the exporter to send logs to the OpenTelemetry Collector using HTTP.| | No |
| `log.otlp.http.endpoint` | The endpoint of the OpenTelemetry Collector. (format=`<scheme>://<host>:<port><path>`) | `https://localhost:4318/v1/logs` | No |
| `log.otlp.http.headers` | Additional headers sent with logs by the exporter to the OpenTelemetry Collector. | [ ] | No |
| `log.otlp.http.tls` | Defines the Client TLS configuration used by the exporter to send logs to the OpenTelemetry Collector. | | No |
| `log.otlp.http.tls.ca` | The path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle. | | No |
| `log.otlp.http.tls.cert` | The path to the certificate to use for the OpenTelemetry Collector. | | No |
| `log.otlp.http.tls.key` | The path to the key to use for the OpenTelemetry Collector. | | No |
| `log.otlp.http.tls.insecureSkipVerify` | Instructs the OpenTelemetry Collector to accept any certificate presented by the server regardless of the hostname in the certificate. | false | No |
| `log.otlp.grpc` | This instructs the exporter to send logs to the OpenTelemetry Collector using gRPC.| | No |
| `log.otlp.grpc.endpoint` | The endpoint of the OpenTelemetry Collector. (format=`<host>:<port>`) | `localhost:4317` | No |
| `log.otlp.grpc.headers` | Additional headers sent with logs by the exporter to the OpenTelemetry Collector. | [ ] | No |
| `log.otlp.grpc.insecure` | Instructs the exporter to send logs to the OpenTelemetry Collector using an insecure protocol. | false | No |
| `log.otlp.grpc.tls` | Defines the Client TLS configuration used by the exporter to send logs to the OpenTelemetry Collector. | | No |
| `log.otlp.grpc.tls.ca` | The path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle. | | No |
| `log.otlp.grpc.tls.cert` | The path to the certificate to use for the OpenTelemetry Collector. | | No |
| `log.otlp.grpc.tls.key` | The path to the key to use for the OpenTelemetry Collector. | | No |
| `log.otlp.grpc.tls.insecureSkipVerify` | Instructs the OpenTelemetry Collector to accept any certificate presented by the server regardless of the hostname in the certificate. | false | No |
## AccessLogs
Access logs concern everything that happens to the requests handled by Traefik.
### Configuration Example
```yaml tab="File (YAML)"
@ -111,6 +185,7 @@ accessLog:
--accesslog.fields.headers.names.Authorization=drop
```
### Configuration Options
The section below describes how to configure Traefik access logs using the static configuration.
@ -121,15 +196,87 @@ The section below describes how to configure Traefik access logs using the stati
| `accesslog.format` | By default, logs are written using the Common Log Format (CLF).<br />To write logs in JSON, use `json` in the `format` option.<br />If the given format is unsupported, the default (CLF) is used instead.<br />More information about CLF fields [here](#clf-format-fields). | "common" | No |
| `accesslog.bufferingSize` | To write the logs in an asynchronous fashion, specify a `bufferingSize` option.<br />This option represents the number of log lines Traefik will keep in memory before writing them to the selected output.<br />In some cases, this option can greatly help performances.| 0 | No |
| `accesslog.addInternals` | Enables access logs for internal resources (e.g.: `ping@internal`). | false | No |
| `accesslog.filters.statusCodes` | Limit the access logs to requests with a status codes in the specified range. | false | No |
| `accesslog.filters.statusCodes` | Limit the access logs to requests with a status codes in the specified range. | [ ] | No |
| `accesslog.filters.retryAttempts` | Keep the access logs when at least one retry has happened. | false | No |
| `accesslog.filters.minDuration` | Keep access logs when requests take longer than the specified duration (provided in seconds or as a valid duration format, see [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration)). | 0 | No |
| `accesslog.fields.defaultMode` | Mode to apply by default to the access logs fields (`keep`, `redact` or `drop`). | keep | No |
| `accesslog.fields.names` | Set the fields list to display in the access logs (format `name:mode`).<br /> Available fields list [here](#available-fields). | - | No |
| `accesslog.fields.names` | Set the fields list to display in the access logs (format `name:mode`).<br /> Available fields list [here](#available-fields). | [ ] | No |
| `accesslog.headers.defaultMode` | Mode to apply by default to the access logs headers (`keep`, `redact` or `drop`). | drop | No |
| `accesslog.headers.names` | Set the headers list to display in the access logs (format `name:mode`). | - | No |
| `accesslog.headers.names` | Set the headers list to display in the access logs (format `name:mode`). | [ ] | No |
#### CLF format fields
### OpenTelemetry
Traefik supports OpenTelemetry for access logs. To enable OpenTelemetry, you need to set the following in the static configuration:
```yaml tab="File (YAML)"
experimental:
otlpLogs: true
```
```toml tab="File (TOML)"
[experimental]
otlpLogs = true
```
```sh tab="CLI"
--experimental.otlpLogs=true
```
!!! warning
This is an experimental feature.
#### Configuration Example
```yaml tab="File (YAML)"
experimental:
otlpLogs: true
accesslog:
otlp:
http:
endpoint: https://collector:4318/v1/logs
headers:
Authorization: Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL
```
```toml tab="File (TOML)"
[experimental]
otlpLogs = true
[accesslog.otlp]
http.endpoint = "https://collector:4318/v1/logs"
http.headers.Authorization = "Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL"
```
```yaml tab="CLI"
--experimental.otlpLogs=true
--accesslog.otlp.http.endpoint=https://collector:4318/v1/logs
--accesslog.otlp.http.headers.Authorization=Bearer auth_asKXRhIMplM7El1JENjrotGouS1LYRdL
```
#### Configuration Options
| Field | Description | Default | Required |
|:-----------|:--------------------------|:--------|:---------|
| `accesslog.otlp.http` | This instructs the exporter to send access logs to the OpenTelemetry Collector using HTTP.| | No |
| `accesslog.otlp.http.endpoint` | The endpoint of the OpenTelemetry Collector. (format=`<scheme>://<host>:<port><path>`) | `https://localhost:4318/v1/logs` | No |
| `accesslog.otlp.http.headers` | Additional headers sent with access logs by the exporter to the OpenTelemetry Collector. | [ ] | No |
| `accesslog.otlp.http.tls` | Defines the Client TLS configuration used by the exporter to send access logs to the OpenTelemetry Collector. | | No |
| `accesslog.otlp.http.tls.ca` | The path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle. | | No |
| `accesslog.otlp.http.tls.cert` | The path to the certificate to use for the OpenTelemetry Collector. | | No |
| `accesslog.otlp.http.tls.key` | The path to the key to use for the OpenTelemetry Collector. | | No |
| `accesslog.otlp.http.tls.insecureSkipVerify` | Instructs the OpenTelemetry Collector to accept any certificate presented by the server regardless of the hostname in the certificate. | false | No |
| `accesslog.otlp.grpc` | This instructs the exporter to send access logs to the OpenTelemetry Collector using gRPC.| | No |
| `accesslog.otlp.grpc.endpoint` | The endpoint of the OpenTelemetry Collector. (format=`<host>:<port>`) | `localhost:4317` | No |
| `accesslog.otlp.grpc.headers` | Additional headers sent with access logs by the exporter to the OpenTelemetry Collector. | [ ] | No |
| `accesslog.otlp.grpc.insecure` | Instructs the exporter to send access logs to the OpenTelemetry Collector using an insecure protocol. | false | No |
| `accesslog.otlp.grpc.tls` | Defines the Client TLS configuration used by the exporter to send access logs to the OpenTelemetry Collector. | | No |
| `accesslog.otlp.grpc.tls.ca` | The path to the certificate authority used for the secure connection to the OpenTelemetry Collector, it defaults to the system bundle. | | No |
| `accesslog.otlp.grpc.tls.cert` | The path to the certificate to use for the OpenTelemetry Collector. | | No |
| `accesslog.otlp.grpc.tls.key` | The path to the key to use for the OpenTelemetry Collector. | | No |
| `accesslog.otlp.grpc.tls.insecureSkipVerify` | Instructs the OpenTelemetry Collector to accept any certificate presented by the server regardless of the hostname in the certificate. | false | No |
### CLF format fields
Below the fields displayed with the CLF format:
@ -140,7 +287,7 @@ Below the fields displayed with the CLF format:
"<Traefik_router_name>" "<Traefik_server_URL>" <request_duration_in_ms>ms
```
#### Available Fields
### Available Fields
| Field | Description |
|-------------------------|------------------|
@ -179,7 +326,7 @@ Below the fields displayed with the CLF format:
| `TLSCipher` | The TLS cipher used by the connection (e.g. `TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA`) (if connection is TLS). |
| `TLSClientSubject` | The string representation of the TLS client certificate's Subject (e.g. `CN=username,O=organization`). |
#### Log Rotation
### Log Rotation
Traefik close and reopen its log files, assuming they're configured, on receipt of a USR1 signal.
This allows the logs to be rotated and processed by an external program, such as `logrotate`.
@ -187,7 +334,7 @@ This allows the logs to be rotated and processed by an external program, such as
!!! warning
This does not work on Windows due to the lack of USR signals.
#### Time Zones
### Time Zones
Traefik will timestamp each log line in UTC time by default.

38
docs/content/reference/install-configuration/providers/swarm.md
View File

@ -43,25 +43,25 @@ services:
## Configuration Options
| Field | Description | Default | Required |
|:------|:----------------------------------------------------------|:---------------------|:---------|
| `providers.providersThrottleDuration` | Minimum amount of time to wait for, after a configuration reload, before taking into account any new configuration refresh event.<br />If multiple events occur within this time, only the most recent one is taken into account, and all others are discarded.<br />**This option cannot be set per provider, but the throttling algorithm applies to each of them independently.** | 2s | No |
| `providers.swarm.endpoint` | Specifies the Docker API endpoint. See [here](#endpoint) for more information| `unix:///var/run/docker.sock` | Yes |
| `providers.swarm.username` | Defines the username for Basic HTTP authentication. This should be used when the Docker daemon socket is exposed through an HTTP proxy that requires Basic HTTP authentication.| "" | No |
| `providers.swarm.password` | Defines the password for Basic HTTP authentication. This should be used when the Docker daemon socket is exposed through an HTTP proxy that requires Basic HTTP authentication.| "" | No |
| `providers.swarm.useBindPortIP` | Instructs Traefik to use the IP/Port attached to the container's binding instead of its inner network IP/Port. See [here](#usebindportip) for more information | false | No |
| `providers.swarm.exposedByDefault` | Expose containers by default through Traefik. See [here](./overview.md#restrict-the-scope-of-service-discovery) for additional information | true | No |
| `providers.swarm.network` | Defines a default docker network to use for connections to all containers. This option can be overridden on a per-container basis with the `traefik.docker.network` label.| "" | No |
| `providers.swarm.defaultRule` | Defines what routing rule to apply to a container if no rule is defined by a label. See [here](#defaultrule) for more information | ```"Host(`{{ normalize .Name }}`)"``` | No |
| `providers.swarm.refreshSeconds` | Defines the polling interval for Swarm Mode. | "15s" | No |
| `providers.swarm.httpClientTimeout` | Defines the client timeout (in seconds) for HTTP connections. If its value is 0, no timeout is set. | 0 | No |
| `providers.swarm.watch` | Instructs Traefik to watch Docker events or not. | True | No |
| `providers.swarm.constraints` | Defines an expression that Traefik matches against the container labels to determine whether to create any route for that container. See [here](#constraints) for more information. | "" | No |
| `providers.swarm.allowEmptyServices` | Instructs the provider to create any [servers load balancer](../../../routing/services/index.md#servers-load-balancer) defined for Docker containers regardless of the [healthiness](https://docs.docker.com/engine/reference/builder/#healthcheck) of the corresponding containers. | false | No |
| `providers.swarm.tls.ca` | Defines the path to the certificate authority used for the secure connection to Docker, it defaults to the system bundle. | "" | No |
| `providers.swarm.tls.cert` | Defines the path to the public certificate used for the secure connection to Docker. When using this option, setting the `key` option is required. | "" | Yes |
| `providers.swarm.tls.key` | Defines the path to the private key used for the secure connection to Docker. When using this option, setting the `cert` option is required. | "" | Yes |
| `providers.swarm.tls.insecureSkipVerify` | Instructs the provider to accept any certificate presented by the Docker server when establishing a TLS connection, regardless of the hostnames the certificate covers. | false | No |
| Field | Description | Default | Required |
|:-----------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------|:---------|
| `providers.providersThrottleDuration` | Minimum amount of time to wait for, after a configuration reload, before taking into account any new configuration refresh event.<br />If multiple events occur within this time, only the most recent one is taken into account, and all others are discarded.<br />**This option cannot be set per provider, but the throttling algorithm applies to each of them independently.** | 2s | No |
| `providers.swarm.endpoint` | Specifies the Docker API endpoint. See [here](#endpoint) for more information | `unix:///var/run/docker.sock` | Yes |
| `providers.swarm.username` | Defines the username for Basic HTTP authentication. This should be used when the Docker daemon socket is exposed through an HTTP proxy that requires Basic HTTP authentication. | "" | No |
| `providers.swarm.password` | Defines the password for Basic HTTP authentication. This should be used when the Docker daemon socket is exposed through an HTTP proxy that requires Basic HTTP authentication. | "" | No |
| `providers.swarm.useBindPortIP` | Instructs Traefik to use the IP/Port attached to the container's binding instead of its inner network IP/Port. See [here](#usebindportip) for more information | false | No |
| `providers.swarm.exposedByDefault` | Expose containers by default through Traefik. See [here](./overview.md#restrict-the-scope-of-service-discovery) for additional information | true | No |
| `providers.swarm.network` | Defines a default docker network to use for connections to all containers. This option can be overridden on a per-container basis with the `traefik.swarm.network` label. | "" | No |
| `providers.swarm.defaultRule` | Defines what routing rule to apply to a container if no rule is defined by a label. See [here](#defaultrule) for more information | ```"Host(`{{ normalize .Name }}`)"``` | No |
| `providers.swarm.refreshSeconds` | Defines the polling interval for Swarm Mode. | "15s" | No |
| `providers.swarm.httpClientTimeout` | Defines the client timeout (in seconds) for HTTP connections. If its value is 0, no timeout is set. | 0 | No |
| `providers.swarm.watch` | Instructs Traefik to watch Docker events or not. | True | No |
| `providers.swarm.constraints` | Defines an expression that Traefik matches against the container labels to determine whether to create any route for that container. See [here](#constraints) for more information. | "" | No |
| `providers.swarm.allowEmptyServices` | Instructs the provider to create any [servers load balancer](../../../routing/services/index.md#servers-load-balancer) defined for Docker containers regardless of the [healthiness](https://docs.docker.com/engine/reference/builder/#healthcheck) of the corresponding containers. | false | No |
| `providers.swarm.tls.ca` | Defines the path to the certificate authority used for the secure connection to Docker, it defaults to the system bundle. | "" | No |
| `providers.swarm.tls.cert` | Defines the path to the public certificate used for the secure connection to Docker. When using this option, setting the `key` option is required. | "" | Yes |
| `providers.swarm.tls.key` | Defines the path to the private key used for the secure connection to Docker. When using this option, setting the `cert` option is required. | "" | Yes |
| `providers.swarm.tls.insecureSkipVerify` | Instructs the provider to accept any certificate presented by the Docker server when establishing a TLS connection, regardless of the hostnames the certificate covers. | false | No |
### `endpoint`

299
docs/content/setup/docker.md Normal file
View File

@ -0,0 +1,299 @@
---
title: Setup Traefik Proxy in Docker Standalone
description: "Learn how to Setup Traefik on Docker with HTTP/HTTPS entrypoints, redirects, secure dashboard, basic TLS, metrics, tracing, access‑logs."
---
This guide provides an in-depth walkthrough for installing and configuring Traefik Proxy within a Docker container using the official Traefik Docker image & Docker Compose. In this guide, we'll cover the following:
- Enable the [Docker provider](../reference/install-configuration/providers/docker.md)
- Expose **web** (HTTP :80) and **websecure** (HTTPS :443) entrypoints
- Redirect all HTTP traffic to HTTPS
- Secure the Traefik dashboard with **basic‑auth**
- Terminate TLS with a self‑signed certificate for `*.docker.localhost`
- Deploy the **whoami** demo service
- Enable access‑logs and Prometheus metrics
## Prerequisites
- Docker Desktop / Engine
- Docker Compose
- `openssl`
- `htpasswd` from `apache2-utils`
## Create a self‑signed certificate
Before Traefik can serve HTTPS locally it needs a certificate. In production you’d use one from a trusted CA, but for a single‑machine stack a quick self‑signed cert is enough. We can create one with openssl by running the following commands:
```bash
mkdir -p certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout certs/local.key -out certs/local.crt \
-subj "/CN=*.docker.localhost"
```
The `certs` folder now holds `local.crt` and `local.key`, which will be mounted read‑only into Traefik.
## Create the Traefik Dashboard Credentials
In production, it is advisable to have some form of authentication/security for the Traefik dashboard. Traefik can be secured with the [basic‑auth middleware](../reference/routing-configuration/http/middlewares/basicauth.md). To do this, generate a hashed username / password pair that Traefik’s middleware will validate:
```bash
htpasswd -nb admin "P@ssw0rd" | sed -e 's/\$/\$\$/g'
```
Copy the full output (e.g., admin:$$apr1$$…) — we'll need this for the middleware configuration.
## Create a docker-compose.yaml
Now define the whole stack in a Compose file. This file declares Traefik, mounts the certificate, sets up a dedicated network, and later hosts the whoami demo service.
!!! note
You can also choose to use the Docker CLI and a configuration file to run Traefik, but for this tutorial, we'll be using Docker Compose.
First, create a folder named `dynamic` and create a file named `tls.yaml` for dynamic configuration. Paste the TLS certificate configuration into the file:
```yaml
tls:
certificates:
- certFile: /certs/local.crt
keyFile: /certs/local.key
```
In the same folder as the `dynamic/tls.yaml` file, create a `docker-compose.yaml` file and include the following:
```yaml
services:
traefik:
image: traefik:v3.4
container_name: traefik
restart: unless-stopped
security_opt:
- no-new-privileges:true
networks:
# Connect to the 'traefik_proxy' overlay network for inter-container communication across nodes
- proxy
ports:
- "80:80"
- "443:443"
- "8080:8080"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- ./certs:/certs:ro
- ./dynamic:/dynamic:ro
command:
# EntryPoints
- "--entrypoints.web.address=:80"
- "--entrypoints.web.http.redirections.entrypoint.to=websecure"
- "--entrypoints.web.http.redirections.entrypoint.scheme=https"
- "--entrypoints.web.http.redirections.entrypoint.permanent=true"
- "--entrypoints.websecure.address=:443"
- "--entrypoints.websecure.http.tls=true"
# Attach the static configuration tls.yaml file that contains the tls configuration settings
- "--providers.file.filename=/dynamic/tls.yaml"
# Providers
- "--providers.docker=true"
- "--providers.docker.exposedbydefault=false"
- "--providers.docker.network=proxy"
# API & Dashboard
- "--api.dashboard=true"
- "--api.insecure=false"
# Observability
- "--log.level=INFO"
- "--accesslog=true"
- "--metrics.prometheus=true"
# Traefik Dynamic configuration via Docker labels
labels:
# Enable self‑routing
- "traefik.enable=true"
# Dashboard router
- "traefik.http.routers.dashboard.rule=Host(`dashboard.docker.localhost`)"
- "traefik.http.routers.dashboard.entrypoints=websecure"
- "traefik.http.routers.dashboard.service=api@internal"
- "traefik.http.routers.dashboard.tls=true"
# Basic‑auth middleware
- "traefik.http.middlewares.dashboard-auth.basicauth.users=<PASTE_HASH_HERE>"
- "traefik.http.routers.dashboard.middlewares=dashboard-auth@docker"
# Whoami application
whoami:
image: traefik/whoami
container_name: whoami
restart: unless-stopped
networks:
- proxy
labels:
- "traefik.enable=true"
- "traefik.http.routers.whoami.rule=Host(`whoami.docker.localhost`)"
- "traefik.http.routers.whoami.entrypoints=websecure"
- "traefik.http.routers.whoami.tls=true"
networks:
proxy:
name: proxy
```
!!! info
- Remember to replace `<PASTE_HASH_HERE>` with the hash generated earlier.
- The `--api.insecure=false` flag is used to secure the API and prevent the dashboard from being exposed on port 8080. This is done because we are exposing the dashboard with a HTTPS router.
## Launch the stack
With the Compose file and supporting assets in place, start the containers and let Docker wire up networking behind the scenes:
```bash
docker compose up -d
```
Traefik will start, read its static configuration from the `command` arguments, connect to the Docker socket, detect its own labels for dynamic configuration (dashboard routing and auth), and begin listening on ports 80 and 443. HTTP requests will be redirected to HTTPS.
## Access the Dashboard
Now that Traefik is deployed, you can access the dashboard at [https://dashboard.docker.localhost](https://dashboard.docker.localhost) and it should prompt for the Basic Authentication credentials you configured:
![Traefik Dashboard](../assets/img/setup/traefik-dashboard-docker.png)
## Test the whoami Application
You can test the application using curl:
```bash
curl -k https://whoami.docker.localhost/
```
```bash
Hostname: whoami-76c9859cfc-k7jzs
IP: 127.0.0.1
IP: ::1
IP: 10.42.0.59
IP: fe80::50d7:a2ff:fed5:2530
RemoteAddr: 10.42.0.60:54148
GET / HTTP/1.1
Host: whoami.docker.localhost
User-Agent: curl/8.7.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 10.42.0.1
X-Forwarded-Host: whoami.docker.localhost
X-Forwarded-Port: 443
X-Forwarded-Proto: https
X-Forwarded-Server: traefik-644b7c67d9-f2tn9
X-Real-Ip: 10.42.0.1
```
Making the same request to the HTTP entrypoint will return the following:
```bash
curl -k http://whoami.docker.localhost
Moved Permanently
```
The above confirms that a redirection has taken place which means our setup works correctly.
You can also open a browser and navigate to [https://whoami.docker.localhost](https://whoami.docker.localhost) to see a JSON dump from the service:
![Whoami](../assets/img/setup/whoami-json-dump.png)
!!! info
You can also navigate to the Traefik Dashboard at [https://dashboard.docker.localhost](https://dashboard.docker.localhost) to see that the route has been created.
### Other Key Configuration Areas
Beyond this initial setup, Traefik offers extensive configuration possibilities. Here are brief introductions and minimal examples using Docker Compose `command` arguments or `labels`. Consult the main documentation linked for comprehensive details.
### TLS Certificate Management (Let's Encrypt)
To make the `websecure` entry point serve valid HTTPS certificates automatically, enable Let's Encrypt (ACME).
*Example `command` additions:*
```yaml
command:
# ... other command arguments ...
- "--certificatesresolvers.le.acme.email=your-email@example.com"
- "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json" # Path inside container volume
- "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
# - "--certificatesresolvers.le.acme.dnschallenge.provider=your-dns-provider" # Needs provider setup
# Optionally make 'le' the default resolver for TLS-enabled routers
- "--entrypoints.websecure.http.tls.certresolver=le"
```
This defines a resolver named `le`, sets the required email and storage path (within the mounted `/letsencrypt` volume), and enables the HTTP challenge. Refer to the [HTTPS/TLS Documentation](../reference/install-configuration/tls/certificate-resolvers/overview.md) and [Let's Encrypt Documentation](../reference/install-configuration/tls/certificate-resolvers/acme.md) for details on challenges and DNS provider configuration.
### Metrics (Prometheus)
You can expose Traefik's internal metrics for monitoring with Prometheus. We already enabled prometheus in our setup but we can further configure it.
*Example `command` additions:*
```yaml
command:
# If using a dedicated metrics entry point, define it:
- "--entrypoints.metrics.address=:8082"
# ... other command arguments ...
- "--metrics.prometheus=true"
# Optionally change the entry point metrics are exposed on (defaults to 'traefik')
- "--metrics.prometheus.entrypoint=metrics"
# Add labels to metrics for routers/services (can increase cardinality)
- "--metrics.prometheus.addrouterslabels=true"
- "--metrics.prometheus.addserviceslabels=true"
```
This enables the `/metrics` endpoint (typically accessed via the internal API port, often 8080 by default if not secured, or via a dedicated entry point). See the [Metrics Documentation](../reference/install-configuration/observability/metrics.md) for options.
### Tracing (OTel):
You can enable distributed tracing to follow requests through Traefik.
*Example `command` additions:*
```yaml
command:
# ... other command arguments ...
- "--tracing.otel=true"
- "--tracing.otel.grpcendpoint=otel-collector:4317" # Adjust endpoint as needed
- "--tracing.otel.httpendpoint=otel-collector.observability:4318" # Adjust endpoint as needed
```
!!! note
This option requires a running OTEL collector accessible by Traefik. Consult the [Tracing Documentation](../reference/install-configuration/observability/tracing.md).
### Access Logs
You can configure Traefik to log incoming requests for debugging and analysis.
*Example `command` additions:*
```yaml
command:
# ... other command arguments ...
- "--accesslog=true" # Enable access logs to stdout
# Optionally change format or output file (requires volume)
- "--accesslog.format=json"
- "--accesslog.filepath=/path/to/access.log"
# Optionally filter logs
- "--accesslog.filters.statuscodes=400-599"
```
This enables access logs to the container's standard output (viewable via `docker compose logs <traefik-container-id>`). See the [Access Logs Documentation](../reference/install-configuration/observability/logs-and-accesslogs.md).
### Conclusion
You now have a basic Traefik setup in Docker with secure dashboard access and HTTP-to-HTTPS redirection.
{!traefik-for-business-applications.md!}

398
docs/content/setup/kubernetes.md Normal file
View File

@ -0,0 +1,398 @@
---
title: "Setup Traefik on Kubernetes"
description: "Learn how to Setup Traefik on Kubernetes with HTTP/HTTPS entrypoints, redirects, secure dashboard, basic TLS, metrics, tracing, access‑logs."
---
This guide provides an in-depth walkthrough for installing and configuring Traefik Proxy within a Kubernetes cluster using the official Helm chart. In this guide, we'll cover the following:
- Configure standard HTTP (`web`) and HTTPS (`websecure`) entry points,
- Implement automatic redirection from HTTP to HTTPS
- Secure the Traefik Dashboard using Basic Authentication.
- Deploy a demo application to test the setup
- Explore some other key configuration options
## Prerequisites
- A Kubernetes cluster
- Helm v3,
- Kubectl
## Create the Cluster
If you do not have a Kubernetes cluster already, you can spin up one with K3d:
```bash
k3d cluster create traefik \
--port 80:80@loadbalancer \
--port 443:443@loadbalancer \
--port 8000:8000@loadbalancer \
--k3s-arg "--disable=traefik@server:0"
```
Ports `80` and `443` reach Traefik from the host, while port `8000` remains free for later demos. The built-in Traefik shipped with k3s is disabled to avoid conflicts.
Check the context:
```bash
kubectl cluster-info --context k3d-traefik
```
You should see something like this:
```bash
Kubernetes control plane is running at https://0.0.0.0:56049
CoreDNS is running at https://0.0.0.0:56049/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
Metrics-server is running at https://0.0.0.0:56049/api/v1/namespaces/kube-system/services/https:metrics-server:https/proxy
To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
```
## Add the chart repo and namespace
Using Helm streamlines Kubernetes application deployment. Helm packages applications into "charts," which are collections of template files describing Kubernetes resources. We use the official Traefik Helm chart for a managed and customizable installation.
```bash
helm repo add traefik https://traefik.github.io/charts
helm repo update
kubectl create namespace traefik
```
The first command registers the `traefik` repository alias pointing to the official chart location. The second command refreshes your local cache to ensure you have the latest list of charts and versions available from all configured repositories.
## Create a Local Self‑Signed TLS Secret
Traefik's Gateway listeners require a certificate whenever a listener uses `protocol: HTTPS`.
For local development create a throw‑away self‑signed certificate and
store it in a Kubernetes Secret named **local‑selfsigned‑tls**.
The Gateway references this secret to terminate TLS on the `websecure` listener.
```bash
# 1) Generate a self‑signed certificate valid for *.docker.localhost
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout tls.key -out tls.crt \
-subj "/CN=*.docker.localhost"
# 2) Create the TLS secret in the traefik namespace
kubectl create secret tls local-selfsigned-tls \
--cert=tls.crt --key=tls.key \
--namespace traefik
```
### Why Do We Need To Do This
The Gateway's HTTPS listener references this secret via `certificateRefs`.
Without it, the helm chart validation fails and the HTTP→HTTPS redirect chain breaks.
!!! info "Production tip"
The self-signed certificate above is **only for local development**. For production, either store a certificate issued by your organization's CA in a Secret or let an automated issuer such as cert-manager or Traefik's ACME (Let's Encrypt) generate certificates on demand. Update the `certificateRefs` in the `websecure` listener—or use `traefik.io/tls.certresolver`—so clients receive a trusted certificate and no longer see browser warnings.
## Prepare Helm Chart Configuration Values
Create a `values.yaml` file with the following content:
```yaml
# Configure Network Ports and EntryPoints
# EntryPoints are the network listeners for incoming traffic.
ports:
# Defines the HTTP entry point named 'web'
web:
port: 80
nodePort: 30000
# Instructs this entry point to redirect all traffic to the 'websecure' entry point
redirections:
entryPoint:
to: websecure
scheme: https
permanent: true
# Defines the HTTPS entry point named 'websecure'
websecure:
port: 443
nodePort: 30001
# Enables the dashboard in Secure Mode
api:
dashboard: true
insecure: false
ingressRoute:
dashboard:
enabled: true
matchRule: Host(`dashboard.docker.localhost`)
entryPoints:
- websecure
middlewares:
- name: dashboard-auth
# Creates a BasiAuth Middleware and Secret for the Dashboard Security
extraObjects:
- apiVersion: v1
kind: Secret
metadata:
name: dashboard-auth-secret
type: kubernetes.io/basic-auth
stringData:
username: admin
password: "P@ssw0rd" # Replace with an Actual Password
- apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: dashboard-auth
spec:
basicAuth:
secret: dashboard-auth-secret
# We will route with Gateway API instead.
ingressClass:
enabled: false
# Enable Gateway API Provider & Disables the KubernetesIngress provider
# Providers tell Traefik where to find routing configuration.
providers:
kubernetesIngress:
enabled: false
kubernetesGateway:
enabled: true
## Gateway Listeners
gateway:
listeners:
web: # HTTP listener that matches entryPoint `web`
port: 80
protocol: HTTP
namespacePolicy: All
websecure: # HTTPS listener that matches entryPoint `websecure`
port: 443
protocol: HTTPS # TLS terminates inside Traefik
namespacePolicy: All
mode: Terminate
certificateRefs:
- kind: Secret
name: local-selfsigned-tls # the Secret we created before the installation
group: ""
# Enable Observability
logs:
general:
level: INFO
# This enables access logs, outputting them to Traefik's standard output by default. The [Access Logs Documentation](https://doc.traefik.io/traefik/observability/access-logs/) covers formatting, filtering, and output options.
access:
enabled: true
# Enables Prometheus for Metrics
metrics:
prometheus:
enabled: true
```
## Install the Traefik Using the Helm Values
Now, apply the configuration using the Helm client.
```bash
# Install the chart into the 'traefik' namespace
helm install traefik traefik/traefik \
--namespace traefik \
--values values.yaml
```
**Command Breakdown:**
- `helm install traefik`: Instructs Helm to install a new release named `traefik`.
- `traefik/traefik`: Specifies the chart to use (`traefik` chart from the `traefik` repository added earlier).
- `--namespace traefik`: Specifies the Kubernetes namespace to install into. Using a dedicated namespace is recommended practice.
- `--values values.yaml`: Applies the custom configuration from your `values.yaml` file.
## Accessing the Dashboard
Now that Traefik is deployed, you can access its dashboard at [https://dashboard.docker.localhost/](https://dashboard.docker.localhost/). When you access this link, your browser will prompt for the username and password. Ensure you use the credentials set in the `values.yaml` file to log in. Upon successful login, the dashboard will be displayed as shown below:
![Traefik Dashboard](../assets/img/setup/traefik-dashboard.png)
## Deploy a Demo Application
To test the setup, deploy the [Traefik whoami](https://github.com/traefik/whoami) application in the Kubernetes cluster. Create a file named `whoami.yaml` and paste the following:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: whoami
namespace: traefik
spec:
replicas: 2
selector:
matchLabels:
app: whoami
template:
metadata:
labels:
app: whoami
spec:
containers:
- name: whoami
image: traefik/whoami
ports:
- containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
name: whoami
namespace: traefik
spec:
selector:
app: whoami
ports:
- port: 80
```
Apply the manifest:
```bash
kubectl apply -f whoami.yaml
```
After deploying the application, you can expose the application by creating a [Gateway API HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/). To do this, create a file named `whoami-route.yaml` and paste the following:
```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: whoami
namespace: traefik
spec:
parentRefs:
- name: traefik-gateway # Name of the Gateway that Traefik creates when you enable the Gateway API provider
hostnames:
- "whoami.docker.localhost"
rules:
- matches:
- path:
type: PathPrefix
value: /
backendRefs:
- name: whoami
port: 80
```
Apply the manifest:
```bash
kubectl apply -f whoami-route.yaml
```
After you apply the manifest, navigate to the Routes in the Traefik Dashboard; you’ll see that the [https://whoami.docker.localhost](https://whoami.docker.localhost) route has been created.
![Route](../assets/img/setup/route-in-dashboard.png)
You can test the application using curl:
```bash
curl -k https://whoami.docker.localhost/
```
```bash
Hostname: whoami-76c9859cfc-k7jzs
IP: 127.0.0.1
IP: ::1
IP: 10.42.0.59
IP: fe80::50d7:a2ff:fed5:2530
RemoteAddr: 10.42.0.60:54148
GET / HTTP/1.1
Host: whoami.docker.localhost
User-Agent: curl/8.7.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 10.42.0.1
X-Forwarded-Host: whoami.docker.localhost
X-Forwarded-Port: 443
X-Forwarded-Proto: https
X-Forwarded-Server: traefik-644b7c67d9-f2tn9
X-Real-Ip: 10.42.0.1
```
You can also open a browser and navigate to [https://whoami.docker.localhost](https://whoami.docker.localhost) to see a JSON dump from the service.
![Whoami](../assets/img/setup/whoami-json-dump.png)
## Other Key Configuration Areas
The above setup provides a secure base, but Traefik offers much more. Here's a brief overview of other essential configurations, with minimal examples using Helm `values.yaml` overrides.
These examples illustrate how to enable features; consult the main documentation for detailed options.
### TLS Certificate Management (Let's Encrypt)
On the `websecure` entry point TLS is enabled by default. However, it currently lacks a valid certificate. Traefik can automatically obtain and renew TLS certificates from Let's Encrypt using the ACME protocol.
*Example `values.yaml` addition:*
```yaml
additionalArguments:
- "--certificatesresolvers.le.acme.email=your-email@example.com"
- "--certificatesresolvers.le.acme.storage=/data/acme.json"
- "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
# - "--certificatesresolvers.le.acme.dnschallenge.provider=your-dns-provider" # Requires provider-specific config, adjust if you control your DNS provider
# Enable persistence for ACME data (certificates, account) to ensure it survives pod restarts:
persistence:
enabled: true
name: data
size: 1Gi
storageClass: ""
```
This enables a certificate resolver named `le`, configures the mandatory email and storage file, and sets up the HTTP challenge (requires port 80 access). Refer to the [HTTPS/TLS Documentation](../reference/install-configuration/tls/certificate-resolvers/overview.md) and [Let's Encrypt Documentation](../reference/install-configuration/tls/certificate-resolvers/acme.md) for full details, including DNS challenge configuration.
!!!info "Let's Encrypt in Production"
Let's Encrypt can only issue certificates for hostnames that point to a public IP address reachable on ports 80 (HTTP‑01) or via your DNS provider's API (DNS‑01). Replace the `*.docker.localhost` examples with a real domain you control, create the DNS records, and keep ports 80/443 open to your cluster so the validation can succeed.
### Gateway API & ACME
Traefik’s built‑in ACME/Let’s Encrypt integration works for IngressRoute and Ingress resources, but it does not issue certificates for Gateway API listeners.
If you’re using the Gateway API, install [cert‑manager](https://cert-manager.io/docs/) (or another certificate controller) and reference the secret it creates in `gateway.listeners.websecure.certificateRefs`.
### Metrics (Prometheus)
Traefik can expose detailed metrics in Prometheus format, essential for monitoring its performance and the traffic it handles.
*Example `values.yaml` addition:*
```yaml
# Enable metrics endpoint
metrics:
prometheus:
# The entry point metrics will be available on (usually internal/admin)
entryPoint: metrics
# Add standard Prometheus metrics
addRoutersLabels: true
addServicesLabels: true
# ... other options available
```
This enables the Prometheus endpoint on a dedicated `metrics` entry point (port 9100). See the [Metrics Documentation](../reference/install-configuration/observability/metrics.md) for configuration details and available metrics.
### Tracing (OTel)
Distributed tracing helps understand request latency and flow through your system, including Traefik itself.
*Example `values.yaml` addition:*
```yaml
additionalArguments:
- "--tracing.otel=true"
- "--tracing.otel.grpcendpoint=otel-collector.observability:4317" # Adjust endpoint as needed
- "--tracing.otel.httpendpoint=otel-collector.observability:4318" # Adjust endpoint as needed
```
This enables OTel tracing and specifies the collector endpoint. Consult the [Tracing Documentation](../reference/install-configuration/observability/tracing.md) for details on OTel tracing.
## Conclusion
This setup establishes Traefik with secure dashboard access and HTTPS redirection, along with pointers to enable observability & TLS.
{!traefik-for-business-applications.md!}

330
docs/content/setup/swarm.md Normal file
View File

@ -0,0 +1,330 @@
---
title: Setup Traefik Proxy in Docker Swarm
description: "Learn how to run Traefik v3 in Docker Swarm with HTTP/HTTPS entrypoints, redirects, a secured dashboard, self‑signed TLS, metrics, tracing, and access‑logs."
---
This guide provides an in‑depth walkthrough for installing and configuring Traefik Proxy as a **Swarm service** using `docker stack deploy`. It follows the same structure as the standalone‑Docker tutorial and covers:
- Enable the [Swarm provider](../reference/install-configuration/providers/swarm.md)
- Expose **web** (HTTP :80) and **websecure** (HTTPS :443) entrypoints
- Redirect all HTTP traffic to HTTPS
- Secure the Traefik dashboard with **basic‑auth**
- Terminate TLS with a self‑signed certificate for `*.swarm.localhost`
- Deploy the **whoami** demo service
- Enable access‑logs and Prometheus metrics
## Prerequisites
- Docker Engine with **Swarm mode** initialised (`docker swarm init`)
- Docker Compose
- `openssl`
- `htpasswd`
## Create a self‑signed certificate
Before Traefik can serve HTTPS locally it needs a certificate. In production you’d use one from a trusted CA, but for a multi‑node dev swarm a quick self‑signed cert is enough:
```bash
mkdir -p certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout certs/local.key -out certs/local.crt \
-subj "/CN=*.swarm.localhost"
```
## Create the Traefik Dashboard Credentials
Generate a hashed username / password pair that Traefik’s middleware will validate:
```bash
htpasswd -nb admin "P@ssw0rd" | sed -e 's/\$/\$\$/g'
```
Copy the full output (e.g., `admin:$$apr1$$…`) — we’ll paste it into the middleware label.
## Create a docker‑compose‑swarm.yaml
!!! note
Swarm uses `docker stack deploy`. The compose file can be named anything; we’ll use `docker‑compose‑swarm.yaml`.
First, create a folder named **dynamic** and add **tls.yaml** for dynamic TLS configuration:
```yaml
# dynamic/tls.yaml
tls:
certificates:
- certFile: /certs/local.crt
keyFile: /certs/local.key
```
In the same directory, create `docker‑compose‑swarm.yaml`:
```yaml
services:
traefik:
image: traefik:v3.4
networks:
# Connect to the 'traefik_proxy' overlay network for inter-container communication across nodes
- traefik_proxy
ports:
# Expose Traefik's entry points to the Swarm
# Swarm requires the long syntax for ports.
- target: 80 # Container port (Traefik web entry point)
published: 80 # Host port exposed on the nodes
protocol: tcp
# 'host' mode binds directly to the node's IP where the task runs.
# 'ingress' mode uses Swarm's Routing Mesh (load balances across nodes).
# Choose based on your load balancing strategy. 'host' is often simpler if using an external LB.
mode: host
- target: 443 # Container port ( Traefik websecure entry point)
published: 443 # Host port
protocol: tcp
mode: host
volumes:
# Mount the Docker socket for the Swarm provider
# This MUST be run from a manager node to access the Swarm API via the socket.
- /var/run/docker.sock:/var/run/docker.sock:ro # Swarm API socket
- ./certs:/certs:ro
- ./dynamic:/dynamic:ro
# Traefik Static configuration via command-line arguments
command:
# HTTP EntryPoint
- "--entrypoints.web.address=:80"
# Configure HTTP to HTTPS Redirection
- "--entrypoints.web.http.redirections.entrypoint.to=websecure"
- "--entrypoints.web.http.redirections.entrypoint.scheme=https"
- "--entrypoints.web.http.redirections.entrypoint.permanent=true"
# HTTPS EntryPoint
- "--entrypoints.websecure.address=:443"
- "--entrypoints.websecure.http.tls=true"
# Attach dynamic TLS file
- "--providers.file.filename=/dynamic/tls.yaml"
# Providers
# Enable the Docker Swarm provider (instead of Docker provider)
- "--providers.swarm.endpoint=unix:///var/run/docker.sock"
# Watch for Swarm service changes (requires socket access)
- "--providers.swarm.watch=true"
# Recommended: Don't expose services by default; require explicit labels
- "--providers.swarm.exposedbydefault=false"
# Specify the default network for Traefik to connect to services
- "--providers.swarm.network=traefik_traefik_proxy"
# API & Dashboard
- "--api.dashboard=true" # Enable the dashboard
- "--api.insecure=false" # Explicitly disable insecure API mod
# Observability
- "--log.level=INFO" # Set the Log Level e.g INFO, DEBUG
- "--accesslog=true" # Enable Access Logs
- "--metrics.prometheus=true" # Enable Prometheus
deploy:
mode: replicated
replicas: 1
placement:
# Placement constraints restrict where Traefik tasks can run.
# Running on manager nodes is common for accessing the Swarm API via the socket.
constraints:
- node.role == manager
# Traefik Dynamic configuration via labels
# In Swarm, labels on the service definition configure Traefik routing for that service.
labels:
- "traefik.enable=true"
# Dashboard router
- "traefik.http.routers.dashboard.rule=Host(`dashboard.swarm.localhost`)"
- "traefik.http.routers.dashboard.entrypoints=websecure"
- "traefik.http.routers.dashboard.service=api@internal"
- "traefik.http.routers.dashboard.tls=true"
# Basic‑auth middleware
- "traefik.http.middlewares.dashboard-auth.basicauth.users=<PASTE_HASH_HERE>"
- "traefik.http.routers.dashboard.middlewares=dashboard-auth@swarm"
# Service hint
- "traefik.http.services.traefik.loadbalancer.server.port=8080"
# Deploy the Whoami application
whoami:
image: traefik/whoami
networks:
- traefik_proxy
deploy:
labels:
# Enable Service discovery for Traefik
- "traefik.enable=true"
# Define the WHoami router rule
- "traefik.http.routers.whoami.rule=Host(`whoami.swarm.localhost`)"
# Expose Whoami on the HTTPS entrypoint
- "traefik.http.routers.whoami.entrypoints=websecure"
# Enable TLS
- "traefik.http.routers.whoami.tls=true"
# Expose the whoami port number to Traefik
- traefik.http.services.whoami.loadbalancer.server.port=80
# Define the overlay network for Swarm
networks:
traefik_proxy:
driver: overlay
attachable: true
```
!!! info
- Replace `<PASTE_HASH_HERE>` with the escaped hash from the previous step.
- The password hash is stored directly in a service label. This is fine for local development, but anyone with access to the Docker API can view it using `docker service inspect`. For production, use a more secure method to store secrets.
## Launch the stack
Create the overlay network once (if it doesn’t exist) and deploy:
```bash
docker network create --driver overlay --attachable traefik_proxy || true
docker stack deploy -c docker-compose-swarm.yaml traefik
```
Swarm schedules the services on a manager node and binds ports 80/443.
## Access the Dashboard
Open **https://dashboard.swarm.localhost/** in your browser — the dashboard should prompt for the basic‑auth credentials you configured.
![Traefik Dashboard](../assets/img/setup/traefik-dashboard-swarm.png)
## Test the whoami Application
You can test the application using curl:
```bash
curl -k https://whoami.swarm.localhost/
```
```bash
Hostname: whoami-76c9859cfc-k7jzs
IP: 127.0.0.1
IP: ::1
IP: 10.42.0.59
IP: fe80::50d7:a2ff:fed5:2530
RemoteAddr: 10.42.0.60:54148
GET / HTTP/1.1
Host: whoami.swarm.localhost
User-Agent: curl/8.7.1
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 10.42.0.1
X-Forwarded-Host: whoami.swarm.localhost
X-Forwarded-Port: 443
X-Forwarded-Proto: https
X-Forwarded-Server: traefik-644b7c67d9-f2tn9
X-Real-Ip: 10.42.0.1
```
Making the same request to the HTTP entrypoint will return the following:
```bash
curl -k http://whoami.swarm.localhost
Moved Permanently
```
Requesting the HTTP endpoint redirects to HTTPS, confirming the setup works.
You can also open a browser and navigate to [https://whoami.swarm.localhost](https://whoami.swarm.localhost) to see a JSON dump from the service:
![Whoami](../assets/img/setup/whoami-json-dump.png)
### Other Key Configuration Areas
Beyond this initial setup, Traefik offers extensive configuration possibilities. Here are brief introductions and minimal examples using Docker Compose `command` arguments or `labels`. Consult the main documentation linked for comprehensive details.
#### TLS Certificate Management (Let’s Encrypt)
To make the `websecure` entry point serve valid HTTPS certificates automatically, enable Let's Encrypt (ACME).
```yaml
command:
# ...
- "--certificatesresolvers.le.acme.email=you@example.com"
- "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
- "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
- "--entrypoints.websecure.http.tls.certresolver=le"
```
This defines a resolver named `le`, sets the required email and storage path (within the mounted `/letsencrypt` volume), and enables the HTTP challenge. Refer to the [HTTPS/TLS Documentation](../reference/install-configuration/tls/certificate-resolvers/overview.md) and [Let's Encrypt Documentation](../reference/install-configuration/tls/certificate-resolvers/acme.md) for details on challenges and DNS provider configuration.
!!! note
- Ensure the `/letsencrypt` path is on a **shared volume** or NFS so all nodes can read certificates.
- Ensure to mount the `/letsencrypt` volume in the `traefik` service in the `docker-compose-swarm.yaml` file.
#### Metrics (Prometheus)
You can expose Traefik's internal metrics for monitoring with Prometheus. We already enabled prometheus in our setup but we can further configure it.
*Example `command` additions:*
```yaml
command:
# If using a dedicated metrics entry point, define it:
- "--entrypoints.metrics.address=:8082"
- "--metrics.prometheus=true"
# Optionally change the entry point metrics are exposed on (defaults to 'traefik')
- "--metrics.prometheus.entrypoint=metrics"
# Add labels to metrics for routers/services (can increase cardinality)
- "--metrics.prometheus.addrouterslabels=true"
```
This enables the `/metrics` endpoint (typically accessed via the internal API port, often 8080 by default if not secured, or via a dedicated entry point). See the [Metrics Documentation](../reference/install-configuration/observability/metrics.md) for options.
#### Tracing (OTel)
You can enable distributed tracing to follow requests through Traefik.
*Example `command` additions:*
```yaml
command:
# ...
- "--tracing.otel=true"
- "--tracing.otel.grpcendpoint=otel-collector:4317"
```
!!! note
This option requires a running OTEL collector accessible by Traefik. Consult the [Tracing Documentation](../reference/install-configuration/observability/tracing.md).
#### Access Logs
You can configure Traefik to log incoming requests for debugging and analysis.
*Example `command` additions:*
```yaml
command:
# ... other command arguments ...
- "--accesslog=true" # Enable access logs to stdout
# Optionally change format or output file (requires volume)
- "--accesslog.format=json"
- "--accesslog.filepath=/path/to/access.log"
# Optionally filter logs
- "--accesslog.filters.statuscodes=400-599"
```
### Conclusion
You now have Traefik running on Docker Swarm with HTTPS, a secured dashboard, automatic HTTP → HTTPS redirects, and foundational observability. Expand this stack with Let’s Encrypt, additional middlewares, or multiple Traefik replicas as your Swarm grows.
{!traefik-for-business-applications.md!}

10
docs/mkdocs.yml
View File

@ -50,6 +50,7 @@ markdown_extensions:
- pymdownx.inlinehilite
- pymdownx.highlight:
use_pygments: false # hljs is used instead of pygment for TOML highlighting support
- pymdownx.smartsymbols
- pymdownx.superfences
- pymdownx.tabbed
@ -72,6 +73,15 @@ nav:
- 'Docker': 'getting-started/docker.md'
- 'Configuration Introduction': 'getting-started/configuration-overview.md'
- 'Frequently Asked Questions': 'getting-started/faq.md'
- 'Setup':
- 'Kubernetes': 'setup/kubernetes.md'
- 'Docker': 'setup/docker.md'
- 'Swarm': 'setup/swarm.md'
- 'Expose':
- 'Overview': 'expose/overview.md'
- 'Kubernetes': 'expose/kubernetes.md'
- 'Docker': 'expose/docker.md'
- 'Swarm': 'expose/swarm.md'
- 'Observe':
- 'Overview': 'observe/overview.md'
- 'Logs & Access Logs': 'observe/logs-and-access-logs.md'

2
go.mod
View File

@ -207,7 +207,7 @@ require (
github.com/go-playground/validator/v10 v10.16.0 // indirect
github.com/go-resty/resty/v2 v2.16.5 // indirect
github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
github.com/go-viper/mapstructure/v2 v2.2.1 // indirect
github.com/go-viper/mapstructure/v2 v2.3.0 // indirect
github.com/go-zookeeper/zk v1.0.3 // indirect
github.com/goccy/go-json v0.10.5 // indirect
github.com/gofrs/flock v0.12.1 // indirect

4
go.sum
View File

@ -423,8 +423,8 @@ github.com/go-stack/stack v1.8.0/go.mod h1:v0f6uXyyMGvRgIKkXu+yp6POWl0qKG85gN/me
github.com/go-task/slim-sprig v0.0.0-20210107165309-348f09dbbbc0/go.mod h1:fyg7847qk6SyHyPtNmDHnmrv/HOrqktSC+C9fM+CJOE=
github.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1vB6EwHI=
github.com/go-task/slim-sprig/v3 v3.0.0/go.mod h1:W848ghGpv3Qj3dhTPRyJypKRiqCdHZiAzKg9hl15HA8=
github.com/go-viper/mapstructure/v2 v2.2.1 h1:ZAaOCxANMuZx5RCeg0mBdEZk7DZasvvZIxtHqx8aGss=
github.com/go-viper/mapstructure/v2 v2.2.1/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
github.com/go-viper/mapstructure/v2 v2.3.0 h1:27XbWsHIqhbdR5TIC911OfYvgSaW93HM+dX7970Q7jk=
github.com/go-viper/mapstructure/v2 v2.3.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
github.com/go-zookeeper/zk v1.0.2/go.mod h1:nOB03cncLtlp4t+UAkGSV+9beXP/akpekBwL+UX1Qcw=
github.com/go-zookeeper/zk v1.0.3 h1:7M2kwOsc//9VeeFiPtf+uSJlVpU66x9Ba5+8XK7/TDg=
github.com/go-zookeeper/zk v1.0.3/go.mod h1:nOB03cncLtlp4t+UAkGSV+9beXP/akpekBwL+UX1Qcw=

32
pkg/provider/kubernetes/crd/fixtures/services.yml
View File

@ -301,6 +301,38 @@ spec:
type: ClusterIP
clusterIP: 10.10.0.1
---
apiVersion: v1
kind: Service
metadata:
name: native-disabled-svc
namespace: default
spec:
ports:
- name: web
port: 80
type: ClusterIP
clusterIP: 10.10.0.1
---
kind: EndpointSlice
apiVersion: discovery.k8s.io/v1
metadata:
name: native-disabled-svc-abc
namespace: default
labels:
kubernetes.io/service-name: native-disabled-svc
addressType: IPv4
ports:
- name: web
port: 80
endpoints:
- addresses:
- 10.10.0.20
- 10.10.0.21
conditions:
ready: true
---
apiVersion: v1
kind: Service

39
pkg/provider/kubernetes/crd/fixtures/tcp/services.yml
View File

@ -298,11 +298,46 @@ metadata:
spec:
ports:
- name: myapp
port: 8000
- name: tcp
protocol: TCP
port: 9000
type: ClusterIP
clusterIP: 10.10.0.1
---
apiVersion: v1
kind: Service
metadata:
name: native-disabled-svc-tcp
namespace: default
spec:
ports:
- name: tcp
protocol: TCP
port: 9000
type: ClusterIP
clusterIP: 10.10.0.1
---
kind: EndpointSlice
apiVersion: discovery.k8s.io/v1
metadata:
name: native-disabled-tcp-abc
namespace: default
labels:
kubernetes.io/service-name: native-disabled-svc-tcp
addressType: IPv4
ports:
- name: tcp
protocol: TCP
port: 9000
endpoints:
- addresses:
- 10.10.0.30
- 10.10.0.31
conditions:
ready: true
---
apiVersion: v1
kind: Service

2
pkg/provider/kubernetes/crd/fixtures/tcp/with_global_native_service_lb.yml
View File

@ -12,4 +12,4 @@ spec:
- match: HostSNI(`foo.com`)
services:
- name: native-svc-tcp
port: 8000
port: 9000

2
pkg/provider/kubernetes/crd/fixtures/tcp/with_native_service_lb.yml
View File

@ -12,5 +12,5 @@ spec:
- match: HostSNI(`foo.com`)
services:
- name: native-svc-tcp
port: 8000
port: 9000
nativeLB: true

12
pkg/provider/kubernetes/crd/fixtures/tcp/with_native_service_lb_disabled.yml Normal file
View File

@ -0,0 +1,12 @@
apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
name: tcp.route.native-disabled
namespace: default
spec:
routes:
- match: HostSNI(`foo.com`)
services:
- name: native-disabled-svc-tcp
port: 9000
nativeLB: false

37
pkg/provider/kubernetes/crd/fixtures/udp/services.yml
View File

@ -252,11 +252,46 @@ metadata:
spec:
ports:
- name: myapp
- name: udp
protocol: UDP
port: 8000
type: ClusterIP
clusterIP: 10.10.0.1
---
apiVersion: v1
kind: Service
metadata:
name: native-disabled-svc-udp
namespace: default
spec:
ports:
- name: udp
protocol: UDP
port: 8000
type: ClusterIP
clusterIP: 10.10.0.1
---
kind: EndpointSlice
apiVersion: discovery.k8s.io/v1
metadata:
name: native-disabled-udp-abc
namespace: default
labels:
kubernetes.io/service-name: native-disabled-svc-udp
addressType: IPv4
ports:
- name: udp
protocol: UDP
port: 8000
endpoints:
- addresses:
- 10.10.0.30
- 10.10.0.31
conditions:
ready: true
---
apiVersion: v1
kind: Service

11
pkg/provider/kubernetes/crd/fixtures/udp/with_native_service_lb_disabled.yml Normal file
View File

@ -0,0 +1,11 @@
apiVersion: traefik.io/v1alpha1
kind: IngressRouteUDP
metadata:
name: udp.route.native-disabled
namespace: default
spec:
routes:
- services:
- name: native-disabled-svc-udp
port: 8000
nativeLB: false

13
pkg/provider/kubernetes/crd/fixtures/with_native_service_lb_disabled.yml Normal file
View File

@ -0,0 +1,13 @@
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: test.route.native-disabled
namespace: default
spec:
routes:
- match: Host(`foo.com`)
kind: Rule
services:
- name: native-disabled-svc
port: 80
nativeLB: false

142
pkg/provider/kubernetes/crd/kubernetes_test.go
View File

@ -7778,7 +7778,7 @@ func TestNativeLB(t *testing.T) {
LoadBalancer: &dynamic.TCPServersLoadBalancer{
Servers: []dynamic.TCPServer{
{
Address: "10.10.0.1:8000",
Address: "10.10.0.1:9000",
Port: "",
},
},
@ -8375,6 +8375,52 @@ func TestGlobalNativeLB(t *testing.T) {
TLS: &dynamic.TLSConfiguration{},
},
},
{
desc: "HTTP with global native Service LB but service reference has nativeLB disabled",
paths: []string{"services.yml", "with_native_service_lb_disabled.yml"},
NativeLBByDefault: true,
expected: &dynamic.Configuration{
UDP: &dynamic.UDPConfiguration{
Routers: map[string]*dynamic.UDPRouter{},
Services: map[string]*dynamic.UDPService{},
},
TCP: &dynamic.TCPConfiguration{
ServersTransports: map[string]*dynamic.TCPServersTransport{},
Routers: map[string]*dynamic.TCPRouter{},
Middlewares: map[string]*dynamic.TCPMiddleware{},
Services: map[string]*dynamic.TCPService{},
},
HTTP: &dynamic.HTTPConfiguration{
ServersTransports: map[string]*dynamic.ServersTransport{},
Routers: map[string]*dynamic.Router{
"default-test-route-native-disabled-6f97418635c7e18853da": {
Service: "default-test-route-native-disabled-6f97418635c7e18853da",
Rule: "Host(`foo.com`)",
Priority: 0,
},
},
Middlewares: map[string]*dynamic.Middleware{},
Services: map[string]*dynamic.Service{
"default-test-route-native-disabled-6f97418635c7e18853da": {
LoadBalancer: &dynamic.ServersLoadBalancer{
Strategy: dynamic.BalancerStrategyWRR,
ResponseForwarding: &dynamic.ResponseForwarding{FlushInterval: dynamic.DefaultFlushInterval},
Servers: []dynamic.Server{
{
URL: "http://10.10.0.20:80",
},
{
URL: "http://10.10.0.21:80",
},
},
PassHostHeader: pointer(true),
},
},
},
},
TLS: &dynamic.TLSConfiguration{},
},
},
{
desc: "HTTP with native Service LB in ingressroute",
paths: []string{"services.yml", "with_native_service_lb.yml"},
@ -8448,7 +8494,51 @@ func TestGlobalNativeLB(t *testing.T) {
LoadBalancer: &dynamic.TCPServersLoadBalancer{
Servers: []dynamic.TCPServer{
{
Address: "10.10.0.1:8000",
Address: "10.10.0.1:9000",
Port: "",
},
},
},
},
},
},
TLS: &dynamic.TLSConfiguration{},
},
},
{
desc: "TCP with global native Service LB but service reference has nativeLB disabled",
paths: []string{"tcp/services.yml", "tcp/with_native_service_lb_disabled.yml"},
NativeLBByDefault: true,
expected: &dynamic.Configuration{
UDP: &dynamic.UDPConfiguration{
Routers: map[string]*dynamic.UDPRouter{},
Services: map[string]*dynamic.UDPService{},
},
HTTP: &dynamic.HTTPConfiguration{
ServersTransports: map[string]*dynamic.ServersTransport{},
Routers: map[string]*dynamic.Router{},
Middlewares: map[string]*dynamic.Middleware{},
Services: map[string]*dynamic.Service{},
},
TCP: &dynamic.TCPConfiguration{
ServersTransports: map[string]*dynamic.TCPServersTransport{},
Routers: map[string]*dynamic.TCPRouter{
"default-tcp.route.native-disabled-fdd3e9338e47a45efefc": {
Service: "default-tcp.route.native-disabled-fdd3e9338e47a45efefc",
Rule: "HostSNI(`foo.com`)",
},
},
Middlewares: map[string]*dynamic.TCPMiddleware{},
Services: map[string]*dynamic.TCPService{
"default-tcp.route.native-disabled-fdd3e9338e47a45efefc": {
LoadBalancer: &dynamic.TCPServersLoadBalancer{
Servers: []dynamic.TCPServer{
{
Address: "10.10.0.30:9000",
Port: "",
},
{
Address: "10.10.0.31:9000",
Port: "",
},
},
@ -8488,7 +8578,7 @@ func TestGlobalNativeLB(t *testing.T) {
LoadBalancer: &dynamic.TCPServersLoadBalancer{
Servers: []dynamic.TCPServer{
{
Address: "10.10.0.1:8000",
Address: "10.10.0.1:9000",
Port: "",
},
},
@ -8578,6 +8668,49 @@ func TestGlobalNativeLB(t *testing.T) {
TLS: &dynamic.TLSConfiguration{},
},
},
{
desc: "UDP with global native Service LB but service reference has nativeLB disabled",
paths: []string{"udp/services.yml", "udp/with_native_service_lb_disabled.yml"},
NativeLBByDefault: true,
expected: &dynamic.Configuration{
UDP: &dynamic.UDPConfiguration{
Routers: map[string]*dynamic.UDPRouter{
"default-udp.route.native-disabled-0": {
Service: "default-udp.route.native-disabled-0",
},
},
Services: map[string]*dynamic.UDPService{
"default-udp.route.native-disabled-0": {
LoadBalancer: &dynamic.UDPServersLoadBalancer{
Servers: []dynamic.UDPServer{
{
Address: "10.10.0.30:8000",
Port: "",
},
{
Address: "10.10.0.31:8000",
Port: "",
},
},
},
},
},
},
HTTP: &dynamic.HTTPConfiguration{
ServersTransports: map[string]*dynamic.ServersTransport{},
Routers: map[string]*dynamic.Router{},
Middlewares: map[string]*dynamic.Middleware{},
Services: map[string]*dynamic.Service{},
},
TCP: &dynamic.TCPConfiguration{
ServersTransports: map[string]*dynamic.TCPServersTransport{},
Routers: map[string]*dynamic.TCPRouter{},
Middlewares: map[string]*dynamic.TCPMiddleware{},
Services: map[string]*dynamic.TCPService{},
},
TLS: &dynamic.TLSConfiguration{},
},
},
}
for _, test := range testCases {
@ -8595,8 +8728,6 @@ func TestGlobalNativeLB(t *testing.T) {
objects := k8s.MustParseYaml(yamlContent)
for _, obj := range objects {
switch o := obj.(type) {
case *corev1.Service, *corev1.Endpoints, *corev1.Secret:
k8sObjects = append(k8sObjects, o)
case *traefikv1alpha1.IngressRoute:
crdObjects = append(crdObjects, o)
case *traefikv1alpha1.IngressRouteTCP:
@ -8612,6 +8743,7 @@ func TestGlobalNativeLB(t *testing.T) {
case *traefikv1alpha1.TLSStore:
crdObjects = append(crdObjects, o)
default:
k8sObjects = append(k8sObjects, o)
}
}
}

2
pkg/provider/kubernetes/gateway/annotations.go
View File

@ -16,7 +16,7 @@ type ServiceConfig struct {
// Service is the service's configuration from annotations.
type Service struct {
NativeLB bool `json:"nativeLB"`
NativeLB *bool `json:"nativeLB"`
}
func parseServiceAnnotations(annotations map[string]string) (ServiceConfig, error) {

3
pkg/provider/kubernetes/gateway/annotations_test.go
View File

@ -5,6 +5,7 @@ import (
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"k8s.io/utils/ptr"
)
func Test_parseServiceConfig(t *testing.T) {
@ -22,7 +23,7 @@ func Test_parseServiceConfig(t *testing.T) {
},
expected: ServiceConfig{
Service: Service{
NativeLB: true,
NativeLB: ptr.To(true),
},
},
},

51
pkg/provider/kubernetes/gateway/fixtures/httproute/simple_nativelb_disabled.yml Normal file
View File

@ -0,0 +1,51 @@
---
kind: GatewayClass
apiVersion: gateway.networking.k8s.io/v1
metadata:
name: my-gateway-class
spec:
controllerName: traefik.io/gateway-controller
---
kind: Gateway
apiVersion: gateway.networking.k8s.io/v1
metadata:
name: my-gateway
namespace: default
spec:
gatewayClassName: my-gateway-class
listeners: # Use GatewayClass defaults for listener definition.
- name: http
protocol: HTTP
port: 80
allowedRoutes:
kinds:
- kind: HTTPRoute
group: gateway.networking.k8s.io
namespaces:
from: Same
---
kind: HTTPRoute
apiVersion: gateway.networking.k8s.io/v1
metadata:
name: http-app-1
namespace: default
spec:
parentRefs:
- name: my-gateway
kind: Gateway
group: gateway.networking.k8s.io
hostnames:
- "foo.com"
rules:
- matches:
- path:
type: Exact
value: /bar
backendRefs:
- name: whoami-native-disabled
port: 80
weight: 1
kind: Service
group: ""

79
pkg/provider/kubernetes/gateway/fixtures/services.yml
View File

@ -471,3 +471,82 @@ spec:
- protocol: TCP
port: 10000
name: tcp-2
---
apiVersion: v1
kind: Service
metadata:
name: whoami-native-disabled
namespace: default
annotations:
traefik.io/service.nativelb: "false"
spec:
clusterIP: 10.10.10.2
ports:
- name: web
protocol: TCP
port: 80
targetPort: web
selector:
app: containous
task: whoami
---
kind: EndpointSlice
apiVersion: discovery.k8s.io/v1
metadata:
name: whoami-native-disabled-abc
namespace: default
labels:
kubernetes.io/service-name: whoami-native-disabled
addressType: IPv4
ports:
- name: web
port: 80
endpoints:
- addresses:
- 10.10.0.20
- 10.10.0.21
conditions:
ready: true
---
apiVersion: v1
kind: Service
metadata:
name: whoamitcp-native-disabled
namespace: default
annotations:
traefik.io/service.nativelb: "false"
spec:
clusterIP: 10.10.10.3
ports:
- protocol: TCP
port: 9000
name: tcp-1
- protocol: TCP
port: 10000
name: tcp-2
---
kind: EndpointSlice
apiVersion: discovery.k8s.io/v1
metadata:
name: whoamitcp-native-disabled-abc
namespace: default
labels:
kubernetes.io/service-name: whoamitcp-native-disabled
addressType: IPv4
ports:
- name: tcp-1
protocol: TCP
port: 9000
- name: tcp-2
protocol: TCP
port: 10000
endpoints:
- addresses:
- 10.10.0.30
- 10.10.0.31
conditions:
ready: true

46
pkg/provider/kubernetes/gateway/fixtures/tcproute/simple_nativelb_disabled.yml Normal file
View File

@ -0,0 +1,46 @@
---
kind: GatewayClass
apiVersion: gateway.networking.k8s.io/v1
metadata:
name: my-gateway-class
namespace: default
spec:
controllerName: traefik.io/gateway-controller
---
kind: Gateway
apiVersion: gateway.networking.k8s.io/v1
metadata:
name: my-tcp-gateway
namespace: default
spec:
gatewayClassName: my-gateway-class
listeners: # Use GatewayClass defaults for listener definition.
- name: tcp
protocol: TCP
port: 9000
allowedRoutes:
namespaces:
from: Same
kinds:
- kind: TCPRoute
group: gateway.networking.k8s.io
---
kind: TCPRoute
apiVersion: gateway.networking.k8s.io/v1alpha2
metadata:
name: tcp-app-1
namespace: default
spec:
parentRefs:
- name: my-tcp-gateway
kind: Gateway
group: gateway.networking.k8s.io
rules:
- backendRefs:
- name: whoamitcp-native-disabled
port: 9000
weight: 1
kind: Service
group: ""

7
pkg/provider/kubernetes/gateway/kubernetes.go
View File

@ -918,7 +918,12 @@ func (p *Provider) getBackendAddresses(namespace string, ref gatev1.BackendRef)
return nil, corev1.ServicePort{}, fmt.Errorf("parsing service annotations config: %w", err)
}
if p.NativeLBByDefault || annotationsConfig.Service.NativeLB {
nativeLB := p.NativeLBByDefault
if annotationsConfig.Service.NativeLB != nil {
nativeLB = *annotationsConfig.Service.NativeLB
}
if nativeLB {
if service.Spec.ClusterIP == "" || service.Spec.ClusterIP == "None" {
return nil, corev1.ServicePort{}, fmt.Errorf("no clusterIP found for service: %s/%s", service.Namespace, service.Name)
}

120
pkg/provider/kubernetes/gateway/kubernetes_test.go
View File

@ -2522,6 +2522,69 @@ func TestLoadHTTPRoutes(t *testing.T) {
TLS: &dynamic.TLSConfiguration{},
},
},
{
desc: "Simple HTTPRoute with NativeLBByDefault enabled but service has disabled nativelb",
paths: []string{"services.yml", "httproute/simple_nativelb_disabled.yml"},
nativeLB: true,
entryPoints: map[string]Entrypoint{"web": {
Address: ":80",
}},
expected: &dynamic.Configuration{
UDP: &dynamic.UDPConfiguration{
Routers: map[string]*dynamic.UDPRouter{},
Services: map[string]*dynamic.UDPService{},
},
TCP: &dynamic.TCPConfiguration{
Routers: map[string]*dynamic.TCPRouter{},
Middlewares: map[string]*dynamic.TCPMiddleware{},
Services: map[string]*dynamic.TCPService{},
ServersTransports: map[string]*dynamic.TCPServersTransport{},
},
HTTP: &dynamic.HTTPConfiguration{
Routers: map[string]*dynamic.Router{
"httproute-default-http-app-1-gw-default-my-gateway-ep-web-0-1c0cf64bde37d9d0df06": {
EntryPoints: []string{"web"},
Service: "httproute-default-http-app-1-gw-default-my-gateway-ep-web-0-1c0cf64bde37d9d0df06-wrr",
Rule: "Host(`foo.com`) && Path(`/bar`)",
Priority: 100008,
RuleSyntax: "default",
},
},
Middlewares: map[string]*dynamic.Middleware{},
Services: map[string]*dynamic.Service{
"httproute-default-http-app-1-gw-default-my-gateway-ep-web-0-1c0cf64bde37d9d0df06-wrr": {
Weighted: &dynamic.WeightedRoundRobin{
Services: []dynamic.WRRService{
{
Name: "default-whoami-native-disabled-http-80",
Weight: ptr.To(1),
},
},
},
},
"default-whoami-native-disabled-http-80": {
LoadBalancer: &dynamic.ServersLoadBalancer{
Strategy: dynamic.BalancerStrategyWRR,
Servers: []dynamic.Server{
{
URL: "http://10.10.0.20:80",
},
{
URL: "http://10.10.0.21:80",
},
},
PassHostHeader: ptr.To(true),
ResponseForwarding: &dynamic.ResponseForwarding{
FlushInterval: ptypes.Duration(100 * time.Millisecond),
},
},
},
},
ServersTransports: map[string]*dynamic.ServersTransport{},
},
TLS: &dynamic.TLSConfiguration{},
},
},
}
for _, test := range testCases {
@ -4429,6 +4492,63 @@ func TestLoadTCPRoutes(t *testing.T) {
TLS: &dynamic.TLSConfiguration{},
},
},
{
desc: "Simple TCPRoute with NativeLBByDefault enabled but service has disabled nativelb",
paths: []string{"services.yml", "tcproute/simple_nativelb_disabled.yml"},
nativeLB: true,
entryPoints: map[string]Entrypoint{
"tcp": {Address: ":9000"},
},
expected: &dynamic.Configuration{
UDP: &dynamic.UDPConfiguration{
Routers: map[string]*dynamic.UDPRouter{},
Services: map[string]*dynamic.UDPService{},
},
TCP: &dynamic.TCPConfiguration{
Routers: map[string]*dynamic.TCPRouter{
"tcproute-default-tcp-app-1-gw-default-my-tcp-gateway-ep-tcp-0-e3b0c44298fc1c149afb": {
EntryPoints: []string{"tcp"},
Service: "tcproute-default-tcp-app-1-gw-default-my-tcp-gateway-ep-tcp-0-e3b0c44298fc1c149afb-wrr",
Rule: "HostSNI(`*`)",
RuleSyntax: "default",
},
},
Middlewares: map[string]*dynamic.TCPMiddleware{},
Services: map[string]*dynamic.TCPService{
"tcproute-default-tcp-app-1-gw-default-my-tcp-gateway-ep-tcp-0-e3b0c44298fc1c149afb-wrr": {
Weighted: &dynamic.TCPWeightedRoundRobin{
Services: []dynamic.TCPWRRService{
{
Name: "default-whoamitcp-native-disabled-9000",
Weight: ptr.To(1),
},
},
},
},
"default-whoamitcp-native-disabled-9000": {
LoadBalancer: &dynamic.TCPServersLoadBalancer{
Servers: []dynamic.TCPServer{
{
Address: "10.10.0.30:9000",
},
{
Address: "10.10.0.31:9000",
},
},
},
},
},
ServersTransports: map[string]*dynamic.TCPServersTransport{},
},
HTTP: &dynamic.HTTPConfiguration{
Routers: map[string]*dynamic.Router{},
Middlewares: map[string]*dynamic.Middleware{},
Services: map[string]*dynamic.Service{},
ServersTransports: map[string]*dynamic.ServersTransport{},
},
TLS: &dynamic.TLSConfiguration{},
},
},
}
for _, test := range testCases {

53
pkg/provider/kubernetes/ingress/fixtures/Ingress-with-native-lb-by-default-but-service-has-disabled-nativelb.yml Normal file
View File

@ -0,0 +1,53 @@
kind: Ingress
apiVersion: networking.k8s.io/v1
metadata:
name: global-native-lb
namespace: default
spec:
rules:
- host: traefik.tchouk
http:
paths:
- path: /bar
backend:
service:
name: native-disabled-svc
port:
name: web
number: 8080
pathType: Prefix
---
kind: Service
apiVersion: v1
metadata:
name: native-disabled-svc
namespace: default
annotations:
traefik.ingress.kubernetes.io/service.nativelb: "false"
spec:
ports:
- name: web
port: 8080
clusterIP: 10.0.0.1
type: ClusterIP
externalName: traefik.wtf
---
kind: EndpointSlice
apiVersion: discovery.k8s.io/v1
metadata:
name: native-disabled-svc-abc
namespace: default
labels:
kubernetes.io/service-name: native-disabled-svc
addressType: IPv4
ports:
- name: web
port: 8080
endpoints:
- addresses:
- 10.10.0.20
- 10.10.0.21
conditions:
ready: true

31
pkg/provider/kubernetes/ingress/kubernetes_test.go
View File

@ -2179,6 +2179,37 @@ func TestLoadConfigurationFromIngressesWithNativeLBByDefault(t *testing.T) {
},
},
},
{
desc: "Ingress with native lb by default but service has disabled nativelb",
expected: &dynamic.Configuration{
HTTP: &dynamic.HTTPConfiguration{
Middlewares: map[string]*dynamic.Middleware{},
Routers: map[string]*dynamic.Router{
"default-global-native-lb-traefik-tchouk-bar": {
Rule: "Host(`traefik.tchouk`) && PathPrefix(`/bar`)",
Service: "default-native-disabled-svc-web",
},
},
Services: map[string]*dynamic.Service{
"default-native-disabled-svc-web": {
LoadBalancer: &dynamic.ServersLoadBalancer{
Strategy: dynamic.BalancerStrategyWRR,
ResponseForwarding: &dynamic.ResponseForwarding{FlushInterval: dynamic.DefaultFlushInterval},
PassHostHeader: pointer(true),
Servers: []dynamic.Server{
{
URL: "http://10.10.0.20:8080",
},
{
URL: "http://10.10.0.21:8080",
},
},
},
},
},
},
},
},
}
for _, test := range testCases {

11
pkg/server/service/loadbalancer/p2c/p2c.go
View File

@ -43,6 +43,7 @@ type rnd interface {
type Balancer struct {
wantsHealthCheck bool
// handlersMu is a mutex to protect the handlers slice, the status and the fenced maps.
handlersMu sync.RWMutex
handlers []*namedHandler
// status is a record of which child services of the Balancer are healthy, keyed
@ -50,11 +51,12 @@ type Balancer struct {
// created via Add, and it is later removed or added to the map as needed,
// through the SetStatus method.
status map[string]struct{}
// fenced is the list of terminating yet still serving child services.
fenced map[string]struct{}
// updaters is the list of hooks that are run (to update the Balancer
// parent(s)), whenever the Balancer status changes.
updaters []func(bool)
// fenced is the list of terminating yet still serving child services.
fenced map[string]struct{}
sticky *loadbalancer.Sticky
@ -181,7 +183,10 @@ func (b *Balancer) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
if err != nil {
log.Error().Err(err).Msg("Error while getting sticky handler")
} else if h != nil {
if _, ok := b.status[h.Name]; ok {
b.handlersMu.RLock()
_, ok := b.status[h.Name]
b.handlersMu.RUnlock()
if ok {
if rewrite {
if err := b.sticky.WriteStickyCookie(rw, h.Name); err != nil {
log.Error().Err(err).Msg("Writing sticky cookie")

11
pkg/server/service/loadbalancer/wrr/wrr.go
View File

@ -27,6 +27,7 @@ type namedHandler struct {
type Balancer struct {
wantsHealthCheck bool
// handlersMu is a mutex to protect the handlers slice, the status and the fenced maps.
handlersMu sync.RWMutex
handlers []*namedHandler
// status is a record of which child services of the Balancer are healthy, keyed
@ -34,11 +35,12 @@ type Balancer struct {
// created via Add, and it is later removed or added to the map as needed,
// through the SetStatus method.
status map[string]struct{}
// fenced is the list of terminating yet still serving child services.
fenced map[string]struct{}
// updaters is the list of hooks that are run (to update the Balancer
// parent(s)), whenever the Balancer status changes.
updaters []func(bool)
// fenced is the list of terminating yet still serving child services.
fenced map[string]struct{}
sticky *loadbalancer.Sticky
@ -180,7 +182,10 @@ func (b *Balancer) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
if err != nil {
log.Error().Err(err).Msg("Error while getting sticky handler")
} else if h != nil {
if _, ok := b.status[h.Name]; ok {
b.handlersMu.RLock()
_, ok := b.status[h.Name]
b.handlersMu.RUnlock()
if ok {
if rewrite {
if err := b.sticky.WriteStickyCookie(rw, h.Name); err != nil {
log.Error().Err(err).Msg("Writing sticky cookie")

6
script/gcg/traefik-bugfix.toml
View File

@ -4,11 +4,11 @@ RepositoryName = "traefik"
OutputType = "file"
FileName = "traefik_changelog.md"
# example new bugfix v3.4.3
# example new bugfix v3.4.4
CurrentRef = "v3.4"
PreviousRef = "v3.4.2"
PreviousRef = "v3.4.3"
BaseBranch = "v3.4"
FutureCurrentRefName = "v3.4.3"
FutureCurrentRefName = "v3.4.4"
ThresholdPreviousRef = 10
ThresholdCurrentRef = 10