expose service

AI Community

Skill notes

Exposure policy (ADR 0012, amended 2026-04-17)

Pick by who needs to reach the workload, not by what feels easiest: LAN clients only → envoy-internal HTTPRoute. Split-horizon DNS via k8s-gateway returns the internal LB to LAN clients. Off-LAN HTTP admin UI (browser) → Tailscale Ingress (ingressClassName: tailscale + tls.hosts: [<slug>]). The operator provisions a Let's Encrypt cert on <slug>.<tailnet>.ts.net; browsers trust it natively. Recipe A in references/tailscale.md.

Gateway-choice matrix

Use case · Path · Hostname · TLS in browser? · Reaches LAN only (default) · envoy-internal HTTPRoute · <app>.${SECRET_DOMAIN} · Yes (cert-manager) · LAN → k8s-gateway DNS → cluster Off-LAN HTTP admin UI · Tailscale Ingress (ingressClassName: tailscale) · <slug>.<tailnet>.ts.net · Yes (Let's Encrypt via MagicDNS) · Tailnet device → operator proxy → Service Off-LAN raw TCP / non-HTTP · Tailscale Service annotation · <slug>.<tailnet>.ts.net · No (TCP pass-through) · Tailnet device → operator proxy → Service

Workflow

Confirm the path against the exposure policy above. If envoy-external is on the table, verify the user has approved public exposure before writing anything. "I want to reach it off-LAN" is a Tailscale reason, not an envoy-external reason. Author the resource(s): HTTPRoute path (envoy-internal or envoy-external) — write kubernetes/apps/<ns>/<app>/app/httproute.yaml using the template in references/authoring-httproute.md, or use the chart-values variant (Workflow B) if the chart supports it (bjw-s app-template).

Pre-commit checklist

Common: [ ] Path choice matches policy (LAN-only → internal; off-LAN HTTP → Tailscale Ingress; off-LAN raw TCP → Tailscale annotation; external only when explicitly approved) [ ] Diff contains Tailscale changes only — no Cilium / gateway / CNI edits in the same commit (ADR 0012) [ ] No plaintext secrets: any *.sops.* files show encrypted via sops filestatus HTTPRoute path:

Canonical in-tree examples

Read the live manifest rather than a frozen copy: Public, app-template inline route: values (Workflow B) → kubernetes/apps/default/echo/app/helmrelease.yaml Internal, standalone HTTPRoute (Workflow A) → kubernetes/apps/observability/kube-prometheus-stack/app/httproute.yaml DNSEndpoint shape (CNAME to tunnel on a secondary domain) → kubernetes/apps/network/cloudflare-tunnel/app/dnsendpoint.yaml

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
AI
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@wcygan · no license declared
Token usage
Lean
Setup complexity
Plug-and-play
External API key
Not required
Operating systems
macOS
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Output preview expose-service.preview
# Canonical in-tree examples

- **Public, app-template inline `route:` values** (Workflow B) → `kubernetes/apps/default/echo/app/helmrelease.yaml`
- **Internal, standalone HTTPRoute** (Workflow A) → `kubernetes/apps/observability/kube-prometheus-stack/app/httproute.yaml`
- **DNSEndpoint shape** (CNAME to tunnel on a secondary domain) → `kubernetes/apps/network/cloudflare-tunnel/app/dnsendpoint.yaml`

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.