Skip to content

Commit 1bd37b1

Browse files
committed
chore: merge main into vishwa/cedar-openshell
Bring the branch up to date with main (9a85667), which hosts sandboxes on a shared supervisor and isolates networking state per sandbox instance. Conflict resolution: - openshell-supervisor: the policy poll loop keys on the per-instance `gateway` from main and the `PolicyEngine` from this branch. - openshell-supervisor-network: `run_networking` keeps main's per-instance token-grant resolver and denial log; the OPA import is gone because the engine is reached through `PolicyEngine`. - openshell-server: keep main's rewritten authorization test together with the assertion that `Health` stays callable by ordinary users for Cedar capability discovery. - Cargo.lock: main's rustls-webpki and webpki-roots versions are kept; Cedar's regex requirement is retained. Adapt tests that main added since the merge base: the passthrough relay test selects middleware through `PolicyEngine::passthrough_middleware`, the Cedar mixed-version test builds a `GatewayEndpoint`, and the testkit sandbox configuration fetch advertises Cedar support. Refs #4474 Signed-off-by: Vishwanath Raman <[email protected]>
2 parents 2995fb5 + 9a85667 commit 1bd37b1

407 files changed

Lines changed: 37298 additions & 4682 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/build-from-issue/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,5 @@ Use a single issue comment beginning with `> **🏗️ build-plan**` when a plan
3232
Every PR from this issue-backed workflow must have its own existing issue and use `Closes #<id>` in its Related Issue section. For work needing multiple PRs, split the scope into a closable issue per PR. A high-level issue may track those issues but should not be closed by an incomplete PR. Report the implementation, verification, and any remaining limitation in the PR description, rather than copying earlier issue diagnostics.
3333

3434
Do not apply acceptance or roadmap decisions on behalf of a maintainer. Do not introduce `agent:*` workflow labels.
35+
36+
For first-party security-sensitive crypto, use `openshell-crypto` and extend its facade/backend contracts when needed. Follow the [crypto architecture](../../../crates/openshell-crypto/CRYPTO.md) for compatibility, failure handling, and explicit coverage exceptions.

‎.agents/skills/create-github-pr/SKILL.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,9 @@ PR descriptions must follow the project's [PR template](.github/PULL_REQUEST_TEM
176176
## Changes
177177
<!-- Bullet list of key changes -->
178178

179+
## Release Notes
180+
<!-- Optional: a few short, easy-to-read sentences about the user-facing change -->
181+
179182
## Testing
180183
<!-- What testing was done? -->
181184
- [ ] Checks appropriate to the affected code and behavior pass
@@ -188,6 +191,8 @@ PR descriptions must follow the project's [PR template](.github/PULL_REQUEST_TEM
188191
```
189192

190193
Populate the testing checklist based on what was actually run. Check boxes for steps that were completed.
194+
Keep the Release Notes section concise, with only a few easy-to-read sentences.
195+
Leave it empty when the summary already captures the user-facing change.
191196

192197
## Example PR (Complete)
193198

@@ -209,6 +214,10 @@ Closes #456
209214
- Default page size is 100, max is 1,000
210215
- Structured responses include `next_page_token`
211216
217+
## Release Notes
218+
219+
Sandbox list results can now be paged through with `--page-size` and `--page-token`.
220+
212221
## Testing
213222
214223
- [x] Relevant CLI format, lint, and unit checks pass

‎.agents/skills/fix-security-issue/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,5 @@ Use this skill after an authorized `review-security-issue` review identifies an
1616
5. Follow `create-github-pr` and use `Closes #<id>` for the reviewed issue. Every PR from this issue-backed remediation workflow must close its own issue; split multi-PR remediations into separate issues in the authorized security workflow. Keep the PR description appropriately scoped to its disclosure venue.
1717

