Replace ingress-nginx references with Traefik

welteki · welteki · commit bfc1fc09849d · 2026-04-02T14:08:59.000+02:00
Update documentation across multiple pages to recommend Traefik
as the default ingress controller instead of ingress-nginx:

- Switch ingress controller references from nginx to Traefik
- Update installation commands to use arkade install traefik2
- Replace nginx-specific annotations with Traefik equivalents
- Update ingressClassName from nginx to traefik
- Add Traefik timeout configuration guide

Signed-off-by: Han Verstraete (OpenFaaS Ltd) &lt;han@openfaas.com&gt;
diff --git a/docs/architecture/production.md b/docs/architecture/production.md
@@ -193,9 +193,7 @@ Whether you need to configure new networking for your OpenFaaS deployments, or i
 
 It is recommended that you use an IngressController and TLS so that traffic between your clients and your OpenFaaS Gateway is encrypted.
 
-You may already have opinions about what IngressController you want to use, the maintainers like to use Nginx given its broad adoption and relative ubiquity.
-
-> See also: [Nginx IngressController](https://github.com/kubernetes/ingress-nginx) 
+> See also: [Traefik Proxy](https://doc.traefik.io/traefik/) 
 
 Heptio Contour also includes automatic retries and additional Ingress extensions which you may find useful:
 
diff --git a/docs/deployment/kubernetes.md b/docs/deployment/kubernetes.md
@@ -74,7 +74,7 @@ There are three recommended ways to install OpenFaaS and you can pick whatever m
 
 #### 1) Deploy the Chart with `arkade` (fastest option)
 
-The `arkade install` command installs OpenFaaS using its official helm chart. arkade can also install other important software for OpenFaaS users such as `cert-manager` and `nginx-ingress`. It's the easiest and quickest way to get up and running.
+The `arkade install` command installs OpenFaaS using its official helm chart. arkade can also install other important software for OpenFaaS users such as `cert-manager` and `traefik`. It's the easiest and quickest way to get up and running.
 
 You can use [arkade](https://arkade.dev/) to install OpenFaaS to a regular cloud cluster, your laptop, a VM, a Raspberry Pi, or a 64-bit Arm machine.
 
@@ -197,7 +197,7 @@ Also, ensure any [default load-balancer timeouts within GKE](https://cloud.googl
 To enable TLS while using Helm, try one of the following references:
 
 * [Get TLS for OpenFaaS the easy way with arkade](https://blog.alexellis.io/tls-the-easy-way-with-openfaas-and-k3sup/)
-* [Configure TLS with nginx-ingress and cert-manager](/reference/tls-openfaas)
+* [Configure TLS with Traefik and cert-manager](/reference/tls-openfaas)
 
 ### Setting an Image Pull Policy for your functions
 
diff --git a/docs/reference/tls-openfaas.md b/docs/reference/tls-openfaas.md
@@ -1,4 +1,4 @@
-## TLS for OpenFaaS
+# TLS for OpenFaaS
 
 Transport Layer Security (TLS) is a cryptographic protocol that provides secure encryption on top of HTTP. It is required for any OpenFaaS gateway which is exposed to the Internet.
 
@@ -8,62 +8,69 @@ This guide explains how to obtain TLS certificates for the OpenFaaS Gateway runn
 * Configure cert-manager to obtain a certificate from Let's Encrypt
 * Configure the an Ingress record for the OpenFaaS Gateway
 
-### Pre-requisites
+## Pre-requisites
 
 * A domain name under your control, and access to create A or CNAME records
 * A public IP address with NodePorts, a Load Balancer or a tunnel such as [inlets](https://inlets.dev/)
 * A Kubernetes cluster
 
 Where you see `example.com` given in an example, replace that with your own domain name.
 
-### Make sure you can obtain public IP addresses
+## Make sure you can obtain public IP addresses
 
 Managed Kubernetes services have a built-in LoadBalancer provisioner, which will provide a public IP address or CNAME for you, once you create a Service of type LoadBalancer.
 
 If you're running self-managed Kubernetes, where each node has its own Public IP address, then you can configure your Ingress Controller to use a NodePort mapped to port 80 and 443 on the host.
 
 If you are running on a local or private network, you can use [inlets-operator](https://github.com/inlets/inlets-operator) instead, which provisions a VM and uses its public IP address over a websocket tunnel.
 
-### Set up an Ingress Controller
+## Set up an Ingress Controller
 
-We recommend ingress-nginx for OpenFaaS, however any Ingress controller will work, or you can use Istio with separate instructions.
+We recommend Traefik for OpenFaaS, however any Ingress controller will work, or you can use Istio with separate instructions.
 
-To install ingress-nginx, use either the Helm chart, or arkade:
+Install Traefik with Helm:
 
 ```sh
-$ arkade install ingress-nginx
-```
+helm repo add traefik https://traefik.github.io/charts
+helm repo update
 
-See also: [ingress-nginx installation](https://kubernetes.github.io/ingress-nginx/deploy/)
+helm install --namespace=traefik traefik traefik/traefik \
+  --create-namespace
+```
 
+See also: [Traefik installation](https://doc.traefik.io/traefik/getting-started/install-traefik/)
 
-#### Timeouts for synchronous invocations
+### Timeouts for synchronous invocations
 
 Despite configuring OpenFaaS and your functions for [extended timeouts](/tutorials/expanded-timeouts.md), you may find that your Ingress Controller, Istio Gateway, or Cloud Load Balancer implements its own timeouts on connections. If you think you have everything configured correctly for OpenFaaS, but see a timeout at a very specific number such as 30s or 60s, then check the timeouts on your Ingress Controller or Load Balancer.
 
-For Ingress Nginx, to extend a synchronous invocation beyond one minute, add the `nginx.ingress.kubernetes.io/proxy-read-timeout` annotation to your Ingress resource. This annotation is specified in seconds - for example, to extend the timeout to 30 minutes, use `nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"`. 
+For Traefik, timeouts are typically configured at the EntryPoint level in the static configuration. See the [expanded timeouts guide](/tutorials/expanded-timeouts.md#load-balancers-ingress-and-service-meshes) for more details on configuring Traefik timeouts.
+
+Ingress Nginx is now a retired project and should not be used for new installations. If you are still using Ingress Nginx, to extend a synchronous invocation beyond one minute, add the `nginx.ingress.kubernetes.io/proxy-read-timeout` annotation to your Ingress resource. This annotation is specified in seconds - for example, to extend the timeout to 30 minutes, use `nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"`.
 
-### Install cert-manager
+## Install cert-manager
 
 cert-manager is a Kubernetes operator maintained by the Cloud Native Computing Foundation (CNCF) which automates TLS certificate management.
 
-To install cert-manager, use either the Helm chart, or arkade:
+To install cert-manager:
 
 ```sh
-$ arkade install cert-manager
+helm install \
+  cert-manager oci://quay.io/jetstack/charts/cert-manager \
+  --namespace cert-manager \
+  --create-namespace \
+  --set crds.enabled=true
 ```
 
 See also: [cert-manager installation](https://cert-manager.io/docs/installation/)
 
-### Configure cert-manager
+## Configure cert-manager
 
 You'll need to create an Issuer or ClusterIssuer for your cert-manager installation. This will tell cert-manager which domain it is operating on, and how to register an account for you.
 
 The below will create an Issuer that only operates in the openfaas namespace, with a HTTP01 challenge. Note the ingress class specified in the HTTP01 challenge, this should match the class of your Ingress controller. You can view ingress classes with `kubectl get ingressclass`.
 
 ```bash
-export EMAIL="you@example.com"
-
 cat > issuer.yaml <<EOF
 apiVersion: cert-manager.io/v1
 kind: Issuer
@@ -73,14 +80,13 @@ metadata:
 spec:
   acme:
     server: https://acme-v02.api.letsencrypt.org/directory
-    email: $EMAIL
     privateKeySecretRef:
       name: letsencrypt
     solvers:
     - selector: {}
       http01:
         ingress:
-          class: nginx
+          class: traefik
 ---
 apiVersion: cert-manager.io/v1
 kind: Issuer
@@ -90,14 +96,13 @@ metadata:
 spec:
   acme:
     server: https://acme-staging-v02.api.letsencrypt.org/directory
-    email: $EMAIL
     privateKeySecretRef:
       name: letsencrypt-staging
     solvers:
     - selector: {}
       http01:
         ingress:
-          class: nginx
+          class: traefik
 ---
 
 EOF
@@ -109,38 +114,37 @@ Apply the staging and production Issuers:
 $ kubectl apply -f issuer.yaml
 ```
 
-### Create the required DNS records
+## Create the required DNS records
 
 You will need to create an A or CNAME record for your domain, pointing to the public IP address of your Ingress controller.
 
-If you created the Ingress Controller with arkade, you'll see a new service in the default namespace called `ingress-nginx-controller`. You can find the public IP address with:
+After installing Traefik, you'll see a new LoadBalancer service for traefik in the `traefik namespace. You can find the public IP address with:
 
 ```sh
-$ kubectl get svc -n default ingress-nginx-controller
+$ kubectl get svc/traefik -n traefik
 
-NAME                       TYPE           CLUSTER-IP   EXTERNAL-IP     PORT(S)                      AGE
-ingress-nginx-controller   LoadBalancer   10.43.87.4   18.136.136.18   80:31876/TCP,443:30108/TCP   28d
+NAME      TYPE           CLUSTER-IP   EXTERNAL-IP     PORT(S)                      AGE
+traefik   LoadBalancer   10.43.87.4   18.136.136.18   80:31876/TCP,443:31706/TCP   28d
 ```
 
-Take the IP address from the `EXTERNAL-IP` column and create an A record for your domain in your domain management software, or a CNAME record if you're using AWS EKS, and see a domain name in this field.
+Take the IP address from the `EXTERNAL-IP` column and create an A record for your domain in your domain management software, or a CNAME record if you see a domain name in this field.
 
 All users should create an entry for: `gateway.example.com` and then OpenFaaS dashboard users should create an additional record pointing at the same address for: `dashboard.example.com`.
 
-### Configure TLS for the OpenFaaS gateway
+## Configure TLS for the OpenFaaS gateway
 
 You can now configure the OpenFaaS gateway to use TLS by setting the following Helm values, you can save them in a file called `tls.yaml`:
-
+ 
 ```sh
 export DOMAIN="gw.example.com"
-export NGINX_TIMEOUT_SECS="1800" # 30 minutes
 
 cat > tls.yaml <<EOF
 ingress:
   enabled: true
-  ingressClassName: nginx
+  ingressClassName: traefik
   annotations:
     cert-manager.io/issuer: letsencrypt-prod
-    nginx.ingress.kubernetes.io/proxy-read-timeout: "$NGINX_TIMEOUT_SECS"
+    traefik.ingress.kubernetes.io/router.entrypoints: websecure
   tls:
     - hosts:
         - $DOMAIN
@@ -159,10 +163,12 @@ ingress:
 EOF
 ```
 
-If you're using something other than ingress-nginx, then change the `ingressClassName` field accordingly. Note that the `kubernetes.io/ingress.class` annotation is deprecated and should not be used.
+If you're using something other than Traefik, then change the `ingressClassName` field accordingly. Note that the `kubernetes.io/ingress.class` annotation is deprecated and should not be used.
 
 The `cert-manager.io/issuer` annotation is used to pick between the staging and production Issuers for Let's Encrypt. If this is your first time working with cert-manager, you may want to use the staging issuer first to avoid running into rate limits if you have something misconfigured.
 
+> Note: For extended timeouts beyond Traefik's defaults, see the [expanded timeouts guide](/tutorials/expanded-timeouts.md#load-balancers-ingress-and-service-meshes) for information on configuring Traefik's EntryPoint timeouts.
+
 Now upgrade OpenFaaS via helm, use any custom values.yaml files that you have saved from a previous installation:
 
 ```sh
@@ -173,7 +179,7 @@ helm repo update && \
         --values values-custom.yaml
 ```
 
-### Configure TLS for the OpenFaaS dashboard
+## Configure TLS for the OpenFaaS dashboard
 
 If you're using OpenFaaS Standard or OpenFaaS for Enterprises, you will probably want to create an additional Ingress record for the OpenFaaS dashboard.
 
@@ -182,15 +188,14 @@ Edit the previous example:
 ```sh
 export DOMAIN="gw.example.com"
 export DOMAIN_DASHBOARD="dashboard.example.com"
-export NGINX_TIMEOUT_SECS="1800" # 30 minutes
 
 cat > tls.yaml <<EOF
 ingress:
   enabled: true
-  ingressClassName: nginx
+  ingressClassName: traefik
   annotations:
     cert-manager.io/issuer: letsencrypt-prod
-    nginx.ingress.kubernetes.io/proxy-read-timeout: "$NGINX_TIMEOUT_SECS"
+    traefik.ingress.kubernetes.io/router.entrypoints: websecure
   tls:
     - hosts:
         - $DOMAIN
@@ -224,7 +229,7 @@ EOF
 
 As above, run the `helm upgrade` command to apply the changes.
 
-### Verifying the installation
+## Verifying the installation
 
 First, check that the DNS records you created have taken effect. You can use `nslookup` or `dig` to check that the domain names resolve to the public address of your Ingress Controller's service.
 
diff --git a/docs/tutorials/expanded-timeouts.md b/docs/tutorials/expanded-timeouts.md
@@ -86,7 +86,17 @@ AWS EKS is configured to use an [Elastic Load Balancer (ELB)](https://aws.amazon
 
 Google Cloud's various Load Balancer options have their [own configuration options too](https://cloud.google.com/load-balancing/docs/https).
 
-For Ingress Nginx, set the `nginx.ingress.kubernetes.io/proxy-read-timeout` annotation to extend the timeout. This annotation is specified in seconds - for example, to extend the timeout to 30 minutes, use `nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"`.
+For Traefik, see [Configuring Traefik timeouts](#configuring-traefik-timeouts) below.
+
+Ingress Nginx is now a retired project and should not be used for new installations. If you are still using it, set the `nginx.ingress.kubernetes.io/proxy-read-timeout` annotation to extend the timeout. This annotation is specified in seconds - for example, to extend the timeout to 30 minutes, use `nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"`.
+
+### Configuring Traefik timeouts
+
+Traefik has two separate sets of timeouts to be aware of:
+
+**Client-to-Traefik (EntryPoints)** - configured in the static configuration (CLI flags or Helm values). Controls how long Traefik waits for the client to send a request or receive a response. The key fields are `readTimeout` (default 60s), `writeTimeout` (default 0s) and `idleTimeout` (default 180s). See [EntryPoints - RespondingTimeouts](https://doc.traefik.io/traefik/routing/entrypoints/#respondingtimeouts).
+
+**Traefik-to-App (ServersTransport)** - configured in the dynamic configuration using a [ServersTransport CRD](https://doc.traefik.io/traefik/reference/routing-configuration/kubernetes/crd/http/serverstransport/), and referenced via the `traefik.ingress.kubernetes.io/service.serverstransport` annotation on the Ingress. By default there is no timeout on how long Traefik waits for a backend to respond (`responseHeaderTimeout` is 0s). Consider setting `responseHeaderTimeout` to match the gateway's `upstreamTimeout` so that Traefik returns a 504 quickly when a function hangs, rather than waiting indefinitely.
 
 Finally, if you need to invoke a function for longer than one of your infrastructure components allows, then you should use an [asynchronous invocation](/reference/async). Asynchronous function invocations bypass these components because they are eventually invoked from the queue-worker, not the Internet. The queue-worker for OpenFaaS Standard will also retry invocations if required.
 
diff --git a/docs/tutorials/local-kind-ingress.md b/docs/tutorials/local-kind-ingress.md
@@ -2,7 +2,7 @@
 
 Most users will use port-forwarding to access the OpenFaaS gateway, it's the simplest option and works everywhere.
 
-However, in this tutorial, we will show you how to deploy OpenFaaS with ingress-nginx.
+However, in this tutorial, we will show you how to deploy OpenFaaS with Traefik ingress.
 
 When you use an Ingress Controller:
 
@@ -53,14 +53,19 @@ EOF
 kind create cluster --name openfaas --config kind-config.yaml
 ```
 
-## Install the ingress-nginx IngressController
+## Install the Traefik IngressController
 
-Use arkade, or [install ingress-nginx manually](https://kubernetes.github.io/ingress-nginx/deploy/).
+Install Traefik with Helm:
 
 ```sh
-arkade install ingress-nginx
+helm repo add traefik https://traefik.github.io/charts
+helm repo update
+helm install --namespace=traefik traefik traefik/traefik \
+  --create-namespace
 ```
 
+See also: [Traefik installation](https://doc.traefik.io/traefik/getting-started/install-traefik/)
+
 ## Install OpenFaaS with local Ingress enabled
 
 Usually, Ingress is used when a cluster has a public IP address, and you want to obtain TLS certificates from Let's Encrypt. In this case, we'll use it to access the OpenFaaS gateway on the host machine.
@@ -77,7 +82,7 @@ ingress:
       serviceName: gateway
       servicePort: 8080
       path: /
-  ingressClassName: nginx
+  ingressClassName: traefik
 ```
 
 > Note: if you're migrating from an older version of Kubernetes, the `annotations.kubernetes.io/ingress.class` [annotation is deprecated](https://kubernetes.io/docs/concepts/services-networking/ingress/#deprecated-annotation), use `ingressClassName` instead.
@@ -103,4 +108,3 @@ faas-cli store deploy env
 
 faas-cli list
 ```
-
