cadet

module
v0.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: BSD-3-Clause

README

cadet

Service-discovery-driven routing for your homelab. Register a service in Consul and cadet turns it into a reverse-proxy route (and a DNS record) automatically — no restart, no config reload.

Cadet ships as two plugins that both read the same consul data:

  • plugins/caddy — a Caddy app that watches the consul catalog and generates reverse-proxy routes for every tagged service, with per-service TLS, hostnames, and ACLs.
  • plugins/coredns — a CoreDNS plugin that answers queries for the same hostnames the caddy plugin publishes.

Service model

A service is published if it carries the cadet tag in consul. Behavior is controlled by meta keys on the registration:

meta key effect
cadet-name override the hostname (default: service name)
cadet-zone publish into this zone instead of the default
cadet-acl ACL policy for this service, overriding the global default
cadet-proxy false points DNS straight at the service instead of the proxy, and skips the proxy route
tag cadet-nopublish skip the whole service even though it carries the cadet tag

Global config lives in consul under cadet/:

  • cadet/caddy.json — the Caddy app config
  • cadet/zone.json — default zone and zone list
  • cadet/acl.json — ACL networks, groups, and default policy/action
  • cadet/services/ — static services, one JSON document per key
Static services

Services that can't register in the consul catalog can be declared in the KV store instead. Each key under cadet/services/ holds one service:

consul kv put cadet/services/nas '{
  "id": "nas",
  "name": "files",
  "endpoints": [
    { "address": "10.10.0.20", "port": 5000 },
    { "address": "10.10.0.21", "port": 5000 }
  ],
  "zones": ["lab.internal"],
  "acls": "allow admin; deny *"
}'
field effect
id unique service ID
name hostname to publish under
endpoints upstreams to proxy to, as address (an IP) and port
zones zones to publish into (default: the default zone)
acls ACL policy, same syntax as cadet-acl (default: the global policy)
no_publish skip this service (default: false)
use_proxy false points DNS straight at the endpoints instead of the proxy (default: true)

Services are keyed by id, not by KV key. A catalog service with the same ID takes precedence over a static one.

Example configs

Caddy — /etc/caddy/config.json

The bootstrap config that tells Caddy where to find consul; everything else (routes, TLS, upstreams) is generated from the consul catalog at runtime.

{
  "apps": {
    "cadet": {
      "consul": {
        "endpoint": "http://consul:8500"
      },
      "auto_reverse_proxy": {
        "http_port": 80,
        "https_port": 443,
        "protocols": ["h1", "h2"],
        "tls_issuers": []
      }
    },
    "tls": {
      "automation": {
        "policies": [
          {
            "subjects": ["*.cadet.internal"],
            "issuers": [{ "module": "internal" }]
          }
        ]
      }
    }
  }
}

Every field under cadet.consul has a default; the minimal form is just {"endpoint": "..."}. The full set with its defaults:

{
  "endpoint": "http://localhost:8500",
  "token": "",
  "global_config_prefix": "cadet",
  "tags":  { "service": "cadet",       "no_publish": "cadet-nopublish" },
  "keys":  { "name":    "cadet-name",  "zone":       "cadet-zone",
             "acl":     "cadet-acl",   "proxy":      "cadet-proxy" }
}
Dashboard

Setting dashboard in the cadet app config publishes the web UI as a service: it gets a hostname, TLS and ACLs like any other proxied service, but is served by caddy itself rather than proxied to an upstream.

"dashboard": {
  "enabled": true,
  "name": "cadet",
  "zones": ["cadet.internal"],
  "acl": "allow trusted"
}

name defaults to cadet, zones to the default zone and acl to the global default policy, so {"enabled": true} publishes the dashboard at cadet.<default_zone>. The CoreDNS plugin reads the same block from cadet/caddy.json and resolves the dashboard's hostname to the proxy, subject to the same ACL.

Zone — consul kv put cadet/zone.json ...
{
  "default_zone": "cadet.internal",
  "zones": ["cadet.internal", "lab.internal"]
}

A service without a cadet-zone meta key is published at <name>.<default_zone>. Setting cadet-zone=lab.internal on a registration publishes it at <name>.lab.internal instead.

