Secure Tunnel

A secure tunnel connects your Zuplo gateway to a backend API that isn't reachable from the public internet. You run a small tunnel service inside your network, it opens an outbound connection to Zuplo, and your gateway routes requests back through that connection to your private API.

Tunnels suit backends that run where IAM roles and mTLS aren't available — bare metal, on-premises data centers, or a non-cloud hosting provider. For the other ways to secure gateway-to-backend traffic, see Securing your backend.

A tunnel gives you three things:

• Your API doesn't need to be exposed on the internet at all, because the tunnel dials out rather than accepting inbound connections.
• All traffic between Zuplo and your API is encrypted.
• You don't need to configure ingress, firewall rules, or load balancers to let gateway traffic in. Install the tunnel and Zuplo routes to it.

How a tunnel works

The tunnel is a lightweight service that runs on Linux, most often as a Docker container. On startup it authenticates with a token you generate in Zuplo and establishes an outbound connection to Zuplo's network.

Once connected, the tunnel can reach internal services on your network by their private DNS names. You tell Zuplo which of those services to expose by naming them in a tunnel configuration file. Your gateway then calls each one through the service:// URL scheme instead of a hostname. A service named payments-api becomes service://payments-api, and the tunnel forwards those requests to whatever internal endpoint you mapped it to, such as http://payments.internal:8080.

The following diagram shows the path a request takes. Note that the gateway never opens a connection into your network — it reuses the connection the tunnel already established.

Because the tunnel controls which internal endpoints it forwards to, and Zuplo controls which projects and environments can use each service, no traffic reaches your API until you configure both halves.

Architecture example

The following diagram shows a tunnel running in an AWS ECS cluster. The VPC is fully private: there's no public IP address and no inbound traffic. The tunnel makes an outbound connection to Zuplo, then uses internal DNS to reach the private API.

The same pattern applies to Azure Container Instances, GCP Cloud Run, Kubernetes, and plain Linux hosts. Only the deployment mechanics change.

Security model

Zuplo's tunnel is built on cloudflared, Cloudflare's open source tunnel connector, and inherits Cloudflare's network for transport. Several layers control what can reach your API:

• Token authentication. Each tunnel has its own secret token. Without it, a tunnel instance can't connect.
• Per-tunnel access policies. Each tunnel accepts connections only from the Zuplo gateways you authorize.
• Per-service scoping. Each service in your tunnel configuration names the projects and environments allowed to call it, so a preview environment can't reach a production backend unless you say so.
• Edge protections. Incoming requests terminate on Cloudflare's network, which adds DDoS, bot, and threat protection ahead of your gateway.
• Gateway policies. Requests then pass through your Zuplo gateway, where your own policies and code apply. Until you configure routes and URL rewrites, the gateway sends nothing to your API.

Traffic is terminated with TLS at the edge and encrypted for the rest of the path to your API. Requests your gateway makes to Zuplo's internal services, such as API key management and rate limiting, travel over encrypted connections as well.

Every request is logged, and you can forward gateway logs to the log service of your choice.

Availability and scale

Each tunnel instance opens several connections to more than one Cloudflare data center, so a single instance survives the loss of an individual connection. Run at least two instances so the tunnel keeps serving traffic if a host or pod fails. Instances that share a token act as replicas of the same tunnel, and Zuplo distributes traffic across whichever ones are available.

A single instance handles a high request volume, and adding instances or enabling autoscaling raises the ceiling further. If you have specific throughput requirements, contact support.

Network access control

The tunnel can reach anything its host can reach, so treat its network position as the security boundary. Restrict it to the services you want your gateway to call, using whichever mechanism fits your platform:

• IAM roles or service accounts scoped to specific resources
• Network segmentation, security groups, or egress rules
• Service mesh authorization policies

Naming a service in your tunnel configuration is what makes it callable from Zuplo. Restricting the host is what limits the damage if the tunnel is misconfigured. Do both.

Requirements

Running a tunnel requires:

• A Linux host or container runtime. The zuplo/tunnel image is a Linux container, and non-containerized deployments must target Linux.
• Outbound internet access from the tunnel host, so it can reach Zuplo's network.
• Internal DNS resolution from the tunnel host to your backend services.

Managed container platforms such as AWS ECS, Azure Container Instances, GCP Cloud Run, and Kubernetes run Linux containers by default and need no extra configuration.

Next steps

• Set up a tunnel — create a tunnel, run the container, and expose your first service.
• Connect to tunnel services — call service:// URLs from your gateway code and configuration.
• Advanced tunnel configuration — the cloudflared foundation, environment variable reference, and self-managed images.
• Troubleshoot a tunnel — diagnose a tunnel that's down or not passing traffic.