Cloudflare

Norn v2 uses Cloudflare Tunnels (cloudflared) for external routing and optionally Cloudflare Access for API authentication.

Tunnel Routing

cloudflared runs locally as a Homebrew LaunchAgent, managed via a config file on disk. During the forge step of the deploy pipeline, Norn reads the config, updates ingress rules, writes it back, and restarts the tunnel process.

How It Works

Norn manages cloudflared's config file directly (default ~/.cloudflared/config.yml). No Kubernetes or Docker dependency is required — cloudflared runs as a native macOS service.

Component	Details
Config file	~/.cloudflared/config.yml (override with NORN_CLOUDFLARED_CONFIG)
Process management	Homebrew LaunchAgent (homebrew.mxcl.cloudflared)
Restart method	launchctl kickstart -k (kills + relaunches immediately)
Tunnel type	Named tunnel with credentials file

Setup

1. Install cloudflared and create a named tunnel:

brew install cloudflared
cloudflared tunnel login
cloudflared tunnel create multi-domain-tunnel

2. Configure ~/.cloudflared/config.yml:

tunnel: multi-domain-tunnel
credentials-file: /Users/you/.cloudflared/multi-domain-tunnel.json

ingress:
  - hostname: myapp.example.com
    service: http://192.168.4.124:3001
  - service: http_status:404    # catch-all (required)

3. Update the Homebrew plist to include tunnel run arguments:

<key>ProgramArguments</key>
<array>
  <string>/opt/homebrew/opt/cloudflared/bin/cloudflared</string>
  <string>tunnel</string>
  <string>run</string>
</array>

Homebrew default plist

The default Homebrew plist for cloudflared only includes the binary path with no arguments. Without tunnel run, cloudflared exits immediately and the LaunchAgent crash-loops. Always verify the plist includes the tunnel and run arguments.

4. Start the service:

# If a system-level daemon exists (token-based), unload it first:
sudo launchctl unload /Library/LaunchDaemons/com.cloudflare.cloudflared.plist

# Start the Homebrew service:
brew services start cloudflared

Infraspec Configuration

endpoints:
  - url: https://myapp.example.com
  - url: https://myapp-staging.example.com
    region: us-east

What Forge Does

1. Reads the app's endpoints from the infraspec
2. Finds the Nomad allocation's node address and static port
3. Updates cloudflared's ingress rules to route each hostname to the service
4. Writes the config file and restarts cloudflared via launchctl kickstart -k

What Teardown Does

norn teardown <app> removes the app's entries from the cloudflared ingress configuration.

Per-Endpoint Toggle

You can enable or disable individual endpoints without affecting the rest of the app's routing. This is useful for temporarily taking a hostname offline (e.g. during maintenance) without tearing down all endpoints.

From the dashboard: each external endpoint badge shows a cloud toggle icon. A green cloud means the endpoint is active in cloudflared; a dim cloud-slash means it's inactive. Click the icon to toggle.

From the CLI:

# List endpoints with their cloudflared status
norn endpoints myapp

# Toggle a single hostname
norn endpoints toggle myapp app.example.com

Via API:

# List active ingress hostnames
curl http://localhost:8800/api/cloudflared/ingress

# Enable an endpoint
curl -X POST http://localhost:8800/api/apps/myapp/endpoints/toggle \
  -H "Content-Type: application/json" \
  -d '{"hostname": "app.example.com", "enabled": true}'

# Disable an endpoint
curl -X POST http://localhost:8800/api/apps/myapp/endpoints/toggle \
  -H "Content-Type: application/json" \
  -d '{"hostname": "app.example.com", "enabled": false}'

Configuration

Environment Variable	Default	Description
NORN_CLOUDFLARED_CONFIG	~/.cloudflared/config.yml	Path to the cloudflared config file

Config File Format

Norn reads and writes the standard cloudflared config format:

tunnel: multi-domain-tunnel
credentials-file: /Users/you/.cloudflared/multi-domain-tunnel.json

ingress:
  - hostname: app1.example.com
    service: http://192.168.4.124:3001
  - hostname: app2.example.com
    service: http://192.168.4.124:8080
  - service: http_status:404

The catch-all rule (service: http_status:404) must be the last entry. Norn always inserts new rules before it.

Host Networking Considerations

Nomad runs Docker containers in bridge networking by default. This affects how cloudflared routes reach your services:

Network Mode	Service Address	Use When
Bridge (default)	http://<node-ip>:<static-port>	Standard setup. Nomad reserves a static port on the host when endpoints are defined.
Host (network_mode: host)	http://127.0.0.1:<port>	When your app needs to reach host-local services (e.g. signal-cli on localhost).

Bridge mode example (default — forge handles this automatically):

# infraspec.yaml
processes:
  web:
    port: 3001

endpoints:
  - url: https://myapp.example.com

Forge resolves the Nomad allocation's node address (e.g. 192.168.4.124) and writes:

# ~/.cloudflared/config.yml (managed by Norn)
ingress:
  - hostname: myapp.example.com
    service: http://192.168.4.124:3001

When your app connects to host-local services (e.g. a database or signal-cli on localhost), the Docker container can reach the host via host.docker.internal — Docker Desktop resolves this to the macOS host automatically. Use this in env vars:

# infraspec.yaml
env:
  DATABASE_URL: postgres://norn:norn@host.docker.internal:5432/mydb?sslmode=disable
  SIGNAL_URL: http://host.docker.internal:8080/v1/receive/+1234567890

127.0.0.1 vs host.docker.internal

Inside a Docker container with bridge networking, 127.0.0.1 refers to the container's own loopback, not the host. Use host.docker.internal to reach services on the macOS host. This applies to all Nomad Docker tasks unless network_mode: host is explicitly set.

