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.8/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml # Install RBAC for Traefik: kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.8/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 Field Description Default Required providers.providersThrottleDuration Minimum amount of time to wait for, after a configuration reload, before taking into account any new configuration refresh event. If multiple events occur within this time, only the most recent one is taken into account, and all others are discarded. This option cannot be set per provider, but the throttling algorithm applies to each of them independently. 2s No providers.kubernetesCRD.endpoint Server endpoint URL. More information here. "" No providers.kubernetesCRD.token Bearer token used for the Kubernetes client configuration (not needed for in-cluster client). It accepts either a token value or a file path to the token. "" No providers.kubernetesCRD.certAuthFilePath Path to the certificate authority file. Used for the Kubernetes client configuration. "" No providers.kubernetesCRD.namespaces Array of namespaces to watch. If left empty, watch all namespaces. [] No providers.kubernetesCRD.labelSelector Allow filtering on specific resource objects only using label selectors. Only to Traefik Custom Resources (they all must match the filter). No effect on Kubernetes Secrets, EndpointSlices and Services. See label-selectors for details. "" No providers.kubernetesCRD.ingressClass Value of spec.ingressClassName field (or the deprecated kubernetes.io/ingress.class annotation) that identifies resource objects to be processed. If empty, resources missing the field/annotation, having an empty value, or the value traefik are processed. The spec.ingressClassName field takes precedence over the annotation. "" No providers.kubernetesCRD.throttleDuration Minimum amount of time to wait between two Kubernetes events before producing a new configuration. This prevents a Kubernetes cluster that updates many times per second from continuously changing your Traefik configuration. If empty, every event is caught. 0s No providers.kubernetesCRD.allowEmptyServices Allows creating a route to reach a service that has no endpoint available. It allows Traefik to handle the requests and responses targeting this service (applying middleware or observability operations) before returning a 503 HTTP Status. false No providers.kubernetesCRD.allowCrossNamespace Allows the IngressRoutes to reference resources in namespaces other than theirs. false No providers.kubernetesCRD.allowExternalNameServices Allows the IngressRoutes to reference ExternalName services. false No providers.kubernetesCRD.crossProviderNamespaces List of namespaces from which IngressRoute, IngressRouteTCP, IngressRouteUDP, and TraefikService are allowed to declare cross-provider references (e.g. myservice@file). When unset, all namespaces are allowed. When set to [], every cross-provider reference is rejected. [] No providers.kubernetesCRD.nativeLBByDefault Allow using the Kubernetes Service load balancing between the pods instead of the one provided by Traefik for every IngressRoute by default. It can be overridden in the Service. false No providers.kubernetesCRD.disableClusterScopeResources Prevent from discovering cluster scope resources ( IngressClass and Nodes). By doing so, it alleviates the requirement of giving Traefik the rights to look up for cluster resources. Furthermore, Traefik will not handle IngressRoutes with IngressClass references, therefore such Ingresses will be ignored (please note that annotations are not affected by this option). This will also prevent from using the NodePortLB options on services. false No providers.kubernetesCRD.defaultTLSResourcesNamespace Restricts the namespace in which the TLSOption and the TLSStore named default can be defined. More information here. "" No providers.kubernetesCRD.safeNaming Enables collision-safe naming for the routers, middlewares and services generated by the provider. When unset, the legacy naming scheme is used and a warning is logged on startup. More information here. false No 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. Value Behavior not set Current naming is used (default, backward compatible), and a warning is logged on startup. true Collision-safe naming is used. false Current naming is used, and the startup warning is silenced. !!! 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. !!! warning "Cross-provider references" The generated names are also the ones the other providers reference. When `safeNaming` is enabled, a namespaced `@kubernetescrd` reference, such as the `traefik.ingress.kubernetes.io/router.middlewares` annotation on an Ingress, must be of form `namespace_name@kubernetescrd` instead of `namespace-name@kubernetescrd`. A reference left in the legacy form is not resolved, and the routers using it are not created. For a TLS options reference, the TLS handshake is refused on the host names served by those routers. 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: Resource Purpose IngressRoute HTTP Routing Middleware Tweaks the HTTP requests before they are sent to your service TraefikService Abstraction for HTTP loadbalancing/mirroring TLSOptions Allows configuring some parameters of the TLS connection TLSStores Allows configuring the default TLS store ServersTransport Allows configuring the transport between Traefik and the backends IngressRouteTCP TCP Routing MiddlewareTCP Tweaks the TCP requests before they are sent to your service ServersTransportTCP Allows configuring the transport between Traefik and the backends IngressRouteUDP UDP Routing 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" %}