Add consul catalog options: requireConsistent, stale, cache

docs/content/providers/consul-catalog.md

@@ -39,174 +39,125 @@ See the dedicated section in [routing](../routing/providers/consul-catalog.md).
 
 ## Provider Configuration
 
-### `exposedByDefault`
+### `refreshInterval`
 
-_Optional, Default=true_
+_Optional, Default=15s_
 
 ```toml tab="File (TOML)"
 [providers.consulCatalog]
-  exposedByDefault = false
+  refreshInterval = "30s"
   # ...
 ```
 
 ```yaml tab="File (YAML)"
 providers:
   consulCatalog:
-    exposedByDefault: false
+    refreshInterval: 30s
     # ...
 ```
 
 ```bash tab="CLI"
---providers.consulcatalog.exposedByDefault=false
+--providers.consulcatalog.refreshInterval=30s
 # ...
 ```
 
-Expose Consul Catalog services by default in Traefik.
-If set to false, services that don't have a `traefik.enable=true` label will be ignored from the resulting routing configuration.
-
-See also [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery).
+Defines the polling interval.
 
-### `defaultRule`
+### `prefix`
 
-_Optional, Default=```Host(`{{ normalize .Name }}`)```_
+_Optional, Default=/latest_
 
 ```toml tab="File (TOML)"
 [providers.consulCatalog]
-  defaultRule = "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
+  prefix = "/test"
   # ...
 ```
 
 ```yaml tab="File (YAML)"
 providers:
   consulCatalog:
-    defaultRule: "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
+    prefix: /test
     # ...
 ```
 
 ```bash tab="CLI"
---providers.consulcatalog.defaultRule="Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
+--providers.consulcatalog.prefix=/test
 # ...
 ```
 
