feat(deploy): Template Entries decide what a template deployment opens and shares (ADR-0081)

[aimeritething]

Decision (product owner, 2026-09-08 — documented in ADR-0081)

Sealos templates may declare Template Entries in their header:

spec:
  entries:
    open: https://${{ defaults.app_host }}.${{ SEALOS_CLOUD_DOMAIN }}/admin
    share: https://${{ defaults.app_host }}.${{ SEALOS_CLOUD_DOMAIN }}/?server=wss://${{ defaults.app_host }}.${{ SEALOS_CLOUD_DOMAIN }}/

Both are full URLs with the template's normal ${{ }} substitution. Open is what the Open control opens after a template deployment; Share is what the Success Record's share strip copies / QR-encodes / posts. Entries are not probed (decided 2026-09-09, below): an entry is kept only when an Ingress of the same deployment serves its host, and that host is a required Deployment Access Endpoint whose probe already gates the record; whether the app answers on a path is not routing health (CONTEXT.md, Public Address Health). The Open Entry is the record's first entry, headed by the App Listening Port it reaches when an AP observed that address (de-duplicated by full URL with the Ingress card's entry); the Share Entry is the record's share address and is never listed as an entry. When the Open URL maps to an App Listening Port (URL host = Ingress rule host → longest-prefix path → backend Service + port), Brain writes brain.io/default-open-port: "<port>" on that Service unless the template preset it, so the AP Public Access Node's Open and the record's Open agree.

This deliberately revises CONTEXT.md's Default Open Port sentence "there is no Project-level or Template-Instance-level open link"; ADR-0079 and ADR-0080 get Status sections pointing at the amendment.

Fallback chains