1818
Begin any fix comments with `> **🔧 security-fix-agent**`. Do not change human disposition or introduce `agent:*` workflow labels.
19+
20+
For first-party security-sensitive crypto, use `openshell-crypto` and extend its facade/backend contracts when needed. Follow the [crypto architecture](../../../crates/openshell-crypto/CRYPTO.md) for compatibility, failure handling, and explicit coverage exceptions.

‎.agents/skills/helm-dev-environment/SKILL.md‎

Lines changed: 49 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,45 @@ Override with env vars before running `helm:k3s:create`:
5757
`mcr.microsoft.com/dotnet/aspire-dashboard:latest`)
5858
- `HELM_K3S_COLLECTOR_HEALTH_TIMEOUT` (default: `120` seconds)
5959

60+
### Shared supervisor plumbing
61+
62+
Set `gatewayConfig.openshell.drivers.kubernetes.supervisor_topology`
63+
using a values file (the table key is literally `openshell.drivers.kubernetes`):
64+
65+
```yaml
66+
gatewayConfig:
67+
openshell.drivers.kubernetes:
68+
supervisor_topology: gateway
69+
```
70+
71+
The gateway chart creates a single-replica shared supervisor Deployment,
72+
Service, NetworkPolicy, and an empty `<release>-supervisor-token` Secret in
73+
the release namespace, regardless of shared/managed/operator workspace mode.
74+
The gateway mints a supervisor token from its sandbox-JWT signing key, writes
75+
it into that Secret (the gateway Role may `get`/`patch` only that Secret), and
76+
renews it at half its lifetime; the supervisor mounts the Secret and presents
77+
the token on the private `openshell.supervisor.host.v1` assignment stream,
78+
which accepts nothing else. The topology requires gateway TLS and the signing
79+
key (`server.disableTls` is rejected; the gateway refuses to start without
80+
`gateway_jwt`). New sandbox generations run as sandbox instances in that
81+
process. The chart starts `--mode=shared`, sets `--gateway-endpoint` to the
82+
gateway gRPC URL, mounts the token at `--token-file`, and binds `--address`
83+
(5501) to a plain TCP health listener for the `tcpSocket` probes; nothing
84+
dials the supervisor but sandbox runtimes (5500) and the kubelet. Build the gateway, supervisor, and sandbox
85+
images from the same branch: all three must support the routed runtime
86+
connection and the assignment stream. `workspace` is reserved and rejected.
87+
Omit the field to disable it. `mise run
88+
e2e:kubernetes:shared-supervisor` runs the focused e2e
89+
(`ci/values-supervisor.yaml`). The task prepends that overlay to any
90+
colon-separated `OPENSHELL_E2E_KUBE_EXTRA_VALUES` list, so layer a
91+
workspace-mode overlay to cover managed namespaces:
92+
93+
```bash
94+
OPENSHELL_E2E_KUBE_EXTRA_VALUES=deploy/helm/openshell/ci/values-workspace-managed.yaml \
95+
OPENSHELL_E2E_KUBE_IMAGE_PULL_SECRET=e2e-regcred \
96+
mise run e2e:kubernetes:shared-supervisor
97+
```
98+
6099
### 2. Deploy OpenShell
61100

