Skip to main content

Ingress Requirements

OLIVE renders ordinary Ingress objects and expects an ingress controller to serve them. Traefik is the only supported controller, and OLIVE needs a small number of specific behaviours from it.

NGINX Ingress is no longer supported

NGINX Ingress was deprecated in 1.2 and is not supported in 1.3. OLIVE renders Traefik router annotations and Middleware resources, which have no NGINX equivalent in the charts. A cluster running NGINX Ingress has to add Traefik for the OLIVE hosts.

This page states what OLIVE requires. Installing, upgrading, tuning and troubleshooting the controller itself is yours.


Hostnames​

Each tenant is reached under its own subdomain, built from global.tenant, the cluster name and the root domain:

<tenant>.<cluster>.<domain>

Five names are used per tenant, and all of them must resolve to the ingress controller:

NameServes
<tenant>.<cluster>.<domain>The start page
app.<tenant>.<cluster>.<domain>The application
repo.<tenant>.<cluster>.<domain>The repository editor
api.<tenant>.<cluster>.<domain>The API
workflow.<tenant>.<cluster>.<domain>The workflow engine

A wildcard DNS record for *.<cluster>.<domain> covers all of them, for every tenant, and is the usual arrangement. global.tenant is part of the name, which is one of the reasons a tenant designation is permanent.


The ingress controller​

global.ingress.className selects the controller. OLIVE renders controller-specific configuration, so this value must match what is installed.

ValueWhat OLIVE renders
traefikTraefik router annotations and a chain of Middleware resources

Traefik on RKE2 and on other clusters​

OLIVE works with RKE2's bundled Traefik and with a separately installed Traefik (for example the upstream Traefik Helm chart on Amazon EKS) alike. Nothing in the OLIVE configuration is tied to the rke2-traefik name except the network policy selector:

AspectRKE2 bundled TraefikSeparately installed Traefik (upstream chart)
IngressClass nametraefikThe release name — install it as traefik, or set ingressClass.name: traefik, or point global.ingress.className at your name
Entry points used by OLIVEweb, websecureSame — the upstream defaults
Providers neededkubernetesIngress, kubernetesCRDSame — both enabled by default
CRD traefik.io/v1alpha1 MiddlewareInstalled with RKE2Installed with the chart (Traefik v3)
Network policy selector (global.networkPolicy.ingressController)kube-system / app.kubernetes.io/name: rke2-traefik (default)Your release namespace / app.kubernetes.io/name: traefik — must be changed, see Networking
Enrolling Traefik in the service meshHelmChartConfig (traefikEnrollment.method: helmChartConfig)Label in your own Traefik values (traefikEnrollment.method: external)
Plugins (login redirect)Configured on the RKE2 Traefik via HelmChartConfigConfigured in your own Traefik values (experimental.plugins) — it does not carry over from RKE2
Behind a cloud load balancer

On EKS, Traefik usually sits behind an NLB or ALB. Keycloak and OAuth2 Proxy rely on the X-Forwarded-* headers Traefik sets, so configure Traefik to trust the load balancer (forwardedHeaders.trustedIPs on the entry points, or the PROXY protocol on an NLB). Otherwise redirects use the wrong scheme and client addresses are the load balancer's.

What the controller must support​

RequirementWhyHow OLIVE asks for it
External / forward authenticationEvery request is authenticated at the edge against OAuth2 Proxy before it reaches a service. Without it, the platform is either open or unreachableforwardAuth middleware
Path prefix strippingServices are mounted under a path prefix and expect it removedstripPrefix middleware
A request body limit large enough for importsImporting an OLIVE Connectivity Bundle or uploading files goes through the ingressbuffering middleware — OLIVE renders one per stateful service with maxRequestBodyBytes: 52428800 (50 MB) and maxResponseBodyBytes: 0 (unlimited). Traefik itself imposes no body limit, so 50 MB is OLIVE's number, not a default being raised. It is traefik.buffering.* on the service chart, on by default
No read timeout shorter than the longest orchestrationAn orchestration call holds the connection open for as long as it runsNothing — and that is the point. Traefik's entry-point respondingTimeouts.readTimeout defaults to 0 (no limit), which is what OLIVE needs. If your installation sets a finite value, it has to exceed the longest orchestration you expect to run through the ingress

What your installation currently does, for the two that are yours to set:

# Entry-point timeouts, if any are configured at all
kubectl -n <traefik-namespace> get deploy traefik -o yaml \
| grep -E 'entry[Pp]oints|respondingTimeouts|readTimeout|idleTimeout'

