Skip to main content

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

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

Annotations

AnnotationDescriptionDefaultRequiredExample
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.
0No10
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.
falseNotrue
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.