62101
**Iterative dev** (rebuilds on file changes, recommended during active development):
@@ -81,7 +120,16 @@ The Skaffold flow builds distinct `gateway`, `sandbox`, and `supervisor` images
81120
and deploys the OpenShell Helm chart. The Kubernetes driver creates a
82121
capability-free workload Pod and a directly managed capability-free supervisor
83122
Pod. One namespace-wide NetworkPolicy denies direct egress from every OpenShell
84-
workload Pod. The
123+
workload Pod. New sandbox generations use `runtime-initiated` control: the sandbox
124+
runtime dials its supervisor through `os-supervisor-<id>`. The legacy
125+
`os-boundary-<id>` Service keeps selecting the workload for old gateways during
126+
rolling upgrades. New gateways create both Services and bind the control-mode
127+
annotation to its runtime generation. The driver adds a per-sandbox
128+
`os-control-<id>` NetworkPolicy for that path only. Existing running generations
129+
keep their connection until replaced; stop/start and gateway recovery that
130+
recreates both Pods upgrade legacy generations automatically. Use compatible
131+
gateway, supervisor, and sandbox runtime images together; there is no legacy
132+
rollout flag. The
85133
`pkiInitJob` hook (a pre-install Job that runs `openshell-gateway generate-certs`)
86134
generates gateway and CLI TLS secrets on first install. Supervisor Pods project
87135
only `ca.crt` and authenticate gateway RPCs with sandbox bearer tokens. User
Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
---
2+
name: release-captain
3+
description: Run the weekly OpenShell release captain checklist. Monday checks the pre-release train, triages failures and the compatibility review, and drafts the coordination post. Tuesday promotes the qualified pre-release after approval, verifies publication, and starts the next train. Trigger keywords - release captain, weekly release, Tuesday release, cut the release, release checklist, pre-release status, release train, start next train, stable release.
4+
metadata:
5+
internal: true
6+
---
7+
8+
# Release Captain
9+
10+
OpenShell publishes a stable release every Tuesday from a qualified
11+
pre-release ([RFC 0014](../../../rfc/0014-release-stability/README.md)). The
12+
release captain keeps the week's pre-release train green, coordinates the last
13+
merges, cuts the release, and starts the next train.
14+
15+
## How to use this skill
16+
17+
| When | Ask | What happens |
18+
|---|---|---|
19+
| The week before your turn | "I'm release captain next week. Is the train ready?" | Checks that the next version's `-pre.1` exists. If not, ask this week's captain to start the train (Tuesday step 6). Then check each weekday that Auto-Tag's pre-release ran and passed (`gh run list --workflow release-prerelease.yml --limit 3`), and fix failures as they happen (Monday step 3) instead of on Monday. |
20+
| Monday | "Run the release captain Monday checklist." | Monday steps 1–4. |
21+
| A pre-release failed | "`vX.Y.Z-pre.N` failed, help me fix it." | Monday step 3 and Recovery. |
22+
| Tuesday | "Cut the release." | Tuesday steps 1–6, ending with starting the next train. |
23+
24+
## Guardrails
25+
26+
Get explicit approval, with the exact command and target SHA, before pushing a
27+
tag, dispatching, rerunning, or cancelling a workflow, merging or approving a
28+
PR, or posting in Slack or GitHub. Never repoint a stable tag, delete a `-pre.N`
29+
tag, or start a second `Pre-release` run for a tag; it has no concurrency guard.
30+
31+
## How the train works
32+
33+
- A train has one base version, such as `v0.1.4`, fixed by its `-pre.1` tag. A
34+
patch train can't take breaking changes to Stable interfaces.
35+
- `Release Auto-Tag` runs on weekdays at 14:00 Europe/Zurich. If `main` has
36+
commits since the latest `-pre.N`, it tags the next one and dispatches
37+
`Pre-release` (`release-prerelease.yml`, about 45 minutes). It skips when the
38+
train has no `-pre.1` or the base version is already stable.
39+
- `Pre-release` builds, then publishes and qualifies in parallel, and writes a
40+
`release-notes` preview artifact. Pushing a `-pre.N` tag by hand starts it.
41+
- `Release` (`release.yml`) is dispatched by hand with the stable version. It
42+
picks the highest `-pre.N` on `main` whose whole `Pre-release` run passed,
43+
creates the stable tag on that commit, and publishes without requalifying.
44+
45+
## Setup
46+
47+
```shell
48+
export GH_REPO=NVIDIA/OpenShell
49+
git fetch origin main --tags --force
50+
PREV=$(git tag -l 'v*' --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
51+
git tag -l 'v*' --sort=-v:refname | grep -E -- '-pre\.[0-9]+$' | head -5
52+
```
53+
54+
Find the `Pre-release` run for a tag. A tag pushed by hand runs on the tag; an
55+
Auto-Tag run is dispatched on `main`:
56+
57+
```shell
58+
TAG=vX.Y.Z-pre.N
59+
gh run list --workflow release-prerelease.yml --branch "$TAG"
60+
gh run list --workflow release-prerelease.yml --event workflow_dispatch --commit "$(git rev-parse "$TAG^{commit}")"
61+
```
62+
63+
Preview the candidate `Release` would promote, read-only:
64+
65+
```shell
66+
VERSION=vX.Y.Z
67+
wt=$(mktemp -d)
68+
git worktree add -q --detach "$wt" origin/main
69+
(cd "$wt" && GITHUB_REPOSITORY=NVIDIA/OpenShell uv run -q --no-project python tasks/scripts/select-release-candidate.py "$VERSION" --branch main | jq .)
70+
git worktree remove --force "$wt"
71+
```
72+
73+
## Monday: pre-flight
74+
75+
1. **Check the candidate.** Run the preview. If the latest `-pre.N` isn't the
76+
candidate, its run failed; read why:
77+
78+
```shell
79+
RUN=<run-id>
80+
gh run view "$RUN" --json jobs --jq '.jobs[] | select(.conclusion == "failure" or .conclusion == "timed_out") | "\(.name)\t\(.url)"'
81+
gh run view "$RUN" --log-failed
82+
```
83+
84+
If the next version has no `-pre.1`, start the train (Tuesday step 6).
85+
86+
2. **Triage the compatibility review** for the candidate's run. It's advisory,
87+
and a green job doesn't mean it found no breaks:
88+
89+
```shell
90+
ATTEMPT=$(gh run view "$RUN" --json attempt --jq .attempt)
91+
dir=$(mktemp -d)
92+
gh run download "$RUN" -n "compatibility-review-run-$RUN-attempt-$ATTEMPT" -D "$dir"
93+
jq '{status, verdict: .review.verdict}' "$dir/report.json"
94+
cat "$dir/report.md"
95+
```
96+
97+
Only `complete` with `no_unaddressed_breaks` is clean. A real break needs a
98+
fix, a revert, a minor train, or a maintainer-approved exception with upgrade
99+
steps in the release notes.
100+
101+
3. **Fix forward.** A failed pre-release doesn't end the train. Find the cause,
102+
and let the failed run finish rather than cancelling it.
103+
104+
A rerun repeats the same commit and workflow, so it only helps with a
105+
transient failure (see Recovery). Anything that needs a code or workflow
106+
fix ships in a new number: that `-pre.N` stays failed, and `Release` skips
107+
it. Merge the fix, then cut the next `-pre.N` from the tip of `main` after
108+
approval:
109+
110+
```shell
111+
gh workflow run release-auto-tag.yml --ref main
112+
```
113+
114+
Tag a specific commit by hand (as in Tuesday step 6) only when the tip of
115+
`main` isn't the commit you want.
116+
117+
4. **Draft the coordination post.** Start a thread in the OpenShell channel of
118+
the CNCF Slack. The release ships from `main` with no release branch, so the
119+
thread is for getting ready PRs reviewed and merged before the cutoff. List
120+
approved PRs:
121+
122+
```shell
123+
gh pr list --base main --state open --search "review:approved" --json number,title,author --jq '.[] | "#\(.number) \(.title) (@\(.author.login))"'
124+
```
125+
126+
The release ships the final pre-release's commit, if it passes. Pick a
127+
cutoff before Tuesday's Auto-Tag run, or a later one after which you tag the
128+
final pre-release by hand. Don't promise that everything merged by the
129+
cutoff ships, or name the next version.
130+
131+
```text
132+
:thread: OpenShell vX.Y.Z release, Tuesday <date>. I'm release captain this week.
133+
134+
Status: vX.Y.Z-pre.N (<commit>) passed qualification. <blockers and owners, or "No blockers.">
135+
136+
Reply here with any ready PRs you'd like in vX.Y.Z. Merge cutoff is <HH:MM UTC> (<local time>) Tuesday. <"Tuesday's automatic pre-release picks up everything merged by then" | "I'll cut the final pre-release after the cutoff">, and vX.Y.Z ships from it if it passes qualification. Anything that misses it goes in the next release.
137+
```
138+
139+
If the pre-release that ships was cut before the posted cutoff, say so in
140+
the thread, with its commit and time.
141+
142+
## Tuesday: cut the release
143+
144+
1. **Select the final candidate.** For a late cutoff, cut the final `-pre.N`
145+
after the cutoff as in Monday step 3. When it finishes, run the preview and
146+
repeat Monday step 2 for its run.
147+
148+
2. **Request approval.** Present the candidate tag, commit, qualification run,
149+
compatibility assessment, commits since `$PREV`, and release notes preview:
150+
151+
```shell
152+
git log --oneline --no-merges "$PREV..<candidate_tag>"
153+
gh run download "$RUN" -n release-notes -D "$dir/notes" && cat "$dir/notes/release-notes.md"
154+
```
155+
156+
The notes come from each PR's "Release Notes" section. To fix them, edit the
157+
PR, then preview with
158+
`gh workflow run release.yml --ref main -f tag="$VERSION" -f notes-only=true`.
159+
160+
3. **Dispatch the release.** After approval:
161+
162+
```shell
163+
gh workflow run release.yml --ref main -f tag="$VERSION"
164+
```
165+
166+
4. **Watch and verify.** Check that `Select Qualified Prerelease` names the
167+
approved candidate, the GitHub Release has assets, no job failed, and the
168+
wheel reached PyPI:
169+
170+
```shell
171+
gh run watch <run-id> --exit-status
172+
gh release view "$VERSION" --json isPrerelease,publishedAt,assets --jq '{isPrerelease, publishedAt, assets: (.assets | length)}'
173+
```
174+
175+
5. **Close the loop.** Draft a short reply to the coordination thread. Point
176+
to the release notes rather than repeating them:
177+
178+
```text
179+
:white_check_mark: :ship: OpenShell vX.Y.Z is out: https://github.com/NVIDIA/OpenShell/releases/tag/vX.Y.Z
180+
181+
It shipped from vX.Y.Z-pre.N (<commit>). I'll be starting the <next version>-pre.* jobs shortly for next week.
182+
183+
Please check the release notes for upgrade notes that operators might care about. I'm also moving everything still open in the X.Y.Z milestone to <next milestone>.
184+
185+
Thanks everyone!
186+
```
187+
188+
After approval, move the milestone's open items to the next milestone.
189+
190+
6. **Start the next train.** This is this week's captain's last duty. Until the
191+
next `-pre.1` exists, Auto-Tag skips. Agree with the maintainers on patch
192+
(the default) or minor
193+
([version selection](../../../rfc/0014-release-stability/release-version-selection.md)).
194+
Seed it on a commit after `$VERSION` with a passing `Release Dev` run:
195+
196+
```shell
197+
for sha in $(git rev-list --max-count=10 "$VERSION..origin/main"); do
198+
state=$(gh run list --workflow release-dev.yml --commit "$sha" --json status,conclusion --jq '.[0] | if .status == "completed" then .conclusion else .status end')
199+
echo "${sha:0:9} ${state:-none} $(git log -1 --format=%s "$sha")"
200+
done
201+
```
202+
203+
After approval, push the tag. The `-c` and `/dev/null` keep `git` from
204+
signing the tag and opening an editor:
205+
206+
```shell
207+
NEXT=vX.Y.Z-pre.1 NEXT_SHA=<commit>
208+
git -c tag.gpgSign=false tag "$NEXT" "$NEXT_SHA" </dev/null
209+
git push origin "refs/tags/$NEXT"
210+
```
211+
212+
You're done when that `Pre-release` run passes, or its failure is handed to
213+
next week's captain.
214+
215+
## Recovery
216+
217+
| Symptom | Action |
218+
|---|---|
219+
| Transient infrastructure failure in a pre-release, including a registry push | After approval, `gh run rerun <run-id> --failed`. `Release` won't select the run until all of it passes. |
220+
| Pre-release run ends in `startup_failure` | The workflow file is invalid at that commit. Fix it in a new `-pre.N` (Monday step 3). |
221+
| Code defect or `Cargo Deny` advisory | Rerunning won't help. Fix it in a new `-pre.N` (Monday step 3). |
222+
| `Release` fails after selection | After approval, rerun only the failed jobs that haven't published. |
223+
224+
## Related
225+
226+
- `release-openshell`: the short procedure behind Tuesday steps 1–4.
227+
- `watch-github-actions`: general `gh run` monitoring and log retrieval.
228+
- `CI.md`: release workflows, qualification profile, and scanner policies.

