75 lines
3.3 KiB
Markdown
75 lines
3.3 KiB
Markdown
# Newt (Pangolin Tunnel Agent) Playbook
|
|
|
|
## Overview
|
|
|
|
`newt.yml` deploys [Newt](https://github.com/fosrl/newt), the tunnel agent for the Pangolin reverse proxy platform. Newt establishes an outbound tunnel from a Docker host back to your Pangolin server, allowing Pangolin to route traffic to services on that host without opening inbound ports.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────┐ ┌──────────────────────────┐
|
|
│ Target Docker Host │ │ Pangolin Server │
|
|
│ │ │ pangolin.wulfconsulting │
|
|
│ ┌───────────────────┐ │ tunnel │ .cloud │
|
|
│ │ newt container │──────────▶│ │
|
|
│ │ (fosrl/newt) │ │ │ Routes traffic to sites │
|
|
│ └───────────────────┘ │ │ configured in dashboard │
|
|
│ │ └──────────────────────────┘
|
|
│ /opt/stacks/newt/ │
|
|
│ └── compose.yaml │
|
|
└─────────────────────────┘
|
|
```
|
|
|
|
### Playbook structure
|
|
|
|
| Section | Purpose |
|
|
|---------|---------|
|
|
| **vars** | Sets `newt_stack_dir` (`/opt/stacks/newt`) and the default `pangolin_endpoint` |
|
|
| **pre_tasks** | Validates that `newt_id`, `newt_secret`, and `pangolin_endpoint` are provided; checks Docker is running |
|
|
| **tasks** | Creates the stack directory, writes `compose.yaml`, and deploys via `docker_compose_v2` |
|
|
|
|
The compose file defines a single service — the `fosrl/newt` image configured with three environment variables that authenticate it to the Pangolin server.
|
|
|
|
## Usage
|
|
|
|
### Required extra vars
|
|
|
|
| Variable | Source | Description |
|
|
|----------|--------|-------------|
|
|
| `newt_id` | Pangolin dashboard (per-site) | Tunnel identity |
|
|
| `newt_secret` | Pangolin dashboard (per-site) | Tunnel secret |
|
|
|
|
### Optional extra vars
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `pangolin_endpoint` | `https://pangolin.wulfconsulting.cloud` | Pangolin server URL |
|
|
|
|
### Deploy to a host
|
|
|
|
```bash
|
|
ansible-playbook playbooks/newt.yml --limit kaercher02 \
|
|
-e newt_id=kigig6jtds5qr3a \
|
|
-e newt_secret=9qznq1wasaapy0cwpxzzi8sji6z5r4nkukqpkt4k8lyy6jx3
|
|
```
|
|
|
|
### Override the Pangolin endpoint
|
|
|
|
```bash
|
|
ansible-playbook playbooks/newt.yml --limit somehost \
|
|
-e newt_id=... \
|
|
-e newt_secret=... \
|
|
-e pangolin_endpoint=https://pangolin.other.domain
|
|
```
|
|
|
|
### Verify the container is running
|
|
|
|
```bash
|
|
ansible kaercher02 -a "docker ps --filter name=newt"
|
|
```
|
|
|
|
## Notes
|
|
|
|
- **Credentials are runtime-only.** `newt_id` and `newt_secret` are passed as extra vars and written into the compose file on the target host. They are not stored in the Ansible repo.
|
|
- **One Newt per host.** The container name is fixed to `newt`, so each host runs a single instance. If you need multiple tunnels on one host, duplicate the playbook with a different container name and stack directory.
|
|
- **`--limit` is required.** The playbook targets `all` hosts, so always use `--limit` to select which host to deploy to.
|