benvin
65 lines
2.4 KiB
Markdown
65 lines
2.4 KiB
Markdown
# tomswallapi
|
|
|
|
Fleet control plane for [tomswall](https://git.unkin.net/unkin/tomswall).
|
|
|
|
Declare zones, address groups, and firewall policy **once**; the API compiles each
|
|
intent into the concrete per-device rules every firewall and router on the path
|
|
needs, and serves each device its rendered `tomswall.yaml`. A connection that
|
|
crosses several firewalls — `src → rt1 → rt2 → rt3 → dest` — is expressed as a
|
|
single rule.
|
|
|
|
The full design (data model, compile algorithm, invariants, agent protocol) lives
|
|
in [`DESIGN.md`](https://git.unkin.net/unkin/tomswall/src/branch/main/DESIGN.md) in
|
|
the tomswall repo.
|
|
|
|
## Architecture
|
|
|
|
- **tomswallapi** (this repo) — Terraform-managed HTTP API. Stores the fleet model
|
|
in Postgres, peers with FRR for reachability, compiles intents into per-device
|
|
configs, and serves them.
|
|
- **tomswall agent** — pulls its rendered config, runs the existing differential
|
|
`apply`, maintains dns-backed ipsets via an on-device resolver, and reports the
|
|
config generation it has applied. Does **not** fail closed on API-unreachable.
|
|
|
|
## Running locally
|
|
|
|
```sh
|
|
docker compose up --build
|
|
# API on :8000, Postgres on :5432
|
|
curl -s localhost:8000/healthz
|
|
```
|
|
|
|
## Configuration
|
|
|
|
All configuration is via environment variables (`TOMSWALLAPI_*`):
|
|
|
|
| var | default | purpose |
|
|
|---|---|---|
|
|
| `TOMSWALLAPI_LISTEN_ADDR` | `:8000` | HTTP listen address |
|
|
| `TOMSWALLAPI_DB_HOST` | `localhost` | Postgres host |
|
|
| `TOMSWALLAPI_DB_PORT` | `5432` | Postgres port |
|
|
| `TOMSWALLAPI_DB_USER` | `tomswallapi` | Postgres user |
|
|
| `TOMSWALLAPI_DB_PASSWORD` | — | Postgres password |
|
|
| `TOMSWALLAPI_DB_NAME` | `tomswallapi` | Postgres database |
|
|
| `TOMSWALLAPI_DB_SSLMODE` | `disable` | Postgres sslmode |
|
|
| `TOMSWALLAPI_WRITE_TOKEN` | — | bearer token guarding mutating endpoints (Terraform) |
|
|
| `TOMSWALLAPI_AGENT_TOKEN` | — | bearer token guarding the per-device config endpoint (agents) |
|
|
| `TOMSWALLAPI_IPLOCATE_API_KEY` | — | iplocate key for ASN address-group expansion |
|
|
|
|
Migrations are embedded and applied automatically on startup.
|
|
|
|
## Development
|
|
|
|
```sh
|
|
make build # build the binary
|
|
make test # run tests
|
|
make lint # gofmt + go vet
|
|
make run # build and run
|
|
```
|
|
|
|
## Releases
|
|
|
|
`make patch|minor|major` computes and pushes the next `v*` tag, which triggers the
|
|
Woodpecker docker pipeline to build and push the image to
|
|
`git.unkin.net/unkin/tomswallapi`.
|