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

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.