Skip to content

Commit c1a8394

Browse files
katarzyna-koltun-mxkatarzyna-koltun-mx
authored
Merge pull request mendix#10441 from zlogic/fix-ingress-deprecation
Updated MxOK ingress documentation (no release date)
2 parents 31c41e5 + 1d51200 commit c1a8394

4 files changed

Lines changed: 149 additions & 28 deletions

File tree

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ OpenShift Routes remain a suitable choice if meet your current needs and you do
7777

7878
## Known Issues
7979

80-
* Application load balancers do not work correctly with HTTP2 WebSockets.
80+
* AWS Application Load Balancers do not work correctly with HTTP2 WebSockets.
8181

8282
As a workaround, you can use HTTP1 as the ingress backend protocol: `alb.ingress.kubernetes.io/backend-protocol-version: HTTP1`
8383

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

Lines changed: 19 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -69,15 +69,19 @@ In this way, you can configure the following settings:
6969
* Specify the name of an existing TLS certificate secret.
7070
* Provide TLS Certificate and Private Key values directly in the environment specification.
7171

72-
## Configuring Headers in NGINX Ingress
72+
## Configuring HTTP Headers
7373

74-
For NGINX Ingress, you can set headers in a namespace which will further be propagated across all apps in that namespace by using a configuration snippet in the OperatorConfiguration object. Alternatively, you can configure headers for individual app environments by adding the `nginx.ingress.kubernetes.io/configuration-snippet` annotation in the Mendix on Kubernetes Portal.
74+
You can configure HTTP headers for NGINX Ingress and for Mendix Runtime. For more information, refer to the following sections.
75+
76+
### Configuring Headers in NGINX Ingress
77+
78+
For NGINX Ingress (from F5 Networks), you can use a configuration snippet in the `OperatorConfiguration` object to set headers in a namespace. The headers that you set are then further propagated across all apps in that namespace. Alternatively, you can configure headers for individual app environments by adding the `nginx.org/location-snippets` annotation in the Mendix on Kubernetes Portal.
7579

7680
{{< figure src="/attachments/deployment/private-cloud/private-cloud-cluster/private-cloud-networking/advanced-headers.png" class="no-border" >}}
7781

78-
Mendix only supports unencrypted HTTP between the Ingress controller and the app. However, there is no higher level of security with service-to-service encryption and policy controls. In such situation, integrating Ingress controllers with Istio Service Mesh or Linkerd can help you manage both external traffic entering your Kubernetes cluster (by using an Ingress Controller) and internal traffic between services (by using Istio or Linkerd).
82+
Mendix only supports unencrypted HTTP between the Ingress controller and the app. However, there is no higher level of security with service-to-service encryption and policy controls. In such situations, integrating Ingress controllers with Istio Service Mesh or Linkerd can help you manage both external traffic entering your Kubernetes cluster (by using an Ingress Controller) and internal traffic between services (by using Istio or Linkerd).
7983

80-
Istio Service Mesh and Linkerd help manage service-to-service communication within a Kubernetes cluster. It provides features such as the following:
84+
Istio Service Mesh and Linkerd help manage service-to-service communication within a Kubernetes cluster. It provides the following features:
8185

8286
* Traffic management (for example, canary releases)
8387
* Service discovery
@@ -91,7 +95,15 @@ In an Istio- or Linkerd-enabled Kubernetes cluster, an Ingress controller can be
9195
AWS Application Load Balancer and Azure Application Gateway Ingress Controller only work with Istio.
9296
{{% /alert %}}
9397

