Field Log · Entry

Production RAG Knowledge Base Release Runbook: Build·Canary·Rollback (10/10)

오늘의 결론

• Production RAG의 배포 단위는 vector DB나 애플리케이션 image 하나가 아닙니다. Source snapshot, parser·chunker, metadata·vocabulary, ACL policy, embedding·index, query encoder와 evaluation 결과를 묶은 immutable knowledge-base release입니다.
• Build와 activation을 분리합니다. Candidate generation을 격리해 완성하고 source coverage·구조 보존·ACL·deletion·freshness·retrieval·latency·cost gate를 통과한 뒤 logical route를 전환합니다.
• Canary는 “트래픽 5%”가 아니라 제한된 blast radius에서 실제 authorization context와 query cohort를 검증하는 단계입니다. Security invariant 위반은 표본 수와 무관하게 즉시 중단합니다.
• Rollback은 command가 아니라 보존된 이전 generation, 호환 query encoder, delta freshness, cache namespace, trigger와 권한을 포함한 능력입니다. Release 전에 rehearsal합니다.
• Runbook은 정상 절차와 장애 절차를 함께 담습니다. 누가 go/no-go를 결정하고, 어떤 metric에서 멈추며, 어떤 증거로 복구 완료를 선언하는지 사전에 고정합니다.

앞 글에서는 삭제가 모든 derived artifact와 restore 경로에 전파됐음을 증명했습니다. 이제 71~79번의 설계를 하나의 반복 가능한 release control loop로 묶습니다.

plan and freeze release contract
  → build isolated candidate from immutable inputs
  → validate data, security, retrieval and operations
  → shadow then bounded canary
  → atomically activate one compatible generation
  → observe, rollback if needed, verify and learn
  → retire old artifacts under retention policy

먼저 답하기: index build 성공과 release 성공은 무엇이 다른가?

Index build 성공은 대개 다음만 뜻합니다.

documents were accepted by the search engine

Release 성공은 훨씬 넓습니다.

the intended source state
was transformed by the intended pipeline revisions
with correct identity, metadata, ACL, time and deletion semantics,
passed retrieval and operational gates,
became the only active compatible generation,
and can be rolled back without violating freshness or security.

그래서 release controller는 단순 index job보다 상위의 orchestration입니다.

이 글의 대상과 학습 시간

• 대상: Enterprise RAG를 production에 올리거나 운영 절차를 표준화하는 초·중급 개발자와 platform owner
• 선수 지식: 이 시리즈 71~79번 또는 동등한 ingestion·retrieval 운영 개념
• 빠르게 읽기: 약 15분
• Runbook 설계까지 이해하기: 약 45분
• Staging rehearsal 포함: 반나절 이상

1. Knowledge-base release의 경계를 정의한다

일반 application release와 다른 점은 data artifact와 code가 함께 움직인다는 것입니다.

Release에 포함되는 것

• Canonical source snapshot·high-watermark
• Source connector revision
• Parser·OCR·table extractor
• Stable identity·dedup rule
• Metadata schema·controlled vocabulary·entity registry
• ACL projection·authorization policy
• Temporal semantics·tombstone registry cutoff
• Chunking contract
• Document·query embedding model
• Sparse analyzer·vector index configuration
• Physical index·logical route
• Query rewrite·reranker·context policy
• Gold dataset·quality assertion revision
• Cache namespace
• Application compatibility range

모두 항상 변경되는 것은 아니지만 manifest에는 어떤 revision을 사용했는지 기록합니다.

2. Release 종류를 구분한다

Incremental content release

동일 pipeline contract에서 source update·delete·ACL delta를 반영합니다.

Full rebuild

Parser, chunking, embedding, metadata schema나 index setting이 바뀌어 새 generation을 만듭니다.

Policy-only release

ACL·classification·retention policy가 바뀝니다. Content parse와 분리해 빠르게 적용할 수 있어야 합니다.

Emergency deny·deletion release

일반 cadence와 gate를 기다리지 않고 serving을 즉시 제한합니다. 물리 artifact 정리는 뒤따르지만 security invariant는 즉시 확인합니다.

Rollback release

이전 known-good generation으로 route를 되돌리되, 최신 revoke·delete·content delta를 어떻게 유지할지 명시합니다.

한 workflow에 모두 억지로 넣지 않고 공통 state machine과 유형별 gate를 둡니다.

3. Immutable release manifest를 만든다

release_id: kb-2026-07-16.10
release_type: full_rebuild
created_at: 2026-07-16T06:00:00Z

inputs:
  canonical_snapshot_id: kb-snap-8842
  source_high_watermarks:
    dms: seq-99142
    wiki: cursor-22018
  tombstone_registry_revision: tomb-441

