Kubernetes CRD Provider

Use Traefik Custom Resource Definitions (CRD) for advanced Kubernetes routing with IngressRoute, Middleware, and more.

Kubernetes CRD Provider

The Kubernetes Ingress Controller, The Custom Resource Way

The Traefik team developed Custom Resource Definitions (CRDs) to provide access to all Traefik features through native Kubernetes resources, going beyond the limitations of the standard Ingress resource.

Why Use CRDs?

The Kubernetes Ingress resource is limited to basic HTTP routing. Traefik CRDs unlock:

✅ TCP and UDP routing
✅ Native middleware support
✅ Advanced routing rules
✅ TLS options and configurations
✅ Type-safe Kubernetes resources
✅ No annotation overload

Quick Start

1. Install CRDs and RBAC

   # Install Traefik CRDs
   kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml
   
   # Install RBAC
   kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/reference/dynamic-configuration/kubernetes-crd-rbac.yml
   
2. Enable Provider

   Static Config

   providers:
     kubernetesCRD:
       enabled: true
   
3. Create IngressRoute

   apiVersion: traefik.io/v1alpha1
   kind: IngressRoute
   metadata:
     name: my-app
     namespace: default
   spec:
     entryPoints:
       - websecure
     routes:
       - match: Host(`app.example.com`)
         kind: Rule
         services:
           - name: my-app
             port: 80
     tls:
       certResolver: letsencrypt
   

Available Custom Resources

IngressRoute (HTTP)

Define HTTP/HTTPS routing rules:

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: api-route
  namespace: production
spec:
  entryPoints:
    - websecure
  routes:
    # Multiple routes
    - match: Host(`api.example.com`) && PathPrefix(`/v1`)
      kind: Rule
      services:
        - name: api-v1
          port: 8080
      middlewares:
        - name: api-auth
        - name: rate-limit
    
    - match: Host(`api.example.com`) && PathPrefix(`/v2`)
      kind: Rule
      services:
        - name: api-v2
          port: 8080
  
  tls:
    certResolver: letsencrypt
    domains:
      - main: example.com
        sans:
          - "*.example.com"

IngressRouteTCP

Route TCP traffic:

apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
  name: postgres-route
spec:
  entryPoints:
    - postgresql
  routes:
    - match: HostSNI(`db.example.com`)
      services:
        - name: postgres
          port: 5432
  tls:
    passthrough: true

IngressRouteUDP

Route UDP traffic:

apiVersion: traefik.io/v1alpha1
kind: IngressRouteUDP
metadata:
  name: dns-route
spec:
  entryPoints:
    - dns
  routes:
    - services:
        - name: coredns
          port: 53

Middleware

Define reusable middleware:

Authentication

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: basic-auth
  namespace: default
spec:
  basicAuth:
    secret: auth-secret

TLSOption

Configure TLS settings:

apiVersion: traefik.io/v1alpha1
kind: TLSOption
metadata:
  name: modern-tls
  namespace: default
spec:
  minVersion: VersionTLS13
  cipherSuites:
    - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  curvePreferences:
    - CurveP521
    - CurveP384

TLSStore

Define default certificates:

apiVersion: traefik.io/v1alpha1
kind: TLSStore
metadata:
  name: default
  namespace: default
spec:
  defaultCertificate:
    secretName: default-tls-cert

Provider Configuration

endpoint

Optional, Default: Auto-detected

Kubernetes API server endpoint.

providers:
  kubernetesCRD:
    endpoint: "https://kubernetes.default.svc"

namespaces

Optional, Default: All namespaces

Limit watched namespaces:

providers:
  kubernetesCRD:
    namespaces:
      - production
      - staging

labelSelector

Optional, Default: ""

Filter resources by label:

providers:
  kubernetesCRD:
    labelSelector: "environment=production"

The label selector applies to all Traefik CRDs. All resources must match the filter.

ingressClass

Optional, Default: ""

Filter by ingress class:

providers:
  kubernetesCRD:
    ingressClass: "traefik-internal"