Port Handling

When endpoints are defined, the Nomad translator uses static ports instead of dynamic ports. This ensures the service is always reachable at a predictable address for cloudflared routing.

Cloudflare Access

Norn can validate Cloudflare Access JWTs to authenticate API requests.

Setup

1. Create a Cloudflare Access application for your Norn instance
2. Set the environment variables:

Variable	Description
NORN_CF_ACCESS_TEAM_DOMAIN	Your Cloudflare Access team domain (e.g. myteam.cloudflareaccess.com)
NORN_CF_ACCESS_AUD	The Application Audience (AUD) tag from your Access policy

How It Works

When both variables are set, the API middleware validates the Cf-Access-Jwt-Assertion header on every request (except exempt routes).

Exempt routes (no auth required):

• /ws — WebSocket
• /api/health — health check
• /api/version — version endpoint
• /api/webhooks/* — webhook receivers
• /api/access/cloudflare/logpush — Cloudflare Logpush receiver with its own shared-secret header
• /api/apps/*/exec — exec into allocations

Combining with Bearer Token

Both CF Access and bearer token auth can be enabled simultaneously. The request must pass whichever auth checks are configured.

# Both enabled
export NORN_CF_ACCESS_TEAM_DOMAIN=myteam.cloudflareaccess.com
export NORN_CF_ACCESS_AUD=abc123...
export NORN_API_TOKEN=secret-token

Access Observations

Norn can use Cloudflare traffic data as an access-pattern signal for the advisory resource tuner. This is useful when public services are reached through cloudflared and the Norn control plane would otherwise only see API traffic, not app traffic.

There are two supported ingestion paths:

Path	Use	Required configuration
GraphQL sync	Backfill or periodically import hourly request counts by hostname	NORN_CLOUDFLARE_API_TOKEN, NORN_CLOUDFLARE_ZONE_ID
HTTP Logpush	Continuously receive request logs from Cloudflare	NORN_CLOUDFLARE_LOGPUSH_TOKEN

norn access cloudflare status reports whether the GraphQL and Logpush credentials are configured and lists the public service hostnames Norn can map to app/process pairs.

norn access cloudflare sync --window 14d queries Cloudflare's GraphQL Analytics API for each mapped public hostname and records hourly aggregate observations as cloudflare-graphql. The Cloudflare token must be able to read analytics for the configured zone. Norn records only aggregate counts and status buckets; it does not persist request bodies or authorization headers.

GraphQL syncs are split into day-sized Cloudflare queries and clamped to Norn's configured GraphQL lookback ceiling. A requested 14-day import can therefore produce a shorter effective window when the Cloudflare zone only exposes recent analytics. Re-running the sync is idempotent for the same hourly aggregate buckets: GraphQL-imported buckets replace the previous cloudflare-graphql value instead of adding to it, so retries and interrupted runs do not inflate traffic counts.

Cloudflare Logpush can deliver HTTP request logs to:

https://<norn-host>/api/access/cloudflare/logpush

Set a secret header in the Logpush destination URL, for example:

?header_X-Norn-Logpush-Token=<random-token>

Store the same value as NORN_CLOUDFLARE_LOGPUSH_TOKEN in the Norn API secret bundle. The receiver also accepts X-Logpush-Secret and Authorization: Bearer <token> for compatibility with existing Logpush setups. Keep this endpoint HTTPS-only and protected by the shared secret.

Imported observations feed /api/access/patterns and /api/tuning/recommendations, allowing idle candidates and active windows to be based on Cloudflare traffic instead of manual observations.

Wake Gateway

Norn can sit on the live request path for selected public endpoints through the wake gateway. Use this when a public service may be scaled down and should wake on the next request.

Production Setup

Point each wakeable public hostname at the Norn API origin. Do not add a path prefix.

ingress:
  - hostname: app.example.com
    service: http://127.0.0.1:8800
  - service: http_status:404

The only required routing header is the original public Host header. cloudflared preserves this automatically for hostname ingress rules. Generic reverse proxies must do the same:

proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://127.0.0.1:8800;

With host-based routing, a request stays in its normal shape:

https://app.example.com/archive/123

Norn receives Host: app.example.com, maps that hostname to a public endpoint from the service manifest, wakes the mapped app/process if needed, and proxies /archive/123 unchanged to the service.

Local Smoke Test

From the Norn host:

curl -i -H "Host: app.example.com" http://127.0.0.1:8800/health

A gateway-handled response includes:

X-Norn-Wake-Gateway: true
X-Norn-Wake-Action: ready

X-Norn-Wake-Action: scaled means Norn had to scale the mapped process from zero before proxying the request.

Explicit Path Form

The explicit API route is useful for local tests or proxies that cannot preserve the original Host header:

https://<norn-host>/api/wake-gateway/<public-hostname>/<original-path>

Example:

curl -i http://127.0.0.1:8800/api/wake-gateway/app.example.com/health

This strips /api/wake-gateway/app.example.com before proxying, so the service receives /health.

Behavior

The gateway maps the public hostname back to a service endpoint from the service manifest, records a wake-gateway access observation, checks for a passing Consul instance, and reverse-proxies to that instance. If no passing instance exists, it scales the mapped Nomad task group to 1, waits for readiness, then proxies the request. Requests that cannot wake before the bounded timeout return 504 with Retry-After.

The default wake wait is 30s. A request can override it with wakeTimeout, up to 2m:

https://app.example.com/archive/123?wakeTimeout=60s

The gateway removes wakeTimeout before forwarding the request to the service.

This route is intentionally hostname-mapped and does not proxy arbitrary upstream URLs. Point only selected cloudflared or local proxy rules at it, and keep direct Norn API access controlled separately.