pipeline:
  connector_revision: connector-2.7
  parser_revision: parser-3.2
  parser_image_digest: sha256:...
  metadata_schema_revision: meta-6
  vocabulary_revision: vocab-12
  entity_registry_snapshot: entity-291
  acl_policy_revision: acl-184
  chunking_revision: layout-semantic-v4
  embedding_revision: embed-ko-v7

index:
  physical_name: rag-docs-g10
  dimension: 1024
  distance: cosine
  sparse_analyzer_revision: ko-analyzer-5
  ann_config_revision: ann-9

query_runtime:
  query_encoder_revision: embed-ko-v7
  reranker_revision: rerank-4
  context_policy_revision: context-12
  compatible_app_versions: ">=2026.07.3 <2026.08"

evaluation:
  gold_snapshot: rag-gold-42
  assertions_revision: qa-17
  report_id: eval-881

activation:
  logical_route: rag-search-active
  previous_release_id: kb-2026-07-09.7
  cache_namespace: kb-2026-07-16.10

숫자와 version은 가상 예시입니다. Manifest는 commit 또는 immutable object로 저장하고 signature·approval을 연결합니다.

4. Release state machine을 명시한다

PLANNED
  → BUILDING
  → BUILT
  → VALIDATING
  → SHADOW
  → CANARY
  → APPROVED
  → ACTIVE
  → SOAKING
  → STABLE
  → RETIRED

alternative transitions:
  BLOCKED
  ABORTED
  ROLLED_BACK
  FAILED_VALIDATION

각 transition은 자동 조건과 human approval을 구분합니다.

{
  "release_id": "kb-2026-07-16.10",
  "from": "CANARY",
  "to": "APPROVED",
  "at": "2026-07-16T08:00:00Z",
  "automated_gates": ["gate-report-771"],
  "approvals": ["data-owner:ap-11", "security:ap-12", "oncall:ap-13"],
  "exceptions": []
}

5. 역할과 결정 권한을 분리한다

역할	책임	Stop 권한
Release owner	전체 일정·manifest·상태	예
Data owner	Source scope·authority·quality	예
Search/ML owner	Embedding·retrieval 평가	예
Security owner	Tenant·ACL·secret handling	즉시
Privacy owner	Retention·deletion·hold	즉시
SRE/on-call	Capacity·SLO·incident response	예
Product owner	User cohort·impact·communication	예
Incident commander	장애 중 단일 지휘	예

한 사람이 여러 역할을 맡을 수 있지만 approval evidence와 escalation path를 명시합니다. Security·privacy gate는 일정 압박으로 우회하지 않습니다.

6. 사전 계획에서 변경 범위와 위험을 적는다

Release proposal:

why: scanned PDF table retrieval regression 개선
what changes: parser 3.1→3.2, chunker 3→4, embedding 6→7
what does not change: source connectors, ACL policy 184
affected cohorts: scanned PDF, Korean, table queries
expected benefit: table gold Recall@20 개선
primary risks: OCR loss, vector dimension mismatch, index capacity
rollback: previous release + encoder 6, delta kept current
maintenance window: none; alias cutover
owners and approvers: ...

Expected benefit도 measurable hypothesis로 둡니다. “최신 model이라 좋을 것”은 release reason이 아닙니다.

7. Preflight에서 되돌릴 수 없는 조건을 확인한다

Build 전 체크:

• Canonical snapshot이 immutable하고 읽을 수 있음
• Source high-watermark와 delta log retention 충분
• Tombstone·ACL registry revision 고정
• New parser·encoder artifact digest 검증
• Candidate index dimension·metric·capacity 준비
• Backfill quota와 cost budget 승인
• Previous generation이 healthy하고 rollback 가능
• Gold dataset와 canary principal 준비
• Monitoring·alert·runbook link 배포
• On-call coverage와 change calendar 확인
• Third-party provider quota·region·retention 설정 확인

Delta log retention이 backfill 예상 시간보다 짧으면 cutover 전 변경을 잃을 수 있습니다. 시작하지 않는 것이 낫습니다.

8. Candidate를 production route 밖에서 빌드한다

canonical snapshot S8842
  → parser 3.2
  → metadata/ACL contract
  → chunker 4
  → embed model 7
  → physical index rag-docs-g10

logical route still points to previous G9

Candidate build 원칙:

• Active physical index를 mutate하지 않음
• Partition·checkpoint·resume 가능
• Every artifact carries release·run·source revision
• Quarantine는 숨기지 않고 manifest에 count·reason 기록
• ACL·delete update는 high-priority delta lane
• Resource guard가 production query SLO를 보호

9. Build completeness를 먼저 검증한다

