traefik/docs/content/providers/kubernetes-crd.md

Traefik & Kubernetes

The Kubernetes Ingress Controller, The Custom Resource Way. {: .subtitle }

The Traefik Kubernetes provider used to be a Kubernetes Ingress controller in the strict sense of the term; that is to say, it would manage access to a cluster services by supporting the Ingress specification.

However, as the community expressed the need to benefit from Traefik features without resorting to (lots of) annotations, we ended up writing a Custom Resource Definition (alias CRD in the following) for an IngressRoute type, defined below, in order to provide a better way to configure access to a Kubernetes cluster.

Provider Configuration

endpoint

Optional, Default=empty

The Kubernetes server endpoint as URL.

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

The access token will be 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 provided 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 will try 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
--providers.kubernetescrd.endpoint="http://localhost:8080"

token

Optional, Default=empty

Bearer token used for the Kubernetes client configuration.

[Providers.KubernetesCRD]
  token = "mytoken"
  # ...

--providers.kubernetescrd
--providers.kubernetescrd.token="mytoken"

certAuthFilePath

Optional, Default=empty

Path to the certificate authority file. Used for the Kubernetes client configuration.

[Providers.KubernetesCRD]
  certAuthFilePath = "/my/ca.crt"
  # ...

--providers.kubernetescrd
--providers.kubernetescrd.certauthfilepath="/my/ca.crt"

namespaces

Optional, Default: all namespaces (empty array)

Array of namespaces to watch.

[Providers.KubernetesCRD]
  namespaces = ["default", "production"]
  # ...

--providers.kubernetescrd
--providers.kubernetescrd.namespaces="default,production"

labelselector

Optional,Default: empty (process all Ingresses)

By default, Traefik processes all Ingress objects in the configured namespaces. A label selector can be defined to filter on specific Ingress objects only.

See label-selectors for details.

[Providers.KubernetesCRD]
  labelselector = "A and not B"
  # ...

--providers.kubernetescrd
--providers.kubernetescrd.labelselector="A and not B"

ingressClass

Optional, Default: empty

Value of kubernetes.io/ingress.class annotation that identifies Ingress objects to be processed.

If the parameter is non-empty, only Ingresses containing an annotation with the same value are processed. Otherwise, Ingresses missing the annotation, having an empty value, or the value traefik are processed.

[Providers.KubernetesCRD]
  ingressClass = "traefik-internal"
  # ...

--providers.kubernetescrd
--providers.kubernetescrd.ingressclass="traefik-internal"

Resource Configuration

If you're in a hurry, maybe you'd rather go through the dynamic configuration reference.

Traefik IngressRoute definition

--8<-- "content/providers/crd_ingress_route.yml"

That IngressRoute kind can then be used to define an IngressRoute object, such as:

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: ingressroutefoo.crd

spec:
  entryPoints:
    - web
  routes:
  # Match is the rule corresponding to an underlying router.
  # Later on, match could be the simple form of a path prefix, e.g. just "/bar",
  # but for now we only support a traefik style matching rule.
  - match: Host(`foo.com`) && PathPrefix(`/bar`)
    # kind could eventually be one of "Rule", "Path", "Host", "Method", "Header",
    # "Parameter", etc, to support simpler forms of rule matching, but for now we
    # only support "Rule".
    kind: Rule
    # Priority disambiguates rules of the same length, for route matching.
    priority: 12
    services:
    - name: whoami
      port: 80

Middleware

Additionally, to allow for the use of middlewares in an IngressRoute, we defined the CRD below for the Middleware kind.

--8<-- "content/providers/crd_middlewares.yml"

Once the Middleware kind has been registered with the Kubernetes cluster, it can then be used in IngressRoute definitions, such as:

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: stripprefix

spec:
  stripPrefix:
    prefixes:
      - /stripit

---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: ingressroutebar.crd

spec:
  entryPoints:
    - web
  routes:
  - match: Host(`bar.com`) && PathPrefix(`/stripit`)
    kind: Rule
    services:
    - name: whoami
      port: 80
    middlewares:
    - name: stripprefix

More information about available middlewares in the dedicated middlewares section.

TLS

To allow for TLS, we made use of the Secret kind, as it was already defined, and it can be directly used in an IngressRoute:

apiVersion: v1
kind: Secret
metadata:
  name: supersecret

data:
  tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
  tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=

---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: ingressroutetls.crd

spec:
  entryPoints:
    - web
  routes:
  - match: Host(`foo.com`) && PathPrefix(`/bar`)
    kind: Rule
    services:
    - name: whoami
      port: 443
  tls:
    secretName: supersecret

Further

Also see the full example with Let's Encrypt.