Consul Catalog Enterprise

The consulCatalogEnterprise provider enables Traefik Hub API Gateway to integrate with Consul Enterprise, leveraging advanced features like partitions and multi-namespace support. This provider extends the capabilities of the standard Consul Catalog provider by allowing you to specify partitions and automatically discover services across all namespaces within those partitions.

info

If both consulCatalog and consulCatalogEnterprise providers are configured, only the consulCatalogEnterprise provider will be used.

Configuration Example

To use the consulCatalogEnterprise provider, you need to enable & configure it.

Below is an example of how to enable & configure the provider:

Static Configuration

hub:
  providers:
    consulCatalogEnterprise:
      endpoint:
        address: "127.0.0.1:8500"
      partition: "myPartition"

Configuration Options

Field	Description	Default	Required
`hub.providers.consulCatalogEnterprise.cache`	Instruct Traefik Hub to use local agent caching for catalog reads.	false	No
`hub.providers.consulCatalogEnterprise.connectAware`	Enable Consul Catalog Enterprise Connect support. If set to `true`, Traefik will be enabled to communicate with Connect services.	false	No
`hub.providers.consulCatalogEnterprise.connectByDefault`	If set to true, Traefik will consider every Consul Catalog service to be Connect capable by default.	false	No
`hub.providers.consulCatalogEnterprise.constraints`	Defines an expression that Traefik matches against the container labels to determine whether to create any route for that container. See Constraints for more information.	""	No
`hub.providers.consulCatalogEnterprise.defaultRule`	The Default Host rule for all services. See Default Rule for more information	"Host(`{{ normalize .Name }}`)"	No
`hub.providers.consulCatalogEnterprise.namespaces`	Defines the namespaces to query. See Namespaces for more information	default	No
`hub.providers.consulCatalogEnterprise.endpoint`	Defines the Consul Catalaog Enterprise server endpoint.	""	Yes
`hub.providers.consulCatalogEnterprise.endpoint.address`	Defines the address of the Consul server.	127.0.0.1:8500	No
`hub.providers.consulCatalogEnterprise.endpoint.scheme`	Defines the URI scheme for the Consul server.	""	No
`hub.providers.consulCatalogEnterprise.endpoint.datacenter`	Defines the datacenter to use. If not provided in Traefik, Consul uses the default agent datacenter.	""	No
`hub.providers.consulCatalogEnterprise.endpoint.token`	Defines a per-request ACL token which overwrites the agent's default token.	""	No
`hub.providers.consulCatalogEnterprise.endpoint.endpointWaitTime`	Defines a duration for which a `watch` can block. If not provided, the agent default values will be used.	""	No
`hub.providers.consulCatalogEnterprise.endpoint.httpAuth`	Defines authentication settings for the HTTP client using HTTP Basic Authentication.	""	No
`hub.providers.consulCatalogEnterprise.endpoint.httpAuth.username`	Defines the username to use for HTTP Basic Authentication.	""	No
`hub.providers.consulCatalogEnterprise.endpoint.httpAuth.password`	Defines the password to use for HTTP Basic Authentication.	""	No
`hub.providers.consulCatalogEnterprise.exposedByDefault`	Expose Consul Catalog Enterprise services by default in Traefik. If set to `false`, services that do not have a `traefik.enable=true` tag will be ignored.	true	No
`hub.providers.consulCatalogEnterprise.partition`	Defines the partition used to discover services. See Partition for more information.	""	No
`hub.providers.consulCatalogEnterprise.prefix`	Defines the prefix for Consul Catalog Enterprise tags defining Traefik labels.	traefik	Yes
`hub.providers.consulCatalogEnterprise.refreshInterval`	Defines the polling interval.	15s	No
`hub.providers.consulCatalogEnterprise.requireConsistent`	Forces the read to be fully consistent. See here for more information.	false	Yes
`hub.providers.consulCatalogEnterprise.serviceName`	Defines the name of the Traefik service in Consul Catalog Enterprise.	"traefik"	No
`hub.providers.consulCatalogEnterprise.stale`	Instruct Traefik Hub to use stale consistency for catalog reads.	false	No
`hub.providers.consulCatalogEnterprise.strictChecks`	Define which Consul Service health checks are allowed to take on traffic.	"passing,warning"	no
`hub.providers.consulCatalogEnterprise.tls`	Defines the TLS configuration used for the secure connection to Consul Calatog Enterprise	N/A	No
`hub.providers.consulCatalogEnterprise.tls.ca`	Defines the path to the certificate authority used for the secure connection to Consul Calatog Enterprise, it defaults to the system bundle.	""	No
`hub.providers.consulCatalogEnterprise.tls.cert`	Defines the path to the public certificate used for the secure connection to Consul Calatog Enterprise. When using this option, setting the `key` option is required.	""	Yes
`hub.providers.consulCatalogEnterprise.tls.key`	Defines the path to the private key used for the secure connection to Consul Catalog Enterprise. When using this option, setting the `cert` option is required.	""	Yes
`hub.providers.consulCatalogEnterprise.tls.insecureSkipVerify`	Instructs the provider to accept any certificate presented by Consul Catalog Enterprise when establishing a TLS connection, regardless of the hostnames the certificate covers.	false	No
`hub.providers.consulCatalogEnterprise.watch`	When set to `true`, watches for Consul changes (Consul watches checks).	false	No

