Kubernetes Custom Resources

Traefik provides some Kubernetes Custom Resources, such as IngressRoute, Middleware, etc.

When using KubernetesCRD as a provider, Traefik uses Custom Resource Definition to retrieve its routing configuration. Traefik Custom Resource Definitions are listed below.

When Traefik is installed using the Helm Chart, by default, the provider kubernetesCRD is enabled.

Requirements

When you install Traefik without using the Helm Chart, or when you are upgrading the stack using Helm, ensure that you satisfy the following requirements:

• Add/update all the Traefik resources definitions
• Add/update the RBAC for the Traefik custom resources

# Install Traefik Resource Definitions:
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.7/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

# Install RBAC for Traefik:
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.7/docs/content/reference/dynamic-configuration/kubernetes-crd-rbac.yml

Configuration Example

You can enable the kubernetesCRD provider as detailed below:

providers:
  kubernetesCRD: {}

[providers.kubernetesCRD]

--providers.kubernetescrd=true

## Values file
providers:
  kubernetesCRD:
    enabled: true

Configuration Options

endpoint

The Kubernetes server endpoint URL.

When deployed into Kubernetes, Traefik reads the environment variables KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT or KUBECONFIG to construct the endpoint.

The access token is looked up in /var/run/secrets/kubernetes.io/serviceaccount/token and the SSL CA certificate in /var/run/secrets/kubernetes.io/serviceaccount/ca.crt. Both are mounted automatically when deployed inside Kubernetes.

The endpoint may be specified to override the environment variable values inside a cluster.

When the environment variables are not found, Traefik tries to connect to the Kubernetes API server with an external-cluster client. In this case, the endpoint is required. Specifically, it may be set to the URL used by kubectl proxy to connect to a Kubernetes cluster using the granted authentication and authorization of the associated kubeconfig.

providers:
  kubernetesCRD:
    endpoint: "http://localhost:8080"
    # ...

[providers.kubernetesCRD]
  endpoint = "http://localhost:8080"
  # ...

--providers.kubernetesCRD.endpoint=http://localhost:8080

defaultTLSResourcesNamespace

The TLSOption and the TLSStore named default are cluster-wide, whatever the namespace they are defined in: the former holds the TLS enforcement policy of every router that does not reference a TLSOption explicitly, the latter holds the default certificate served by every entry point. This option allows the cluster operator to reserve their definition to a namespace they control.

When the option is not set, a TLSOption or a TLSStore named default is taken into account whatever its namespace, which is the default and backward compatible behavior. When it is set to a namespace, only the resources named default in this namespace are taken into account.

!!! warning "Ignored resources"

A `TLSOption` or a `TLSStore` named `default` defined outside of the configured namespace is ignored,
and cannot be referenced under its namespaced name either.
For a `TLSStore`, this also applies to the certificates it defines.

providers:
  kubernetesCRD:
    defaultTLSResourcesNamespace: traefik
    # ...

[providers.kubernetesCRD]
  defaultTLSResourcesNamespace = "traefik"
  # ...

--providers.kubernetesCRD.defaultTLSResourcesNamespace=traefik

safeNaming

By default, the Kubernetes CRD provider generates the names of the routers, middlewares and services it builds by joining the namespace and the name of the object they come from, which can produce the same name for two distinct objects, one silently replacing the other.

safeNaming enables collision-safe naming instead: generated names are derived from the identity of the object they come from, and Kubernetes Services referenced from several parents (a route with several services, or a Weighted/Mirroring/HighestRandomWeight TraefikService) are scoped to their parent instead of being shared by identity.

!!! warning "Startup warning"

When `safeNaming` is left unset, a warning is logged on startup, since the current naming scheme is collision-prone.
It is recommended to explicitly set this option, to `true` on new setups, or to `false` to keep the current
behavior and silence the warning.

When safeNaming is enabled, the generated names are no longer normalized: their components are joined with a _ separator, which cannot appear in a Kubernetes namespace or name, and the ones generated for a route are derived from the route index instead of its rule. For example, for a Kubernetes Service named whoami and an IngressRoute named test.route, both in the default namespace:

default-whoami-80                          ->    default_whoami_80
default-test-route-6b204d94623b3df4370c    ->    default_test.route_0

The services generated for the Kubernetes Services referenced by a TraefikService (weighted, mirroring or highest random weight), or by a route with several services, are named after the parent declaring the reference, followed by the index of the reference, and the namespace, the name and the port of the referenced Kubernetes Service:

default-whoami-80    ->    default_wrr1_wrr_1_default_whoami_80

Each of these references carries its own options (serversTransport, scheme, sticky, healthCheck, ...), which were not part of the generated name before: two references to the same Kubernetes Service with different options were collapsed into a single service, and the last one built silently won. With safeNaming enabled, they are distinct services, which also means that the servers of a Kubernetes Service referenced from several parents are health checked once per reference, instead of once for all of them.

!!! warning "Observability"

These names are user-visible: they appear in the dashboard and API, in the access logs `RouterName` and `ServiceName` fields,
and in the `router` and `service` labels of the metrics.
Dashboards, alerting rules, and log queries that match on Kubernetes CRD router, middleware or service names must be updated accordingly
when `safeNaming` is enabled.

providers:
  kubernetesCRD:
    safeNaming: true
    # ...

[providers.kubernetesCRD]
  safeNaming = true
  # ...

--providers.kubernetesCRD.safeNaming=true

Routing Configuration

Traefik CRDs are building blocks that you can assemble according to your needs.

The available custom resources are in the table below:

Particularities

• The usage of name and namespace to refer to another Kubernetes resource.
• The usage of secret for sensitive data (TLS certificates and credentials).

Full Example

For additional information on exposing services with Kubernetes, refer to the Kubernetes guide.

{% include-markdown "includes/traefik-for-business-applications.md" %}