Relevance 평가 전에 intended corpus가 들어왔는지 확인합니다.

Inventory gate

expected source active IDs
  ↔ canonical active IDs
  ↔ candidate represented document IDs
  ↔ candidate chunk IDs

확인:

• Missing·extra ID set
• Version·content hash parity
• File type·tenant·classification cohort coverage
• Quarantine count와 approval
• Source high-watermark lag
• Tombstone exclusion

Count 총합만 같아서는 안 됩니다. ID set diff를 봅니다.

10. Parser·structure gate를 통과한다

72번 글의 구조 품질을 release gate로 만듭니다.

• Source pages vs extracted pages
• Empty page·document rate
• Text chars·tokens by cohort
• Heading depth·reading order
• Table count, row·cell·header link
• Bbox validity
• OCR language·confidence
• Fallback·warning distribution
• Golden document key cell

Parser revision이 같아도 runtime image, dependency나 OCR model digest가 바뀔 수 있으므로 artifact digest를 manifest에 넣습니다.

11. Identity·metadata gate를 통과한다

73번과 74번의 규칙을 검사합니다.

• Document·version uniqueness
• Duplicate cluster change
• Source locator→stable ID mapping
• Chunk span parent integrity
• Required typed field validity
• Unknown·not applicable·redacted 상태
• Vocabulary revision coverage
• Entity linking wrong-link·abstain sample
• Assertion provenance·conflict
• Search projection hash parity

Entity registry merge가 retrieval 결과를 크게 바꿀 수 있으므로 model migration처럼 평가합니다.

12. ACL·security gate는 0 tolerance invariant다

75번 글의 항목:

missing tenant ID = 0
chunk without authorization decision = 0
document-chunk ACL mismatch = 0
cross-tenant synthetic result = 0
revoked resource result = 0
unauthorized candidate sent to reranker/model = 0
cache auth mismatch = 0

Filter selectivity별 authorized Recall과 latency도 봅니다. Security correctness와 quality trade-off를 섞지 않습니다.

13. Freshness·temporal·deletion gate를 통과한다

76번과 79번에서 정의한 상태를 확인합니다.

• Candidate source high-watermark 도달
• Out-of-order old version active 0
• Current·as-of valid interval query
• Scheduled document 제외/표시
• ACL revoke lag within SLO
• Tombstone set parity
• Deleted resource exact·dense·citation result 0
• Restore·backfill resurrection 0
• Cache invalidation complete
• Pending legal hold·backup state manifest

Content coverage가 좋아도 삭제 대상 1건이 보이면 release를 중단합니다.

14. Embedding·index compatibility gate를 통과한다

77번 글의 generation contract:

• Vector dimension exact
• NaN·Inf·zero norm 0
• Model revision mix 0
• Document prefix·query prefix hash
• Normalization과 distance metric 일치
• Sparse/vector pair coverage
• Query encoder-index matrix compatible
• Shard·replica health
• Active alias는 아직 previous generation
• Candidate exact probe와 ANN probe

Score threshold, no-answer와 rerank cutoff는 새 model score distribution에서 재보정합니다.

15. Retrieval quality gate를 query cohort별로 통과한다

Offline gold

• Recall@k
• MRR·nDCG
• Filtered Recall@k
• Source-span relevance
• Citation correctness
• Answer groundedness
• Abstention precision·coverage

Cohort

• Language
• Acronym·part number
• Table·OCR
• Short·long query
• Entity head·tail
• Current·historical
• Tenant·ACL selectivity
• Source type·document class

전체 평균 개선이 critical cohort regression을 숨기지 않게 합니다.

16. Performance·capacity·cost gate를 통과한다

Online path

• Query embedding latency
• Sparse·vector retrieval latency
• Filtered ANN latency
• Reranker latency
• Context assembly
• End-to-end p50·p95·p99
• Timeout·error

Saturation

• CPU·GPU
• Vector memory
• Disk·segment merge
• Queue depth·oldest age
• Connection pool
• Provider quota

Cost

• Backfill parser·embedding cost
• Storage delta vs previous
• Cost per 1,000 queries
• Shadow·canary overhead
• Old generation soak cost

Google SRE의 monitoring guidance는 latency, traffic, errors와 saturation을 핵심 신호로 다룹니다. RAG release에서는 여기에 data coverage, freshness, security와 relevance를 추가해야 합니다.

17. Gate report는 machine-readable하고 재현 가능해야 한다

