IngressRoute

IngressRoute is the CRD implementation of a Traefik HTTP router.

Before creating IngressRoute objects, you need to apply the Traefik Kubernetes CRDs to your Kubernetes cluster.

This registers the IngressRoute kind and other Traefik-specific resources.

Configuration Example¶

You can declare an IngressRoute as detailed below:

IngressRoute

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: test-name
  namespace: apps

spec:
  entryPoints:
    - web
  routes:
  - kind: Rule
    # Rule on the Host
    match: Host(`test.example.com`)
    # Attach a middleware
    middlewares:
    - name: middleware1
      namespace: apps
    # Enable Router observability
    observability:
      accessLogs: true
      metrics: true
      tracing: true
    # Set a pirority
    priority: 10
    services:
    # Target a Kubernetes Support
    - kind: Service
      name: foo
      namespace: apps
      # Customize the connection between Traefik and the backend
      passHostHeader: true
      port: 80
      responseForwarding:
        flushInterval: 1ms
      scheme: https
      sticky:
        cookie:
          httpOnly: true
          name: cookie
          secure: true
      strategy: RoundRobin
      weight: 10
  tls:
    # Generate a TLS certificate using a certificate resolver
    certResolver: foo
    domains:
    - main: example.net
      sans:
      - a.example.net
      - b.example.net
    # Customize the TLS options
    options:
      name: opt
      namespace: apps
    # Add a TLS certificate from a Kubernetes Secret
    secretName: supersecret

Configuration Options¶

Field	Description	Default	Required
`entryPoints`	List of entry points names. If not specified, HTTP routers will accept requests from all EntryPoints in the list of default EntryPoints.		No
`routes`	List of routes.		Yes
`routes[n].kind`	Kind of router matching, only `Rule` is allowed yet.	"Rule"	No
`routes[n].match`	Defines the rule corresponding to an underlying router.		Yes
`routes[n].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
`routes[n].middlewares`	List of middlewares to attach to the IngressRoute. More information here.	""	No
`routes[n].` `middlewares[m].` `name`	Middleware name. The character `@` is not authorized. More information here.		Yes
`routes[n].` `middlewares[m].` `namespace`	Middleware namespace. Can be empty if the middleware belongs to the same namespace as the IngressRoute. More information here.		No
`routes[n].` `observability.` `accesslogs`	Defines whether the route will produce access-logs. See here for more information.	false	No
`routes[n].` `observability.` `metrics`	Defines whether the route will produce metrics. See here for more information.	false	No
`routes[n].` `observability.` `tracing`	Defines whether the route will produce traces. See here for more information.	false	No
`tls`	TLS configuration. Can be an empty value(`{}`): A self signed is generated in such a case (or the default certificate is used if it is defined.)		No
`routes[n].` `services`	List of any combination of TraefikService and Kubernetes service. Exhaustive list of option in the `Service` documentation.		No
`tls.secretName`	Secret name used to store the certificate (in the same namesapce as the `IngressRoute`)	""	No
`tls.` `options.name`	Name of the `TLSOption` to use. More information here.	""	No
`tls.` `options.namespace`	Namespace of the `TLSOption` to use.	""	No
`tls.certResolver`	Name of the Certificate Resolver to use to generate automatic TLS certificates.	""	No
`tls.domains`	List of domains to serve using the certificates generates (one `tls.domain`= one certificate). More information in the dedicated section.		No
`tls.` `domains[n].main`	Main domain name	""	Yes
`tls.` `domains[n].sans`	List of alternative domains (SANs)		No

Middleware¶

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.
In Kubernetes, the option middleware allow you to attach a middleware using its name and namespace (the namespace can be omitted when the Middleware is in the same namespace as the IngressRoute)

IngressRoute attached to a few middlewares

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-app
  namespace: apps

spec:
  entryPoints:
    - websecure
  routes:
  - match: Host(`example.com`)
    kind: Rule
    middlewares:
    # same namespace as the IngressRoute
    - name: middleware01
    # default namespace
    - name: middleware02
      namespace: apps
    # Other namespace
    - name: middleware03
      namespace: other-ns
    services:
    - name: whoami
      port: 80

routes.services.kind

As the field name can reference different types of objects, use the field kind to avoid any ambiguity. The field kind allows the following values:

Service (default value): to reference a Kubernetes Service
TraefikService: to reference an object TraefikService

TLS Options¶

The options field enables fine-grained control of the TLS parameters. It refers to a TLSOption and will be applied only if a Host rule is defined.

Server Name Association¶

A TLS options reference is always mapped to the host name found in the Host part of the rule, but neither to a router nor a router rule. There could also be several Host parts in a rule. In such a case the TLS options reference would be mapped to as many host names.

A TLS option is picked from the mapping mentioned above and based on the server name provided during the TLS handshake, and it all happens before routing actually occurs.

In the case of domain fronting, if the TLS options associated with the Host Header and the SNI are different then Traefik will respond with a status code 421.

Conflicting TLS Options¶

Since a TLS options reference is mapped to a host name, if a configuration introduces a situation where the same host name (from a Host rule) gets matched with two TLS options references, a conflict occurs, such as in the example below.

Example

IngressRoute01

  apiVersion: traefik.io/v1alpha1
  kind: IngressRoute
  metadata:
    name: IngressRoute01
    namespace: apps

  spec:
    entryPoints:
      - foo
    routes:
    - match: Host(`example.net`)
      kind: Rule
    tls:
      options: foo
      ...

IngressRoute02

  apiVersion: traefik.io/v1alpha1
  kind: IngressRoute
  metadata:
    name: IngressRoute02
    namespace: apps

  spec:
    entryPoints:
      - foo
    routes:
    - match: Host(`example.net`)
      kind: Rule
    tls:
      options: bar
    ...

If that happens, both mappings are discarded, and the host name (example.net in the example) for these routers gets associated with the default TLS options instead.