97 lines
4.6 KiB
Markdown
97 lines
4.6 KiB
Markdown
# 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/apps/sealed-secrets/`), generate a `SealedSecret` from your workstation (rotate credentials in Pangolin first if they were exposed):
|
||
|
||
```bash
|
||
chmod +x clusters/noble/apps/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/apps/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/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](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/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](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.
|