From f790b9aa546ba449218a929d3fcac5df3875bf53 Mon Sep 17 00:00:00 2001 From: Robert Baker <51850403+robertbaker@users.noreply.github.com> Date: Mon, 28 Oct 2019 07:50:06 -0700 Subject: [PATCH] Add example for changing the port used by traefik to connect to a service --- docs/content/routing/providers/docker.md | 187 ++++++++++-------- .../routing/services/.markdownlint.json | 3 +- docs/content/routing/services/index.md | 64 +++--- 3 files changed, 139 insertions(+), 115 deletions(-) diff --git a/docs/content/routing/providers/docker.md b/docs/content/routing/providers/docker.md index 9fc796b87..f81d0daaa 100644 --- a/docs/content/routing/providers/docker.md +++ b/docs/content/routing/providers/docker.md @@ -12,16 +12,16 @@ Attach labels to your containers and let Traefik do the rest! ??? example "Configuring Docker & Deploying / Exposing Services" Enabling the docker provider - + ```toml tab="File (TOML)" [providers.docker] ``` - + ```yaml tab="File (YAML)" providers: docker: {} ``` - + ```bash tab="CLI" --providers.docker=true ``` @@ -37,6 +37,27 @@ Attach labels to your containers and let Traefik do the rest! - traefik.http.routers.my-container.rule=Host(`mydomain.com`) ``` +??? example "Specify a Custom Port for the Container" + + Forward requests for `http://mydomain.com` to `http://:12345`: + + ```yaml + version: "3" + services: + my-container: + # ... + labels: + - traefik.http.routers.my-container.rule=Host(`mydomain.com`) + # Tell Traefik to use the port 12345 to connect to `my-container` + - traefik.http.services.my-service.loadbalancer.server.port=12345 + ``` + + !!! important "Traefik Connecting to the Wrong Port: `HTTP/502 Gateway Error`" + By default, Traefik uses the first exposed port of a container. + + Setting the label `raefik.http.services.xxx.loadbalancer.server.port` + overrides that behavior. + ??? example "Configuring Docker Swarm & Deploying / Exposing Services" Enabling the docker provider (Swarm Mode) @@ -49,7 +70,7 @@ Attach labels to your containers and let Traefik do the rest! endpoint = "tcp://127.0.0.1:2377" swarmMode = true ``` - + ```yaml tab="File (YAML)" providers: docker: @@ -59,7 +80,7 @@ Attach labels to your containers and let Traefik do the rest! endpoint: "tcp://127.0.0.1:2375" swarmMode: true ``` - + ```bash tab="CLI" --providers.docker.endpoint="tcp://127.0.0.1:2375" --providers.docker.swarmMode=true @@ -85,7 +106,7 @@ Attach labels to your containers and let Traefik do the rest! ## Routing Configuration !!! info "Labels" - + - Labels are case insensitive. - The complete list of labels can be found in [the reference page](../../reference/dynamic-configuration/docker.md). @@ -132,81 +153,81 @@ For example, to change the rule, you could add the label ```traefik.http.routers !!! warning "The character `@` is not authorized in the router name ``." ??? info "`traefik.http.routers..rule`" - - See [rule](../routers/index.md#rule) for more information. - + + See [rule](../routers/index.md#rule) for more information. + ```yaml - "traefik.http.routers.myrouter.rule=Host(`mydomain.com`)" ``` ??? info "`traefik.http.routers..entrypoints`" - - See [entry points](../routers/index.md#entrypoints) for more information. - + + See [entry points](../routers/index.md#entrypoints) for more information. + ```yaml - "traefik.http.routers.myrouter.entrypoints=web,websecure" ``` ??? info "`traefik.http.routers..middlewares`" - - See [middlewares](../routers/index.md#middlewares) and [middlewares overview](../../middlewares/overview.md) for more information. - + + See [middlewares](../routers/index.md#middlewares) and [middlewares overview](../../middlewares/overview.md) for more information. + ```yaml - "traefik.http.routers.myrouter.middlewares=auth,prefix,cb" ``` ??? info "`traefik.http.routers..service`" - - See [rule](../routers/index.md#service) for more information. - + + See [rule](../routers/index.md#service) for more information. + ```yaml - "traefik.http.routers.myrouter.service=myservice" ``` ??? info "`traefik.http.routers..tls`" - + See [tls](../routers/index.md#tls) for more information. - + ```yaml - "traefik.http.routers.myrouter.tls=true" ``` ??? info "`traefik.http.routers..tls.certresolver`" - + See [certResolver](../routers/index.md#certresolver) for more information. - + ```yaml - "traefik.http.routers.myrouter.tls.certresolver=myresolver" ``` ??? info "`traefik.http.routers..tls.domains[n].main`" - + See [domains](../routers/index.md#domains) for more information. - + ```yaml - "traefik.http.routers.myrouter.tls.domains[0].main=foobar.com" ``` ??? info "`traefik.http.routers..tls.domains[n].sans`" - + See [domains](../routers/index.md#domains) for more information. - + ```yaml - "traefik.http.routers.myrouter.tls.domains[0].sans=test.foobar.com,dev.foobar.com" ``` ??? info "`traefik.http.routers..tls.options`" - + See [options](../routers/index.md#options) for more information. - + ```yaml - "traefik.http.routers.myrouter.tls.options=foobar" ``` ??? info "`traefik.http.routers..priority`" - + See [options](../routers/index.md#priority) for more information. - + ```yaml - "traefik.http.routers.myrouter.priority=42" ``` @@ -222,124 +243,124 @@ you'd add the label `traefik.http.services..loadbalancer.pa !!! warning "The character `@` is not authorized in the service name ``." ??? info "`traefik.http.services..loadbalancer.server.port`" - + Registers a port. Useful when the container exposes multiples ports. - + Mandatory for Docker Swarm. - + ```yaml - "traefik.http.services.myservice.loadbalancer.server.port=8080" ``` ??? info "`traefik.http.services..loadbalancer.server.scheme`" - + Overrides the default scheme. - + ```yaml - "traefik.http.services.myservice.loadbalancer.server.scheme=http" ``` ??? info "`traefik.http.services..loadbalancer.passhostheader`" - + See [pass Host header](../services/index.md#pass-host-header) for more information. - + ```yaml - "traefik.http.services.myservice.loadbalancer.passhostheader=true" ``` ??? info "`traefik.http.services..loadbalancer.healthcheck.headers.`" - + See [health check](../services/index.md#health-check) for more information. - + ```yaml - "traefik.http.services.myservice.loadbalancer.healthcheck.headers.X-Foo=foobar" ``` ??? info "`traefik.http.services..loadbalancer.healthcheck.hostname`" - + See [health check](../services/index.md#health-check) for more information. - + ```yaml - "traefik.http.services.myservice.loadbalancer.healthcheck.hostname=foobar.com" ``` ??? info "`traefik.http.services..loadbalancer.healthcheck.interval`" - + See [health check](../services/index.md#health-check) for more information. - + ```yaml - "traefik.http.services.myservice.loadbalancer.healthcheck.interval=10" ``` ??? info "`traefik.http.services..loadbalancer.healthcheck.path`" - + See [health check](../services/index.md#health-check) for more information. - + ```yaml - "traefik.http.services.myservice.loadbalancer.healthcheck.path=/foo" ``` ??? info "`traefik.http.services..loadbalancer.healthcheck.port`" - + See [health check](../services/index.md#health-check) for more information. - + ```yaml - "traefik.http.services.myservice.loadbalancer.healthcheck.port=42" ``` ??? info "`traefik.http.services..loadbalancer.healthcheck.scheme`" - + See [health check](../services/index.md#health-check) for more information. - + ```yaml - "traefik.http.services.myservice.loadbalancer.healthcheck.scheme=http" ``` ??? info "`traefik.http.services..loadbalancer.healthcheck.timeout`" - + See [health check](../services/index.md#health-check) for more information. - + ```yaml - "traefik.http.services.myservice.loadbalancer.healthcheck.timeout=10" ``` ??? info "`traefik.http.services..loadbalancer.sticky`" - + See [sticky sessions](../services/index.md#sticky-sessions) for more information. - + ```yaml - "traefik.http.services.myservice.loadbalancer.sticky=true" ``` ??? info "`traefik.http.services..loadbalancer.sticky.cookie.httponly`" - + See [sticky sessions](../services/index.md#sticky-sessions) for more information. - + ```yaml - "traefik.http.services.myservice.loadbalancer.sticky.cookie.httponly=true" ``` ??? info "`traefik.http.services..loadbalancer.sticky.cookie.name`" - + See [sticky sessions](../services/index.md#sticky-sessions) for more information. - + ```yaml - "traefik.http.services.myservice.loadbalancer.sticky.cookie.name=foobar" ``` ??? info "`traefik.http.services..loadbalancer.sticky.cookie.secure`" - + See [sticky sessions](../services/index.md#sticky-sessions) for more information. - + ```yaml - "traefik.http.services.myservice.loadbalancer.sticky.cookie.secure=true" ``` ??? info "`traefik.http.services..loadbalancer.responseforwarding.flushinterval`" - + See [response forwarding](../services/index.md#response-forwarding) for more information. - + ```yaml - "traefik.http.services.myservice.loadbalancer.responseforwarding.flushinterval=10" ``` @@ -397,73 +418,73 @@ You can declare TCP Routers and/or Services using labels. #### TCP Routers ??? info "`traefik.tcp.routers..entrypoints`" - + See [entry points](../routers/index.md#entrypoints_1) for more information. - + ```yaml - "traefik.tcp.routers.mytcprouter.entrypoints=ep1,ep2" ``` ??? info "`traefik.tcp.routers..rule`" - + See [rule](../routers/index.md#rule_1) for more information. - + ```yaml - "traefik.tcp.routers.mytcprouter.rule=HostSNI(`myhost.com`)" ``` ??? info "`traefik.tcp.routers..service`" - + See [service](../routers/index.md#services) for more information. - + ```yaml - "traefik.tcp.routers.mytcprouter.service=myservice" ``` ??? info "`traefik.tcp.routers..tls`" - + See [TLS](../routers/index.md#tls_1) for more information. - + ```yaml - "traefik.tcp.routers.mytcprouter.tls=true" ``` ??? info "`traefik.tcp.routers..tls.certresolver`" - + See [certResolver](../routers/index.md#certresolver_1) for more information. - + ```yaml - "traefik.tcp.routers.mytcprouter.tls.certresolver=myresolver" ``` ??? info "`traefik.tcp.routers..tls.domains[n].main`" - + See [domains](../routers/index.md#domains_1) for more information. - + ```yaml - "traefik.tcp.routers.mytcprouter.tls.domains[0].main=foobar.com" ``` ??? info "`traefik.tcp.routers..tls.domains[n].sans`" - + See [domains](../routers/index.md#domains_1) for more information. - + ```yaml - "traefik.tcp.routers.mytcprouter.tls.domains[0].sans=test.foobar.com,dev.foobar.com" ``` ??? info "`traefik.tcp.routers..tls.options`" - + See [options](../routers/index.md#options_1) for more information. - + ```yaml - "traefik.tcp.routers.mytcprouter.tls.options=mysoptions" ``` ??? info "`traefik.tcp.routers..tls.passthrough`" - + See [TLS](../routers/index.md#tls_1) for more information. - + ```yaml - "traefik.tcp.routers.mytcprouter.tls.passthrough=true" ``` @@ -471,17 +492,17 @@ You can declare TCP Routers and/or Services using labels. #### TCP Services ??? info "`traefik.tcp.services..loadbalancer.server.port`" - + Registers a port of the application. - + ```yaml - "traefik.tcp.services.mytcpservice.loadbalancer.server.port=423" ``` ??? info "`traefik.tcp.services..loadbalancer.terminationdelay`" - + See [termination delay](../services/index.md#termination-delay) for more information. - + ```yaml - "traefik.tcp.services.mytcpservice.loadbalancer.terminationdelay=100" ``` diff --git a/docs/content/routing/services/.markdownlint.json b/docs/content/routing/services/.markdownlint.json index e803880c0..dd98ee65a 100644 --- a/docs/content/routing/services/.markdownlint.json +++ b/docs/content/routing/services/.markdownlint.json @@ -1,4 +1,5 @@ { "extends": "../../../.markdownlint.json", - "MD024": false + "MD024": false, + "MD046": false } diff --git a/docs/content/routing/services/index.md b/docs/content/routing/services/index.md index 212754fe0..0b582918d 100644 --- a/docs/content/routing/services/index.md +++ b/docs/content/routing/services/index.md @@ -5,9 +5,9 @@ Configuring How to Reach the Services ![services](../../assets/img/services.png) -The `Services` are responsible for configuring how to reach the actual services that will eventually handle the incoming requests. +The `Services` are responsible for configuring how to reach the actual services that will eventually handle the incoming requests. -## Configuration Example +## Configuration Examples ??? example "Declaring an HTTP Service with Two Servers -- Using the [File Provider](../../providers/file.md)" @@ -17,11 +17,11 @@ The `Services` are responsible for configuring how to reach the actual services [http.services.my-service.loadBalancer] [[http.services.my-service.loadBalancer.servers]] - url = "http://private-ip-server-1/" + url = "http://:/" [[http.services.my-service.loadBalancer.servers]] - url = "http://private-ip-server-2/" + url = "http://:/" ``` - + ```yaml tab="YAML" ## Dynamic configuration http: @@ -29,8 +29,8 @@ The `Services` are responsible for configuring how to reach the actual services my-service: loadBalancer: servers: - - url: "http://private-ip-server-1/" - - url: "http://private-ip-server-2/" + - url: "http://:/" + - url: "http://:/" ``` ??? example "Declaring a TCP Service with Two Servers -- Using the [File Provider](../../providers/file.md)" @@ -40,26 +40,28 @@ The `Services` are responsible for configuring how to reach the actual services [tcp.services] [tcp.services.my-service.loadBalancer] [[tcp.services.my-service.loadBalancer.servers]] - address = "xx.xx.xx.xx:xx" + address = ":" [[tcp.services.my-service.loadBalancer.servers]] - address = "xx.xx.xx.xx:xx" + address = ":" ``` - + ```yaml tab="YAML" tcp: services: my-service: - loadBalancer: + loadBalancer: servers: - - address: "xx.xx.xx.xx:xx" - - address: "xx.xx.xx.xx:xx" + - address: ":" + - address: ":" ``` ## Configuring HTTP Services ### Servers Load Balancer -The load balancers are able to load balance the requests between multiple instances of your programs. +The load balancers are able to load balance the requests between multiple instances of your programs. + +Each service has a load-balancer, even if there is only one server to forward traffic to. ??? example "Declaring a Service with Two Servers (with Load Balancing) -- Using the [File Provider](../../providers/file.md)" @@ -87,10 +89,10 @@ The load balancers are able to load balance the requests between multiple instan #### Servers Servers declare a single instance of your program. -The `url` option point to a specific instance. +The `url` option point to a specific instance. !!! info "" - Paths in the servers' `url` have no effect. + Paths in the servers' `url` have no effect. If you want the requests to be sent to a specific path on your servers, configure your [`routers`](../routers/index.md) to use a corresponding [middleware](../../middlewares/overview.md) (e.g. the [AddPrefix](../../middlewares/addprefix.md) or [ReplacePath](../../middlewares/replacepath.md)) middlewares. @@ -103,7 +105,7 @@ The `url` option point to a specific instance. [[http.services.my-service.loadBalancer.servers]] url = "http://private-ip-server-1/" ``` - + ```yaml tab="YAML" ## Dynamic configuration http: @@ -142,21 +144,21 @@ For now, only round robin load balancing is supported: ``` #### Sticky sessions - + When sticky sessions are enabled, a cookie is set on the initial request to track which server handles the first response. On subsequent requests, the client is forwarded to the same server. !!! info "Stickiness & Unhealthy Servers" - + If the server specified in the cookie becomes unhealthy, the request will be forwarded to a new server (and the cookie will keep track of the new server). -!!! info "Cookie Name" - +!!! info "Cookie Name" + The default cookie name is an abbreviation of a sha1 (ex: `_1d52e`). !!! info "Secure & HTTPOnly flags" - By default, the affinity cookie is created without those flags. One however can change that through configuration. + By default, the affinity cookie is created without those flags. One however can change that through configuration. ??? example "Adding Stickiness -- Using the [File Provider](../../providers/file.md)" @@ -166,7 +168,7 @@ On subsequent requests, the client is forwarded to the same server. [http.services.my-service] [http.services.my-service.loadBalancer.sticky.cookie] ``` - + ```yaml tab="YAML" ## Dynamic configuration http: @@ -223,8 +225,8 @@ Below are the available options for the health check mechanism: The interval must be greater than the timeout. If configuration doesn't reflect this, the interval will be set to timeout + 1 second. !!! info "Recovering Servers" - - Traefik keeps monitoring the health of unhealthy servers. + + Traefik keeps monitoring the health of unhealthy servers. If a server has recovered (returning `2xx` -> `3xx` responses again), it will be added back to the load balacer rotation pool. ??? example "Custom Interval & Timeout -- Using the [File Provider](../../providers/file.md)" @@ -261,7 +263,7 @@ Below are the available options for the health check mechanism: path = "/health" port = 8080 ``` - + ```yaml tab="YAML" ## Dynamic configuration http: @@ -283,7 +285,7 @@ Below are the available options for the health check mechanism: path = "/health" scheme = "http" ``` - + ```yaml tab="YAML" ## Dynamic configuration http: @@ -308,7 +310,7 @@ Below are the available options for the health check mechanism: My-Custom-Header = "foo" My-Header = "bar" ``` - + ```yaml tab="YAML" ## Dynamic configuration http: @@ -337,7 +339,7 @@ By default, `passHostHeader` is true. [http.services.Service01.loadBalancer] passHostHeader = false ``` - + ```yaml tab="YAML" ## Dynamic configuration http: @@ -358,7 +360,7 @@ Below are the available options for the Response Forwarding mechanism: A negative value means to flush immediately after each write to the client. The FlushInterval is ignored when ReverseProxy recognizes a response as a streaming response; for such responses, writes are flushed to the client immediately. - + ??? example "Using a custom FlushInterval -- Using the [File Provider](../../providers/file.md)" ```toml tab="TOML" @@ -368,7 +370,7 @@ Below are the available options for the Response Forwarding mechanism: [http.services.Service-1.loadBalancer.responseForwarding] flushInterval = "1s" ``` - + ```yaml tab="YAML" ## Dynamic configuration http: