docs(release): draft M5 core broker truth rollout
This commit is contained in:
Hermes Agent
@@ -0,0 +1,144 @@
|
||||
# REL-011 M5 trex-core operator broker truth hotfix — deployment runbook
|
||||
|
||||
- Release: `REL-011`
|
||||
- Target source: `6d90f8951dbf354eb41301492d0bcaf0af24d882`
|
||||
- Runtime implementation: BAT-057 / PR #42 merge `94e148940adb008db0bbd215052a1e984f7c566b`
|
||||
- Execution owner: 운영팀
|
||||
- Approval required: team lead review + user release approval
|
||||
- Safety classification: production daemon restart; no DB migration; broker-read smoke only
|
||||
|
||||
> Do not paste credentials, tokens, account numbers, DSNs, `.env` contents, raw KIS responses, or full command lines containing secrets into the evidence log. Use `[REDACTED]`.
|
||||
|
||||
## 1. Scope and hard stops
|
||||
|
||||
Allowed after release approval:
|
||||
|
||||
- Pinned source checkout, existing trex-core daemon stop/start, startup log inspection.
|
||||
- Existing approved instance configuration used without semantic changes.
|
||||
- `sync --all --dry-run` and `verify` as broker-read/CLI smoke checks.
|
||||
|
||||
Not allowed in this runbook:
|
||||
|
||||
- `sync --live`, `--yes` with a live write, `enter`, `exit`, `cancel`, or any automated remediation.
|
||||
- Changing `credential_fetch_enabled`, `TREX_KIS_BROKER_BREAK_GLASS`, broker mode, instance key, portfolio-hub endpoint, or secrets.
|
||||
- Database schema migration, manual DB update/delete, AMQP topology change, or strategy daemon deployment.
|
||||
|
||||
If any prohibited action appears necessary, stop and return to the release approver.
|
||||
|
||||
## 2. Preflight — record before modifying the host
|
||||
|
||||
1. Confirm the approved release, target SHA, and approved 장외 window.
|
||||
2. From the operating checkout, capture only redacted metadata:
|
||||
|
||||
```bash
|
||||
pwd
|
||||
git status --short
|
||||
git rev-parse HEAD
|
||||
git rev-parse --abbrev-ref HEAD
|
||||
```
|
||||
|
||||
- Record the exact pre-deploy revision as `ROLLBACK_REVISION`.
|
||||
- If the checkout is dirty or target source cannot be verified, **stop**.
|
||||
|
||||
3. Identify the active instance configuration and process supervisor without printing secrets. Confirm the existing config’s `credential_fetch_enabled` and break-glass state will remain unchanged.
|
||||
4. Confirm the expected process command remains the established runtime form:
|
||||
|
||||
```bash
|
||||
.venv/bin/trex-core-daemon --config <approved-instance-config>
|
||||
```
|
||||
|
||||
5. Confirm target/source characteristics from a clean checkout:
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
git show -s --format='%H %s' 6d90f8951dbf354eb41301492d0bcaf0af24d882
|
||||
git diff --name-only "$ROLLBACK_REVISION" 6d90f8951dbf354eb41301492d0bcaf0af24d882 -- pyproject.toml trex_core/adapters/persistence/migrations
|
||||
```
|
||||
|
||||
Expected for the reviewed M4 baseline: no dependency or migration path. If actual output differs, **stop** and request lead review; do not infer safety from this draft.
|
||||
|
||||
6. Ensure the deployment host’s virtual environment has the existing runtime dependencies. Do not run dependency upgrades as an implicit part of this release.
|
||||
|
||||
## 3. Deploy source and restart daemon
|
||||
|
||||
Use the host’s approved supervisor procedure. The following expresses the source boundary, not a replacement for host-specific service management:
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
git checkout --detach 6d90f8951dbf354eb41301492d0bcaf0af24d882
|
||||
# Stop the existing trex-core daemon through the approved host supervisor.
|
||||
# Start exactly one daemon with the unchanged approved instance config.
|
||||
.venv/bin/trex-core-daemon --config <approved-instance-config>
|
||||
```
|
||||
|
||||
Record, with sensitive values redacted:
|
||||
|
||||
- checkout SHA;
|
||||
- prior process stop confirmation;
|
||||
- new process identifier or supervisor status;
|
||||
- selected instance key (not account details);
|
||||
- startup log interval and log location.
|
||||
|
||||
## 4. Startup acceptance
|
||||
|
||||
Before any CLI smoke, confirm:
|
||||
|
||||
- the daemon completed startup and RabbitMQ topology declaration;
|
||||
- worker threads are running according to the instance profile;
|
||||
- no `ERROR`, `CRITICAL`, or traceback appears in the post-restart interval;
|
||||
- the daemon is using the unchanged configuration mode. Source evidence may show only safe mode/label (`fetched`, `env`, or `break_glass`), never credential payload or account number.
|
||||
|
||||
Any KIS credential-resolution or balance-read failure must be treated as a failure; BAT-057 intentionally prevents treating it as a normal empty broker balance.
|
||||
|
||||
## 5. Read-only/dry-run smoke
|
||||
|
||||
Run against the same explicit approved configuration. These calls may read the configured broker and database but must not write a slot, warning, broker order, or ledger record.
|
||||
|
||||
```bash
|
||||
.venv/bin/trex-core sync --all --dry-run --config <approved-instance-config> --json
|
||||
.venv/bin/trex-core verify --config <approved-instance-config> --json
|
||||
```
|
||||
|
||||
Acceptance:
|
||||
|
||||
- Commands either succeed with sanitized source/balance evidence, or fail loudly with safe error code/message.
|
||||
- A failure must not be reinterpreted as an empty balance or “zero quantity” condition.
|
||||
- For `unmanaged_position` or `managed_non_holding_divergence`, record classification only and stop for triage; no remediation is performed.
|
||||
- Never add `--live` or `--yes` in this runbook.
|
||||
|
||||
## 6. Rollback
|
||||
|
||||
Trigger rollback for any daemon startup failure, unexpected source-mode change, unexpected credential fetch/fallback behavior, broker-read failure not safely surfaced, AMQP connectivity regression, or smoke behavior inconsistent with BAT-057’s fail-loud/no-auto-remediation contract.
|
||||
|
||||
```bash
|
||||
# Stop the new daemon via the approved host supervisor.
|
||||
git checkout --detach "$ROLLBACK_REVISION"
|
||||
# Restart with the same unchanged approved configuration via the supervisor.
|
||||
```
|
||||
|
||||
Then confirm the previous daemon revision is running and collect redacted logs. Do not run database rollback commands; REL-011 introduces no migration.
|
||||
|
||||
## 7. Evidence record template
|
||||
|
||||
```text
|
||||
Release: REL-011
|
||||
Approved by / timestamp: [REDACTED AS NEEDED]
|
||||
Window: [REDACTED]
|
||||
Host identity: [REDACTED]
|
||||
Instance key: [REDACTED]
|
||||
Pre-deploy revision (ROLLBACK_REVISION): <sha>
|
||||
Target revision: 6d90f8951dbf354eb41301492d0bcaf0af24d882
|
||||
Configuration mode unchanged: yes/no (credential_fetch_enabled / break-glass values not recorded)
|
||||
Daemon stop/start evidence: <supervisor status or PID, redacted>
|
||||
Startup log interval: <path/time range, redacted>
|
||||
Startup acceptance: pass/fail
|
||||
sync --dry-run result: pass/fail + sanitized exit code/output summary
|
||||
verify result: pass/fail + sanitized exit code/output summary
|
||||
Unexpected divergence classification: none / unmanaged_position / managed_non_holding_divergence
|
||||
Rollback performed: no / yes (reason and restored SHA)
|
||||
Operator: [REDACTED]
|
||||
```
|
||||
|
||||
## 8. Completion criteria
|
||||
|
||||
REL-011 may move from `Release-Pending` only after the exact target revision, restart evidence, startup acceptance, dry-run smoke result, verify result, and rollback disposition are reviewed by the team lead. Production live sync remains a separate approval gate even after REL-011 is released.
|
||||
Reference in New Issue
Block a user