Kubernetes Routers - Ingress

Kubernetes provides the Ingress objects that allow exposing the Kubernetes service.

Traefik Hub API Gateway provides annotations to customize the routing.

"Annotations or IngressRoute?"

The Ingress and Service objects are limited and force using annotations. For such a reason, we have created our own CRD IngressRoute that eases the configuration.

Even if you can use Ingress and Service objects, we recommend to use the IngressRoute to expose your APIs through Traefik Hub API Gateway.

Configuration Example

Ingress

YAML

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: whoami
  namespace: apps
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.priority: "42"
    traefik.ingress.kubernetes.io/router.middlewares: apps-middleware1@kubernetescrd
    traefik.ingress.kubernetes.io/router.tls: "true"
    traefik.ingress.kubernetes.io/router.tls.options: apps-opt@kubernetescrd
spec:
  rules:
    - host: my-domain.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name:  whoami
                namespace: apps
                port:
                  number: 80
  tls:
  - secretName: supersecret

Middleware

  # All resources definition must be declared
  # Prefixing with /foo
  apiVersion: traefik.io/v1alpha1
  kind: Middleware
  metadata:
    name: middleware1
    namespace: apps
  spec:
    addPrefix:
      prefix: /foo

TLSOption

  apiVersion: traefik.io/v1alpha1
  kind: TLSOption
  metadata:
    name: opt
    namespace: apps
  spec:
    minVersion: VersionTLS12

Secret

  apiVersion: v1
  kind: Secret
  metadata:
    name: supersecret
    namespace: apps
  data:
    tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
    tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=

Service & Deployment

kind: Deployment
apiVersion: apps/v1
metadata:
  name: whoami
  namespace: apps
spec:
  replicas: 3
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
      - name: whoami
        image: traefik/whoami

---
apiVersion: v1
kind: Service
metadata:
  name: whoami
  namespace: apps
spec:
  ports:
  - port: 80
    name: whoami
  selector:
    app: whoami

Annotations

Annotation	Description	Default	Required	Example
traefik.ingress.kubernetes.io/ router.entrypoints	List of entry points names. If not specified, HTTP routers will accept requests from all EntryPoints in the list of default EntryPoints.	""	No	"web,websecure"
traefik.ingress.kubernetes.io/ router.pathmatcher	Overrides the default router rule type used for a path. Only path-related matcher name can be specified: Path, PathPrefixor PathRegexp. More information here.	"PathPrefix"	No	"Path"
traefik.ingress.kubernetes.io/ router.priority	Defines the priority to disambiguate rules of the same length, for route matching. If not set, the priority is directly equal to the length of the rule, and so the longest length has the highest priority. A value of 0 for the priority is ignored, the default rules length sorting is used.	0	No	10
traefik.ingress.kubernetes.io/ router.middlewares	List of middlewares to attach to the Ingress. Format: <middleware-namespace>-<middleware-name>@<providername>. More information here.	""	No	"apps-middleware1@kubernetescrd"
traefik.ingress.kubernetes.io/ router.tls	Force TLS connection for this Ingress. A certificate can be provided using the tls option or generated using a certificate resolver defined with the annotation traefik.ingress.kubernetes.io/ router.tls.certresolver.	false	No	true
traefik.ingress.kubernetes.io/ router.tls options	Name of the TLSOption to use. Format: <tlsoptionnamespace>-<tlsoptionname>@providername.	""	No	"apps-mintls12@kubernetescrd"
traefik.ingress.kubernetes.io/ router.tls. certresolver	Name of the Certificate Resolver to use to generate automatic TLS certificates.	""	No	"myresolver"
traefik.ingress.kubernetes.io/ router.tls. domains.n.main More information in the dedicated section.	Main domain name	""	No	"example.com"
traefik.ingress.kubernetes.io/ router.tls. domains.n.sans	List of alternative domains (SANs). More information in the dedicated section.		No	"test.example.org,dev.example.org"

Path Types

Since Kubernetes cluster v1.18, the pathType property can be leveraged to define the rules matchers:

• Exact: This path type forces the rule matcher to Path
• Prefix: This path type forces the rule matcher to PathPrefix

Please see this documentation for more information.

"Multiple Matches"

In the case of multiple matches, Traefik will not ensure the priority of a Path matcher over a PathPrefix matcher, as stated in this documentation.

Middlewares

• You can attach a list of middlewares to each HTTP router.

• The middlewares will take effect only if the rule matches, and before forwarding the request to the service.

• Middlewares are applied in the same order as their declaration in router.

• The annotation traefik.ingress.kubernetes.io/router.middlewares allows attaching a list of middleware using the format <middlewarenamespace>-<middlewarename>@<providername> as described in the example below:

  # Attach the middleware auth defined using the File provier and the middleware default-prefix defined using a Kubernetes CRD
  traefik.ingress.kubernetes.io/router.middlewares: auth@file,default-prefix@kubernetescrd

Global Default Backend Ingresses

An Ingress can be created that look like the following:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: cheese
  namespace: apps
spec:
  defaultBackend:
    service:
      name: stilton
      port:
        number: 80

This ingress follows the Global Default Backend property of ingresses. This will allow users to create a "default router" that will match all unmatched requests.

note

Due to Traefik's use of priorities, you may have to set this ingress priority lower than other ingresses in your environment, to avoid this global ingress from satisfying requests that could match other ingresses.

To do this, use the traefik.ingress.kubernetes.io/router.priority annotation (as seen in Annotations on Ingress) on your ingresses accordingly.