docs(spec): xcecli-presets: server preset directory, pull name collisions, /xce/v1 routes

- server presets live in <TopDir>/config/presets/ (or presets.dir in
  app.yaml), one file per preset, re-read on change; not in ClusterConfig
- pull refuses a name collision unless it updates the same server preset;
  --as / --force (keeps .bak); submit uses local presets only
- fix route prefix: /xce/v1/presets, not /api/v1

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Rongsong Shen 2026-10-12 10:33:31 +00:00
parent d1e03055e4
commit 83c6eb8024
Signed by untrusted user: rshen
GPG key ID: 80533536B0EB651C
3 changed files with 39 additions and 7 deletions

View file

@ -380,7 +380,7 @@ Not part of this spec, recorded here because they replace profile defaults:
values.
- Personal presets live one file per preset under `~/.config/xce/presets/`.
- The apiserver **only shares**: admin-deployed preset files served
read-only (`GET /api/v1/presets`, `GET /api/v1/presets/{name}`). Pulling
read-only (`GET /xce/v1/presets`, `GET /xce/v1/presets/{name}`) from `<TopDir>/config/presets/`. Pulling
copies a preset into the local file, so a server preset being removed
never affects users. `preset diff` / `pull --force` are user-initiated.
- User-to-user sharing by `preset export` / `import` (file, mail, git).

View file

@ -49,16 +49,48 @@ configuration level.
- **Personal presets** are files under `~/.config/xce/presets/`; users
change them on the fly (`xcecli preset set / edit / show / list / delete`).
- **The server only shares.** The apiserver serves admin-deployed preset
files read-only: `GET /api/v1/presets` (list) and
`GET /api/v1/presets/{name}` (fetch). Team presets are namespaced
(`<team>/<name>`, a subdirectory). No database, no HA; with several apiservers the files
are deployed to each, like `rbac.yaml`. Every authenticated user may see
them.
files read-only: `GET /xce/v1/presets` (list, with each preset's content
hash) and `GET /xce/v1/presets/{name}` / `{ns}/{name}` (fetch). Every
authenticated user may see them.
- **Where server presets live** (user, 2026-10-12): a directory beside the
apiserver's other config, `<TopDir>/config/presets/` (as
`config/rbac.yaml` and `config/auth.yaml`, `apiserver/cmd/main.go:144`,
`:152`), overridable by `presets.dir` in `app.yaml` (e.g.
`/etc/xce/presets`).
- One file per preset; site presets at the top level, team presets one
subdirectory deep (`cfd-team/openfoam-large.yaml`).
- Re-read when a file's mtime changes, no restart; a file that fails to
parse is skipped, logged and not listed, without affecting the others.
- No database, no HA. With several apiservers the directory is deployed
to each, like `rbac.yaml`; the content hashes in the listing let a
client notice a mismatch.
- Delegation needs no feature: `presets.dir` can be a git checkout pulled
by a timer, so teams change presets by pull request with history.
- Not in `ClusterConfig`: controller and scheduler never use presets
(independence rule, `config-design.md`) and presets change far more
often than cluster config (frequency rule); it would also turn every
preset edit into a cluster config upgrade.
- **Pull copies.** `xcecli preset pull <name>` writes a complete, standalone
local preset with an informational `origin` (server name, content hash,
pull date). Removing or changing a server preset never affects local
copies. `xcecli preset diff <name>` compares with the server (reports when
it is gone); `preset pull --force` refreshes. Both are user-initiated.
- **Name collisions on pull** (user, 2026-10-12). Namespaced presets go to
their subdirectory, so only the same path can collide:
- the local file is a pulled copy of the same server preset (its `origin`
matches): an update; pull shows the diff and stops, `--force` replaces
it;
- anything else (a personal preset, or a copy from another server or
path): pull refuses and suggests `--as <name>` (pull under another local
name; `origin` keeps the server name, so `diff` still works) or
`--force`;
- `--force` keeps the replaced file as `<name>.yaml.bak`;
- `preset pull --all [ns]` applies the same rules per preset, listing and
skipping collisions.
- **Submit uses local presets only.** `--preset X` not found locally but
present on the server stops with "not found locally; the server has `X`:
run `xcecli preset pull X`". Never an automatic pull, so server changes
or removals never affect a submit.
- **User-to-user sharing** without the server: `preset export` / `import`
(file, mail, git).
- **Site presets complement profiles.** Admins typically publish a preset

View file

@ -123,7 +123,7 @@ Direction: `.kiro/steering/resource-model.md`. Decisions, proposals (PR-1 generi
- [ ] job-resize — NEW 2026-10-10 (from long-running services discovery; not on the services path). Grow/shrink a running parallel job's allocation (LSF resizable jobs, `bresize`) for elastic applications. Brief: `.kiro/specs/job-resize/brief.md`. Dependencies: parjob-placement, host-failure-job-recovery.
- [ ] project-delegated-membership — NEW 2026-10-10 (from project-config requirements, user decision: future). Project managers edit their project's (and subtree's) members at runtime without an admin config push; needs a durable store that coexists with `xceadmin` config pushes (e.g. a separate delegated member list) and audit. Dependencies: project-config, rbac-persistence.
- [ ] job-modify — NEW 2026-10-12 (from application-profile discussion, user decision; backlog, no brief yet). Modify a pending job (LSF `bmod`): apiserver action (today `"modify"` is commented out, `controllers/jobs.go:2446`; `JOB_MODIFY` only an enum), controller opcode, WAL fact with snapshot field-completeness, scheduler re-merge, xcecli. First attributes: `--app` (owner with `app:use` on the new profile; admins in bulk, e.g. `--app-from <old>`), `-R`, `-n`, queue; later begin/end time (`job-time-window`), dependencies. Dependencies: application-profile, job-config-merge.
- [ ] xcecli-presets — NEW 2026-10-12 (from application-profile discussion, user decisions). Client-side presets replace convenience defaults in profiles: a preset is a set of job options (`--app`, `--queue`, `-R`, `-n`, env, limits) expanded by the client, a flag replacing the preset's value for that option; one file per preset (`~/.config/xce/presets/<ns>/<name>.yaml`, same layout in the apiserver's presets dir), env capture by name (`pass:`; `XCE_*` and secret-looking names excluded); the apiserver only shares admin-deployed presets read-only (`GET /api/v1/presets[/{name}]`), and `preset pull` copies one locally so server-side removal never affects users (`preset diff`, `pull --force` user-initiated); user-to-user sharing by `preset export`/`import`; presets carry no privilege and are not a configuration level; optional preset-name job label; the portal does the same expansion. Brief: `.kiro/specs/xcecli-presets/brief.md`. Dependencies: application-profile.
- [ ] xcecli-presets — NEW 2026-10-12 (from application-profile discussion, user decisions). Client-side presets replace convenience defaults in profiles: a preset is a set of job options (`--app`, `--queue`, `-R`, `-n`, env, limits) expanded by the client, a flag replacing the preset's value for that option; one file per preset (`~/.config/xce/presets/<ns>/<name>.yaml`, same layout in the apiserver's presets dir), env capture by name (`pass:`; `XCE_*` and secret-looking names excluded); the apiserver only shares admin-deployed presets read-only (`GET /xce/v1/presets[/{ns}/{name}]`, files in `<TopDir>/config/presets/` or `presets.dir`, re-read on change; not in ClusterConfig), and `preset pull` copies one locally so server-side removal never affects users; on a name collision pull refuses unless it is an update of the same server preset (`--as` / `--force` with `.bak`); submit uses local presets only (`preset diff`, `pull --force` user-initiated); user-to-user sharing by `preset export`/`import`; presets carry no privilege and are not a configuration level; optional preset-name job label; the portal does the same expansion. Brief: `.kiro/specs/xcecli-presets/brief.md`. Dependencies: application-profile.
- [ ] profile-usage-insight — NEW 2026-10-12 (from application-profile discussion, backlog; no brief yet). Per-profile report over recent jobs comparing the profile's defaults with actual use (requested vs. peak memory, CPU efficiency, OOM kills, pend time, runtime by variant) and suggesting better values for site presets (or a profile essential), e.g. "preset openfoam rusage mem 4000, p95 peak 1600 → suggest 2000" (Kubernetes VPA recommender precedent). **Advisory only** (user decision): the admin applies changes to site presets or `applications.yaml`; nothing tunes itself. Optional user hint ("used 1.4G of 4G requested"). Dependencies: application-profile, run usage in job records.
- [ ] lsf-config-migration — NEW 2026-10-09 (user idea, backlog; no brief yet). A tool (likely an `xceadmin` subcommand) that converts LSF configuration (`lsb.queues`, `lsb.applications`, `lsb.resources` Limit sections, `lsb.users`/`lsb.hosts` groups, `lsb.params` defaults, project settings) into XCE `configs/*.yaml`, with a report of what does not map: queue `RES_REQ` (XCE queues are policy only; move into a profile or drop), LSF's full per-section merge rules vs XCE's simplified ones, compound/alternative resreqs, unsupported parameters. Dependencies: job-config-merge, application-profile, project-config, parjob-placement (span), admin-config-tool. Promote via `/kiro-discovery` when those land.