Improve error and documentation on the needed link between router and service

This commit is contained in:
Michel Loiseleur 2024-07-29 15:39:06 +02:00 committed by GitHub
parent 5a70910dce
commit 898eab20ac
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 78 additions and 60 deletions

View file

@ -21,7 +21,7 @@ and [Docker Swarm Mode](https://docs.docker.com/engine/swarm/).
## Configuration Examples ## Configuration Examples
??? example "Configuring Docker & Deploying / Exposing Services" ??? example "Configuring Docker & Deploying / Exposing one Service"
Enabling the docker provider Enabling the docker provider
@ -49,7 +49,7 @@ and [Docker Swarm Mode](https://docs.docker.com/engine/swarm/).
- traefik.http.routers.my-container.rule=Host(`example.com`) - traefik.http.routers.my-container.rule=Host(`example.com`)
``` ```
??? example "Configuring Docker Swarm & Deploying / Exposing Services" ??? example "Configuring Docker Swarm & Deploying / Exposing one Service"
Enabling the docker provider (Swarm Mode) Enabling the docker provider (Swarm Mode)
@ -80,7 +80,9 @@ and [Docker Swarm Mode](https://docs.docker.com/engine/swarm/).
--providers.docker.swarmMode=true --providers.docker.swarmMode=true
``` ```
Attach labels to services (not to containers) while in Swarm mode (in your docker compose file) Attach labels to a single service (not containers) while in Swarm mode (in your Docker compose file).
When there is only one service, and the router does not specify a service,
then that service is automatically assigned to the router.
```yaml ```yaml
version: "3" version: "3"

View file

@ -22,7 +22,7 @@ With Docker, Traefik can leverage labels attached to a container to generate rou
## Configuration Examples ## Configuration Examples
??? example "Configuring Docker & Deploying / Exposing Services" ??? example "Configuring Docker & Deploying / Exposing one Service"
Enabling the docker provider Enabling the docker provider
@ -50,6 +50,56 @@ With Docker, Traefik can leverage labels attached to a container to generate rou
- traefik.http.routers.my-container.rule=Host(`example.com`) - traefik.http.routers.my-container.rule=Host(`example.com`)
``` ```
??? example "Configuring Docker Swarm & Deploying / Exposing one Service"
Enabling the docker provider (Swarm Mode)
```yaml tab="File (YAML)"
providers:
docker:
# swarm classic (1.12-)
# endpoint: "tcp://127.0.0.1:2375"
# docker swarm mode (1.12+)
endpoint: "tcp://127.0.0.1:2377"
swarmMode: true
```
```toml tab="File (TOML)"
[providers.docker]
# swarm classic (1.12-)
# endpoint = "tcp://127.0.0.1:2375"
# docker swarm mode (1.12+)
endpoint = "tcp://127.0.0.1:2377"
swarmMode = true
```
```bash tab="CLI"
# swarm classic (1.12-)
# --providers.docker.endpoint=tcp://127.0.0.1:2375
# docker swarm mode (1.12+)
--providers.docker.endpoint=tcp://127.0.0.1:2377
--providers.docker.swarmMode=true
```
Attach labels to services (not containers) while in Swarm mode (in your Docker compose file).
When there is only one service, and the router does not specify a service,
then that service is automatically assigned to the router.
```yaml
version: "3"
services:
my-container:
deploy:
labels:
- traefik.http.routers.my-container.rule=Host(`example.com`)
- traefik.http.services.my-container-service.loadbalancer.server.port=8080
```
!!! important "Labels in Docker Swarm Mode"
While in Swarm Mode, Traefik uses labels found on services, not on individual containers.
Therefore, if you use a compose file with Swarm Mode, labels should be defined in the `deploy` part of your service.
This behavior is only enabled for docker-compose version 3+ ([Compose file reference](https://docs.docker.com/compose/compose-file/compose-file-v3/#labels-1)).
??? example "Specify a Custom Port for the Container" ??? example "Specify a Custom Port for the Container"
Forward requests for `http://example.com` to `http://<private IP of container>:12345`: Forward requests for `http://example.com` to `http://<private IP of container>:12345`:
@ -61,6 +111,7 @@ With Docker, Traefik can leverage labels attached to a container to generate rou
# ... # ...
labels: labels:
- traefik.http.routers.my-container.rule=Host(`example.com`) - traefik.http.routers.my-container.rule=Host(`example.com`)
- traefik.http.routers.my-container.service=my-service"
# Tell Traefik to use the port 12345 to connect to `my-container` # Tell Traefik to use the port 12345 to connect to `my-container`
- traefik.http.services.my-service.loadbalancer.server.port=12345 - traefik.http.services.my-service.loadbalancer.server.port=12345
``` ```
@ -92,54 +143,6 @@ With Docker, Traefik can leverage labels attached to a container to generate rou
- traefik.http.services.admin-service.loadbalancer.server.port=9000 - traefik.http.services.admin-service.loadbalancer.server.port=9000
``` ```
??? example "Configuring Docker Swarm & Deploying / Exposing Services"
Enabling the docker provider (Swarm Mode)
```yaml tab="File (YAML)"
providers:
docker:
# swarm classic (1.12-)
# endpoint: "tcp://127.0.0.1:2375"
# docker swarm mode (1.12+)
endpoint: "tcp://127.0.0.1:2377"
swarmMode: true
```
```toml tab="File (TOML)"
[providers.docker]
# swarm classic (1.12-)
# endpoint = "tcp://127.0.0.1:2375"
# docker swarm mode (1.12+)
endpoint = "tcp://127.0.0.1:2377"
swarmMode = true
```
```bash tab="CLI"
# swarm classic (1.12-)
# --providers.docker.endpoint=tcp://127.0.0.1:2375
# docker swarm mode (1.12+)
--providers.docker.endpoint=tcp://127.0.0.1:2377
--providers.docker.swarmMode=true
```
Attach labels to services (not to containers) while in Swarm mode (in your docker compose file)
```yaml
version: "3"
services:
my-container:
deploy:
labels:
- traefik.http.routers.my-container.rule=Host(`example.com`)
- traefik.http.services.my-container-service.loadbalancer.server.port=8080
```
!!! important "Labels in Docker Swarm Mode"
While in Swarm Mode, Traefik uses labels found on services, not on individual containers.
Therefore, if you use a compose file with Swarm Mode, labels should be defined in the `deploy` part of your service.
This behavior is only enabled for docker-compose version 3+ ([Compose file reference](https://docs.docker.com/compose/compose-file/compose-file-v3/#labels-1)).
## Routing Configuration ## Routing Configuration
!!! info "Labels" !!! info "Labels"
@ -158,7 +161,7 @@ and the router automatically gets a rule defined by `defaultRule` (if no rule fo
--8<-- "content/routing/providers/service-by-label.md" --8<-- "content/routing/providers/service-by-label.md"
??? example "Automatic service assignment with labels" ??? example "Automatic assignment with one Service"
With labels in a compose file With labels in a compose file
@ -169,7 +172,7 @@ and the router automatically gets a rule defined by `defaultRule` (if no rule fo
- "traefik.http.services.myservice.loadbalancer.server.port=80" - "traefik.http.services.myservice.loadbalancer.server.port=80"
``` ```
??? example "Automatic service creation and assignment with labels" ??? example "Automatic service creation with one Router"
With labels in a compose file With labels in a compose file
@ -180,6 +183,18 @@ and the router automatically gets a rule defined by `defaultRule` (if no rule fo
- "traefik.http.routers.myproxy.rule=Host(`example.net`)" - "traefik.http.routers.myproxy.rule=Host(`example.net`)"
``` ```
??? example "Explicit definition with one Service"
With labels in a compose file
```yaml
labels:
- traefik.http.routers.www-router.rule=Host(`example-a.com`)
# Explicit link between the router and the service
- traefik.http.routers.www-router.service=www-service
- traefik.http.services.www-service.loadbalancer.server.port=8000
```
### Routers ### Routers
To update the configuration of the Router automatically attached to the container, To update the configuration of the Router automatically attached to the container,
@ -469,7 +484,7 @@ More information about available middlewares in the dedicated [middlewares secti
You can declare TCP Routers and/or Services using labels. You can declare TCP Routers and/or Services using labels.
??? example "Declaring TCP Routers and Services" ??? example "Declaring TCP Routers with one Service"
```yaml ```yaml
services: services:
@ -598,7 +613,7 @@ You can declare TCP Routers and/or Services using labels.
You can declare UDP Routers and/or Services using labels. You can declare UDP Routers and/or Services using labels.
??? example "Declaring UDP Routers and Services" ??? example "Declaring UDP Routers with one Service"
```yaml ```yaml
services: services:

2
go.mod
View file

@ -67,6 +67,7 @@ require (
github.com/vulcand/predicate v1.2.0 github.com/vulcand/predicate v1.2.0
go.elastic.co/apm/module/apmot/v2 v2.4.8 go.elastic.co/apm/module/apmot/v2 v2.4.8
go.elastic.co/apm/v2 v2.4.8 go.elastic.co/apm/v2 v2.4.8
golang.org/x/exp v0.0.0-20240506185415-9bf2ced13842 // No tag on the repo.
golang.org/x/mod v0.18.0 golang.org/x/mod v0.18.0
golang.org/x/net v0.26.0 golang.org/x/net v0.26.0
golang.org/x/text v0.16.0 golang.org/x/text v0.16.0
@ -326,7 +327,6 @@ require (
go4.org/intern v0.0.0-20230525184215-6c62f75575cb // indirect go4.org/intern v0.0.0-20230525184215-6c62f75575cb // indirect
go4.org/unsafe/assume-no-moving-gc v0.0.0-20230525183740-e7c30c78aeb2 // indirect go4.org/unsafe/assume-no-moving-gc v0.0.0-20230525183740-e7c30c78aeb2 // indirect
golang.org/x/crypto v0.24.0 // indirect golang.org/x/crypto v0.24.0 // indirect
golang.org/x/exp v0.0.0-20240506185415-9bf2ced13842 // indirect
golang.org/x/oauth2 v0.21.0 // indirect golang.org/x/oauth2 v0.21.0 // indirect
golang.org/x/sync v0.7.0 // indirect golang.org/x/sync v0.7.0 // indirect
golang.org/x/sys v0.21.0 // indirect golang.org/x/sys v0.21.0 // indirect

View file

@ -13,6 +13,7 @@ import (
"github.com/traefik/traefik/v2/pkg/config/dynamic" "github.com/traefik/traefik/v2/pkg/config/dynamic"
"github.com/traefik/traefik/v2/pkg/log" "github.com/traefik/traefik/v2/pkg/log"
"github.com/traefik/traefik/v2/pkg/tls" "github.com/traefik/traefik/v2/pkg/tls"
"golang.org/x/exp/maps"
) )
// Merge merges multiple configurations. // Merge merges multiple configurations.
@ -383,7 +384,7 @@ func BuildTCPRouterConfiguration(ctx context.Context, configuration *dynamic.TCP
if len(configuration.Services) > 1 { if len(configuration.Services) > 1 {
delete(configuration.Routers, routerName) delete(configuration.Routers, routerName)
loggerRouter. loggerRouter.
Error("Could not define the service name for the router: too many services") Errorf("Router %s cannot be linked automatically with multiple Services: %q", routerName, maps.Keys(configuration.Services))
continue continue
} }
@ -405,7 +406,7 @@ func BuildUDPRouterConfiguration(ctx context.Context, configuration *dynamic.UDP
if len(configuration.Services) > 1 { if len(configuration.Services) > 1 {
delete(configuration.Routers, routerName) delete(configuration.Routers, routerName)
loggerRouter. loggerRouter.
Error("Could not define the service name for the router: too many services") Errorf("Router %s cannot be linked automatically with multiple Services: %q", routerName, maps.Keys(configuration.Services))
continue continue
} }
@ -452,7 +453,7 @@ func BuildRouterConfiguration(ctx context.Context, configuration *dynamic.HTTPCo
if len(configuration.Services) > 1 { if len(configuration.Services) > 1 {
delete(configuration.Routers, routerName) delete(configuration.Routers, routerName)
loggerRouter. loggerRouter.
Error("Could not define the service name for the router: too many services") Errorf("Router %s cannot be linked automatically with multiple Services: %q", routerName, maps.Keys(configuration.Services))
continue continue
} }