Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,17 @@ the app page show the chain. Release v0.8.0. Accepted with `tweinmann/shelf-hell
2 min 36 s (Phase 10: 1 min 33 s), an unsigned artifact and an unsigned image were refused, and
`gretter` was exposed only once verified. `shelf serve` now follows a rewritten kubeconfig.
Results in `openspec/changes/archive/2026-10-28-phase-11-verification-chain`.
Next: Phase 12 (hardening).
Phase 12 complete (2026-10-28): hardening. App and preview namespaces enforce Pod Security
`baseline` (and list what `restricted` would refuse), and the NetworkPolicy `shelf-isolation`
lets pods reach their own namespace, DNS and the internet only; only Traefik reaches in, only
cloudflared reaches Traefik. LAN ranges are per app and the operator's (`--allow-lan`), never a
preview's. `tests:` in app.yaml run as Helm test hooks after every rollout: a failing test rolls
an app back and leaves a preview red, and `--wait` is Ready only once they pass; `shelf app
report` writes the per-branch report for a pull request. Release v0.9.0. Accepted with
`tweinmann/shelf-hello`: a test on main was Ready, a broken test on a branch kept a red preview
running, and on main it rolled `gretter` back within 32 s while it kept answering. Results in
`openspec/changes/archive/2026-10-28-phase-12-hardening`.
Next: Phase 13 (host).

## Working agreements

Expand Down
13 changes: 8 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,10 @@ your own Cloudflare account, or a temporary `*.trycloudflare.com` name that need
> shelf is a learning and reference project for platform engineering, and it is
> **pre-production**: production is a separate cluster reached through eject (planned). It is
> **still under construction**: today a push to your repository deploys your app, and the CLI or
> an admin UI in the browser adds, changes and removes apps, every branch runs as a preview, and
> only a signed and scanned app can be exposed. The host setup, the installer and eject are
> planned, not built. See [Status](#status).
> an admin UI in the browser adds, changes and removes apps, every branch runs as an isolated
> preview that counts as green once its tests pass, and only a signed and scanned app can be
> exposed. The host setup, the installer and eject are planned, not built. See
> [Status](#status).

Where this is going: you run Claude Code (other agents later) in several worktrees at once. Every
branch your agents push gets its own preview of the complete stack, database included, in a
Expand Down Expand Up @@ -113,7 +114,7 @@ one starts.
| 9 | Agent interface: `--json`, `shelf app status --wait`, `shelf app open` | ✅ done |
| 10 | Branch previews: one isolated preview per branch, discovered from the registry | ✅ done |
| 11 | Verification chain: signatures, scans, provenance; exposure only for verified digests | ✅ done |
| 12 | Hardening: Pod Security, NetworkPolicies, smoke tests per preview | planned |
| 12 | Hardening: Pod Security, NetworkPolicies, smoke tests per preview | ✅ done |
| 13 | Host: macOS with Colima and Linux with k3s, `shelf doctor`, `shelf destroy` | planned |
| 14 | Service and one-command installer | planned |
| 15 | Logs, resource usage, self-update | planned |
Expand Down Expand Up @@ -465,7 +466,9 @@ A test passes when its container exits with 0. It runs inside the app's namespac
the components by their references (`http://${web.host}:${web.port}/`), not through a route,
and it can read the app's secrets. Let it retry its first connection (`curl --retry 5
--retry-connrefused`): for a moment after a pod starts, the network policy may not know it yet,
and refuses it. Until every test passed, the app is not Ready:
and refuses it. A curl test that checks several URLs needs `--fail-early`: without it, curl
exits with the status of the last URL only, so a failure before it passes unnoticed. Until every
test passed, the app is not Ready:

- on the app, a failing test fails the upgrade, so the previous version comes back;
- on a preview, the failing version keeps running, so you can look at it with
Expand Down
3 changes: 3 additions & 0 deletions examples/tenant/.claude/skills/shelf/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,9 @@ The first stage that is not Ready is the cause; everything after it is a consequ
its namespace. A test reaches the components by their references, such as
`http://${web.host}:${web.port}/`, never through a route, and passes when it exits with 0. Add
one for what a change must not break; the wait counts the commit as Ready only once they pass.
With curl, pass `--retry 5 --retry-connrefused` (a new pod's first connection can be refused for
a moment), and `--fail-early` when it checks several URLs, or only the last one counts. Check
that a test can fail: an app that answers every path with 200 makes `-f` on a wrong path pass.

## What you cannot do

Expand Down
9 changes: 3 additions & 6 deletions internal/render/render.go
Original file line number Diff line number Diff line change
Expand Up @@ -315,13 +315,10 @@ func encodeYAML(v any) ([]byte, error) {
const ConfigMapName = "shelf-values"

// ParseApp reads back what MarshalApp wrote, so that anyone holding the ConfigMap of an app can
// see what it is made of without going to the registry for the artifact.
// see what it is made of without going to the registry for the artifact. The artifact may come
// from a newer workflow than this shelf, so fields it does not know are left out.
func ParseApp(data []byte) (*schema.App, error) {
doc, err := schema.Parse(ConfigMapKey, data)
if err != nil {
return nil, err
}
return doc.App, nil
return schema.ParseLenient(ConfigMapKey, data)
}

// ConfigMapKey is the data key holding the resolved app.yaml; the HelmRelease reads it through
Expand Down
34 changes: 34 additions & 0 deletions internal/schema/parse.go
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,40 @@ func Parse(file string, data []byte) (*Document, error) {
return &Document{File: file, App: &app, root: &root}, nil
}

// ParseLenient decodes what another version of shelf may have written, such as the resolved
// app.yaml in an app's ConfigMap: fields this version does not know are left out instead of
// being errors, so an older shelf can still show an app whose workflow is newer. Everything a
// person writes goes through Parse.
func ParseLenient(file string, data []byte) (*App, error) {
var root yaml.Node
if err := yaml.Unmarshal(data, &root); err != nil {
return nil, fmt.Errorf("%s: %w", file, err)
}
if root.Kind == 0 {
return nil, fmt.Errorf("%s: file is empty", file)
}
// Route checks its own keys, since node.Decode knows no KnownFields; drop the ones it
// would refuse.
if components := mappingValue(root.Content[0], "components"); components != nil {
for i := 1; i < len(components.value.Content); i += 2 {
if route := mappingValue(components.value.Content[i], "route"); route != nil && route.value.Kind == yaml.MappingNode {
kept := route.value.Content[:0]
for j := 0; j+1 < len(route.value.Content); j += 2 {
if slices.Contains(routeKeys, route.value.Content[j].Value) {
kept = append(kept, route.value.Content[j], route.value.Content[j+1])
}
}
route.value.Content = kept
}
}
}
var app App
if err := root.Decode(&app); err != nil {
return nil, fmt.Errorf("%s: %w", file, err)
}
return &app, nil
}

// Line returns the line of the node at path, e.g. ("components", "web", "port"). If the path
// does not exist, it returns the line of the deepest ancestor that does, and 0 without a tree.
func (d *Document) Line(path ...string) int {
Expand Down
39 changes: 39 additions & 0 deletions internal/schema/parse_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -136,3 +136,42 @@ func TestSecretEnvName(t *testing.T) {
t.Errorf("got %q", got)
}
}

// TestParseLenient covers what an older shelf reads from the cluster: the resolved app.yaml of a
// newer workflow, with fields it does not know, at the top, in a component and in a route.
func TestParseLenient(t *testing.T) {
t.Parallel()
app, err := ParseLenient("app.yaml", []byte(`apiVersion: shelf.dev/v1alpha1
name: greeter
components:
web:
image: nginx@sha256:0000000000000000000000000000000000000000000000000000000000000000
ports: { main: 8080 }
route: { path: /, port: main, rewrite: true }
sidecar: { image: envoy }
db:
image: postgres:16
route: /db
futureSection:
anything: [1, 2]
`))
if err != nil {
t.Fatal(err)
}
web := app.Components["web"]
if web == nil || web.Ports["main"] != 8080 || web.Route == nil || web.Route.Path != "/" || web.Route.Port != "main" {
t.Errorf("web %+v", web)
}
if db := app.Components["db"]; db == nil || db.Route == nil || db.Route.Path != "/db" {
t.Errorf("db %+v", db)
}
// What a person writes stays strict.
if _, err := Parse("app.yaml", []byte("apiVersion: shelf.dev/v1alpha1\nname: a\nfutureSection: {}\n")); err == nil {
t.Error("Parse accepts an unknown field")
}
for _, bad := range []string{"", "components: [\n", "components: 5\n"} {
if _, err := ParseLenient("app.yaml", []byte(bad)); err == nil {
t.Errorf("ParseLenient accepts %q", bad)
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -378,3 +378,37 @@ What apply found:

Also confirmed: `shelf serve` kept working through two `cluster-reset`s without a restart, the
follow-up of Phase 11.

### Level 3 (`tweinmann/shelf-hello` as `gretter`, release v0.9.0, 2026-10-28)

The dev cluster was installed again from the release, keyless, and `gretter` added privately with
previews. Both release artifacts carried keyless signatures of `release.yml`.

| Check | Result |
|---|---|
| `gretter` on the release platform | verified; Pod Security baseline; for `restricted`, only "unrestricted capabilities, runAsNonRoot" are left per pod (decision 1b), Postgres and Mongo run |
| Push of a curl test to `main` (`33f8756`) | CI 1 min 58 s (Phase 11: 2 min 36 s, cold cache); Ready, "1 passed: smoke"; the scan covers the test's image |
| A branch with a test that fails (`3a40f54`) | CI 1 min 48 s; `--wait --commit` ends `Failed` at "the tests" with exit code 7 and the log; the preview keeps running that commit; `shelf app report --preview` shows it red, with the log, the scan and the comparison with `main` |
| The same commit merged to `main` | CI 1 min 35 s; `--wait` ends `Failed` after 22 s; Helm rolled back 10 s later; after four attempts (about 2 min) `gretter` runs the values of `33f8756` again, `/` answered 200 throughout; "the app" Ready, "the tests" Failed |

Two things the acceptance taught, both now in the README and the tenant skill:
- **A test has to be able to fail.** The web component of `shelf-hello` answers every path with
200, so `curl -f …/nope` passed. Breaking the port did fail.
- **curl with several URLs** exits with the status of the last one; a failure before it passes
unnoticed without `--fail-early`.

As foreseen in the risks, a failing test on `main` makes helm-controller retry the upgrade three
times before it stalls, replacing the pods each time; the verdict does not wait for that.

After the acceptance, the test was fixed on `main` (`801843a`): Ready, verified, and the release
left its stalled state with the new values. `gretter` was then exposed again with
`--cloudflare tobile --domain tobile.ch`: deployed privately, verified, then tunnel and record
created; `https://gretter.tobile.ch/` answered 200, so cloudflared reaches Traefik under
`shelf-cloudflared` on the released platform.

**Found after the archive, and fixed with it:** an admin UI started before Phase 12 failed on the
app page of `gretter` once its values held `tests`: shelf read the resolved app.yaml from the
cluster as strictly as one a person writes. `render.ParseApp` now uses `schema.ParseLenient`,
which leaves out fields it does not know (also in a long-form `route`), so an older shelf can
still show an app built by a newer workflow; `shelf validate` and `render` stay strict. The main
spec `app-manifest` has the requirement "Reading a resolved app.yaml from the cluster".
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@
- `smoke-quick` checks that the quick tunnel's name is still read through the pod proxy.

Record the turnaround with and without a test in design.md under "Results".
- [ ] 9.2 Level 3 with `tweinmann/shelf-hello`:
- [x] 9.2 Level 3 with `tweinmann/shelf-hello`:
- add a curl test and push to main: Ready;
- a branch whose test fails: a red preview that keeps running, then `shelf app report` for it;
- merge a failing test: `gretter` keeps the previous version.
Expand Down
4 changes: 2 additions & 2 deletions openspec/config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ context: |
artefact becomes reachable beyond a preview, and the same verified state goes to any Kubernetes
cloud as a pull request (eject), without depending on shelf. shelf runs on any Linux host with
k3s, with a one-step install on a Mac (Colima). Today it runs against any kubecontext, developed
on the dev cluster, with branch previews and the verification chain; the host setup and eject
are planned. shelf is pre-production: an app's "main" is its stable, verified state, not
on the dev cluster, with isolated, tested branch previews and the verification chain; the host
setup and eject are planned. shelf is pre-production: an app's "main" is its stable, verified state, not
production. Learning and reference project for platform engineering.

OpenSpec is the only planning source: `openspec/specs/` is what shelf does today,
Expand Down
16 changes: 13 additions & 3 deletions openspec/specs/admin-ui/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -163,8 +163,9 @@ reason of the first broken step of its diagnosis.
The system SHALL show at `/apps/<name>` the app's phase, the first stage that is not ready with
its message and hint, its address, artifact, revision and deploy time, its components each with
its phase and address (routed ones as links, the others marked `inside the cluster only` or `not
exposed`), its access settings, the names of its generated secrets, its verification as `shelf
app status` prints it, and the diagnosis chain under `How it gets here`.
exposed`), its access settings, the names of its generated secrets, its verification and its
isolation as `shelf app status` prints them, and the diagnosis chain with the tests under `How
it gets here`.

#### Scenario: Routed and internal components
- **WHEN** an app has a routed `web` component and an unrouted `db` component
Expand All @@ -180,6 +181,10 @@ app status` prints it, and the diagnosis chain under `How it gets here`.
- **WHEN** the running artifact of an app is unsigned
- **THEN** the page says it is not verified and why, and that it cannot be exposed

#### Scenario: Failing test
- **WHEN** the test `smoke` of an app failed
- **THEN** the page shows the tests stage as Failed with the test's name and the end of its log

### Requirement: Changes run as jobs
The system SHALL run every change made from the UI (add an app, deploy another artifact or tag,
deploy again, change an app's connections and domain, remove an app, save or remove a connection)
Expand Down Expand Up @@ -242,7 +247,8 @@ report a failed audit write instead of hiding it.
The system SHALL offer on the app page a form that deploys the app from another artifact or tag
(`POST /apps/<name>/deploy`), a button that deploys the same tag again
(`POST /apps/<name>/redeploy`), and a form that changes the registry connection, the Cloudflare
connection or quick tunnel, and the domain (`POST /apps/<name>/access`), each running as a job.
connection or quick tunnel, the domain and the LAN exceptions (`POST /apps/<name>/access`), each
running as a job.

#### Scenario: Roll back to a commit tag
- **WHEN** the deploy form is submitted with `oci://ghcr.io/owner/greeter:sha-905acce`
Expand All @@ -254,6 +260,10 @@ connection or quick tunnel, and the domain (`POST /apps/<name>/access`), each ru
- **THEN** a job `Change the connections of <name>` makes the app private; the choice `@quick`
asks for a quick tunnel instead

#### Scenario: LAN exception from the browser
- **WHEN** the access form is submitted with the LAN exceptions `192.168.1.10/32`
- **THEN** the job gives the app that exception, as `shelf app credentials --allow-lan 192.168.1.10/32` does; an empty field takes the exceptions away, and an invalid range is answered with status 400 and the reason, without a job

### Requirement: Removing an app needs its name typed
The system SHALL remove an app with its namespace and volumes at `POST /apps/<name>/delete` only
when the field `confirm` equals the app's name.
Expand Down
36 changes: 33 additions & 3 deletions openspec/specs/agent-interface/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,12 +48,12 @@ know. A field without a value SHALL be omitted, never set to `null`.

### Requirement: Commands with JSON output
`--json` SHALL be offered by `shelf app status` (kind `AppList` without a name, `AppStatus` with
one, `WaitResult` with `--wait`), `shelf app tags` (`TagList`), `shelf connection list`
(`ConnectionList`) and `shelf version` (`Version`).
one, `WaitResult` with `--wait`), `shelf app report` (`Report`), `shelf app tags` (`TagList`),
`shelf connection list` (`ConnectionList`) and `shelf version` (`Version`).

#### Scenario: One app in detail
- **WHEN** a user runs `shelf app status hello --json` for a healthy app
- **THEN** the `AppStatus` holds the app's name, phase, address, artifact, registry connection, exposure, revision, commit, deploy time, components with their addresses, and the five stages each with name, object, phase and, where present, reason, message and hint
- **THEN** the `AppStatus` holds the app's name, phase, address, artifact, registry connection, exposure, revision, commit, deploy time, components with their addresses, and the six stages each with name, object, phase and, where present, reason, message and hint

#### Scenario: Tags
- **WHEN** a user runs `shelf app tags hello --json`
Expand Down Expand Up @@ -193,3 +193,33 @@ with `component`, `digest`, `scanned`, `critical`, `high`, `scanner` and `scanne
#### Scenario: Agent reads why it cannot be exposed
- **WHEN** the running artifact has no scan summary
- **THEN** `verification.verified` is false and `reason` names the missing scan

### Requirement: Tests and isolation in the agent interface
The `AppStatus` of an app or preview SHALL hold `tests`, one entry per test of the running
revision with `name`, `phase` and, when it failed, `exitCode` and `log` (its last lines), and
`isolation` with `podSecurity`, `restrictedViolations` (each with `pod` and `reason`) and
`lan` (the exceptions).

#### Scenario: Failed test as JSON
- **WHEN** an agent runs `shelf app status hello --preview feature-login --json` and the test `smoke` failed
- **THEN** `tests` holds `smoke` with phase `Failed`, its exit code and its log, and the stage "the tests" is Failed

### Requirement: Verification report
The system SHALL provide `shelf app report <app> [--preview <branch>]`, read-only, which prints a
Markdown report and with `--json` a `Report` document: the app or preview, its address and how to
open it, the commit, the state with the first stage that is not Ready, the tests, the
verification with the scan per component, and, for a preview, the comparison with the app: each
component whose image digest differs, and the CRITICAL and HIGH counts of the preview against
the app's.

#### Scenario: Report for a pull request
- **WHEN** an agent runs `shelf app report hello --preview feature-login` for a Ready, verified preview whose `web` image differs from the app's
- **THEN** the Markdown names the commit, says Ready, lists the passed tests, the signature and scan, and lists `web` as changed with the findings of both

#### Scenario: Report of an app
- **WHEN** the report is printed without `--preview`
- **THEN** it has no comparison section

#### Scenario: Report as JSON
- **WHEN** `--json` is given
- **THEN** a `Report` document is printed with the same content, and no Markdown
Loading
Loading