Control	1st	2nd	3rd
Open	entries.open	App CR spec.data.url (app.sealos.io/v1 App)	automatic Default Open Port rule (unchanged)
Share	entries.share	the resolved Open URL (today's behaviour)	—
Service annotation	template's own brain.io/default-open-port (kept)	Brain preset from the Open URL when it matches one Ingress host + path → Service port	nothing written

Share never falls back to the App CR URL on its own (catalog App CR urls include #token=… and /invite/<code>). An entry whose host no Ingress of the deployment serves is dropped; credentials and fragments disqualify an entry.

Where it runs

• Brain's renderer (sealos-template artifacts): the rules run over the rendered docs before YAML is dumped, so the annotation ships with the apply. RenderedTemplateDeployment gains entries?.
• Provider-applied templates (template-instance-pending / template-instance, i.e. the catalog path): after the Ingress read-back, the runner reads the template source (spec.entries off templateYaml), the resolved defaults off the Instance CR, this run's in-memory inputs, and the Ingresses / Services / App CR from the cluster, applies the same pure rules, and PATCHes the matched Service. Any failure there degrades to "no declared entry" (console warning), never a failed deployment.

Files changed

New

• apps/ui/src/features/deploy/template-entries.ts — pure rules over rendered docs (+ .test.ts, 13 tests)
• apps/ui/src/features/deploy/task/template-provider-entries.ts — provider-path read-back + Service patch (+ .test.ts, 4 tests, globalThis.fetch stub)
• docs/adr/0081-declare-template-entries-for-open-and-share.md

Changed

• apps/ui/src/lib/brain-labels.ts — BRAIN_DEFAULT_OPEN_PORT_ANNOTATION
• apps/ui/src/features/deploy/template-renderer.ts — render entries with the resource context, preset annotation, renderTemplateEntryExpressions for the provider path
• apps/ui/src/features/deploy/task/timeline.ts — DeploymentTemplateEntryUrls, shareUrl on the record (sanitizer + signature), deploymentTaskSuccessFromTimeline({ templateEntries, templateOpenEntryLabel }) takes the entries as declared, deploymentTaskSuccessShareUrl
• apps/ui/src/features/deploy/task/result-readiness.ts — accessEndpointPortLabelForUrl exported (the Ingress-host naming rule, reused to head the Open Entry)
• apps/ui/src/features/deploy/task/runner.ts — wire both paths, head the Open Entry by its port, pass entries to the success builder; no cards for entries
• apps/ui/src/features/deploy/deployment-task-success-section.tsx — share strip uses shareUrl (fallback: primary entry for old records)
• CONTEXT.md — Default Open Port paragraph revised; new glossary term Template Entry (Open Entry / Share Entry); Deployment Access Endpoint and Deployment Task Success Record updated
• docs/adr/README.md, docs/adr/0079-*.md, docs/adr/0080-*.md — index line and Status sections

Verification

Run from the repo root unless noted.

Command	Result
bun check	Checked 1641 files … No fixes applied. — clean
bun typecheck	5/6 tasks pass; @sealai/ui#typecheck fails on one pre-existing error in src/app/preview-canvas-perf/page.tsx(27,3) ('calendar' does not exist in type …ContainerNodeQuickActionKey…). Reproduced identically on a clean origin/main (git stash -u && bun run typecheck); not touched by this PR.
cd apps/ui && bun test src/features/deploy/template-entries.test.ts src/features/deploy/template-renderer.test.ts src/features/deploy/task/direct-timeline.test.ts src/features/deploy/task/timeline.test.ts	90 pass, 0 fail
cd apps/ui && bun test src/features/deploy/task/result-readiness.test.ts	16 pass, 0 fail
cd apps/ui && bun test src/features/deploy/task/template-provider-entries.test.ts	4 pass, 0 fail
cd apps/ui && bun test src/features/deploy/task/runner.template-preserve.test.ts	5 pass, 0 fail
cd apps/ui && bun test src/features/deploy (whole tree, one process)	506 pass / 42 fail vs. baseline origin/main 485 pass / 42 fail — the same 42 pre-existing failures (bun mock.module leaking across files in result-readiness and the GitHub connection suites). No baseline-passing test regressed.

Tests cover: entries parsing + ${{ }} substitution; the Open chain (entries.open → App CR → automatic); Share never derived from the App CR; Service annotation written on host+longest-prefix-path match (numbered and named ports), not written on no match, kept when preset; the Open Entry leading the record (de-duplicated with an Ingress card's entry, or added headed by its port, or by nothing when no AP observed it); the Share Entry as shareUrl only, never an entry, and never a WS(S) URL; record shareUrl snapshot with fallback and old records without it; the share strip helper; provider-path read-back (Instance defaults, Service PATCH, preset respected, degrade on provider failure).

Not verified (no live cluster)

• The provider path end to end: that POST /api/v2alpha/templates/instances leaves resolved spec.defaults[*].value on the Instance CR (Brain's own renderer does; if the provider does not, entries render empty, fail the Ingress-host gate, and Open falls back to the App CR url — the code path is tested, the provider behaviour is not).
• That the API's k8s/get resolves kind=apps to apps.app.sealos.io (discovery matches plural/singular/shortname across lists; instances already works the same way).
• The mergeDefaultOpenPort read of the presetted annotation on a real AP Product View.
• Visual check of the share strip with a shareUrl that differs from the primary entry.

Decisions (product owner, 2026-09-09)

The four open questions this PR first carried were settled with the product owner:

1. Template Entries are not probed. Their host is an Ingress host of the same deployment, which is a required Deployment Access Endpoint already verified before the record exists; an app's response on a path is not routing health (the Public Address Health definition already excludes 404/500). So there are no entry cards, nothing gates, nothing falls back silently. ADR-0081, ADR-0079's Status, and CONTEXT.md (Template Entry, Deployment Access Endpoint, Deployment Task Success Record) rewritten accordingly.
2. The Share Entry is not a record entry. It feeds the share strip only. The Open Entry is the record's first entry.
3. shareUrl is written on every new record — the record is a snapshot; readers keep the primary-entry fallback for records written before the field.
4. The App CR fallback stays a fallback, documented in ADR-0081 only; template authors are pointed at spec.entries. (No template-author docs live in this repo.)

🤖 Generated with Claude Code

https://claude.ai/code/session_012nPEVVc7yiShA1SrfuTUqM