Services from an agent

An agent can join the tunnel’s private network and forward chosen ports to services it reaches, like a database in the cluster. Only devices in the network can use them; they are never published on an edge.

Docker

List the services and give the agent a mesh auth key and a state directory that survives restarts:

docker run -d --name towonel-agent \
  -e TOWONEL_INVITE_TOKEN=tt_inv_2_… \
  -e TOWONEL_AGENT_MESH_SERVICES='[{"port": 5432, "origin": "db:5432"}]' \
  -e TOWONEL_MESH_AUTH_KEY=tmk_… \
  -e TOWONEL_MESH_NAME=db-agent \
  -e TOWONEL_MESH_STATE_DIR=/home/nonroot/mesh \
  -v towonel-mesh:/home/nonroot \
  git.ow-ops.eu/towonel/towonel-agent:latest

port is what devices connect to; origin is the host:port the agent dials. The key is only needed for the first start; after that the agent reuses the device saved in the state directory. The image runs as uid 10001, which owns /home/nonroot.

Kubernetes

In the console, open the tunnel, go to Private network, click Add a server and pick Kubernetes. It creates a reusable key, so every replica can join, and shows the Secret and the chart values.

From the CLI, with a personal API key (TOWONEL_API_KEY):

towonel mesh auth-key --invite-token "$TOWONEL_INVITE_TOKEN" --tag tag:agent \
  --k8s-secret towonel-mesh --namespace network | kubectl apply -f -

Then enable it in the chart values:

mesh:
  enabled: true
  authKeySecret:
    name: towonel-mesh
  services:
    - port: 5432
      origin: postgres.db.svc.cluster.local:5432

Each replica becomes its own device, named after its pod (towonel-agent-0, towonel-agent-1, …). Use a tagged key: devices from untagged keys expire after 180 days, and a pod can’t renew by signing in.

Enabling the mesh turns the Deployment into a StatefulSet with a small volume per replica for its device key, so the upgrade replaces the pods. Uninstalling keeps the volumes, and the devices stay in the network until you remove them in the console.

Reach the services

towonel mesh status lists the ports each device serves. Connect to one replica by name, or to any replica with the tag:

towonel mesh connect towonel-agent-0:5432   # listens on 127.0.0.1:5432
towonel mesh connect tag:agent:5432         # skips replicas that are down

With a tag, devices serving that port are tried first. Only use a tag that just these replicas carry: another deployment with the same tag and port could answer instead.

An agent has no network interface of its own, so connections to its overlay IP (psql -h towonel-agent-0.towonel.internal) are refused. Use mesh connect or mesh nc.

The access policy applies as for any device. By default your devices can reach a tagged agent.

Monitoring

towonel_agent_mesh_up is 1 while the agent serves its mesh services. With monitoring.prometheusRule.enabled, the chart adds TowonelAgentMeshDown, which fires after 10 minutes out of the network. The agent’s logs say why: a missing or rejected key, the device being removed, or the hub being unreachable.

A rejected key usually means a one-use key and more than one replica. Put a reusable key in the Secret and restart the pods.