# The buffering Middlewares OLIVE created, with the limit each one carries
kubectl get middlewares.traefik.io -A \
-o custom-columns='NS:.metadata.namespace,NAME:.metadata.name,MAXBODY:.spec.buffering.maxRequestBodyBytes'

A MAXBODY of <none> on a -buffering middleware means the object exists with no limit rendered; an empty list means traefik.buffering.enabled is off for that service.

The redirectErrors plugin is required​

An unauthenticated request to a forwardAuth endpoint returns 401 or 403. Browsers do not turn that into a login redirect on their own, so Traefik needs a middleware that converts those statuses into a 302 to the start URL. OLIVE renders it as a Middleware of type plugin.redirectErrors.

A Traefik plugin registered under the name redirectErrors must therefore be loaded in your Traefik installation. It is not built in, and OLIVE cannot install it — a plugin is loaded by the Traefik process at startup from its static configuration, which is the installation's own, not something a tenant chart can reach.

Without it, every unauthenticated user meets an error page instead of a login page

The symptom is not subtle, but the cause is: the Middleware object OLIVE created references a plugin that does not exist, so Traefik rejects the middleware and the route fails. Nothing about it points at a missing plugin in your Traefik values.

How you load it depends on where Traefik came from:

Traefik installationHow the plugin is loaded
RKE2's bundled TraefikAdd it to the static configuration through a HelmChartConfig in kube-system. The rest of the Traefik configuration stays as RKE2 ships it — you are only adding the plugin
A separately installed Traefik (the upstream chart, typical on EKS)Add it to the experimental.plugins block of your own Traefik values

The plugin is github.com/indivisible/redirecterrors, version v0.1.0, and the middleware name must be exactly redirectErrors. It can be loaded as a local plugin (source mounted from a ConfigMap — no egress needed, and what runs is what is in Git) or a remote one (experimental.plugins, fetched from plugins.traefik.io on every pod start, which kills the pod if that host is unreachable). The local form is the one to prefer, and traefik-infra ships it already vendored.

Moving from RKE2's Traefik to your own

The plugin does not carry over. A cluster that worked on RKE2's bundled Traefik and then switches to a separately installed one loses the plugin along with the rest of the bundled static configuration, and the login path breaks at the first unauthenticated request. Add it to the new installation's values as part of the same change.

The security-header and request-header middlewares OLIVE renders are part of the platform and need no plugin; they are described under Security.


TLS​

cert-manager is a requirement

cert-manager must be installed on the cluster, and a ClusterIssuer must exist for OLIVE to reference. OLIVE renders Certificate objects; it does not install cert-manager and it never creates the issuer. Without both, no tenant gets a certificate and every hostname serves an invalid chain or nothing at all.

It is listed as a hard prerequisite in Handover Checklist → What the cluster operator provides and its CRD in Kubernetes Resources. The one exception is below: if you issue certificates by some other means and create the Secret yourself, cert-manager is not needed.

TLS terminates at the ingress. OLIVE expects one certificate per tenant, covering all five names, in a Secret the Ingress references.

The certificate chart renders a cert-manager Certificate for it:

  • Issuer: a ClusterIssuer named by global.clusterIssuer. OLIVE references it and never creates it — the issuer, its ACME account or CA key material, and the solver configuration are yours.
  • Secret: wildcard-<tenant>-<cluster>-<domain>-tls, in the tenant namespace.
  • Names: the five hostnames above.

If you issue certificates some other way, create that Secret yourself with the same name and contents and do not deploy the certificate chart. OLIVE needs the Secret, not cert-manager.

Renewal, trust chains, and what happens when the issuer stops working are cert-manager and PKI matters, not OLIVE ones.

Internal TLS

global.resolveTLS controls whether the Ingress objects carry a TLS block at all. A lab that issues its own certificates should have its CA trusted explicitly rather than have verification switched off — see Internal TLS certificates in a lab.


Network policies and the controller​

With network policies enabled, the ingress controller's pods must match networkPolicy.ingressController, or default-deny closes every route into the namespace. This is the single most common way to make a correctly configured ingress stop working; see Networking.


Not in scope​

Installing, upgrading or tuning Traefik; operating cert-manager; certificate lifecycle and PKI policy; load balancer and DNS provisioning; WAF, rate limiting and edge security policy. Those are cluster responsibilities and belong to those projects' documentation.