Networking

There are four separate parts to networking in Upvale:

A private node network does not make every workload private. Public routes and published ports are separate decisions.

Choose a node network

Choose Swarm node network when you create the cluster. The choice is fixed for the cluster's lifetime.

The mode does not determine whether a node is a manager or worker. Both roles use the same cluster network.

Private VPC / VPN

Add the existing networks under Routed subnets. Each has a name, an IPv4 CIDR, and a priority. For example, 10.20.0.0/16 identifies the addresses used by a provider's private network.

Upvale selects an address from those reported by the node. Lower priority numbers win between candidate networks. If multiple configured ranges contain the same address, the more specific range applies. If equally suitable addresses remain, Upvale can ask you to select one on the node's Overview.

Every selected node address must be reachable from every other node. Different subnets are fine if VPC peering, your VPN, or other routing connects them. Entering a CIDR in Upvale does not create that routing or change the provider's firewall.

After a node joins Swarm, its selected address stays fixed. Changing subnet priorities does not silently move an existing member to another interface. You can add subnets in Cluster → Networking; a subnet in use by an active node cannot be removed.

Public / mixed

Configure any existing routed subnets as above. A node without a matching address may use a stable public IPv4 address instead.

Use Advertised public IPv4 during enrollment only when the server is behind 1:1 NAT and its public address is not reported on an interface. That address must actually forward the required connections to the server.

This mode picks one Swarm address for each node. It does not create private connectivity, and it is different from managed WireGuard choosing a private or public tunnel endpoint for each peer. A private address selected for one node must still be reachable by the other nodes.

Restrict Swarm ports to the exact cluster peer addresses. This mode does not add WireGuard encryption to container traffic; use application TLS or select Managed WireGuard when you want an encrypted node network.

Managed WireGuard

Upvale builds a full mesh: nodes establish encrypted tunnels directly to one another. Container traffic crosses those tunnels, and Swarm uses stable addresses from the mesh range, which defaults to 10.10.0.0/16.

The mesh address is different from the tunnel's transport endpoint. For example, a node can keep mesh address 10.10.0.5 while one peer reaches its private VPC address and another peer reaches its public address.

How private and public endpoints are chosen

Agents report interface addresses and routing information. Upvale tries eligible endpoints, preferring private addresses before directly assigned public addresses and configured NAT overrides. It verifies the path with WireGuard peer probes before accepting it.

That is why two nodes in one reachable VPC can use private transport while nodes in another region use public transport. The decision is based on working paths, not the region name or an assumption that all 10.x addresses are connected.

The provider's routing and firewall still need to permit the chosen UDP endpoint. Upvale cannot open your provider firewall for you.

Address ranges and MTU

The default mesh UDP port is 51820, WireGuard MTU is 1380, and Docker overlay MTU is 1330. Docker's container address pool is separate from the mesh range and can be selected automatically.

Choose nonoverlapping ranges for the mesh, Docker pool, Developer VPN devices, and other private networks you need to reach. The overlay MTU must remain at least 50 bytes smaller than the WireGuard MTU.

An Endpoint IPv4 override is an optional public or routed destination for tunnel packets. It does not assign the mesh IP and is usually unnecessary. Endpoint UDP port supports a NAT mapping whose outside port differs from the node's listen port.

Host firewall ownership

Managed WireGuard configures bounded host firewall rules for the mesh and Swarm traffic. Nodes need WireGuard and nftables support. Conflicting active UFW or firewalld policy can prevent the managed-host checks from passing; resolve that conflict before retrying setup.

When required mesh validation fails, an operation can stop rather than expose raw Swarm traffic on the public interface. Read the failed operation and the node's Managed WireGuard diagnostics to identify the failed path or host check.

Required connections

Use the endpoints supplied by Upvale for your account. Enrollment and agent gateway ports normally use TCP 4443 and 4444.

The control plane communicates through the outbound agent connection; it does not require inbound SSH to your nodes. Keep whatever SSH access you need for your own server administration separate.

For Managed WireGuard, keep raw Swarm ports closed outside the mesh. For Public / mixed, restrict those ports to exact peer addresses. Opening Docker's remote API to the internet is not part of setup.

Workload networks and hostnames

Standalone applications, databases, and scheduled jobs use the cluster's shared workload overlay. A service can run on one node and connect to a service on another through that overlay.

Use the internal hostname shown by the resource rather than a container IP. Containers can be replaced during deployment; the service hostname is the stable address applications should use. For a database, copy the internal host, port, database name, and credentials from Connection.

Projects and environments organize resources but do not isolate standalone workloads from other services on that shared cluster network. Use separate clusters when you need a network separation boundary.

The internal hostname is Docker service discovery inside the workload network. It is not automatically a public DNS record or a name your laptop can resolve.

Compose networks

Managed Compose translates supported Compose services into normal Upvale resources. It also creates a managed overlay for each used logical network in the file. A service receives its declared network memberships and aliases.

For example, if an API and database both join backend, the API can reach the database using its Compose service alias. A frontend that joins only frontend cannot reach that database through backend unless you also attach it to that network.

Services without explicit networks use the Compose default network. Compose resources do not automatically join the standalone workload overlay. Upvale scopes the networks to the managed Compose deployment rather than taking an unrelated host network merely because it has the same name.

For an HTTP route, Traefik joins the selected network used to reach that Compose service. Unsupported network features are reported during preview; resolve them before applying. See Managed Compose for the supported file format and lifecycle.

Public HTTP traffic

The usual request path is:

Visitor → domain DNS → ingress node or external load balancer
        → Traefik → application service → running container

Choose ingress nodes under Cluster → Ingress & TLS, then add an application route with a hostname and target port. Point the domain to the selected ingress address. Route settings control TLS, path changes, and middleware; Routes and traffic covers those options.

Selecting several ingress nodes does not create a provider load balancer. You still decide how DNS, a floating IP, or a load balancer sends traffic to that pool.

Database and other non-HTTP connections

Use internal connections for applications in the workload network. Traefik's normal application routes are HTTP routes, not PostgreSQL, MySQL, MongoDB, or Redis connection URLs.

A database's External access publishes a TCP port. A published port can be reached through an allowed node address, including a private mesh address when the network and firewall permit it. Publishing the port is separate from permitting public internet access: restrict public reachability at your provider firewall.

For a developer laptop, use Developer VPN and an explicit database access rule. Connecting the VPN does not automatically publish every internal container service.

Troubleshooting