Skip to content

Commit 1850638

Browse files
zlogiczlogic
committed
Updated ingress controller documentation:
* Removed recommendation for using deprecated NGINX Ingress * Added a note that the F5 Networks NGINX Ingress would be a suitable replacement * Added notes that Istio Ingress and HAProxy are also supported/compatible.
1 parent 755e311 commit 1850638

2 files changed

Lines changed: 140 additions & 25 deletions

File tree

‎content/en/docs/deployment/private-cloud/private-cloud-cluster/networking/private-cloud-ingress.md‎

Lines changed: 132 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -24,23 +24,27 @@ To ensure proper routing, the DNS server must be configured to direct all subdom
2424

2525
The following sections describe the installation and configuration of various supported Ingress Controllers.
2626

27-
### NGINX Ingress Controller
27+
### NGINX Ingress Controller (F5)
2828

29-
The [NGINX Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/) is an open-source solution that leverages NGINX as a reverse proxy and load balancer to manage Kubernetes Ingress resources.
29+
{{% alert color="info" %}}
30+
This section documents how to use the [NGINX Ingress Controller](https://github.com/nginx/kubernetes-ingress) from the NGINX project (F5 Networks).
31+
{{% /alert %}}
3032

3133
{{% alert color="info" %}}
32-
NGINX path based routing is supported for Operator version 2.19.0 and newer, and Mendix version 10.3.0 and newer. To support this feature, NGINX Ingress uses `nginx.ingress.kubernetes.io/rewrite-target/(.*)` in the ingress path.
34+
NGINX path based routing is supported for Operator version 2.19.0 and newer, and Mendix version 10.3.0 and newer. To support this feature, NGINX Ingress uses `nginx.org/rewrite-target=/$1` annotation that rewrites a `(.*)` regular expresion in the ingress path.
3335
{{% /alert %}}
3436

35-
#### Installing NGINX
37+
#### Installing NGINX Ingress Controller
3638

37-
The recommended way to install NGINX is [Helm](https://docs.nginx.com/nginx-ingress-controller/installation/installing-nic/installation-with-helm/). Alternatively, you can also install NGINX with a [manifest](https://kubernetes.github.io/ingress-nginx/deploy/).
39+
The recommended way to install NGINX is [Helm](https://docs.nginx.com/nginx-ingress-controller/installation/installing-nic/installation-with-helm/).
3840

39-
##### Configuring NGINX in the Mxpc-cli Tool
41+
Some cloud providers might offer NGINX Ingress as a managed service.
42+
43+
##### Configuring NGINX Ingress in the Mxpc-cli Tool
4044

4145
To configure NGINX for Mendix on Kubernetes, set up the following settings:
4246

43-
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
47+
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
4448
* **Ingress Domain Name** - Provide the domain name which you want to set for the Ingress resource file.
4549
* **Ingress Path** - Optional. You can use this option to specify the Ingress path. The default value is `/`.
4650
* **Enable TLS** - Enable or disable TLS for your app's Ingress.
@@ -50,6 +54,63 @@ To configure NGINX for Mendix on Kubernetes, set up the following settings:
5054

5155
{{< figure src="/attachments/deployment/private-cloud/private-cloud-cluster/private-cloud-networking/configure-nginx.png" class="no-border" >}}
5256

57+
Additionally, you can add NGINX-specific annotations to the **Ingress** section of your configuration. The following section shows example annotations. Adjust them as needed based on your specific requirements.
58+
59+
```text
60+
apiVersion: privatecloud.mendix.com/v1alpha1
61+
kind: OperatorConfiguration
62+
# ...
63+
# omitted lines for brevity
64+
# ...
65+
spec:
66+
# Endpoint (Network) configuration
67+
endpoint:
68+
type: ingress
69+
ingress:
70+
annotations:
71+
# Example: allow uploads of files up to 500MB in size
72+
nginx.org/client-max-body-size: 500m
73+
# Example: rewrite path for path-based routing
74+
nginx.org/rewrite-target: /$1
75+
# Example: enable regular expressions for path-based routing
76+
nginx.org/path-regex: case_sensitive
77+
# The following parameters are already configured by mxpc-cli
78+
domain: mendix.example.com
79+
enableTLS: true
80+
ingressClassName: nginx
81+
# Set the path to "/(.*)" when using path-based routing
82+
# When not using path-based routing, set the path to "/"
83+
path: "/(.*)"
84+
pathType: ImplementationSpecific
85+
# ...
86+
# omitted lines for brevity
87+
# ...
88+
```
89+
90+
### HAProxy Ingress Controller
91+
92+
{{% alert color="info" %}}
93+
This section documents how to use the [HAProxy Kubernetes Ingress Controller](https://github.com/haproxytech/kubernetes-ingress).
94+
{{% /alert %}}
95+
96+
#### Installing HAProxy Ingress Controller
97+
98+
For more information about the recommended installation process, see [installation instructions for your platform](https://www.haproxy.com/documentation/kubernetes-ingress/community/installation/).
99+
100+
##### Configuring HAProxy Ingress in the Mxpc-cli Tool
101+
102+
To configure HAProxy Ingress for Mendix on Kubernetes, set up the following settings:
103+
104+
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
105+
* **Ingress Domain Name** - Provide the domain name which you want to set for the Ingress resource file.
106+
* **Ingress Path** - Select `/` from the dropdown.
107+
* **Enable TLS** - Enable or disable TLS for your app's Ingress.
108+
* **Custom Ingress Class** - Set to **enabled**.
109+
* **Ingress Class Name** - Enter **haproxy**. This setting requires Custom Ingress Class to be enabled.
110+
* **Set Ingress Class as Annotation** - Set to **disabled**. This option adds the legacy `kubernetes.io/ingress.class` annotation to set the Ingress class, instead of using the Ingress class name.
111+
112+
Additionally, you can add HAProxy-specific annotations to the **Ingress** section of your configuration. The following section shows example annotations. Adjust them as needed based on your specific requirements.
113+
53114
### AWS Load Balancer Ingress Controller
54115

55116
[AWS Load Balancer Controller](https://kubernetes-sigs.github.io/aws-load-balancer-controller/latest/) is the AWS-recommended way to provide ingress capability on EKS.
@@ -74,7 +135,7 @@ To configure the AWS Load Balancer for Mendix on Kubernetes, perform the followi
74135

75136
1. Set up the following settings:
76137

77-
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
138+
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
78139
* **Ingress Domain Name** - Provide the domain name which which was registered for AWS Load Balancer.
79140
* **Ingress Path** - Set to `/*`.
80141
* **Enable TLS** - Set to **disabled**. In AWS Load Balancer, TLS is enabled through annotations.
@@ -157,7 +218,7 @@ To configure AGIC for Mendix on Kubernetes, perform the following steps:
157218
158219
1. Set up the following settings:
159220
160-
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
221+
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
161222
* **Ingress Domain Name** - Provide the domain name which which was registered for AGIS.
162223
* **Ingress Path** - Set to `/*`.
163224
* **Enable TLS** - Enable or disable TLS for your app's Ingress.
@@ -211,28 +272,80 @@ To configure AGIC for Mendix on Kubernetes, perform the following steps:
211272
212273
4. Optional: To set up TLS certificates, see [Appgw ssl certificate](https://azure.github.io/application-gateway-kubernetes-ingress/features/appgw-ssl-certificate/).
213274
214-
### Traefik Ingress Controller
275+
### HAProxy Ingress Controller
276+
277+
{{% alert color="info" %}}
278+
This section documents how to use the [HAProxy Kubernetes Ingress Controller](https://github.com/haproxytech/kubernetes-ingress).
279+
{{% /alert %}}
280+
281+
#### Installing HAProxy Ingress Controller
215282
216-
Traefik is a cloud-native reverse proxy and a load balancer. When deployed as an Ingress Controller in Kubernetes, it manages HTTP and HTTPS traffic to services running within the cluster. It automatically discovers services using Kubernetes' native APIs, based on Kubernetes Ingress resources and other configurations. One of the main advantages of using Traefik is its built-in [Let's Encrypt](https://doc.traefik.io/traefik/https/acme/) support.
283+
For more information about the recommended installation process, see [installation instructions for your platform](https://www.haproxy.com/documentation/kubernetes-ingress/community/installation/).
217284
218-
#### Installing Traefik
285+
##### Configuring HAProxy Ingress in the Mxpc-cli Tool
219286
220-
For information about installing the Traefik Ingress Controller, see [Traefik & Kubernetes](https://doc.traefik.io/traefik/providers/kubernetes-ingress/).
287+
To configure HAProxy Ingress for Mendix on Kubernetes, set up the following settings:
288+
289+
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
290+
* **Ingress Domain Name** - Provide the domain name which you want to set for the Ingress resource file.
291+
* **Ingress Path** - Select `/` from the dropdown.
292+
* **Enable TLS** - Enable or disable TLS for your app's Ingress.
293+
* **Custom Ingress Class** - Set to **enabled**.
294+
* **Ingress Class Name** - Enter **haproxy**. This setting requires Custom Ingress Class to be enabled.
295+
* **Set Ingress Class as Annotation** - Set to **disabled**. This option adds the legacy `kubernetes.io/ingress.class` annotation to set the Ingress class, instead of using the Ingress class name.
296+
297+
Additionally, you can add HAProxy-specific annotations to the **Ingress** section of your configuration. The following section shows example annotations. Adjust them as needed based on your specific requirements.
298+
299+
### Istio Ingress Controller
300+
301+
Istio is a well-known service mesh that includes a simple [ingress contoller](https://istio.io/latest/docs/tasks/traffic-management/ingress/kubernetes-ingress/).
302+
303+
#### Installing Istio
304+
305+
To install Istio, follow the official [installation instructions](https://istio.io/latest/docs/overview/quickstart/).
306+
307+
You will also need to install an Istio [IngressClass](https://istio.io/latest/docs/tasks/traffic-management/ingress/kubernetes-ingress/).
221308
222309
{{% alert color="info" %}}
223-
Traefik uses 2 types of providers: CRDs or Kubernetes Ingress. Ensure that you install Kubernetes Ingress one, as it is the only one supported by Mendix on Kubernetes.
310+
Istio is a feature-rich system with many configuration options. To validate an Istio configuration, it's highly recommended to test with a simple (non-Mendix) app to validate configuration.
224311
{{% /alert %}}
225312
226-
#### Configuring Traefik in the Mxpc-cli Tool
313+
#### Configuring Istio in the Mxpc-cli Tool
227314
228315
To configure Traefik for Mendix on Kubernetes, set up the following settings:
229316
230-
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
231-
* **Ingress Domain Name** - Provide the domain name which was registered for Traefik
317+
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
318+
* **Ingress Domain Name** - Provide the domain name which was registered for Istio
232319
* **Ingress Path** - Set to `/*`.
233320
* **Enable TLS** - Enable or disable TLS for your app's Ingress.
234321
* **Custom Ingress Class** - Set to **enabled**.
235-
* **Ingress Class Name** - Enter **traefik**. This setting requires Custom Ingress Class to be enabled.
322+
* **Ingress Class Name** - Enter **istio**. This setting requires Custom Ingress Class to be enabled.
323+
* **Set Ingress Class as Annotation** - Set to **disabled**. This option adds the legacy `kubernetes.io/ingress.class` annotation to set the Ingress class, instead of using the Ingress class name.
324+
325+
### DEPRECATED NGINX Ingress Controller
326+
327+
{{% alert color="warning" %}}
328+
The [Kubernetes Ingress NGINX Controller](https://kubernetes.github.io/ingress-nginx/) will be supported [until March 2026](https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/).
329+
330+
We recommend switching to another ingress controller.
331+
The [NGINX Ingress Controller](https://github.com/nginx/kubernetes-ingress) from the NGINX project (F5 Networks) has a similar feature set.
332+
In most cases, switching from the deprecated Kubernetes controller to controller from F5 Networks would only require renaming ingress annotations.
333+
{{% /alert %}}
334+
335+
{{% alert color="info" %}}
336+
NGINX path based routing is supported for Operator version 2.19.0 and newer, and Mendix version 10.3.0 and newer. To support this feature, NGINX Ingress uses `nginx.ingress.kubernetes.io/rewrite-target=/$1` annotation that rewrites a `(.*)` regular expresion in the ingress path.
337+
{{% /alert %}}
338+
339+
##### Configuring the NGINX in the Mxpc-cli Tool
340+
341+
To configure the *deprecated* NGINX ingress controller with Mendix on Kubernetes, set up the following settings:
342+
343+
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
344+
* **Ingress Domain Name** - Provide the domain name which you want to set for the Ingress resource file.
345+
* **Ingress Path** - Optional. You can use this option to specify the Ingress path. The default value is `/`.
346+
* **Enable TLS** - Enable or disable TLS for your app's Ingress.
347+
* **Custom Ingress Class** - Set to **enabled**.
348+
* **Ingress Class Name** - Enter **nginx**. This setting requires Custom Ingress Class to be enabled.
236349
* **Set Ingress Class as Annotation** - Set to **disabled**. This option adds the legacy `kubernetes.io/ingress.class` annotation to set the Ingress class, instead of using the Ingress class name.
237350
238-
{{< figure src="/attachments/deployment/private-cloud/private-cloud-cluster/private-cloud-networking/configure-traefik.png" class="no-border" >}}
351+
{{< figure src="/attachments/deployment/private-cloud/private-cloud-cluster/private-cloud-networking/configure-nginx.png" class="no-border" >}}

‎content/en/docs/deployment/private-cloud/private-cloud-supported-environments.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -354,12 +354,11 @@ Mendix on Kubernetes will use the existing ingress controller.
354354
{{% /alert %}}
355355

356356
{{% alert color="warning" %}}
357-
We strongly recommend using the [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/), even if other Ingress controllers or OpenShift Routes are available. You may need to check which of the [several versions of the NGINX Ingress Controller](https://www.nginx.com/blog/guide-to-choosing-ingress-controller-part-4-nginx-ingress-controller-options/#NGINX-vs.-Kubernetes-Community-Ingress-Controller) is installed in your cluster. Mendix recommends the "community version".
357+
The [Kubernetes Ingress NGINX Controller](https://kubernetes.github.io/ingress-nginx/) will be supported [until March 2026](https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/).
358358

359-
NGINX Ingress can be used to deny access to sensitive URLs, add HTTP headers, enable compression, and cache static content.
360-
NGINX Ingress is fully compatible with [cert-manager](https://cert-manager.io/), removing the need to manually manage TLS certificates. In addition, NGINX Ingress can use a [Linkerd](https://linkerd.io/) Service Mesh to encrypt network traffic between the Ingress Controller and the Pod running a Mendix app.
361-
362-
These features will likely be required once your application is ready for production.
359+
We recommend switching to another ingress controller.
360+
The [NGINX Ingress Controller](https://github.com/nginx/kubernetes-ingress) from the NGINX project (F5 Networks) has a similar feature set.
361+
In most cases, switching from the deprecated Kubernetes controller to controller from F5 Networks would only require renaming ingress annotations.
363362
{{% /alert %}}
364363

365364
### OpenShift Route
@@ -386,11 +385,14 @@ It is also possible to provide a custom TLS configuration for individual environ
386385

387386
Mendix on Kubernetes is compatible with the following ingress controllers:
388387

389-
* [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/)
388+
* [NGINX Ingress Controller](https://github.com/nginx/kubernetes-ingress) from the NGINX project
390389
* [Traefik](https://traefik.io/traefik/)
390+
* [Istio Kubernetes Ingress](https://istio.io/latest/docs/tasks/traffic-management/ingress/kubernetes-ingress/)
391+
* [HAProxy Kubernetes Ingress Controller](https://github.com/haproxytech/kubernetes-ingress)
391392
* [AWS Application Load Balancer](https://docs.aws.amazon.com/eks/latest/userguide/alb-ingress.html)
392393
* [Ingress for External Application Load Balancer](https://cloud.google.com/kubernetes-engine/docs/concepts/ingress-xlb)
393394
* [Azure Application Gateway Ingress Controller](https://learn.microsoft.com/en-us/azure/application-gateway/ingress-controller-overview)
395+
* [Deprecated Kubernetes Ingress NGINX Controller](https://kubernetes.github.io/ingress-nginx/) from the Kubernetes project - ⚠️ supported only until March 2026
394396

395397
For ingress, it is possible to do the following:
396398

0 commit comments

Comments
 (0)