constraints

The constraints option can be set to an expression that Traefik Hub matches against the service tags to determine whether to create any route for that service. If none of the service tags match the expression, no route for that service is created. If the expression is empty, all detected services are included.

The expression syntax is based on the Tag(`tag`), and TagRegex(`tag`) functions, as well as the usual boolean logic, as shown in examples below.

Constraints Expression Examples

# Includes only services having the tag `a.tag.name=foo`
constraints = "Tag(`a.tag.name=foo`)"

# Excludes services having any tag `a.tag.name=foo`
constraints = "!Tag(`a.tag.name=foo`)"

# With logical AND.
constraints = "Tag(`a.tag.name`) && Tag(`another.tag.name`)"

# With logical OR.
constraints = "Tag(`a.tag.name`) || Tag(`another.tag.name`)"

# With logical AND and OR, with precedence set by parentheses.
constraints = "Tag(`a.tag.name`) && (Tag(`another.tag.name`) || Tag(`yet.another.tag.name`))"

# Includes only services having a tag matching the `a\.tag\.t.+` regular expression.
constraints = "TagRegex(`a\.tag\.t.+`)"

defaultRule

The default host rule for all services.

For a given service, if no routing rule was defined by a tag, it is defined by this defaultRule instead. The defaultRule must be set to a valid Go template, and can include sprig template functions. The service name can be accessed with the Name identifier, and the template has access to all the labels (i.e. tags beginning with the prefix) defined on this service.

The option can be overridden on an instance basis with the traefik.http.routers.{name-of-your-choice}.rule tag.

Default rule and Traefik service

The exposure of the Traefik container, combined with the default rule mechanism, can lead to create a router targeting itself in a loop. In this case, to prevent an infinite loop, Traefik adds an internal middleware to refuse the request if it comes from the same router.

requireConsistent

Forces the read to be fully consistent. Setting this option can be expensive due to an extra round-trip but it prevents a stale read.

For more information, see the Consul documentation on consistency.

namespaces

The namespaces option defines the namespaces in which the consul catalog services will be discovered. When using the namespaces option, the discovered configuration object names will be suffixed as shown below:

<resource-name>@consulCatalogEnterprise-<namespace>

If the namespaces option is not set, the provider will discover services from all namespaces. This behavior differs from the Traefik proxy Consul Catalog provider, where the default is to use only the default namespace.

warning

One should only define either the namespaces or the namespace option.

info

The default behavior of discovering all namespaces is implicit and does not require additional configuration.
This behavior is consistent even when using the partition option; all namespaces within the specified partition will be discovered unless explicitly restricted.
If you need to limit the discovery to specific namespaces, you should set the namespaces option with the list of namespaces you want to include.

Static Configuration

File (YAML)
hub:
  providers:
    consulCatalogEnterprise:
      namespaces:
        - "ns1"
        - "ns2"
      # ...

partition

The partition option defines the Consul Enterprise partition used to discover services. This allows Traefik to interact with services within a specific partition, enabling better isolation and organization of services in large-scale environments.

Configuration example

Create a Partition in Consul Catalog Enterprise
Service Definition
Register the Service

curl -X PUT -d '{"Name":"production"}' http://127.0.0.1:8500/v1/partition

my-service.json
{
  "id": "my-service",
  "name": "my-service",
  "partition": "production",
  "tags": [
    "traefik.enable=true",
    "traefik.http.routers.my-service.rule=Host(`my-service.example.com`)
  ],
  "address": "my-service-address",
  "port": 80,
  "check": {
    "http": "http://my-service-address/health",
    "interval": "10s"
  }
}

curl -X PUT -d @my-service.json http://127.0.0.1:8500/v1/agent/service/register

Additional Notes

Ensure that the Consul agent is correctly configured to work with partitions and namespaces.
Be aware that discovering all namespaces may have performance implications in large Consul deployments.
When using the consulCatalogEnterprise provider, service discovery and routing are handled within the specified partition and namespaces, providing better isolation and control in enterprise environments.

Configuration Example​

Configuration Options​

constraints​

defaultRule​

requireConsistent​

namespaces​

partition​

Configuration example​

Additional Notes​