{
  "release_id": "kb-2026-07-16.10",
  "gate_report_id": "gate-771",
  "evaluated_at": "2026-07-16T07:00:00Z",
  "inputs": {
    "candidate_generation": "rag-docs-g10",
    "gold_snapshot": "rag-gold-42",
    "assertion_revision": "qa-17"
  },
  "blocking": {
    "passed": 42,
    "failed": 0
  },
  "warnings": [
    {"id": "ocr_confidence_shift", "owner": "parser-team", "expires_at": "2026-07-23"}
  ],
  "security_invariants": {
    "cross_tenant": 0,
    "acl_mismatch": 0,
    "deleted_visible": 0
  },
  "decision": "eligible_for_shadow"
}

Report가 어떤 data·code·model revision을 평가했는지 빠지면 candidate가 재build된 뒤 오래된 report를 잘못 재사용할 수 있습니다.

18. Exception은 owner·범위·만료를 가진다

Warning을 수용할 때:

exception_id: ex-118
gate_id: optional_author_null_rate
scope: source=legacy-wiki
justification: source field unavailable; retrieval not affected
owner: data-owner
approved_by: release-owner
created_at: 2026-07-16
expires_at: 2026-07-23
compensating_control: weekly source inventory review

Security invariant, missing tenant, deleted content visibility 같은 항목은 exception 대상으로 두지 않습니다. 만료 없는 waiver가 영구 debt가 되지 않게 합니다.

19. Shadow stage에서 실제 query 분포를 비교한다

production request
  ├─ primary: previous compatible release → user
  └─ shadow: candidate compatible release → comparison only

Shadow 조건:

• Same authorization context
• Same query timestamp·temporal mode
• Candidate response never reaches user
• Primary latency independent
• Query privacy·retention policy 준수
• Sampling by cohort
• Cost and rate limit guard

비교:

• Result document·source-span overlap
• New relevant gain·relevant loss sample
• Empty result
• Score·rank distribution
• Citation·answer diff
• Latency·error

20. Canary stage에서 blast radius를 제한한다

Canary cohort

• Internal staff
• Beta tenant
• Non-critical workflow
• Stable synthetic account
• 특정 query cohort

Sticky routing

동일 session·principal은 같은 release를 보게 합니다.

Canary gate

• Security invariants remain 0
• SLO within budget
• Critical cohort no unacceptable regression
• User-visible error and abstention
• Citation open success
• On-call can observe and rollback

Traffic percentage는 마지막 수단입니다. Tenant 1%가 가장 민감한 고객이면 blast radius가 작지 않습니다.

21. Activation pointer는 호환 artifact를 한 번에 선택한다

logical release route
  → query encoder
  → physical sparse/vector index
  → metadata/ACL schema
  → reranker/context policy
  → cache namespace

Elasticsearch 공식 문서는 여러 alias action을 단일 atomic operation으로 처리해 downtime 없이 index를 swap할 수 있다고 설명합니다. 그러나 index alias만 atomic하다고 전체 application release가 자동 atomic해지는 것은 아닙니다.

Release registry 예시:

{
  "route": "rag-search-active",
  "release_id": "kb-2026-07-16.10",
  "query_encoder": "embed-ko-v7",
  "physical_index": "rag-docs-g10",
  "acl_policy": "acl-184",
  "context_policy": "context-12",
  "cache_namespace": "kb-2026-07-16.10",
  "activated_at": "2026-07-16T08:10:00Z",
  "previous": "kb-2026-07-09.7"
}

Application instance가 registry를 cache한다면 refresh와 max stale time을 제어합니다.

22. Activation 순서를 runbook으로 고정한다

1. announce start and freeze manifest
2. confirm candidate health and delta lag
3. confirm previous release rollback health
4. enable high-resolution dashboards and probes
5. record pre-cutover synthetic probe baseline
6. atomically update release route
7. invalidate or switch generation cache namespace
8. run immediate ACL, deletion, current/as-of, lexical/dense probes
9. observe short window at high resolution
10. mark ACTIVE then SOAKING

각 step에 command, expected output, timeout과 abort action을 둡니다.

23. Rollback trigger를 사전에 고정한다

Immediate rollback or deny

• Cross-tenant or unauthorized result 1건
• Deleted·revoked content visible 1건
• Encoder-index generation mismatch
• Critical citation points to wrong tenant/source
• Widespread data corruption

SLO-based rollback

• Error budget burn
• p99 latency sustained breach
• Empty result or no-answer surge
• Critical cohort retrieval regression
• Delta lag growing beyond recovery capacity
• Resource saturation threatens production

Investigate before rollback

• Non-critical warning drift
• Shadow overlap difference without gold regression
• Expected source mix change

Trigger마다 owner와 rollback, pause canary, emergency deny, continue observe action을 정합니다.

24. Rollback readiness를 release 전에 증명한다

필요한 것:

