From 287fb78654f6086b87ce4030074d2d6680204706 Mon Sep 17 00:00:00 2001 From: Ludovic Fernandez Date: Thu, 4 Jan 2018 14:48:03 +0100 Subject: [PATCH] Split Consul and Consul Catalog documentation --- docs/configuration/backends/consul.md | 98 +------------------- docs/configuration/backends/consulcatalog.md | 93 +++++++++++++++++++ docs/user-guide/kv-config.md | 13 +-- mkdocs.yml | 1 + 4 files changed, 102 insertions(+), 103 deletions(-) create mode 100644 docs/configuration/backends/consulcatalog.md diff --git a/docs/configuration/backends/consul.md b/docs/configuration/backends/consul.md index e59d6ca18..086ea874a 100644 --- a/docs/configuration/backends/consul.md +++ b/docs/configuration/backends/consul.md @@ -1,6 +1,4 @@ -# Consul Backend - -## Consul Key-Value backend +# Consul Key-Value backend Træfik can be configured to use Consul as a backend configuration. @@ -61,97 +59,3 @@ prefix = "traefik" To enable constraints see [backend-specific constraints section](/configuration/commons/#backend-specific). Please refer to the [Key Value storage structure](/user-guide/kv-config/#key-value-storage-structure) section to get documentation on Traefik KV structure. - -## Consul Catalog backend - -Træfik can be configured to use service discovery catalog of Consul as a backend configuration. - -```toml -################################################################ -# Consul Catalog configuration backend -################################################################ - -# Enable Consul Catalog configuration backend. -[consulCatalog] - -# Consul server endpoint. -# -# Required -# Default: "127.0.0.1:8500" -# -endpoint = "127.0.0.1:8500" - -# Expose Consul catalog services by default in Traefik. -# -# Optional -# Default: true -# -exposedByDefault = false - -# Default domain used. -# -# Optional -# -domain = "consul.localhost" - -# Prefix for Consul catalog tags. -# -# Optional -# Default: "traefik" -# -prefix = "traefik" - -# Default frontEnd Rule for Consul services. -# -# The format is a Go Template with: -# - ".ServiceName", ".Domain" and ".Attributes" available -# - "getTag(name, tags, defaultValue)", "hasTag(name, tags)" and "getAttribute(name, tags, defaultValue)" functions are available -# - "getAttribute(...)" function uses prefixed tag names based on "prefix" value -# -# Optional -# Default: "Host:{{.ServiceName}}.{{.Domain}}" -# -#frontEndRule = "Host:{{.ServiceName}}.{{Domain}}" -``` - -This backend will create routes matching on hostname based on the service name used in Consul. - -To enable constraints see [backend-specific constraints section](/configuration/commons/#backend-specific). - -### Tags - -Additional settings can be defined using Consul Catalog tags. - -| Tag | Description | -|-----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `traefik.enable=false` | Disable this container in Træfik | -| `traefik.protocol=https` | Override the default `http` protocol | -| `traefik.backend.weight=10` | Assign this weight to the container | -| `traefik.backend.circuitbreaker=EXPR` | Create a [circuit breaker](/basics/#backends) to be used against the backend, ex: `NetworkErrorRatio() > 0.` | -| `traefik.backend.maxconn.amount=10` | Set a maximum number of connections to the backend. Must be used in conjunction with the below label to take effect. | -| `traefik.backend.maxconn.extractorfunc=client.ip` | Set the function to be used against the request to determine what to limit maximum connections to the backend by. Must be used in conjunction with the above label to take effect. | -| `traefik.frontend.rule=Host:test.traefik.io` | Override the default frontend rule (Default: `Host:{{.ServiceName}}.{{.Domain}}`). | -| `traefik.frontend.passHostHeader=true` | Forward client `Host` header to the backend. | -| `traefik.frontend.priority=10` | Override default frontend priority | -| `traefik.frontend.entryPoints=http,https` | Assign this frontend to entry points `http` and `https`. Overrides `defaultEntryPoints`. | -| `traefik.frontend.auth.basic=EXPR` | Sets basic authentication for that frontend in CSV format: `User:Hash,User:Hash` | -| `traefik.backend.loadbalancer=drr` | override the default `wrr` load balancer algorithm | -| `traefik.backend.loadbalancer.stickiness=true` | enable backend sticky sessions | -| `traefik.backend.loadbalancer.stickiness.cookieName=NAME` | Manually set the cookie name for sticky sessions | -| `traefik.backend.loadbalancer.sticky=true` | enable backend sticky sessions (DEPRECATED) | - -### Examples - -If you want that Træfik uses Consul tags correctly you need to defined them like that: -```json -traefik.enable=true -traefik.tags=api -traefik.tags=external -``` - -If the prefix defined in Træfik configuration is `bla`, tags need to be defined like that: -```json -bla.enable=true -bla.tags=api -bla.tags=external -``` \ No newline at end of file diff --git a/docs/configuration/backends/consulcatalog.md b/docs/configuration/backends/consulcatalog.md new file mode 100644 index 000000000..b528946c2 --- /dev/null +++ b/docs/configuration/backends/consulcatalog.md @@ -0,0 +1,93 @@ +# Consul Catalog backend + +Træfik can be configured to use service discovery catalog of Consul as a backend configuration. + +```toml +################################################################ +# Consul Catalog configuration backend +################################################################ + +# Enable Consul Catalog configuration backend. +[consulCatalog] + +# Consul server endpoint. +# +# Required +# Default: "127.0.0.1:8500" +# +endpoint = "127.0.0.1:8500" + +# Expose Consul catalog services by default in Traefik. +# +# Optional +# Default: true +# +exposedByDefault = false + +# Default domain used. +# +# Optional +# +domain = "consul.localhost" + +# Prefix for Consul catalog tags. +# +# Optional +# Default: "traefik" +# +prefix = "traefik" + +# Default frontEnd Rule for Consul services. +# +# The format is a Go Template with: +# - ".ServiceName", ".Domain" and ".Attributes" available +# - "getTag(name, tags, defaultValue)", "hasTag(name, tags)" and "getAttribute(name, tags, defaultValue)" functions are available +# - "getAttribute(...)" function uses prefixed tag names based on "prefix" value +# +# Optional +# Default: "Host:{{.ServiceName}}.{{.Domain}}" +# +#frontEndRule = "Host:{{.ServiceName}}.{{.Domain}}" +``` + +This backend will create routes matching on hostname based on the service name used in Consul. + +To enable constraints see [backend-specific constraints section](/configuration/commons/#backend-specific). + +### Tags + +Additional settings can be defined using Consul Catalog tags. + +| Tag | Description | +|-----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `traefik.enable=false` | Disable this container in Træfik | +| `traefik.protocol=https` | Override the default `http` protocol | +| `traefik.backend.weight=10` | Assign this weight to the container | +| `traefik.backend.circuitbreaker=EXPR` | Create a [circuit breaker](/basics/#backends) to be used against the backend, ex: `NetworkErrorRatio() > 0.` | +| `traefik.backend.maxconn.amount=10` | Set a maximum number of connections to the backend. Must be used in conjunction with the below label to take effect. | +| `traefik.backend.maxconn.extractorfunc=client.ip` | Set the function to be used against the request to determine what to limit maximum connections to the backend by. Must be used in conjunction with the above label to take effect. | +| `traefik.frontend.rule=Host:test.traefik.io` | Override the default frontend rule (Default: `Host:{{.ServiceName}}.{{.Domain}}`). | +| `traefik.frontend.passHostHeader=true` | Forward client `Host` header to the backend. | +| `traefik.frontend.priority=10` | Override default frontend priority | +| `traefik.frontend.entryPoints=http,https` | Assign this frontend to entry points `http` and `https`. Overrides `defaultEntryPoints`. | +| `traefik.frontend.auth.basic=EXPR` | Sets basic authentication for that frontend in CSV format: `User:Hash,User:Hash` | +| `traefik.backend.loadbalancer=drr` | override the default `wrr` load balancer algorithm | +| `traefik.backend.loadbalancer.stickiness=true` | enable backend sticky sessions | +| `traefik.backend.loadbalancer.stickiness.cookieName=NAME` | Manually set the cookie name for sticky sessions | +| `traefik.backend.loadbalancer.sticky=true` | enable backend sticky sessions (DEPRECATED) | + +### Examples + +If you want that Træfik uses Consul tags correctly you need to defined them like that: +```json +traefik.enable=true +traefik.tags=api +traefik.tags=external +``` + +If the prefix defined in Træfik configuration is `bla`, tags need to be defined like that: +```json +bla.enable=true +bla.tags=api +bla.tags=external +``` \ No newline at end of file diff --git a/docs/user-guide/kv-config.md b/docs/user-guide/kv-config.md index dc1542a74..995e50ed2 100644 --- a/docs/user-guide/kv-config.md +++ b/docs/user-guide/kv-config.md @@ -111,7 +111,7 @@ And there, the same global configuration in the Key-value Store (using `prefix = | `/traefik/entrypoints/https/tls/certificates/0/keyfile` | `integration/fixtures/https/snitest.com.key` | | `/traefik/entrypoints/https/tls/certificates/1/certfile` | `--BEGIN CERTIFICATE----END CERTIFICATE--` | | `/traefik/entrypoints/https/tls/certificates/1/keyfile` | `--BEGIN CERTIFICATE----END CERTIFICATE--` | -| `/traefik/entrypoints/other-https/address` | `:4443` +| `/traefik/entrypoints/other-https/address` | `:4443` | | `/traefik/consul/endpoint` | `127.0.0.1:8500` | | `/traefik/consul/watch` | `true` | | `/traefik/consul/prefix` | `traefik` | @@ -341,9 +341,10 @@ And there, the same dynamic configuration in a KV Store (using `prefix = "traefi | Key | Value | |----------------------------------------------------|-----------------------| -| `/traefik/tlsconfiguration/2/entrypoints` | `https,other-https` | +| `/traefik/tlsconfiguration/2/entrypoints` | `https,other-https` | | `/traefik/tlsconfiguration/2/certificate/certfile` | `` | | `/traefik/tlsconfiguration/2/certificate/certfile` | `` | + ### Atomic configuration changes Træfik can watch the backends/frontends configuration changes and generate its configuration automatically. @@ -378,9 +379,9 @@ Here, although the `/traefik_configurations/2/...` keys have been set, the old c | `/traefik_configurations/1/backends/backend1/servers/server1/url` | `http://172.17.0.2:80` | | `/traefik_configurations/1/backends/backend1/servers/server1/weight` | `10` | | `/traefik_configurations/2/backends/backend1/servers/server1/url` | `http://172.17.0.2:80` | -| `/traefik_configurations/2/backends/backend1/servers/server1/weight` | `5` | +| `/traefik_configurations/2/backends/backend1/servers/server1/weight` | `5` | | `/traefik_configurations/2/backends/backend1/servers/server2/url` | `http://172.17.0.3:80` | -| `/traefik_configurations/2/backends/backend1/servers/server2/weight` | `5` | +| `/traefik_configurations/2/backends/backend1/servers/server2/weight` | `5` | Once the `/traefik/alias` key is updated, the new `/traefik_configurations/2` configuration becomes active atomically. @@ -392,9 +393,9 @@ Here, we have a 50% balance between the `http://172.17.0.3:80` and the `http://1 | `/traefik_configurations/1/backends/backend1/servers/server1/url` | `http://172.17.0.2:80` | | `/traefik_configurations/1/backends/backend1/servers/server1/weight` | `10` | | `/traefik_configurations/2/backends/backend1/servers/server1/url` | `http://172.17.0.3:80` | -| `/traefik_configurations/2/backends/backend1/servers/server1/weight` | `5` | +| `/traefik_configurations/2/backends/backend1/servers/server1/weight` | `5` | | `/traefik_configurations/2/backends/backend1/servers/server2/url` | `http://172.17.0.4:80` | -| `/traefik_configurations/2/backends/backend1/servers/server2/weight` | `5` | +| `/traefik_configurations/2/backends/backend1/servers/server2/weight` | `5` | !!! note Træfik *will not watch for key changes in the `/traefik_configurations` prefix*. It will only watch for changes in the `/traefik/alias`. diff --git a/mkdocs.yml b/mkdocs.yml index c354faeea..a66bf22b5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -71,6 +71,7 @@ pages: - 'Backend: Web': 'configuration/backends/web.md' - 'Backend: BoltDB': 'configuration/backends/boltdb.md' - 'Backend: Consul': 'configuration/backends/consul.md' + - 'Backend: Consul Catalog': 'configuration/backends/consulcatalog.md' - 'Backend: Docker': 'configuration/backends/docker.md' - 'Backend: DynamoDB': 'configuration/backends/dynamodb.md' - 'Backend: ECS': 'configuration/backends/ecs.md'