Resource annotation:

metadata:
  annotations:
    kubernetes.io/ingress.class: traefik-internal

allowCrossNamespace

Optional, Default: false

Allow IngressRoutes to reference resources in other namespaces:

providers:
  kubernetesCRD:
    allowCrossNamespace: true

Enabling this has security implications. Ensure proper RBAC is in place.

allowExternalNameServices

Optional, Default: false

Allow ExternalName services:

providers:
  kubernetesCRD:
    allowExternalNameServices: true

allowEmptyServices

Optional, Default: false

Create load balancers even when no endpoints are available (returns 503 vs 404):

providers:
  kubernetesCRD:
    allowEmptyServices: true

nativeLBByDefault

Optional, Default: false

Use Kubernetes native load balancing:

providers:
  kubernetesCRD:
    nativeLBByDefault: true

throttleDuration

Optional, Default: 0

Throttle configuration updates:

providers:
  kubernetesCRD:
    throttleDuration: "2s"

Complete Example

Application Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api-server
  template:
    metadata:
      labels:
        app: api-server
    spec:
      containers:
        - name: api
          image: myorg/api:v1.0
          ports:
            - containerPort: 8080

---
apiVersion: v1
kind: Service
metadata:
  name: api-server
  namespace: production
spec:
  selector:
    app: api-server
  ports:
    - port: 80
      targetPort: 8080

Advanced Patterns

Canary Deployments

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: canary-route
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`app.example.com`)
      kind: Rule
      services:
        # 90% to stable version
        - name: app-v1
          port: 80
          weight: 90
        # 10% to canary version
        - name: app-v2
          port: 80
          weight: 10

Cross-Namespace References

# Middleware in 'shared' namespace
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: common-auth
  namespace: shared
spec:
  basicAuth:
    secret: auth-secret

---
# IngressRoute in 'app' namespace
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-app
  namespace: app
spec:
  routes:
    - match: Host(`app.example.com`)
      kind: Rule
      services:
        - name: my-app
          port: 80
      middlewares:
        # Reference middleware from 'shared' namespace
        - name: common-auth
          namespace: shared

Requires allowCrossNamespace: true in provider configuration.

Multiple Domains with Shared Config

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: multi-domain
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`example.com`) || Host(`www.example.com`)
      kind: Rule
      services:
        - name: web-frontend
          port: 80
      middlewares:
        - name: redirect-www
    
    - match: Host(`api.example.com`)
      kind: Rule
      services:
        - name: api-backend
          port: 8080
      middlewares:
        - name: api-auth

Let’s Encrypt with CRDs

High Availability Limitation: Running multiple Traefik replicas with Let’s Encrypt is not officially supported. Use cert-manager for HA setups.

Single Instance Setup

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-app
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`app.example.com`)
      kind: Rule
      services:
        - name: my-app
          port: 80
  tls:
    certResolver: letsencrypt

HA with cert-manager

1. Install cert-manager
2. Enable Kubernetes Ingress provider (for cert-manager ACME challenges)
3. Reference certificates in IngressRoute:

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-app
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`app.example.com`)
      kind: Rule
      services:
        - name: my-app
          port: 80
  tls:
    secretName: app-tls-cert  # Created by cert-manager

Troubleshooting

CRDs Not Recognized

# Check if CRDs are installed
kubectl get crd | grep traefik

# Reinstall if missing
kubectl apply -f https://raw.githubusercontent.com/traefik/traefik/v3.6/docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml

RBAC Errors

# Verify RBAC
kubectl get clusterrole traefik-ingress-controller -o yaml

# Check service account
kubectl get serviceaccount traefik-ingress-controller -n traefik

Routes Not Working

1. Check IngressRoute Status

   kubectl describe ingressroute my-route
   
2. Verify Service Endpoints

   kubectl get endpoints my-service
   
3. Check Traefik Logs

   kubectl logs -n traefik deployment/traefik
   

Next Steps

CRD Reference

Complete CRD specification and fields

Routing Guide

Advanced routing examples and patterns