• Previous physical index healthy
• Previous query encoder runtime available
• Previous ACL·context policy compatible
• Previous generation received current revoke·delete delta
• Previous cache namespace safe or rebuildable
• Atomic route reversal command
• Approval and credentials
• Synthetic probe suite
• Data corruption 시 safe release 선택 기준

Kubernetes Deployment는 rollout history와 rollback 기능을 제공하지만, RAG data release는 application pod rollback만으로 old index·model·cache가 복원되지 않습니다. Code rollout과 knowledge release route를 함께 설계합니다.

25. Rollback 실행 순서

1. incident declare / change freeze
2. if security: emergency deny first
3. select known-good compatible release
4. verify its delta freshness and tombstones
5. atomically route to previous release
6. switch/invalidate cache namespace
7. run security, deletion and retrieval probes
8. verify latency/error and source freshness
9. keep failed release isolated for evidence
10. communicate state and start diagnosis

Failed candidate를 즉시 삭제하면 원인 분석과 replay 범위를 잃습니다. 접근을 제한하고 retention policy에 따라 보존합니다.

26. Soak에서 보아야 할 것

Cutover 직후 10분만 정상이라고 stable로 선언하지 않습니다.

Short window

• Error·latency·saturation
• Security/deletion probes
• Cache correctness
• Alias·registry convergence

Business cycle

• Peak traffic
• Overnight ingestion
• Large document batch
• ACL directory sync
• Scheduled retention·deletion
• Daily evaluation
• Backup·snapshot job

Soak duration은 system cadence에 맞춥니다. 주간 job이 중요한데 하루만 보면 부족합니다.

27. Post-release delta가 계속 흐르는지 확인한다

Static candidate가 좋아도 activation 뒤 source change가 멈추면 곧 stale합니다.

• CDC/poll cursor advances
• Event→active lag p99
• ACL revoke priority lane
• Tombstone propagation
• New document parser·embedding revision
• No mixed generation
• Reconciliation parity

Release success report에 activation 이후 delta probe를 포함합니다.

28. Incident severity와 command를 단순화한다

SEV-1 예

• Cross-tenant data exposure
• Deleted·restricted content exposure
• Broad incorrect safety-critical answer

Action:

deny / isolate → declare → preserve evidence → rollback safe release

SEV-2 예

• Large cohort retrieval outage
• Severe latency·error
• Freshness SLO breach with bounded impact

SEV-3 예

• Non-critical metadata degradation
• Optional source backlog

실제 severity definition은 조직 incident policy를 따릅니다.

29. Incident command와 communication을 분리한다

필수 역할:

• Incident commander
• Operations lead
• Security/privacy lead when applicable
• Communications lead
• Scribe

Update template:

incident: INC-2026-0716
start: 08:14 UTC
impact: Fab-A scanned PDF queries returned empty results
security/privacy: no unauthorized or deleted result observed
current action: route rolled back G10→G9
data freshness: G9 delta lag 22 seconds
next update: 08:35 UTC
owner: incident commander

관찰 사실과 추정을 구분합니다.

30. Diagnosis는 first bad release와 lineage에서 시작한다

symptom cohort
  → active release manifest
  → changed revisions from previous
  → first bad run / dataset
  → affected document/chunk/vector/index lineage
  → cache and answer exposure

Diff 목록:

• Source snapshot composition
• Parser·dependency digest
• Metadata/vocabulary/entity revision
• ACL policy/projection
• Chunker
• Embedding·prefix·metric
• ANN setting
• Query runtime·reranker·context
• Application code

변경을 한 release에 너무 많이 묶으면 attribution이 어렵습니다. 큰 migration은 단계별 shadow generation으로 분해할 수 있습니다.

31. Disaster recovery도 knowledge release를 복원해야 한다

DR test에서 application service만 뜨면 충분하지 않습니다.

복원 대상:

• Canonical snapshot catalog
• Source high-watermarks·change log offsets
• Tombstone registry
• Release manifests·signatures
• Active and previous index snapshots
• Encoder·parser artifacts
• ACL policy and identity dependency
• Cache는 재생성 가능
• Evaluation·probe suite

Restore 순서:

restore isolated
  → load tombstones and current deny rules
  → restore canonical and index artifacts
  → replay deltas
  → verify ACL/deletion/freshness
  → set active release route
  → admit production traffic

32. Capacity와 release concurrency를 제한한다

동시에 두 full backfill을 실행하면 production과 서로 경쟁합니다.

Control:

• Max concurrent full rebuild
• Tenant/source partition fairness
• Embedding token budget
• Index disk reserve
• Shadow query budget
• Old generation retention capacity
• Release calendar conflict

Release queue에 priority를 둡니다.