‎.agents/skills/release-openshell/SKILL.md‎

Lines changed: 39 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,15 +7,46 @@ metadata:
77

88
# Release OpenShell
99

10-
For the intended release version, pick the latest prerelease whose Release
11-
Qualification job passed. Confirm that its qualification summary matches the
12-
tag and commit. Present the candidate and changes since the previous stable
13-
release to the maintainer; once approved, tag that exact commit as `vX.Y.Z`.
10+
For the intended release version and branch, inspect the latest passing
11+
prerelease and changes since the previous stable release. Present the candidate
12+
to the maintainer. Once approved, dispatch Release from that branch:
13+
14+
```shell
15+
gh workflow run release.yml --ref main -f tag=vX.Y.Z
16+
```
17+
18+
Use the support branch instead of `main` for a previous minor version. Release
19+
selects the highest-numbered `vX.Y.Z-pre.N` reachable from that branch with a
20+
successful Pre-release run triggered by that tag or dispatched on the same branch,
21+
and matching passing `release-tag-v1` qualification evidence. Missing or expired evidence blocks
22+
promotion. Inspect the selected candidate in the promotion job summary.
23+
The entire Pre-release run must succeed, including publication. If qualification
24+
passed but publication failed, rerun the failed jobs before promoting the candidate.
25+
26+
Release creates `vX.Y.Z` at that exact commit, then rebuilds and publishes all
27+
stable artifacts without rerunning qualification. Embedded versions change, so
28+
stable artifacts are not byte-identical to the qualified prerelease. An existing
29+
stable tag may be retried only if it already points to the selected commit.
30+
Stable images are saved as OCI archives during the build and pushed under the
31+
stable version tags during publication. Their SBOMs are verified before updating
32+
`latest`; the qualified prerelease's commit-SHA image tags remain unchanged.
1433

