Towonel Tunnel¶

External traffic reaches the cluster through towonel, a self-hosted tunnel that replaced Cloudflare Tunnel (cloudflared) in July 2026. An agent in the cluster dials out to a hub on a VPS, so the router still needs no inbound port forwards and the home IP stays unpublished.

The tunnel has two halves:

Architecture¶

flowchart LR
    User((User))

    subgraph VPS["ovh-vps — tunnel.wibrow.dev"]
        Caddy[Caddy L4<br/>SNI demux :443]
        Edge[towonel edge]
        Hub[towonel hub<br/>control API]
    end

    subgraph Cluster["pitower"]
        Agent[towonel-agent<br/>2-4 replicas]
        EE[envoy-external]
        Apps[Applications]
    end

    User -->|"HTTPS *.wibrow.dev<br/>(DNS: unproxied CNAME)"| Caddy
    Caddy -->|"tenant SNI"| Edge
    Caddy -->|"SNI = tunnel.wibrow.dev"| Hub
    Edge <-.->|"outbound tunnel"| Agent
    Agent -->|"HTTPS :443"| EE
    EE --> Apps

    classDef vps fill:#f59e0b,stroke:#d97706,color:#000
    classDef gw fill:#7c3aed,stroke:#5b21b6,color:#fff
    class Caddy,Edge,Hub vps
    class EE gw

Traffic flow¶

1. User requests https://myapp.wibrow.dev.
2. Cloudflare DNS returns the unproxied (grey-cloud) CNAME to tunnel.wibrow.dev, which resolves to the VPS. Cloudflare is authoritative DNS only — it is not in the data path.
3. Caddy on the VPS peeks the TLS ClientHello SNI on :443 without decrypting it, and routes tenant hostnames to the towonel edge.
4. The edge forwards the connection over the already-established outbound tunnel to towonel-agent in the cluster.
5. towonel-agent proxies to envoy-external on :443.
6. envoy-external matches the HTTPRoute hostname and routes to the application.

TLS is terminated by envoy-external inside the cluster — the VPS does SNI passthrough and never sees plaintext.

Agent configuration¶

The agent is stateless. It is given an invite token and a list of hostname → origin mappings:

env:
  TOWONEL_AGENT_HEALTH_LISTEN_ADDR: 0.0.0.0:9090
  TOWONEL_AGENT_SERVICES: |
    [
      {"hostname":"*.wibrow.dev","origin":"envoy-external.networking.svc.cluster.local:443"}
    ]
  TOWONEL_INVITE_TOKEN:
    valueFrom:
      secretKeyRef:
        name: towonel-agent-secret
        key: TOWONEL_INVITE_TOKEN

A single wildcard service covers every public hostname, so adding a public app needs no tunnel change — only an HTTPRoute with parentRefs to envoy-external.

The deployment runs 2 replicas with an HPA to 4 on 75% CPU (hpa.yaml), non-root with a read-only root filesystem and all capabilities dropped.

DNS¶

Subdomains are unproxied CNAMEs to the hub — Cloudflare proxying would break the SNI passthrough the edge depends on:

- dnsName: "external.wibrow.dev"
  recordType: CNAME
  targets: ["tunnel.wibrow.dev"]
  providerSpecific:
    - name: external-dns.alpha.kubernetes.io/cloudflare-proxied
      value: "false"
- dnsName: "*.wibrow.dev"
  recordType: CNAME
  targets: ["tunnel.wibrow.dev"]
  providerSpecific:
    - name: external-dns.alpha.kubernetes.io/cloudflare-proxied
      value: "false"

The wildcard means an unmatched subdomain still reaches the edge and hits the envoy-external fallback 404 route rather than returning NXDOMAIN.

Health and troubleshooting¶

The agent serves /healthz on :9090, used for all three probes.

# Agent status
kubectl get pods -n networking -l app.kubernetes.io/name=towonel-agent
kubectl logs -n networking -l app.kubernetes.io/name=towonel-agent --tail=50

# Hub status (on the VPS)
systemctl status towonel-hub
docker logs -f towonel

# Is the hub reachable and presenting a valid cert? (run off-VPS)
curl -v https://tunnel.wibrow.dev/v1/health

# Confirm DNS is unproxied — the answer must be the VPS IP, not a Cloudflare IP
dig +short external.wibrow.dev