From c46af7d038ff1f103da1ccc299825788aa43794b Mon Sep 17 00:00:00 2001 From: nicoletacoman Date: Fri, 8 May 2026 16:26:33 +0200 Subject: [PATCH 1/6] Private Connectivity best practices --- .../private-connectivity/best-practices.md | 103 ++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 content/en/docs/control-center/security/private-connectivity/best-practices.md diff --git a/content/en/docs/control-center/security/private-connectivity/best-practices.md b/content/en/docs/control-center/security/private-connectivity/best-practices.md new file mode 100644 index 00000000000..953b87093a4 --- /dev/null +++ b/content/en/docs/control-center/security/private-connectivity/best-practices.md @@ -0,0 +1,103 @@ +--- +title: "Private Connectivity Best Practices" +url: /control-center/private-connectivity/best-practices/ +description: "Provides best practices for configuring and using Private Connectivity in Mendix Control Center." +weight: 2 +beta: true +--- + +{{% alert color="warning" %}} +Private Connectivity is currently in Public Beta, and will be out of Public Beta on May 31, 2026. After that date, the service will no longer be available, and Mendix will start preparing it for General Availability (GA). Check the [Feature Release Calendar](/releasenotes/feature-release-calendar/) for details on the GA release date. +{{% /alert %}} + +## Introduction + +This page provides best practices for configuring and using Private Connectivity networks, agents, and resources. Following these guidelines helps ensure secure, efficient, and maintainable connections between your Mendix apps and internal infrastructure. + +## Authentication Key Security + +Creating an agent involves creating an authentication key. Agents registered with that authentication key join the agent's network. If you have a production network, only use the generated authentication key for agents placed in your production network. Apply the same principle for development networks. + +## When to Create Networks + +Create a new network only when you have a clear need for isolated networks. Examples include: + +* Environment isolation – Separate production traffic from non-production traffic. +* Organizational separation – Different business units or regional offices, such as separate networks for APAC and EMEA teams. + +The crucial aspect in each network is agent placement. If you create a network for development use only, place agents only in the development environment of your organization's network. + +## Working with Agents + +Agents determine what parts of your infrastructure are accessible. While creating separate networks can help organize your apps on the Mendix side, agents and their placement ultimately determine what infrastructure is accessible. + +### Where to Place Agents + +An agent forwards traffic to the advertised subnets. Place it where it can access those addresses: + +* AWS – Place the agent in your VPC. +* Azure – Place the agent in your VNet. +* On-premises – Place the agent where it has network access to the target resources. + +### Infrastructure Requirements + +Install agents on infrastructure that has direct network reachability to the resources you want to advertise. Typically, a virtual machine (VM) or other host inside the relevant VPC or VNet is the best fit. + +Tailscale supports both Linux and Windows. For the best results and performance, use Linux due to its [kernel integration](https://tailscale.com/docs/reference/kernel-vs-userspace-routers). + +For recommendations on operating system tweaks and machine sizing for the main cloud providers, refer to [Tailscale's performance best practices](https://tailscale.com/docs/reference/best-practices/performance#operating-system-recommendations). + +Suitable infrastructure for agents includes EC2 instances, VMs, and containers with privileged access on EKS or AKS. + +### How Many Agents Do You Need? + +It is more efficient to use one agent with multiple advertised subnets. You can advertise as wide a CIDR range as you need, or as many subnets as necessary on one agent. Using one agent requires less effort to install and is cheaper in both time and maintenance cost. + +However, you need to consider these trade-offs: + +* If you use one agent to expose multiple resources and it suffers an outage or requires maintenance, you may affect more Mendix apps than desired. +* Consider grouping agents by function, advertising only the routes necessary for a particular Mendix app, and creating separate agents for other apps. + +### High Availability + +Subnet routers support high availability. To set this up, create two or more agents that advertise the same routes. For example, if you set up two routers that both advertise `10.0.0.0/16`, the first agent acts as the primary and the second as the failover. + +This setup provides a simple active/passive failover, not load balancing. When Tailscale detects that your primary subnet router is offline, routing immediately switches to the failover device. + +For more information, refer to [Subnet Router High Availability](https://tailscale.com/docs/how-to/set-up-high-availability#subnet-router-high-availability). + +## Using Containers + +Containerized platforms are common, and you may want to keep your agent deployment consistent with the rest of your infrastructure. Tailscale can run in containers, but there are some important considerations. + +### State Persistence + +When a Tailscale container starts, it generates a node key to identify itself and register with the Tailscale control plane. If that key is not persisted, every container restart generates a new key and attempts to register as a new device. Since authentication keys created via the Mendix wizard are single-use, this causes authentication failures. You must persist the state of the container so it remembers itself after each restart. + +Use these parameters to avoid authentication failure issues: + +* Use the `TS_AUTHKEY` parameter to supply the authentication key to your container. For more information, refer to [TS_AUTHKEY](https://tailscale.com/docs/features/containers/docker/docker-params#ts_authkey). +* Use the `TS_AUTH_ONCE` parameter to ensure the container only attempts authentication once. This helps avoid *API key not found* errors on container restarts. For more information, refer to [TS_AUTH_ONCE](https://tailscale.com/docs/features/containers/docker/docker-params#ts_auth_once). +* Use the `TS_STATE_DIR` parameter to declare a space to save the state, then mount it as a volume. For more information, refer to [TS_STATE_DIR](https://tailscale.com/docs/features/containers/docker/docker-params#ts_state_dir). +* On Kubernetes, use the `TS_KUBE_SECRET` parameter to store the state in a secret. The value is the name you want to give that secret. If it is not set, it defaults to `tailscale`. For more information, refer to [TS_KUBE_SECRET](https://tailscale.com/docs/features/containers/docker/docker-params#ts_kube_secret). + +### Privilege Requirements + +Tailscale typically runs in kernel (TUN) mode. If your environment permits privileged containers or host networking, that is the better choice for a subnet router. If it does not, you can run the subnet router in userspace mode, but this is better suited for lighter-duty use and is not the first recommendation for higher-throughput production routing. + +For example, Azure Container Apps do not have privileged container access, so you need to enable userspace mode. For more information, refer to the following pages in the Tailscale documentation: + +* [Docker containers](https://tailscale.com/docs/features/containers/docker) +* [Userspace networking mode](https://tailscale.com/docs/concepts/userspace-networking#start-tailscale-in-userspace-networking-mode) + +## Advertised Routes + +Mendix uses Tailscale subnet routers to advertise routes to your network. This gives you full control over where the agent forwards traffic within your network. + +### Routes to Advertise + +The routes you advertise depend on what your Mendix Cloud app needs to access and what you want to share: + +* Single resource – If your app only needs to reach one specific resource, advertise that single address via a `/32` subnet mask (for example, `192.168.1.10/32`). +* App subnet – If you host all apps in one specific subnet, use the subnet CIDR (for example, `192.168.1.0/24`). +* Entire network – If you want to share the entire network to avoid repeatedly opening new routes, use the entire VPC or VNet CIDR (for example, `192.168.0.0/16`). From 81c49f085cb924a633ca8c6ea69df6481d92df04 Mon Sep 17 00:00:00 2001 From: nicoletacoman Date: Fri, 8 May 2026 16:28:10 +0200 Subject: [PATCH 2/6] Changed heading --- .../security/private-connectivity/best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/control-center/security/private-connectivity/best-practices.md b/content/en/docs/control-center/security/private-connectivity/best-practices.md index 953b87093a4..f91dfa5761c 100644 --- a/content/en/docs/control-center/security/private-connectivity/best-practices.md +++ b/content/en/docs/control-center/security/private-connectivity/best-practices.md @@ -49,7 +49,7 @@ For recommendations on operating system tweaks and machine sizing for the main c Suitable infrastructure for agents includes EC2 instances, VMs, and containers with privileged access on EKS or AKS. -### How Many Agents Do You Need? +### Recommended Number of Agents It is more efficient to use one agent with multiple advertised subnets. You can advertise as wide a CIDR range as you need, or as many subnets as necessary on one agent. Using one agent requires less effort to install and is cheaper in both time and maintenance cost. From 67de54c6054b53c1ca94854dc6488cc715ce8b8d Mon Sep 17 00:00:00 2001 From: nicoletacoman Date: Mon, 11 May 2026 11:23:52 +0200 Subject: [PATCH 3/6] Minor changes --- .../security/private-connectivity/best-practices.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/control-center/security/private-connectivity/best-practices.md b/content/en/docs/control-center/security/private-connectivity/best-practices.md index f91dfa5761c..ff3389197d9 100644 --- a/content/en/docs/control-center/security/private-connectivity/best-practices.md +++ b/content/en/docs/control-center/security/private-connectivity/best-practices.md @@ -68,7 +68,7 @@ For more information, refer to [Subnet Router High Availability](https://tailsca ## Using Containers -Containerized platforms are common, and you may want to keep your agent deployment consistent with the rest of your infrastructure. Tailscale can run in containers, but there are some important considerations. +Containerized platforms are common, and help keep your agent deployment consistent with the rest of your infrastructure. Tailscale can run in containers, but Mendix recommends you keep in mind the following important considerations. ### State Persistence @@ -83,7 +83,7 @@ Use these parameters to avoid authentication failure issues: ### Privilege Requirements -Tailscale typically runs in kernel (TUN) mode. If your environment permits privileged containers or host networking, that is the better choice for a subnet router. If it does not, you can run the subnet router in userspace mode, but this is better suited for lighter-duty use and is not the first recommendation for higher-throughput production routing. +Tailscale typically runs in kernel (TUN) mode. If your environment allows privileged containers or host networking, that is the better choice for a subnet router. If it does not, you can run the subnet router in userspace mode, but this is better suited for lighter-duty use, and is not the first recommendation for higher-throughput production routing. For example, Azure Container Apps do not have privileged container access, so you need to enable userspace mode. For more information, refer to the following pages in the Tailscale documentation: From 8886357f4269c1c380ea0e5281a535c55dbeecf8 Mon Sep 17 00:00:00 2001 From: Olufunke Moronfolu Date: Mon, 11 May 2026 11:52:47 +0200 Subject: [PATCH 4/6] connections update for deployment --- .../connecting-external-resources.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/content/en/docs/deployment/mendix-cloud-deploy/connecting-external-resources.md b/content/en/docs/deployment/mendix-cloud-deploy/connecting-external-resources.md index 5a8544097ad..6c51a50e55d 100644 --- a/content/en/docs/deployment/mendix-cloud-deploy/connecting-external-resources.md +++ b/content/en/docs/deployment/mendix-cloud-deploy/connecting-external-resources.md @@ -23,15 +23,22 @@ This page describes how Technical Contacts can request and manage connections to Before requesting a connection, the following conditions must be met: * You are the [Technical Contact](/developerportal/general/app-roles/#technical-contact) for the Mendix application. -* A Mendix Admin has created and configured the necessary private network in the [Control Center](/control-center/configure-private-connectivity/). This includes installing agents and exposing the specific external resource you want to access. +* A Mendix Admin has created and configured the necessary private network in the [Control Center](/control-center/configure-private-connectivity/). This includes installing agents and [exposing the specific external resource](/control-center/configure-private-connectivity/#private-connectivity-resources-expose) you want to access. ## Connections {#connections} Mendix Cloud Connect Connections allow applications on Mendix Cloud to connect to Mendix Cloud Connect Resources over Mendix Cloud Connect Networks. Each connection request must be initiated by a Technical Contact and approved by a Mendix Admin before the application on Mendix Cloud can connect to the resource. -An application on Mendix Cloud can establish multiple connections to various resources. You can view and manage all connections and their statuses on the [Connectivity](/developerportal/deploy/environments-details/#connections) or [Change Requests](/developerportal/deploy/connecting-to-external-resource/#view-connection-details) tab. +Connections use a private Tailscale network called [Tailnet](https://tailscale.com/docs/concepts/tailnet). Within this Tailnet, a subnet router advertises a subnet/CIDR range, enabling your Mendix Cloud application to securely route traffic to specific applications on your organization’s network. All connectivity remains within the private Tailnet. -{{% alert color="info" %}} An application environment can only connect to a single private network at a time. This means that all external resources you connect to from an application environment must be on the same private network.{{% /alert %}} +An application on Mendix Cloud can establish multiple connections to different resources. You can view and manage all connections and their statuses on the [Connectivity](/developerportal/deploy/environments-details/#connections) or [Change Requests](/developerportal/deploy/connecting-to-external-resource/#view-connection-details) tab. + +{{% alert color="info" %}} + +* An application environment can only connect to a single private network at a time. This means that all external resources you connect to from an application environment must be on the same private network. +* Mendix does not support connections from your organization's network to Mendix Cloud applications. +* Connections between [agents](/control-center/private-connectivity/#agents) are not supported. +{{% /alert %}} ### Requesting a New Connection {#connection-request} From 8b03949673363e778ec274243b3c7dd597dcc1e9 Mon Sep 17 00:00:00 2001 From: nicoletacoman Date: Wed, 13 May 2026 15:52:20 +0200 Subject: [PATCH 5/6] First round of feedback --- .../private-connectivity/best-practices.md | 33 +++++++++---------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/content/en/docs/control-center/security/private-connectivity/best-practices.md b/content/en/docs/control-center/security/private-connectivity/best-practices.md index ff3389197d9..00b045d1935 100644 --- a/content/en/docs/control-center/security/private-connectivity/best-practices.md +++ b/content/en/docs/control-center/security/private-connectivity/best-practices.md @@ -14,9 +14,13 @@ Private Connectivity is currently in Public Beta, and will be out of Public Beta This page provides best practices for configuring and using Private Connectivity networks, agents, and resources. Following these guidelines helps ensure secure, efficient, and maintainable connections between your Mendix apps and internal infrastructure. +{{% alert color="info" %}} +Mendix uses Tailscale subnet routers to access routes in your network. In a Mendix context, these are called agents. +{{% /alert %}} + ## Authentication Key Security -Creating an agent involves creating an authentication key. Agents registered with that authentication key join the agent's network. If you have a production network, only use the generated authentication key for agents placed in your production network. Apply the same principle for development networks. +Creating an agent involves creating an authentication key. An agent registered with that authentication key can join the agent's network. If you have a production network, only use the generated authentication key for agents placed in your production network. Apply the same principle for development networks. ## When to Create Networks @@ -33,25 +37,21 @@ Agents determine what parts of your infrastructure are accessible. While creatin ### Where to Place Agents -An agent forwards traffic to the advertised subnets. Place it where it can access those addresses: - -* AWS – Place the agent in your VPC. -* Azure – Place the agent in your VNet. -* On-premises – Place the agent where it has network access to the target resources. +Place the agent where it has network access to the target resources. ### Infrastructure Requirements -Install agents on infrastructure that has direct network reachability to the resources you want to advertise. Typically, a virtual machine (VM) or other host inside the relevant VPC or VNet is the best fit. +Install agents on infrastructure that has direct network reachability to the resources you want to advertise, i.e. provide access to. Typically, a virtual machine (VM) or other host inside the relevant VPC or VNet is the best fit. Tailscale supports both Linux and Windows. For the best results and performance, use Linux due to its [kernel integration](https://tailscale.com/docs/reference/kernel-vs-userspace-routers). For recommendations on operating system tweaks and machine sizing for the main cloud providers, refer to [Tailscale's performance best practices](https://tailscale.com/docs/reference/best-practices/performance#operating-system-recommendations). -Suitable infrastructure for agents includes EC2 instances, VMs, and containers with privileged access on EKS or AKS. +Suitable infrastructure for agents includes EC2 instances and VMs. -### Recommended Number of Agents +### Agent Placement Strategy -It is more efficient to use one agent with multiple advertised subnets. You can advertise as wide a CIDR range as you need, or as many subnets as necessary on one agent. Using one agent requires less effort to install and is cheaper in both time and maintenance cost. +It is more efficient to use one agent with multiple advertised subnets. You can advertise as wide a subnet range as you need, or as many subnets as necessary on one agent. Using one agent requires less effort to install and is cheaper in both time and maintenance cost. However, you need to consider these trade-offs: @@ -60,9 +60,9 @@ However, you need to consider these trade-offs: ### High Availability -Subnet routers support high availability. To set this up, create two or more agents that advertise the same routes. For example, if you set up two routers that both advertise `10.0.0.0/16`, the first agent acts as the primary and the second as the failover. +Agents support high availability. To set this up, create two or more agents that advertise the same routes. For example, if you set up two routers that both advertise `10.0.0.0/16`, the first agent acts as the primary and the second as the failover. -This setup provides a simple active/passive failover, not load balancing. When Tailscale detects that your primary subnet router is offline, routing immediately switches to the failover device. +This setup provides a simple active/passive failover, not load balancing. When Tailscale detects that your primary agent is offline, routing immediately switches to the failover device. For more information, refer to [Subnet Router High Availability](https://tailscale.com/docs/how-to/set-up-high-availability#subnet-router-high-availability). @@ -79,11 +79,10 @@ Use these parameters to avoid authentication failure issues: * Use the `TS_AUTHKEY` parameter to supply the authentication key to your container. For more information, refer to [TS_AUTHKEY](https://tailscale.com/docs/features/containers/docker/docker-params#ts_authkey). * Use the `TS_AUTH_ONCE` parameter to ensure the container only attempts authentication once. This helps avoid *API key not found* errors on container restarts. For more information, refer to [TS_AUTH_ONCE](https://tailscale.com/docs/features/containers/docker/docker-params#ts_auth_once). * Use the `TS_STATE_DIR` parameter to declare a space to save the state, then mount it as a volume. For more information, refer to [TS_STATE_DIR](https://tailscale.com/docs/features/containers/docker/docker-params#ts_state_dir). -* On Kubernetes, use the `TS_KUBE_SECRET` parameter to store the state in a secret. The value is the name you want to give that secret. If it is not set, it defaults to `tailscale`. For more information, refer to [TS_KUBE_SECRET](https://tailscale.com/docs/features/containers/docker/docker-params#ts_kube_secret). ### Privilege Requirements -Tailscale typically runs in kernel (TUN) mode. If your environment allows privileged containers or host networking, that is the better choice for a subnet router. If it does not, you can run the subnet router in userspace mode, but this is better suited for lighter-duty use, and is not the first recommendation for higher-throughput production routing. +Tailscale typically runs in kernel (TUN) mode. If your environment allows privileged containers or host networking, that is the better choice for an agent. If it does not, you can run the agent in userspace mode, but this is better suited for lighter-duty use, and is not the first recommendation for higher-throughput production routing. For example, Azure Container Apps do not have privileged container access, so you need to enable userspace mode. For more information, refer to the following pages in the Tailscale documentation: @@ -98,6 +97,6 @@ Mendix uses Tailscale subnet routers to advertise routes to your network. This g The routes you advertise depend on what your Mendix Cloud app needs to access and what you want to share: -* Single resource – If your app only needs to reach one specific resource, advertise that single address via a `/32` subnet mask (for example, `192.168.1.10/32`). -* App subnet – If you host all apps in one specific subnet, use the subnet CIDR (for example, `192.168.1.0/24`). -* Entire network – If you want to share the entire network to avoid repeatedly opening new routes, use the entire VPC or VNet CIDR (for example, `192.168.0.0/16`). +* Single resource – If your app only needs to reach one specific resource, advertise it as a `/32` route (for example, `192.168.1.10/32`). +* App subnet – If you host all apps in one specific subnet, use the subnet router (for example, `192.168.1.0/24`). +* Entire network – If you want to share the entire network to avoid repeatedly opening new routes, use the entire VPC or VNet subnet router (for example, `192.168.0.0/16`). From 05f0c4278e0f8e10b2726a36a8d2d494cc09865a Mon Sep 17 00:00:00 2001 From: nicoletacoman Date: Wed, 13 May 2026 17:56:54 +0200 Subject: [PATCH 6/6] Linked to Agents page --- .../security/private-connectivity/best-practices.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/en/docs/control-center/security/private-connectivity/best-practices.md b/content/en/docs/control-center/security/private-connectivity/best-practices.md index 00b045d1935..201d2284095 100644 --- a/content/en/docs/control-center/security/private-connectivity/best-practices.md +++ b/content/en/docs/control-center/security/private-connectivity/best-practices.md @@ -66,6 +66,8 @@ This setup provides a simple active/passive failover, not load balancing. When T For more information, refer to [Subnet Router High Availability](https://tailscale.com/docs/how-to/set-up-high-availability#subnet-router-high-availability). +To monitor agent health, access the **Agents** tab of the **Private Connectivity** page in Control Center. You can find details about this tab in the [Agents](/control-center/configure-private-connectivity/#private-connectivity-agents) section of the *Configuring and Using Private Connectivity* page. + ## Using Containers Containerized platforms are common, and help keep your agent deployment consistent with the rest of your infrastructure. Tailscale can run in containers, but Mendix recommends you keep in mind the following important considerations.