security revoke / deletion
  > critical source repair
  > normal incremental
  > full quality migration
  > experimental rebuild

33. Release engineering 원칙을 RAG에 적용한다

Google SRE의 release engineering 장은 self-service, high velocity, hermetic build와 policy enforcement 같은 원칙을 설명합니다. RAG에 맞게 번역하면 다음과 같습니다.

• Repeatable: 같은 manifest로 같은 candidate를 재생성
• Hermetic: 외부 latest dependency 대신 digest 고정
• Automated: gate·probe·route change 자동화
• Auditable: 누가 무엇을 승인·활성·rollback했는지 기록
• Small blast radius: shadow·canary·tenant cohort
• Fast rollback: previous compatible generation 보존
• Policy enforced: ACL·deletion·privacy gate 우회 불가

Automation이 판단을 없애는 것이 아니라 같은 evidence와 stop rule을 반복 적용하게 합니다.

34. 최소 CLI·API surface 예시

kb-release plan --manifest release.yaml
kb-release build --release kb-2026-07-16.10
kb-release status --release kb-2026-07-16.10
kb-release validate --release kb-2026-07-16.10
kb-release shadow start --sample-policy shadow-7
kb-release canary start --cohort internal-fab-a
kb-release approve --gate-report gate-771
kb-release activate --expect-current kb-2026-07-09.7
kb-release rollback --to kb-2026-07-09.7 --reason INC-2026-0716
kb-release retire --release kb-2026-07-09.7

Command는 idempotency key와 compare-and-swap 조건을 가져야 합니다. --expect-current가 다른 release면 activation을 실패시켜 concurrent operator 충돌을 막습니다.

35. Go/No-Go 회의는 dashboard 낭독이 아니다

짧은 decision record:

release: kb-2026-07-16.10
hypothesis: scanned table retrieval improvement
blocking gates: all pass
security/privacy: all invariants zero; deletion receipt pending none
known warnings: legacy wiki owner null, scoped exception ex-118
shadow: critical cohorts no regression
canary: internal Fab-A 2h, SLO met
rollback: rehearsed at 06:30, previous G9 delta current
capacity: 34% disk headroom after retaining G9 [example]
decision: GO
approvers: data, search, security, on-call

숫자는 예시입니다. No-Go가 실패가 아니라 risk control이 되도록 일정에 rebuild 여유를 둡니다.

36. Release completion report를 남긴다

{
  "release_id": "kb-2026-07-16.10",
  "status": "STABLE",
  "activated_at": "2026-07-16T08:10:00Z",
  "stable_at": "2026-07-18T08:10:00Z",
  "manifest_digest": "sha256:...",
  "gate_report": "gate-771",
  "shadow_report": "shadow-88",
  "canary_report": "canary-42",
  "active_route": "rag-search-active",
  "previous_release": "kb-2026-07-09.7",
  "rollback_rehearsal": "rb-17",
  "exceptions": ["ex-118"],
  "incidents": [],
  "retirement_due": "2026-07-25T00:00:00Z"
}

Report는 다음 release의 baseline이 됩니다.

37. Old release retirement도 gate를 가진다

삭제 전 확인:

• New release soak complete
• No open rollback-trigger incident
• Old release no longer receives traffic
• Old generation delta retention decision
• Cache TTL expired
• Snapshot·manifest retained
• Legal hold·deletion constraints
• Disk capacity and removal plan
• Restore procedure tested
• Data owner approval

Physical index 삭제, old encoder artifact와 secret 폐기, consumer 종료를 별도 task로 추적합니다.

38. 가상 반도체 RAG release 예시

다음은 설명을 위한 가상 시나리오입니다.

목표

Scanned maintenance report의 merged table retrieval을 개선합니다.

변경

• OCR runtime image
• Table structure parser
• Layout-aware chunker
• Korean-domain embedding 1024d

Candidate build

• Snapshot S8842
• 2개 source high-watermark
• 118,000 documents, 1.6M chunks [가상 수치]
• 214 quarantined encrypted files, data owner review [가상 수치]

Gates

• Source ID coverage: approved target 충족
• Golden table cell: all pass
• ACL·cross-tenant·deletion mismatch: 0
• Table-query Recall@20: 개선
• General natural-language cohort: 허용 범위 내
• Filtered p99: SLO 내
• Disk: G9·G10 동시 보존 가능

Shadow·canary

• Internal Fab-A user cohort
• Same ACL context
• Table query citation span human review
• No user response from shadow

Activation

• Registry가 encoder 7 + index G10 + cache namespace G10을 한 번에 선택
• Immediate marker, ACL deny, tombstone, current/as-of probe

Rollback rehearsal

