home-server/clusters/noble/apps/newt/README.md

Newt (Pangolin) — noble

This is the primary automation path for public hostnames to workloads in this cluster (it replaces in-cluster ExternalDNS). Newt is the on-prem agent that connects your cluster to a Pangolin site (WireGuard tunnel). The Fossorial Helm chart deploys one or more instances.

Secrets: Never commit endpoint, Newt ID, or Newt secret. If credentials were pasted into chat or CI logs, rotate them in Pangolin and recreate the Kubernetes Secret.

1. Create the Secret

Keys must match values.yaml (PANGOLIN_ENDPOINT, NEWT_ID, NEWT_SECRET):

kubectl apply -f clusters/noble/apps/newt/namespace.yaml

kubectl -n newt create secret generic newt-pangolin-auth \
  --from-literal=PANGOLIN_ENDPOINT='https://pangolin.pcenicni.dev' \
  --from-literal=NEWT_ID='YOUR_NEWT_ID' \
  --from-literal=NEWT_SECRET='YOUR_NEWT_SECRET'

Use the Pangolin UI or Integration API (pick-site-defaults + create site) to obtain a Newt ID and secret for a new site if you are not reusing an existing pair.

2. Install the chart

helm repo add fossorial https://charts.fossorial.io
helm repo update
helm upgrade --install newt fossorial/newt \
  --namespace newt \
  --version 1.2.0 \
  -f clusters/noble/apps/newt/values.yaml \
  --wait

3. DNS: CNAME at your DNS host + Pangolin API for routes

Pangolin does not replace your public DNS provider. Typical flow:

1. Link a domain in Pangolin (organization Domains). For CNAME-style domains, Pangolin shows the hostname you must CNAME to at Cloudflare / your registrar (see Domains).
2. Create public HTTP resources (and targets to your Newt site) via the Integration API — same flows as the UI. Swagger: https://<your-api-host>/v1/docs (self-hosted: enable enable_integration_api and route api.example.com → integration port per docs).

Minimal patterns (Bearer token = org or root API key):

export API_BASE='https://api.example.com/v1'   # your Pangolin Integration API base
export ORG_ID='your-org-id'
export TOKEN='your-integration-api-key'

# Domains already linked to the org (use domainId when creating a resource)
curl -sS -H "Authorization: Bearer ${TOKEN}" \
  "${API_BASE}/org/${ORG_ID}/domains"

# Create an HTTP resource on a domain (FQDN = subdomain + base domain for NS/wildcard domains)
curl -sS -X PUT -H "Authorization: Bearer ${TOKEN}" -H 'Content-Type: application/json' \
  "${API_BASE}/org/${ORG_ID}/resource" \
  -d '{
    "name": "Example app",
    "http": true,
    "domainId": "YOUR_DOMAIN_ID",
    "protocol": "tcp",
    "subdomain": "my-app"
  }'

# Point the resource at your Newt site backend (siteId from list sites / create site; ip:port inside the tunnel)
curl -sS -X PUT -H "Authorization: Bearer ${TOKEN}" -H 'Content-Type: application/json' \
  "${API_BASE}/resource/RESOURCE_ID/target" \
  -d '{
    "siteId": YOUR_SITE_ID,
    "ip": "10.x.x.x",
    "port": 443,
    "method": "http"
  }'

Exact JSON fields and IDs differ by domain type (ns vs cname vs wildcard); see Common API routes and Swagger.

LAN vs internet

• LAN / VPN: point *.apps.noble.lab.pcenicni.dev at the Traefik LoadBalancer (192.168.50.211) with local or split-horizon DNS if you want direct in-lab access.
• Internet-facing: use Pangolin resources + targets to the Newt site; public names rely on CNAME records at your DNS provider per Pangolin’s domain setup, not on ExternalDNS in the cluster.