1534
If no prerelease exists, agree on the version and source commit, then create and
16-
push `vX.Y.Z-pre.1`. Wait for qualification to pass before promoting it.
35+
push `vX.Y.Z-pre.1`. Prerelease tag pushes start Pre-release. If the tag was
36+
created using `GITHUB_TOKEN`, dispatch Pre-release explicitly on the intended branch:
37+
38+
```shell
39+
gh workflow run release-prerelease.yml --ref main -f tag=vX.Y.Z-pre.1
40+
```
41+
42+
Wait for the entire Pre-release run to pass before promoting it. Stable tag pushes do not
43+
start Release. Release Auto-Tag creates and dispatches prereleases on `main`.
44+
45+
Stable releases serialize across branches. A release older than the highest
46+
stable Git tag publishes versioned artifacts without moving GHCR `latest`, the
47+
GitHub latest release, npm `latest`, or snap `latest/stable`. Its npm package
48+
uses `release-X.Y`; snap files remain available in its GitHub Release rather than
49+
updating a Snap Store support track. Docs retain an
50+
immutable version and advance latest only for a newer version.
1751

18-
Prerelease tag pushes start Pre-release; stable tag pushes start Release.
19-
Release Auto-Tag uses an explicit dispatch because its `GITHUB_TOKEN` pushes do
20-
not trigger workflows.
2152
Watch the stable release run and report its result.

0 commit comments

Comments
 (0)