# Newt (Pangolin) — noble

This is the **primary** automation path for **public** hostnames to workloads in this cluster (it **replaces** in-cluster ExternalDNS). [Newt](https://github.com/fosrl/newt) is the on-prem agent that connects your cluster to a **Pangolin** site (WireGuard tunnel). The [Fossorial Helm chart](https://github.com/fosrl/helm-charts) 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`).

### Option A — Sealed Secret (safe for GitOps)

With the [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) controller installed (`clusters/noble/bootstrap/sealed-secrets/`), generate a `SealedSecret` from your workstation (rotate credentials in Pangolin first if they were exposed):

```bash
chmod +x clusters/noble/bootstrap/sealed-secrets/examples/kubeseal-newt-pangolin-auth.sh
export PANGOLIN_ENDPOINT='https://pangolin.pcenicni.dev'
export NEWT_ID='YOUR_NEWT_ID'
export NEWT_SECRET='YOUR_NEWT_SECRET'
./clusters/noble/bootstrap/sealed-secrets/examples/kubeseal-newt-pangolin-auth.sh > newt-pangolin-auth.sealedsecret.yaml
kubectl apply -f newt-pangolin-auth.sealedsecret.yaml
```

Commit only the `.sealedsecret.yaml` file, not plain `Secret` YAML.

### Option B — Imperative Secret (not in git)

```bash
kubectl apply -f clusters/noble/bootstrap/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](https://docs.pangolin.net/manage/common-api-routes) (`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

```bash
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/bootstrap/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](https://docs.pangolin.net/manage/common-api-routes#list-domains)).
2. **Create public HTTP resources** (and **targets** to your Newt **site**) via the [Integration API](https://docs.pangolin.net/manage/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](https://docs.pangolin.net/self-host/advanced/integration-api)).

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

```bash
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](https://docs.pangolin.net/manage/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.