94-
### Istio Service Mesh Integration with Ingress Controller
98+
### Configuring Headers in the Mendix Runtime
99+
100+
Starting from Mendix 10.24.1, the Mendix Runtime can set headers natively, without relying on an external Ingress controller.
101+
102+
This allows specifying security headers such as `Content-Security-Policy` with any Ingress controller, not just NGINX Ingress.
103+
104+
To set headers, use the [Network Tab](/developerportal/deploy/private-cloud-deploy/#network-tab) (for Connected environments) or the [Headers](/refguide/custom-settings/#Headers) Custom Runtime Setting the [.spec.runtime.customConfiguration field](/developerportal/deploy/private-cloud-operator/#edit-cr) in the MendixApp CR.
105+
106+
## Istio Service Mesh Integration with Ingress Controller
95107

96108
To integrate the Istio Service Mesh with an Ingress Controller, perform the following steps:
97109

@@ -111,7 +123,6 @@ To integrate the Istio Service Mesh with an Ingress Controller, perform the foll
111123
6. In Istio, configure a [Gateway](https://istio.io/latest/docs/reference/config/networking/gateway/) resource to allow traffic through the ingress gateway.
112124
7. Define a [VirtualService](https://istio.io/latest/docs/reference/config/networking/virtual-service/) to route traffic from the gateway to a service in the mesh.
113125
114-
#### Configuring the Istio Service Mesh in the Mxpc-cli Tool
115126
116127
To configure the Istio Service Mesh for Mendix on Kubernetes, set up the following settings:
117128
@@ -124,7 +135,7 @@ To configure the Istio Service Mesh for Mendix on Kubernetes, set up the followi
124135
125136
{{< figure src="/attachments/deployment/private-cloud/private-cloud-cluster/private-cloud-networking/advanced-istio.png" class="no-border" >}}
126137
127-
### Installing Linkerd
138+
## Installing Linkerd
128139
129140
To install Linkerd, perform the following steps:
130141
@@ -141,7 +152,7 @@ To install Linkerd, perform the following steps:
141152
kubectl annotate {namespace} linkerd.io/inject=enabled
142153
```
143154
144-
#### Configuring Linkerd Ingress in the Mxpc-cli Tool
155+
### Configuring Linkerd Ingress in the Mxpc-cli Tool
145156
146157
To configure Linkerd for Mendix on Kubernetes, set up the following settings:
147158

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

Lines changed: 124 additions & 12 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.
@@ -226,13 +287,64 @@ Traefik uses 2 types of providers: CRDs or Kubernetes Ingress. Ensure that you i
226287
#### Configuring Traefik in the Mxpc-cli Tool
227288
228289
To configure Traefik for Mendix on Kubernetes, set up the following settings:
229-
230-
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
290+
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
231291
* **Ingress Domain Name** - Provide the domain name which was registered for Traefik
232-
* **Ingress Path** - Set to `/*`.
292+
* **Ingress Path** - Set to `/*`.
233293
* **Enable TLS** - Enable or disable TLS for your app's Ingress.
234294
* **Custom Ingress Class** - Set to **enabled**.
235295
* **Ingress Class Name** - Enter **traefik**. This setting requires Custom Ingress Class to be enabled.
236296
* **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.
237297
238298
{{< figure src="/attachments/deployment/private-cloud/private-cloud-cluster/private-cloud-networking/configure-traefik.png" class="no-border" >}}
299+
300+
### Istio Ingress Controller
301+
302+
Istio is a service mesh that includes a simple [ingress contoller](https://istio.io/latest/docs/tasks/traffic-management/ingress/kubernetes-ingress/).
303+
304+
#### Installing Istio
305+
306+
To install Istio, follow the [installation instructions](https://istio.io/latest/docs/overview/quickstart/).
307+
308+
Ensure that you also install an [Istio IngressClass](https://istio.io/latest/docs/tasks/traffic-management/ingress/kubernetes-ingress/).
309+
310+
{{% alert color="info" %}}
311+
Istio is a feature-rich system with many configuration options. To validate an Istio configuration, it is highly recommended to test with a simple (non-Mendix) app to validate configuration.
312+
{{% /alert %}}
313+
314+
#### Configuring Istio in the Mxpc-cli Tool
315+
316+
To configure Istio for Mendix on Kubernetes, configure the following settings:
317+
318+
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
319+
* **Ingress Domain Name** - Provide the domain name which was registered for Istio
320+
* **Ingress Path** - Set to `/*`.
321+
* **Enable TLS** - Enable or disable TLS for your app's Ingress.
322+
* **Custom Ingress Class** - Set to **enabled**.
323+
* **Ingress Class Name** - Enter **istio**. This setting requires **Custom Ingress Class** to be enabled.
324+
* **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.
325+
326+
### NGINX Ingress Controller (Deprecated)
327+
328+
{{% alert color="warning" %}}
329+
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/).
330+
331+
We recommend switching to another Ingress controller. The [NGINX Ingress Controller](https://github.com/nginx/kubernetes-ingress) from the NGINX project (F5 Networks) has a similar feature set. In most cases, switching from the deprecated Kubernetes controller to controller from F5 Networks only requires renaming Ingress annotations.
332+
{{% /alert %}}
333+
334+
{{% alert color="info" %}}
335+
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.
336+
{{% /alert %}}
337+
338+
##### Configuring the NGINX in the Mxpc-cli Tool
339+
340+
To configure the deprecated NGINX ingress controller with Mendix on Kubernetes, set up the following settings:
341+
342+
* **Ingress Type** - Select **kubernetes-ingress**; this option configures the Ingress according to the additional domain name you supply.
343+
* **Ingress Domain Name** - Provide the domain name which you want to set for the Ingress resource file.
344+
* **Ingress Path** - Optional. You can use this option to specify the Ingress path. The default value is `/`.
345+
* **Enable TLS** - Enable or disable TLS for your app's Ingress.
346+
* **Custom Ingress Class** - Set to **enabled**.
347+
* **Ingress Class Name** - Enter **nginx**. This setting requires **Custom Ingress Class** to be enabled.
348+
* **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.
349+
350+
{{< 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: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -354,12 +354,7 @@ 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".
358-
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.
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/). We recommend switching to another Ingress controller. The [NGINX Ingress Controller](https://github.com/nginx/kubernetes-ingress) from the NGINX project (F5 Networks) has a similar feature set. In most cases, switching from the deprecated Kubernetes controller to controller from F5 Networks only requires renaming Ingress annotations.
363358
{{% /alert %}}
364359

365360
### OpenShift Route
@@ -386,11 +381,14 @@ It is also possible to provide a custom TLS configuration for individual environ
386381

387382
Mendix on Kubernetes is compatible with the following ingress controllers:
388383

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

395393
For ingress, it is possible to do the following:
396394

0 commit comments

Comments
 (0)