Expose 浏览器编写

AI 智能社区

作者仓库星标 2
作者仓库 anton

解读按原文结构重写，命令、链接、术语均保留；右侧可核对作者原始 SKILL.md

方法与流程

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.

适用与边界

当前原文没有单列适用场景。
当前原文没有单列不适用场景或限制。

原文中的明确线索

要点：「who needs to reach the workload」、「LAN clients only」、「Off-LAN HTTP admin UI (browser)」、「Tailscale Ingress」、「Off-LAN raw TCP or non-HTTP」、「Tailscale Service annotation」、「LAN clients AND off-LAN HTTP access」、「plus」
文件与命令：kubernetes/apps/network/AGENTS.md、envoy-internal、k8s-gateway、Ingress、ingressClassName: tailscale、tls.hosts: [<slug>]、<slug>.<tailnet>.ts.net、references/tailscale.md

流狐整理：以上内容来自当前 SKILL.md 的章节与原词；未补写作者没有声明的工具、兼容性或能力。

Expose a service

Task skill for routing traffic to a workload. Anton has three supported access paths; architecture deep-dive lives in kubernetes/apps/network/AGENTS.md.

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.
Off-LAN raw TCP or non-HTTP → Tailscale Service annotation (tailscale.com/expose: "true"). No TLS termination on the proxy — clients reach whatever the backend serves on its target port. Recipe B in references/tailscale.md.
LAN clients AND off-LAN HTTP access → envoy-internal HTTPRoute plus a Tailscale Ingress for the same workload. LAN users keep the <app>.${SECRET_DOMAIN} URL; remote ops use <slug>.<tailnet>.ts.net.
Genuinely public (audience that cannot be required to join the tailnet) → envoy-external HTTPRoute + Cloudflare tunnel. Requires explicit user approval before authoring.

Do not pick envoy-external to solve "I want to reach this from my laptop off-LAN" — that is what Tailscale is for now (ADR 0012). Shipping something public and pulling it back is irreversible (cached DNS, search engines, external referrers); Tailscale is reversible.

⚠️ Throughput caveat (ADR 0012 amendment). Tailscale proxies default to userspace netstack and on v1.84+ hit upstream bug tailscale/tailscale#16198; SPA payloads over the tailnet run ~12 KB/s from a macOS peer. LAN clients are unaffected. Use Tailscale for off-LAN admin access, not for heavy data paths, until the operator ships 1.98.x. Full context 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
LAN + off-LAN HTTP	HTTPRoute and Tailscale `Ingress`	both above	Yes on both	either path resolves independently
Public (requires approval)	`envoy-external` HTTPRoute	`<app>.${SECRET_DOMAIN}`	Yes (Cloudflare)	Internet → Cloudflare tunnel → cluster
App on a second domain (`${SECRET_DOMAIN_TWO}`)	`envoy-external` HTTPRoute	`<app>.${SECRET_DOMAIN_TWO}`	Yes	also needs an explicit `DNSEndpoint` — see `references/secondary-domain.md`

Both envoy gateways live in namespace network. HTTPRoutes must set parentRefs[].namespace: network (cross-namespace) and sectionName: https (attach to the TLS listener, not port 80). Tailscale exposure does not use a Gateway-API HTTPRoute — it uses either a networking.k8s.io/v1 Ingress (Recipe A) or a Service annotation (Recipe B).

No bundling. Tailscale exposure changes ship on their own PR, never mixed with Cilium / gateway / CNI changes (ADR 0012).

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).
- Tailscale Ingress (Recipe A, HTTP admin UIs) — write an Ingress with ingressClassName: tailscale and tls.hosts: [<slug>]. Prefer the chart's own ingress.* values knob when available. Recipe: references/tailscale.md.
- Tailscale Service annotation (Recipe B, raw TCP / non-HTTP) — add tailscale.com/expose: "true" and tailscale.com/hostname: <short-slug> to the Service's annotations. Prefer the chart's service.annotations knob over a Kustomize patch. Recipe: references/tailscale.md.
- Combined (HTTPRoute + Tailscale Ingress) — do both; they are independent and don't conflict. Same-PR bundling of Tailscale work with Cilium / gateway / CNI changes is forbidden (ADR 0012).
Wire any new manifest file into kubernetes/apps/<ns>/<app>/app/kustomization.yaml. Annotation-only changes via chart values need no kustomization edit.
If the hostname is on a secondary domain (not ${SECRET_DOMAIN}), also add a DNSEndpoint resource and verify the gateway's cert listener covers the domain — see references/secondary-domain.md. Skipping this is the single most common footgun in this skill. (Does not apply to Tailscale — MagicDNS handles its own.)
Ship it. If any *.sops.* files are new, run sops -e -i <file> to encrypt. Then commit + push, and task reconcile (or wait for the Flux interval).
Verify. Run the checks in references/verify.md; for the Tailscale path, also verify as documented in references/tailscale.md.

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:

parentRefs[0].name is envoy-external or envoy-internal (never a Service name)
parentRefs[0].namespace: network set (cross-namespace attach is required)
parentRefs[0].sectionName: https set (attach to TLS listener, not port 80)
backendRefs[].name matches an actual Service in the app's namespace
HTTPRoute (and DNSEndpoint, if any) listed in app/kustomization.yaml
If hostname is on ${SECRET_DOMAIN_TWO} → DNSEndpoint resource present
If a new second-domain cert was added → gateway listener's tls.certificateRefs updated

Tailscale Ingress path (Recipe A):

ingressClassName: tailscale set; no spec.rules[].host (operator reads tls.hosts)
tls.hosts[0] is a short slug (no dots, no tailnet name embedded)
defaultBackend.service points at an actual Service in the app's namespace
Ingress listed in app/kustomization.yaml (or delivered via chart ingress.* values)
No real tailnet name committed anywhere (use <tailnet-name>.ts.net placeholder in docs)

Tailscale Service annotation path (Recipe B, non-HTTP / raw TCP only):

Annotation is on the Service the chart produces, not on a wrapping resource
tailscale.com/hostname is a short slug (no dots, no tailnet name embedded)
Workload is genuinely non-HTTP — if it's a browser UI, use Recipe A instead
No real tailnet name committed anywhere

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

Reference	When to read
`references/authoring-httproute.md`	Writing the HTTPRoute YAML (Workflow A standalone, Workflow B route-in-values)
`references/secondary-domain.md`	Hostname on `${SECRET_DOMAIN_TWO}` or any non-primary domain
`references/verify.md`	After deploy, or when an HTTPRoute exists but the app is unreachable
`references/envoy-gateway.md`	Background on the in-cluster gateway controller (Gateway specs, LB IPs, policies)
`references/cloudflare-tunnel.md`	Background on the public ingress path (`cloudflared`, http2 transport, origin config)
`references/tailscale.md`	What Tailscale does — and does not — do in this cluster

Architecture / traffic flow / debug commands → kubernetes/apps/network/AGENTS.md
Pattern reference for HelmRelease / ks.yaml → anton-repo-conventions
Triaging an HTTPRoute that exists but the app is unreachable → debug-flux-reconciliation

流狐档案作者与许可取自来源；运行、权限和网络为流狐检测或估算

流狐分类: AI 智能
作者声明 Agent: 未找到明确声明；不据此推断已兼容或已测试
静态检查: 88 / 100 · 启发式扫描，不代表运行安全
作者 / 版本 / 许可: @wcygan · 未声明 license
流狐 Token 估算: 低消耗
流狐接入估算: 即装即用
是否需要外部 API Key: 未发现要求
检测到的系统要求: macOS
底层运行要求: 未声明
检测到的文件与系统行为: 只读
允许写入 / 修改
检测到的网络行为: 仅限本地
安装命令数: 无（仅作为资料）

档案由构建时根据 SKILL.md 与安装命令自动衍生，可能与作者实际意图存在差异。

需要注意： 未限定 allowed-tools，默认拥有全部工具权限。

输出预览 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`

SKILL.md SKILL.md

# Expose a service

Task skill for routing traffic to a workload. Anton has three supported access paths; architecture deep-dive lives in `kubernetes/apps/network/AGENTS.md`.

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

Pick by **who needs to reach the workload**, not by what feels easiest:

1. **LAN clients only** → `envoy-internal` HTTPRoute. Split-horizon DNS via `k8s-gateway` returns the internal LB to LAN clients.
2. **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`.
3. **Off-LAN raw TCP or non-HTTP** → **Tailscale Service annotation** (`tailscale.com/expose: "true"`). No TLS termination on the proxy — clients reach whatever the backend serves on its target port. Recipe B in `references/tailscale.md`.
4. **LAN clients AND off-LAN HTTP access** → `envoy-internal` HTTPRoute **plus** a Tailscale `Ingress` for the same workload. LAN users keep the `<app>.${SECRET_DOMAIN}` URL; remote ops use `<slug>.<tailnet>.ts.net`.
5. **Genuinely public** (audience that cannot be required to join the tailnet) → `envoy-external` HTTPRoute + Cloudflare tunnel. **Requires explicit user approval** before authoring.

Do **not** pick `envoy-external` to solve "I want to reach this from my laptop off-LAN" — that is what Tailscale is for now (ADR 0012). Shipping something public and pulling it back is irreversible (cached DNS, search engines, external referrers); Tailscale is reversible.

…

证据边界与执行链路

作者原文负责流程事实；流狐只索引当前章节、要点、文件与命令。

章节    -> Exposure policy (ADR 0012, amended 2026-04-17) → Gateway-choice matrix → Workflow → Pre-commit checklist → Canonical in-tree examples → Further reading
要点    -> who needs to reach the workload · LAN clients only · Off-LAN HTTP admin UI (browser) · Tailscale Ingress · Off-LAN raw TCP or non-HTTP · Tailscale Service annotation · LAN clients AND off-LAN HTTP access · plus
文件/命令 -> kubernetes/apps/network/AGENTS.md · envoy-internal · k8s-gateway · Ingress · ingressClassName: tailscale · tls.hosts: [<slug>] · <slug>.<tailnet>.ts.net · references/tailscale.md
内容 SHA-256 -> 848cc25094c5