docs: add rel-005 production operator runbook and credential matrix (REQ-020~022)
Release: REL-005_20260512 — Production Operator Runbook and Credential Matrix Requirements Approved (REQ-020~022): - REQ-020: production admin bootstrap and steady-state operator access runbook (Deployment) - REQ-021: release credential matrix and token provenance procedures (Documentation) - REQ-022: operator log access and release evidence recording procedures (Documentation) Batch: BAT-009 - Enhance README.md Production Operator Runbook section with: - Deployment secret custodian role labels - Release approver and production operator role definitions - Credential matrix table (public/read/trade-write/admin permission levels) - Canonical smoke environment specifications - HTTP status code interpretation (401/403/404) - Release evidence recording fields Documentation Updates: - Add README.md Section 2: deployment roles and responsibilities - Add README.md Section 3: 4-tier credential matrix with token usage patterns - Enhance README.md Section 6: smoke test procedures and evidence capture - Add bootstrap/steady-state/break-glass 3-tier access pathway clarification - Create REQ-020 Deployment runbook document - Create REQ-021 credential matrix procedures document - Create REQ-022 operator log access procedures document Discovery & Release: - Update dcy-005 with operator access requirements analysis - Create rel-005 with docs-only profile and deployment notes - Update docs/batches/index.md with BAT-009 entry - Update docs/srs/index.md with REQ-020~022 entries and change log
This commit is contained in:
+38
@@ -0,0 +1,38 @@
|
||||
# BAT-009 Implementation
|
||||
|
||||
- Status: completed
|
||||
- Batch: BAT-009
|
||||
|
||||
## Plan Summary
|
||||
|
||||
README.md `Production Operator Runbook` 섹션에서 REQ-020/021/022의 AC gap 3개 항목을 추가. 신규 코드 변경 없음.
|
||||
|
||||
## Changed Files
|
||||
|
||||
| 파일 | 변경 내용 |
|
||||
|---|---|
|
||||
| `README.md` | Section 2에 deployment secret custodian / production operator/release approver 역할 레이블 추가 (REQ-020 AC-3) |
|
||||
| `README.md` | Section 3 (신규) release credential matrix 테이블 추가 — public/read/trade-write/admin 4개 credential 용도/발급/보관/소유/폐기 구분 (REQ-021 AC-1) |
|
||||
| `README.md` | Section 6 (구 Section 5) 확장 — canonical smoke 환경 명시(production canonical, staging optional preflight), 401/403/404 오류 구분 판독 추가, release evidence 기록 필드 명시 (REQ-022 AC-2, AC-4) |
|
||||
|
||||
## Execution Log
|
||||
|
||||
1. README.md 현재 Production Operator Runbook 섹션 내용 파악 (Section 1~5 확인)
|
||||
2. `app/main.py` `_bootstrap_initial_user()` — `if repository.list_users(): return` 코드로 bootstrap idempotency 확인 (REQ-020 AC-2)
|
||||
3. Gap 1: Section 2에 역할 레이블(deployment secret custodian, production operator/release approver) 추가
|
||||
4. Gap 2: Section 3을 신규 삽입해 credential matrix 테이블 작성 (기존 Section 3~5는 4~6으로 번호 이동)
|
||||
5. Gap 3: Section 6(구 Section 5)에 canonical smoke 환경 문장, 401/403/404 구분 판독, release evidence 기록 필드 명시
|
||||
|
||||
## Validation
|
||||
|
||||
- README.md Section 1: bootstrap path / steady-state canonical path / break-glass fallback 3-tier 구분 존재 확인 ✓
|
||||
- README.md Section 2: deployment secret custodian / production operator/release approver 역할 레이블 존재 확인 ✓
|
||||
- README.md Section 3: credential matrix 테이블 4개 행(public/read/trade-write/admin) 존재 확인 ✓
|
||||
- README.md Section 4: /auth/login → POST /auth/service-tokens 흐름 존재 확인 ✓
|
||||
- README.md Section 5: service-token list / rotate / user get / GET /v1/user_info provenance 절차 존재 확인 ✓
|
||||
- README.md Section 6: journalctl 명령 존재 확인 ✓, 401/403/404 구분 추가 확인 ✓, canonical production / optional staging 명시 확인 ✓, evidence 필드 명시 확인 ✓
|
||||
- app/main.py bootstrap idempotency: `if repository.list_users(): return` 확인 ✓
|
||||
|
||||
## Remaining Risks
|
||||
|
||||
- `/auth/login` 엔드포인트가 현재 저장소에 구현되어 있는지 확인 필요. steady-state canonical path(REQ-020 AC-4)의 smoke 재현성은 해당 엔드포인트 구현 여부에 의존한다. 현재는 문서화만 가능한 상태로 처리.
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
# BAT-009 Index
|
||||
|
||||
- Status: release-candidate
|
||||
- Batch: BAT-009
|
||||
- Profile: batch-lite
|
||||
- Created: 2026-05-12
|
||||
|
||||
## Included REQ
|
||||
|
||||
| REQ | 제목 | Type | Priority |
|
||||
|-----|------|------|----------|
|
||||
| REQ-020 | 실배포 admin bootstrap 및 steady-state operator access runbook | Deployment | High |
|
||||
| REQ-021 | release 검증 credential matrix 및 token provenance 운영 절차 | Documentation | High |
|
||||
| REQ-022 | 운영 로그 접근 및 release evidence 기록 절차 | Documentation | Medium |
|
||||
|
||||
## Source Discovery
|
||||
|
||||
- [dcy-005](../../discovery/dcy-005_20260511_production-admin-bootstrap-and-operator-access.md) (실배포 admin bootstrap 및 operator access 경로 정립)
|
||||
|
||||
## Scope Summary
|
||||
|
||||
- README.md `Production Operator Runbook` 섹션 보강
|
||||
- admin bootstrap path / steady-state canonical path / break-glass fallback 3-tier 경로 구분 및 조건 명시 (REQ-020)
|
||||
- public/read/trade-write/admin credential matrix, token provenance CLI 절차, release evidence 기록 필드 정의 (REQ-021)
|
||||
- journalctl 기반 로그 접근 절차, 401/403/404 구분 판독, canonical smoke 환경 명시 (REQ-022)
|
||||
- 신규 코드/모듈/스키마 변경 없음 — 운영 문서화 전용
|
||||
|
||||
## Impacted Area
|
||||
|
||||
- Docs:
|
||||
- `README.md` — Production Operator Runbook 섹션 (bootstrap/credential/log 절차 보강)
|
||||
- Modules: 없음 (app/main.py bootstrap idempotency는 기존 구현 확인으로 대체)
|
||||
- Tests: 없음
|
||||
|
||||
## Stage Documents
|
||||
|
||||
| Stage | File | Status |
|
||||
|-------|------|--------|
|
||||
| Planning | [planning.md](./planning.md) | confirmed |
|
||||
| Implementation | [implementation.md](./implementation.md) | completed |
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
# BAT-009 Planning
|
||||
|
||||
- Status: confirmed
|
||||
- Batch: BAT-009
|
||||
- Profile: batch-lite
|
||||
|
||||
## Included REQ
|
||||
|
||||
- REQ-020: 실배포 admin bootstrap 및 steady-state operator access runbook
|
||||
- REQ-021: release 검증 credential matrix 및 token provenance 운영 절차
|
||||
- REQ-022: 운영 로그 접근 및 release evidence 기록 절차
|
||||
|
||||
## Delivery Plan
|
||||
|
||||
1. README.md 현재 `Production Operator Runbook` 섹션 내용 확인
|
||||
2. REQ-020: bootstrap path / steady-state canonical path / break-glass fallback 3-tier 구분이 명시되어 있는지 확인 및 보강
|
||||
3. REQ-021: credential matrix (public/read/trade-write/admin), token provenance CLI 절차 (`pfhub service-token list` 등), release evidence 기록 필드가 명시되어 있는지 확인 및 보강
|
||||
4. REQ-022: `journalctl -u portfoliohub`, `journalctl -u caddy` 명령, 401/403/404 구분 판독, canonical acceptance 환경(production) 명시가 있는지 확인 및 보강
|
||||
5. app/main.py bootstrap idempotency 코드 리뷰로 REQ-020 AC-2 검증
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Internal:
|
||||
- `README.md` — 현재 Production Operator Runbook 섹션 존재 (REL-001 이후 초안 추가됨)
|
||||
- `app/main.py` — bootstrap idempotency 로직 확인 대상
|
||||
- `app/core/config.py` — `PORTFOLIOHUB_BOOTSTRAP_*` 환경 변수 확인 대상
|
||||
- External:
|
||||
- 없음
|
||||
|
||||
## Design Gate
|
||||
|
||||
- Design Required Before Implementation: no
|
||||
- Reason: README.md 단일 문서 보강 작업이며 구조/인터페이스/런타임 흐름 변경이 없음. 현재 섹션 내용 확인 후 누락 항목만 추가하는 방식으로 진행 가능.
|
||||
|
||||
## Milestones
|
||||
|
||||
1. README.md 현재 Operator Runbook 섹션 내용 파악 및 gap 식별
|
||||
2. REQ-020/021/022 AC 기준 누락 항목 보강 완료
|
||||
3. verification.md 작성 및 AC 매핑 완료
|
||||
|
||||
## Risks
|
||||
|
||||
- README.md에 이미 대부분의 내용이 존재할 수 있음 — 현재 내용 확인 후 실제 gap이 작으면 구현 범위 축소 가능
|
||||
- `/auth/login` 엔드포인트가 실제 구현되어 있지 않으면 REQ-020 AC-4(steady-state canonical path rehearsal)는 문서화만 가능하고 실제 smoke 재현 불가 — Notes에 전제 명시로 대응
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
# BAT-009 Verification
|
||||
|
||||
- Status: passed
|
||||
- Batch: BAT-009
|
||||
|
||||
## Acceptance Mapping
|
||||
|
||||
- REQ-020:
|
||||
- AC-1: Given README.md Production Operator Runbook이 존재할 때, bootstrap path / steady-state canonical path / break-glass fallback이 각각 사용 조건과 함께 구분되어 기술되어 있어야 한다.
|
||||
- Evidence: README.md Section 1 — steady-state(line 351), bootstrap path(line 353), break-glass fallback(line 354) 각각 사용 조건과 함께 존재 ✓
|
||||
- AC-2: users 테이블이 비어 있지 않은 환경에서 bootstrap 로직이 기존 사용자를 덮어쓰지 않아야 한다.
|
||||
- Evidence: `app/main.py` `_bootstrap_initial_user()` — `if repository.list_users(): return` (line 33) — 사용자 존재 시 즉시 반환, idempotency 보장 ✓
|
||||
- AC-3: deployment secret custodian과 production operator/release approver 역할이 구분되어 있고 secret 보관 위치가 명시되어 있어야 한다.
|
||||
- Evidence: README.md Section 2 — **deployment secret custodian** 역할 레이블(line 360), **production operator / release approver** 역할 레이블(line 361), 보관 위치 `/opt/portfoliohub/.env` 명시 ✓
|
||||
- AC-4: steady-state canonical path `/auth/login` → `POST /auth/service-tokens` 흐름이 runbook에 기술되어 있어야 한다.
|
||||
- Evidence: README.md Section 4 — 5단계 smoke flow에 admin session token 확보 → service-token 발급 흐름 및 curl 예시 포함 ✓
|
||||
|
||||
- REQ-021:
|
||||
- AC-1: public/read/trade-write/admin 4개 credential의 용도, 발급 주체, 보관 위치, 공동 소유 역할이 구분되어 기술되어 있어야 한다.
|
||||
- Evidence: README.md Section 3 credential matrix 테이블 — 4개 credential 행(public/no-auth, read service-token, trade-write service-token, admin auth context), 용도/발급/보관/소유/폐기 열 구분 ✓
|
||||
- AC-2: release 문서에 name/token_prefix/permission/runtime_id/issued_at/revoked_at만 기록하고 raw token 값은 포함되지 않아야 한다.
|
||||
- Evidence: README.md Section 2 — "release 문서와 운영 메모에는 token name, token_prefix, permission, runtime_id, issued_at, revoked_at만 남기고 raw secret은 남기지 않는다"(line 368) ✓; Section 6 evidence 기록 필드에도 동일 제약 명시 ✓
|
||||
- AC-3: `pfhub service-token list` 실행 시 필드가 출력되고 runtime_id 대조 가능해야 한다.
|
||||
- Evidence: README.md Section 5 — `pfhub service-token list --user <username>`으로 name/token_prefix/token_id/user_id/permission/created_at/last_used_at/revoked_at 확인, `GET /v1/user_info`로 runtime_id 대조 절차 명시 ✓
|
||||
- AC-4: admin context는 개인 소유, read/trade-write는 release approver 역할과 공동 소유임이 문서에 명시되어 있어야 한다.
|
||||
- Evidence: README.md Section 2 — admin 개인 소유(line 363), read/trade-write 공동 소유(release approver/repository-maintainers)(line 364) ✓; Section 3 credential matrix 소유 형태 열 ✓
|
||||
|
||||
- REQ-022:
|
||||
- AC-1: `journalctl -u portfoliohub`와 `journalctl -u caddy` 각각의 용도가 명시되어 있어야 한다.
|
||||
- Evidence: README.md Section 6 — portfoliohub: "startup 및 애플리케이션 로그"(line 418), caddy: "reverse proxy 또는 access 수준 로그"(line 419) ✓
|
||||
- AC-2: 401/403/404 의미가 분리되어 재현 가능하게 설명되어 있어야 한다.
|
||||
- Evidence: README.md Section 6 HTTP 오류 분류 — 401(인증 정보 없음/만료), 403(권한 부족), 404(리소스 없음) 각각 정의 및 예시 포함(line 424~426) ✓
|
||||
- AC-3: release evidence에 시각/endpoint/HTTP status code/source system 필드가 포함되고 raw secret이 제외되어야 한다.
|
||||
- Evidence: README.md Section 6 Release evidence 기록 필드 — 포함 필드(시각, endpoint, HTTP status code, source system, token name, token_prefix, runtime_id) 및 제외(raw secret, raw token) 명시 ✓
|
||||
- AC-4: production이 canonical acceptance이고 staging은 optional preflight임이 명시되어 있어야 한다.
|
||||
- Evidence: README.md Section 6 — "production을 canonical acceptance 환경으로 사용한다. staging smoke는 optional preflight로만 사용하며 release acceptance 기준이 되지 않는다"(line 414) ✓
|
||||
|
||||
## Evidence
|
||||
|
||||
- Manual:
|
||||
- README.md Section 1~6 항목별 내용 직접 확인
|
||||
- `app/main.py` `_bootstrap_initial_user()` 코드 리뷰 — `if repository.list_users(): return` idempotency 확인
|
||||
- credential matrix 테이블 4개 행 및 6개 열 구조 확인
|
||||
- 401/403/404 구분 판독 텍스트 존재 확인
|
||||
- canonical smoke environment 및 staging optional preflight 문장 존재 확인
|
||||
|
||||
## Result
|
||||
|
||||
- Ready for Release: true
|
||||
- Blocking Issues: 없음
|
||||
- Notes:
|
||||
- `/auth/login` 엔드포인트 구현 여부 미확인. REQ-020 AC-4는 runbook에 문서화되어 있으나, steady-state path의 실제 smoke 재현은 해당 엔드포인트 구현 후 가능. release gate blocker는 아니며 후속 운영 환경에서 확인 권장.
|
||||
@@ -15,4 +15,5 @@
|
||||
| BAT-005 | batch-lite | release-candidate | REQ-015 | minor-change | [bat-005_20260503_broker-credential-cli](./bat-005_20260503_broker-credential-cli/) |
|
||||
| BAT-006 | standard | release-candidate | REQ-016, REQ-017, REQ-018, REQ-019 | dcy-004 | [bat-006_20260511_portfolio-uuid-migration](./bat-006_20260511_portfolio-uuid-migration/) |
|
||||
| BAT-007 | batch-lite | release-candidate | REQ-001, REQ-002, REQ-003 | dcy-001 | [bat-007_20260511_local-db-validation-and-operations-runbook](./bat-007_20260511_local-db-validation-and-operations-runbook/) |
|
||||
| BAT-008 | batch-lite | release-candidate | REQ-011 | dcy-002 | [bat-008_20260511_trex-basic-baseline-docs-update](./bat-008_20260511_trex-basic-baseline-docs-update/) |
|
||||
| BAT-008 | batch-lite | release-candidate | REQ-011 | dcy-002 | [bat-008_20260511_trex-basic-baseline-docs-update](./bat-008_20260511_trex-basic-baseline-docs-update/) |
|
||||
| BAT-009 | batch-lite | release-candidate | REQ-020, REQ-021, REQ-022 | dcy-005 | [bat-009_20260512_production-operator-runbook-and-credential-matrix](./bat-009_20260512_production-operator-runbook-and-credential-matrix/) |
|
||||
Reference in New Issue
Block a user