-The default host rule for all services.
-
-For a given container if no routing rule was defined by a label, it is defined by this defaultRule instead.
-It must be a valid [Go template](https://golang.org/pkg/text/template/),
-augmented with the [sprig template functions](http://masterminds.github.io/sprig/).
-The service name can be accessed as the `Name` identifier,
-and the template has access to all the labels defined on this container.
-
-This option can be overridden on a container basis with the `traefik.http.routers.Router1.rule` label.
+Prefix used for accessing the Consul service metadata.
 
-### `refreshInterval`
+### `requireConsistent`
 
-_Optional, Default=15s_
+_Optional, Default=false_
 
 ```toml tab="File (TOML)"
 [providers.consulCatalog]
-  refreshInterval = "30s"
+  requireConsistent = true
   # ...
 ```
 
 ```yaml tab="File (YAML)"
 providers:
   consulCatalog:
-    refreshInterval: 30s
+    requireConsistent: true
     # ...
 ```
 
 ```bash tab="CLI"
---providers.consulcatalog.refreshInterval=30s
+--providers.consulcatalog.requireConsistent=true
 # ...
 ```
 
-Defines the polling interval.
+Forces the read to be fully consistent.
 
-### `prefix`
+### `stale`
 
-_Optional, Default=/latest_
+_Optional, Default=false_
 
 ```toml tab="File (TOML)"
 [providers.consulCatalog]
-  prefix = "/test"
+  stale = true
   # ...
 ```
 
 ```yaml tab="File (YAML)"
 providers:
   consulCatalog:
-    prefix: "/test"
+    stale: true
     # ...
 ```
 
 ```bash tab="CLI"
---providers.consulcatalog.prefix="/test"
+--providers.consulcatalog.stale=true
 # ...
 ```
 
-Prefix used for accessing the Consul service metadata.
+Use stale consistency for catalog reads.
 
-### `constraints`
+### `cache`
 
-_Optional, Default=""_
+_Optional, Default=false_
 
 ```toml tab="File (TOML)"
 [providers.consulCatalog]
-  constraints = "Label(`a.label.name`, `foo`)"
+  cache = true
   # ...
 ```
 
 ```yaml tab="File (YAML)"
 providers:
   consulCatalog:
-    constraints: "Label(`a.label.name`, `foo`)"
+    cache: true
     # ...
 ```
 
 ```bash tab="CLI"
---providers.consulcatalog.constraints="Label(`a.label.name`, `foo`)"
+--providers.consulcatalog.cache=true
 # ...
 ```
 
-Constraints is an expression that Traefik matches against the container's labels to determine whether to create any route for that container.
-That is to say, if none of the container's labels match the expression, no route for the container is created.
-If the expression is empty, all detected containers are included.
-
-The expression syntax is based on the `Label("key", "value")`, and `LabelRegex("key", "value")` functions, as well as the usual boolean logic, as shown in examples below.
-
-??? example "Constraints Expression Examples"
-
-    ```toml
-    # Includes only containers having a label with key `a.label.name` and value `foo`
-    constraints = "Label(`a.label.name`, `foo`)"
-    ```
-
-    ```toml
-    # Excludes containers having any label with key `a.label.name` and value `foo`
-    constraints = "!Label(`a.label.name`, `value`)"
-    ```
-
-    ```toml
-    # With logical AND.
-    constraints = "Label(`a.label.name`, `valueA`) && Label(`another.label.name`, `valueB`)"
-    ```
-
-    ```toml
-    # With logical OR.
-    constraints = "Label(`a.label.name`, `valueA`) || Label(`another.label.name`, `valueB`)"
-    ```
-
-    ```toml
-    # With logical AND and OR, with precedence set by parentheses.
-    constraints = "Label(`a.label.name`, `valueA`) && (Label(`another.label.name`, `valueB`) || Label(`yet.another.label.name`, `valueC`))"
-    ```
-
-    ```toml
-    # Includes only containers having a label with key `a.label.name` and a value matching the `a.+` regular expression.
-    constraints = "LabelRegex(`a.label.name`, `a.+`)"
-    ```
-
-See also [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery).
+Use local agent caching for catalog reads.
 
 ### `endpoint`
 
@@ -529,3 +480,124 @@ providers:
 ```
 
 If `insecureSkipVerify` is `true`, TLS for the connection to Consul server accepts any certificate presented by the server and any host name in that certificate.
+
+### `exposedByDefault`
+
+_Optional, Default=true_
+
+```toml tab="File (TOML)"
+[providers.consulCatalog]
+  exposedByDefault = false
+  # ...
+```
+
+```yaml tab="File (YAML)"
+providers:
+  consulCatalog:
+    exposedByDefault: false
+    # ...
+```
+
+```bash tab="CLI"
+--providers.consulcatalog.exposedByDefault=false
+# ...
+```
+
+Expose Consul Catalog services by default in Traefik.
+If set to false, services that don't have a `traefik.enable=true` label will be ignored from the resulting routing configuration.
+
+See also [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery).
+
+### `defaultRule`
+
+_Optional, Default=```Host(`{{ normalize .Name }}`)```_
+
+```toml tab="File (TOML)"
+[providers.consulCatalog]
+  defaultRule = "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
+  # ...
+```
+
+```yaml tab="File (YAML)"
+providers:
+  consulCatalog:
+    defaultRule: "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
+    # ...
+```
+
+```bash tab="CLI"
+--providers.consulcatalog.defaultRule="Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
+# ...
+```
+
+The default host rule for all services.
+
+For a given container if no routing rule was defined by a label, it is defined by this defaultRule instead.
+It must be a valid [Go template](https://golang.org/pkg/text/template/),
+augmented with the [sprig template functions](http://masterminds.github.io/sprig/).
+The service name can be accessed as the `Name` identifier,
+and the template has access to all the labels defined on this container.
+
+This option can be overridden on a container basis with the `traefik.http.routers.Router1.rule` label.
+
+### `constraints`
+
+_Optional, Default=""_
+
+```toml tab="File (TOML)"
+[providers.consulCatalog]
+  constraints = "Label(`a.label.name`, `foo`)"
+  # ...
+```
+
+```yaml tab="File (YAML)"
+providers:
+  consulCatalog:
+    constraints: "Label(`a.label.name`, `foo`)"
+    # ...
+```
+
+```bash tab="CLI"
+--providers.consulcatalog.constraints="Label(`a.label.name`, `foo`)"
+# ...
+```
+
+Constraints is an expression that Traefik matches against the container's labels to determine whether to create any route for that container.
+That is to say, if none of the container's labels match the expression, no route for the container is created.
+If the expression is empty, all detected containers are included.
+
+The expression syntax is based on the `Label("key", "value")`, and `LabelRegex("key", "value")` functions, as well as the usual boolean logic, as shown in examples below.
+
+??? example "Constraints Expression Examples"
+
+    ```toml
+    # Includes only containers having a label with key `a.label.name` and value `foo`
+    constraints = "Label(`a.label.name`, `foo`)"
+    ```
+
+    ```toml
+    # Excludes containers having any label with key `a.label.name` and value `foo`
+    constraints = "!Label(`a.label.name`, `value`)"
+    ```
+
+    ```toml
+    # With logical AND.
+    constraints = "Label(`a.label.name`, `valueA`) && Label(`another.label.name`, `valueB`)"
+    ```
+
+    ```toml
+    # With logical OR.
+    constraints = "Label(`a.label.name`, `valueA`) || Label(`another.label.name`, `valueB`)"
+    ```
+
+    ```toml
+    # With logical AND and OR, with precedence set by parentheses.
+    constraints = "Label(`a.label.name`, `valueA`) && (Label(`another.label.name`, `valueB`) || Label(`yet.another.label.name`, `valueC`))"
+    ```
+
+    ```toml
+    # Includes only containers having a label with key `a.label.name` and a value matching the `a.+` regular expression.
+    constraints = "LabelRegex(`a.label.name`, `a.+`)"
+    ```
+
+See also [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery).

docs/content/reference/static-configuration/cli-ref.md

@@ -234,6 +234,9 @@ Enable ping. (Default: ```false```)
 `--ping.entrypoint`:  
 EntryPoint (Default: ```traefik```)
 
+`--providers.consulcatalog.cache`:  
+Use local agent caching for catalog reads. (Default: ```false```)
+
 `--providers.consulcatalog.constraints`:  
 Constraints is an expression that Traefik matches against the container's labels to determine whether to create any route for that container.
 
@@ -285,6 +288,12 @@ Prefix for consul service tags. Default 'traefik' (Default: ```traefik```)
 `--providers.consulcatalog.refreshinterval`:  
 Interval for check Consul API. Default 100ms (Default: ```15```)
 
+`--providers.consulcatalog.requireconsistent`:  
+Forces the read to be fully consistent. (Default: ```false```)
+
+`--providers.consulcatalog.stale`:  
+Use stale consistency for catalog reads. (Default: ```false```)
+
 `--providers.docker`:  
 Enable Docker backend with default settings. (Default: ```false```)
 

docs/content/reference/static-configuration/env-ref.md

@@ -234,6 +234,9 @@ Enable ping. (Default: ```false```)
 `TRAEFIK_PING_ENTRYPOINT`:  
 EntryPoint (Default: ```traefik```)
 
+`TRAEFIK_PROVIDERS_CONSULCATALOG_CACHE`:  
+Use local agent caching for catalog reads. (Default: ```false```)
+
 `TRAEFIK_PROVIDERS_CONSULCATALOG_CONSTRAINTS`:  
 Constraints is an expression that Traefik matches against the container's labels to determine whether to create any route for that container.
 
@@ -285,6 +288,12 @@ Prefix for consul service tags. Default 'traefik' (Default: ```traefik```)
 `TRAEFIK_PROVIDERS_CONSULCATALOG_REFRESHINTERVAL`:  
 Interval for check Consul API. Default 100ms (Default: ```15```)
 
+`TRAEFIK_PROVIDERS_CONSULCATALOG_REQUIRECONSISTENT`:  
+Forces the read to be fully consistent. (Default: ```false```)
+
+`TRAEFIK_PROVIDERS_CONSULCATALOG_STALE`:  
+Use stale consistency for catalog reads. (Default: ```false```)
+
 `TRAEFIK_PROVIDERS_DOCKER`:  
 Enable Docker backend with default settings. (Default: ```false```)
 

docs/content/reference/static-configuration/file.toml

@@ -114,6 +114,9 @@
     defaultRule = "foobar"
     exposedByDefault = true
     refreshInterval = 15
+    requireConsistent = true
+    stale = true
+    cache = true
     [providers.consulCatalog.endpoint]
      address = "foobar"
      scheme = "foobar"

docs/content/reference/static-configuration/file.yaml

@@ -121,6 +121,9 @@ providers:
     defaultRule: foobar
     exposedByDefault: true
     refreshInterval: 15
+    requireConsistent: true
+    stale: true
+    cache: true
     endpoint:
       address: foobar
       scheme: foobar