• G9 consumer는 최신 revoke·delete delta 유지
• Route G10→G9 복원
• Cache namespace 전환
• Probe 통과

이 예시는 실제 운영 결과가 아니라 runbook 구조를 설명하기 위한 것입니다.

39. 시리즈 전체를 release gate로 다시 보기

글	Release에서 묻는 질문
71. Knowledge lifecycle	정본과 artifact state가 무엇인가?
72. Layout·OCR·table	구조와 출처 위치가 보존됐는가?
73. Identity·version·dedup	같은 대상과 새 version을 구분하는가?
74. Metadata·ontology	Filter와 entity가 typed·versioned인가?
75. ACL·multi-tenancy	Unauthorized candidate가 0인가?
76. Freshness·CDC	Source change·revoke·delete가 SLO 안에 반영됐는가?
77. Migration	Candidate를 비교·전환·rollback할 수 있는가?
78. Quality·drift	Silent partial failure를 stage·cohort별로 찾는가?
79. Deletion·retention	Derived copy와 restore 경로까지 삭제 상태를 증명하는가?
80. Release runbook	위 증거를 go/no-go와 운영 행동으로 연결하는가?

40. 구현 순서

1단계. Release manifest와 registry

모든 code·data·model·policy revision, active·previous release를 기록합니다.

2단계. Isolated build

Immutable source snapshot에서 candidate를 만들고 delta convergence를 구현합니다.

3단계. Blocking gates

Coverage, structure, identity, metadata, ACL, freshness, deletion, compatibility를 자동화합니다.

4단계. Retrieval·performance evaluation

Gold·cohort 품질과 latency·saturation·cost를 측정합니다.

5단계. Shadow·canary routing

Authorization-aware shadow와 sticky bounded canary를 구현합니다.

6단계. Atomic release pointer

Encoder, index, policy와 cache namespace를 호환 단위로 전환합니다.

7단계. Rollback·incident rehearsal

Trigger, previous freshness, command, probe와 communication을 훈련합니다.

8단계. Soak·completion·retirement

Business cycle을 관찰하고 evidence를 남긴 뒤 old artifact를 정책에 따라 제거합니다.

Production release 체크리스트

Plan

• Release goal과 measurable hypothesis가 있다.
• Changed·unchanged component와 affected cohort를 적었다.
• Risk, owner, approver, maintenance window와 communication이 있다.
• Rollback target과 trigger가 사전에 정해졌다.

Manifest

• Canonical snapshot·source high-watermark가 immutable하다.
• Connector, parser image digest, chunker, schema, vocabulary revision이 있다.
• Entity, ACL, tombstone·temporal cutoff가 있다.
• Document·query encoder, dimension, prefix, normalization, metric이 있다.
• Physical index, query runtime, cache namespace와 compatible app range가 있다.
• Gold data·assertion revision과 manifest digest가 있다.

Build

• Candidate가 active route 밖에서 생성된다.
• Partition·checkpoint·retry·quarantine가 보인다.
• Backfill 중 delta·ACL revoke·delete가 따라잡힌다.
• Production SLO를 보호하는 resource guard가 있다.

Data and security gates

• Source→canonical→candidate ID coverage와 diff를 확인했다.
• Page·table·reading order·golden document 구조 gate를 통과했다.
• Identity·version·dedup·span integrity를 통과했다.
• Metadata schema·vocabulary·entity assertion을 검증했다.
• Tenant·ACL missing·mismatch·cross-tenant result가 0이다.
• Freshness·current/as-of·source high-watermark를 검증했다.
• Tombstone·deleted·revoked result와 cache visibility가 0이다.
• Embedding dimension·finite·revision mix와 encoder-index compatibility를 통과했다.

Quality and operations

• Gold Recall·MRR·nDCG·citation을 cohort별로 봤다.
• Critical cohort regression 기준을 통과했다.
• p50·p95·p99 latency, error, saturation을 봤다.
• Filter selectivity별 latency·fill rate를 봤다.
• Capacity·backfill·dual generation·shadow cost budget이 있다.
• Gate report가 candidate manifest digest와 연결된다.
• Exception에 scope, owner, compensating control과 expiry가 있다.

Shadow and canary

• Shadow가 primary response·latency에 영향을 주지 않는다.
• Shadow에 같은 auth·temporal context가 적용된다.
• Query privacy·retention policy를 지킨다.
• Canary cohort가 민감도·blast radius 기준으로 선택됐다.
• Sticky routing과 stop rule이 있다.
• On-call이 dashboard와 rollback command를 확인했다.

Activate and rollback

• Encoder·index·policy·cache를 호환 release pointer로 바꾼다.
• Compare-and-swap로 concurrent activation을 막는다.
• Immediate ACL·delete·current·lexical·dense probe가 있다.
• Previous generation과 encoder가 healthy하다.
• Previous generation이 최신 revoke·delete delta를 보유한다.
• Rollback을 실제 rehearsal했다.
• Failed candidate evidence 보존 정책이 있다.

Soak and retire

• Peak·batch·ACL sync·retention job을 포함한 soak가 있다.
• Activation 후 delta freshness를 확인했다.
• Completion report와 incident·exception을 기록했다.
• Old release retirement gate와 approval가 있다.
• Snapshot·manifest를 보존하고 physical index·encoder·secret를 정리한다.

스스로 확인하기

Q1. 매시간 incremental index update에도 이 모든 gate가 필요한가?

Release type에 따라 축소합니다. 매 event마다 full gold evaluation을 할 필요는 없지만 identity·ACL·delete·schema invariant와 freshness는 지속 확인해야 합니다. Full rebuild와 policy change는 더 강한 gate를 적용합니다.

Q2. Application canary와 knowledge-base canary는 같은가?

관련 있지만 다릅니다. Application binary가 같아도 query encoder·index·data snapshot이 다를 수 있습니다. Release route가 code와 knowledge generation 호환성을 함께 보장해야 합니다.

Q3. 모든 gate가 자동이면 human approval은 없어도 되는가?

Risk에 따라 다릅니다. Security·privacy, high-impact data scope와 exception은 accountable owner 승인이 필요할 수 있습니다. 자동화는 evidence 수집과 일관된 stop을 강화합니다.

Q4. Alias swap이 성공하면 downtime 없는 release가 끝난 것인가?

아닙니다. Application registry cache, query encoder, cache namespace, delta consumer와 citation service가 같은 release를 보는지 확인해야 합니다.

Q5. Rollback하면 source freshness를 잃지 않는가?

Old generation이 activation 뒤에도 delta·revoke·delete를 받았다면 줄일 수 있습니다. 그렇지 않으면 rollback 전 missing delta를 replay하거나 security overlay를 우선 적용해야 합니다.

Q6. Retrieval metric이 개선되고 latency도 좋으면 바로 stable인가?

아닙니다. ACL·deletion invariant, business cycle의 ingestion·sync·backup job, cache와 production cohort를 soak에서 확인해야 합니다.

Q7. Runbook이 너무 길면 실제 장애에서 못 읽지 않는가?

맞습니다. 상세 문서와 함께 첫 화면에 decision tree, immediate actions, commands, expected output와 escalation contact를 둡니다. 이 글은 설계 체크리스트이고 실제 runbook은 환경별로 더 짧고 실행 가능해야 합니다.

마무리

Enterprise RAG knowledge base는 한 번 만들고 끝나는 검색 index가 아니라 versioned data product입니다. 좋은 release engineering은 더 빨리 바꾸기 위해 변경을 작게 만들고, 증거로 검증하며, blast radius를 제한하고, 실패했을 때 되돌아갈 길을 유지합니다.

immutable release manifest
  + isolated reproducible build
  + data, security, retrieval and SLO gates
  + authorization-aware shadow and bounded canary
  + atomic compatible activation
  + rehearsed rollback, incident and retirement
  = operable Enterprise RAG knowledge base

이 글로 Enterprise RAG 지식 파이프라인 10편을 마칩니다. 전체 흐름과 순서는 시리즈 페이지에서 다시 볼 수 있습니다. 다음 학습 경로는 이 설계를 실제 애플리케이션 코드로 옮기는 Production RAG Agent 프로젝트 구조입니다.

참고문헌

• Kubernetes, Deployments, accessed 2026-07-16.
• Google, Site Reliability Engineering — Release Engineering, 2016.
• Google, Site Reliability Engineering — Monitoring Distributed Systems, 2016.
• Elastic, Aliases, accessed 2026-07-16.
• Apache Iceberg, Table Specification, accessed 2026-07-16.
• Humble and Farley, Continuous Delivery, Addison-Wesley, 2010.

검증 메모 — 공식 문서는 2026년 7월 16일 확인했습니다. Kubernetes rollout·rollback, search alias atomicity, snapshot semantics와 registry consistency는 실제 제품·version에 따라 다릅니다. 본문의 release ID, 문서·chunk 수, traffic 비율, threshold와 SLO는 가상 예시입니다. 실제 production에서는 staging에서 source cutoff·delta retention, partial build, mixed encoder-index, ACL·deletion violation, alias conflict, cache mismatch, provider timeout, disk saturation, rollback과 isolated restore를 fault injection으로 검증하고 조직 incident·privacy·security 정책에 맞는 짧은 실행 runbook을 별도로 유지해야 합니다.