Kubernetes Routers - Ingress
Kubernetes provides the Ingress
objects that allow exposing the Kubernetes service.
Traefik Hub API Gateway provides annotations to customize the routing.
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
- Middleware
- TLSOption
- Secret
- Service & Deployment
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
# All resources definition must be declared
# Prefixing with /foo
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: middleware1
namespace: apps
spec:
addPrefix:
prefix: /foo
apiVersion: traefik.io/v1alpha1
kind: TLSOption
metadata:
name: opt
namespace: apps
spec:
minVersion: VersionTLS12
apiVersion: v1
kind: Secret
metadata:
name: supersecret
namespace: apps
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=
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 , PathPrefix or 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 toPath
Prefix
: This path type forces the rule matcher toPathPrefix
Please see this documentation for more information.
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.
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.