ACL — consul kv put cadet/acl.json ...
{
  "networks": {
    "local": ["127.0.0.0/8"],
    "admin": ["10.10.0.0/24"],
    "users": ["10.20.0.0/24"],
    "lab":   ["10.40.0.0/24"]
  },
  "groups": {
    "trusted": ["local", "admin"],
    "all":     ["local", "admin", "users", "lab"]
  },
  "default_policy": "allow trusted",
  "default_action": "deny"
}

Requests are matched against networks (CIDRs) and groups (unions of network names). default_policy is a ;-separated list of <action> <name> clauses evaluated top-to-bottom, where * matches every source; default_action is the fallback when nothing matches. With no acl.json, the policy defaults to allow *.

Services can override the global policy per-registration with cadet-acl meta — e.g. cadet-acl: "allow users; deny lab".

Building

make help            # list documented targets
make check           # formatting, go.mod, lint and stylesheet checks
make test            # unit tests (everything but ./e2e)
make e2e             # end-to-end suite against a docker compose stack
make ci              # check, test, build and e2e, as CI runs them
make build           # caddy, coredns and dashboard, all into ./dist
make caddy           # ./dist/caddy with the cadet plugin baked in
make coredns         # ./dist/coredns with the cadet plugin baked in
make dashboard       # ./dist/cadet-dashboard, the standalone dashboard
make css             # regenerate the dashboard stylesheet (css-watch to rebuild on change)
make caddy-docker    # ghcr.io/tmacro/cadet-proxy, tagged with `git describe`
make coredns-docker  # ghcr.io/tmacro/cadet-dns, tagged with `git describe`

make fmt and make tidy fix what check-fmt and check-tidy complain about; make check-css fails when the committed stylesheet is out of date with the templates. make e2e-up / make e2e-down start and stop the e2e stack on their own, which is handy for iterating on single specs.

Pinned tools (xcaddy, golangci-lint, goimports, staticcheck, deadcode, ginkgo, tailwind) install into ./bin on first use, or all at once with make tools. Caddy, CoreDNS and Ginkgo versions are read from go.mod. Go, Docker (with buildx and compose) and curl need to be installed.

Images build for linux/amd64 by default; override DOCKER_PLATFORMS for other targets, e.g. make caddy-docker DOCKER_PLATFORMS=linux/arm64. make coredns downloads the upstream CoreDNS source tarball into ./build once per version, re-extracts it on every build and builds it against this checkout, using the plugin list in images/coredns/plugin.cfg.

make build targets the host; set GOOS/GOARCH to cross-compile, e.g. make build GOOS=linux GOARCH=arm64 DIST=./dist/arm64.

make release publishes a GitHub release with GoReleaser. It runs make build for each of RELEASE_PLATFORMS (default linux/amd64; space-separated, e.g. "linux/amd64 linux/arm64") and hands the binaries, named <binary>_<os>_<arch> (e.g. caddy_linux_amd64), to GoReleaser, which only adds checksums and a changelog and uploads them. It then pushes ghcr.io/tmacro/cadet-proxy and ghcr.io/tmacro/cadet-dns, tagged with the version and latest; these images package the same release binaries rather than building from source. It refuses to run unless HEAD is a clean, tagged commit, and needs GITHUB_TOKEN set and a docker login ghcr.io. Releasing more than one platform needs a buildx builder that can build multi-platform images.

make release-snapshot does everything but publish, and make release-images builds the images from existing release binaries (PUSH=1 to push).

Pushing a v* tag runs make check, make test and make e2e, then make release, in GitHub Actions (.github/workflows/release.yml), so a release is just:

git tag v0.1.0 && git push origin v0.1.0

The workflow needs no secrets: both the GitHub release and the image push to ghcr.io use the built-in GITHUB_TOKEN. Override IMAGE_REGISTRY (default ghcr.io/tmacro) to push elsewhere.

make clean removes ./dist and ./build; make fclean also removes the tools in ./bin.

Directories

Path Synopsis
cmd
dashboard command
watch-services command
e2e
cmd/driver command
cmd/whoami command
internal
pkg
acl
log
plugins

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL