Rongsong Shen
668e3f6893
- .wolf/anatomy-index.json, anatomy.md, memory.md: OpenWolf hook-maintained project index and session log, refreshed by this session's activity. - .kiro/specs/controller-peers-env-fallback/: spec scaffold (brief, requirements, design, research) from prior spec-init work. - issues/new_requirements.md: scheduler simulator enhancement backlog (info-command improvements, pend-reason detail, decision tracing). Excluded as non-persistent: issues/Issues.md (empty placeholder), src/lib/testsuite/test_xcectx_reconnect_race.c (self-documented as an ASAN stress reproduction only, not a committed regression test, and not wired into meson.build), scheduler-replay-20260922-095207.replay (4MB binary debug capture, no .replay files are tracked in this repo). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
140 lines
7.8 KiB
Markdown
140 lines
7.8 KiB
Markdown
# Requirements Document
|
|
|
|
## Introduction
|
|
|
|
Operators and deploy/test scripts must retype the full `--peers` candidate
|
|
list on every invocation of controller, scheduler, worker, and
|
|
harness/xce_test, and the `--controller` target on every invocation of
|
|
xceadmin — there is no way to set a default once per session or
|
|
environment for the four `--peers`-based components today. `--peers` is
|
|
optional for all four, and omitting it intentionally selects each
|
|
component's existing standalone/single-controller behavior (confirmed:
|
|
each component's own startup log already names this an intentional path,
|
|
not an error) — that behavior must keep working unchanged. xceadmin
|
|
already solved the equivalent problem for its own `--controller` option via
|
|
the `XCEADMIN_CONTROLLER` environment variable (bug-1566), and, separately,
|
|
xceadmin's `--controller` option can already accept a comma-separated list
|
|
of candidates and will try each in order until one is reachable (bug-1821),
|
|
rather than only a single target.
|
|
|
|
This feature introduces one new environment variable,
|
|
`XCE_CONTROLLER_PEERS`, read as a fallback default by all five components
|
|
(controller, scheduler, worker, harness/xce_test, and xceadmin) whenever
|
|
their respective connection-target option (`--peers` or `--controller`) is
|
|
not explicitly given on the command line — and only then; an explicit
|
|
option value is always used exactly as it is today, with the environment
|
|
variable never consulted. xceadmin's existing `XCEADMIN_CONTROLLER`
|
|
variable keeps working exactly as it does today, as a lower-priority
|
|
fallback beneath the new variable.
|
|
|
|
## Boundary Context
|
|
|
|
- **In scope**: A single new environment variable, `XCE_CONTROLLER_PEERS`,
|
|
providing the default connection target for controller, scheduler,
|
|
worker, harness/xce_test (via their existing `--peers` option) and
|
|
xceadmin (via its existing `--controller` option), consulted only when
|
|
the corresponding command-line option is omitted.
|
|
- **Out of scope**: The apiserver (its controller connection comes from a
|
|
configuration file, not a command-line option, and is unaffected) and
|
|
xcecli's `--url` option (a different target — the apiserver, not a
|
|
controller — and unaffected). Any change to `src/tools/deploy-ha.sh`'s
|
|
generated scripts, which continue to pass `--peers`/`--controller`
|
|
explicitly exactly as they do today. Any change to what each component
|
|
does today when its connection-target option is omitted and no
|
|
environment variable applies either (today's standalone/single-controller
|
|
behavior is preserved exactly).
|
|
- **Adjacent expectations**: xceadmin's existing multi-candidate,
|
|
try-until-reachable behavior for `--controller` (bug-1821) and its
|
|
existing `XCEADMIN_CONTROLLER` fallback (bug-1566) are both reused
|
|
unmodified — this feature only changes what value feeds into that
|
|
already-existing behavior, never how that behavior itself works.
|
|
|
|
## Requirements
|
|
|
|
### Requirement 1: Default peers candidate list for --peers-based components
|
|
|
|
**Objective:** As an operator running controller, scheduler, worker, or
|
|
harness/xce_test, I want a default `--peers` candidate list available via
|
|
an environment variable, so that I don't have to retype it on every
|
|
invocation while still being able to run any single invocation without it.
|
|
|
|
#### Acceptance Criteria
|
|
1. The peers-based component (controller, scheduler, worker, or
|
|
harness/xce_test) shall recognize `XCE_CONTROLLER_PEERS` as the
|
|
environment variable providing its default `--peers` candidate list.
|
|
2. When the peers-based component starts with an explicit `--peers`
|
|
argument, the peers-based component shall use that argument's value and
|
|
shall not consult `XCE_CONTROLLER_PEERS`.
|
|
3. When the peers-based component starts without an explicit `--peers`
|
|
argument and `XCE_CONTROLLER_PEERS` is set to a non-empty value, the
|
|
peers-based component shall use that value as its `--peers` candidate
|
|
list, exactly as if it had been supplied via `--peers`.
|
|
4. When the peers-based component starts without an explicit `--peers`
|
|
argument and `XCE_CONTROLLER_PEERS` is unset or empty, the peers-based
|
|
component shall behave exactly as it does today when started with no
|
|
`--peers` argument (today's standalone/single-controller behavior,
|
|
unchanged).
|
|
5. If the candidate-list value in use — from either `--peers` or
|
|
`XCE_CONTROLLER_PEERS` — fails to parse as a valid candidate list, the
|
|
peers-based component shall report a parse-error message, and that
|
|
message shall identify whether the invalid value came from the
|
|
`--peers` argument or from the `XCE_CONTROLLER_PEERS` environment
|
|
variable.
|
|
6. The peers-based component's `--peers` help/usage text shall document
|
|
`XCE_CONTROLLER_PEERS` as an environment-variable fallback for that
|
|
option.
|
|
|
|
### Requirement 2: Default controller candidate list for xceadmin
|
|
|
|
**Objective:** As an xceadmin operator, I want `--controller` to fall back
|
|
to the same environment variable the other XCE components use, so that one
|
|
variable configures every tool's default connection target.
|
|
|
|
#### Acceptance Criteria
|
|
1. When an xceadmin subcommand that accepts `--controller` runs without an
|
|
explicit `--controller` option and `XCE_CONTROLLER_PEERS` is set to a
|
|
non-empty value, xceadmin shall derive its controller candidate list
|
|
from `XCE_CONTROLLER_PEERS`.
|
|
2. Where a candidate entry in `XCE_CONTROLLER_PEERS` carries a `name=`
|
|
prefix, xceadmin shall remove the prefix before treating that entry as a
|
|
controller candidate.
|
|
3. When xceadmin derives its controller candidate list from
|
|
`XCE_CONTROLLER_PEERS`, xceadmin shall attempt each resulting candidate
|
|
in the same order the variable lists them, moving to the next candidate
|
|
only when the current one is unreachable — the same behavior xceadmin
|
|
already provides for an explicit multi-candidate `--controller` value.
|
|
4. When an xceadmin subcommand that accepts `--controller` runs with an
|
|
explicit `--controller` option, xceadmin shall use that option's value
|
|
and shall not consult `XCE_CONTROLLER_PEERS` or `XCEADMIN_CONTROLLER`.
|
|
5. When an xceadmin subcommand that accepts `--controller` runs without an
|
|
explicit `--controller` option, and `XCE_CONTROLLER_PEERS` is unset or
|
|
empty, and `XCEADMIN_CONTROLLER` is set to a non-empty value, xceadmin
|
|
shall use `XCEADMIN_CONTROLLER` exactly as it does today.
|
|
6. When an xceadmin subcommand that accepts `--controller` runs without an
|
|
explicit `--controller` option, and both `XCE_CONTROLLER_PEERS` and
|
|
`XCEADMIN_CONTROLLER` are unset or empty, xceadmin shall fall back to
|
|
its existing hardcoded default controller target, unchanged.
|
|
7. The `--controller` option's help text shall document
|
|
`XCE_CONTROLLER_PEERS` as its preferred environment-variable fallback,
|
|
alongside the existing `XCEADMIN_CONTROLLER` mention.
|
|
|
|
### Requirement 3: Documentation of the new environment variable
|
|
|
|
**Objective:** As an operator or future contributor, I want the project's
|
|
build/deployment documentation to describe `XCE_CONTROLLER_PEERS`, so that
|
|
I can discover and use it without reading source code.
|
|
|
|
#### Acceptance Criteria
|
|
1. The project's build/deployment steering documentation shall describe
|
|
`XCE_CONTROLLER_PEERS`: which components read it, its value format, and
|
|
its precedence relative to each component's connection-target option
|
|
(`--peers` or `--controller`).
|
|
2. The HA cluster deployment guidance shall note that
|
|
`XCE_CONTROLLER_PEERS` is available as an alternative to passing
|
|
`--peers`/`--controller` explicitly on every generated script
|
|
invocation, without stating or implying any change to what those
|
|
generated scripts themselves pass.
|
|
3. The multi-host verification guidance shall note the same availability
|
|
wherever it currently documents driving deployment via `--peers`,
|
|
without stating or implying any change to that verification's own
|
|
generated invocations.
|