Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/node-image-prefetch.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,9 @@ readiness 조회로 무조건 보내지 않습니다. 실제 요청은 release·
`artifact_sha256`은 원본 JSON 파일 hash이고 `image_list.sha256`은 줄 단위 목록의
checksum입니다. #70의 `image_set_id`는 architecture와 정렬·중복 제거한 전체
이미지 참조 집합에서 Runtime이 계산하는 별도 식별자입니다. 서로 대체하지 않습니다.
이번 PR은 제안 단계의 API 요청 생성·hash 계산·HTTP 호출을 추가하지 않습니다.
목록 생성·취합기는 준비 API 요청이나 HTTP 호출을 추가하지 않습니다. 별도
[readiness 대조 도구](node-readiness-audit.md)는 기존 bundle과 저장된 조회 응답을
검수하기 위해 image_set_id만 재계산하며, 준비 요청·조회·노드 작업은 실행하지 않습니다.

### 현재 준비 상태는 파일 목록이 아님

Expand Down
91 changes: 91 additions & 0 deletions docs/node-readiness-audit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# 노드 이미지 준비 응답 대조

`scripts/audit_node_image_readiness.py`는 기존 publish bundle과 **저장된 Runtime
readiness 원본 JSON**을 오프라인에서 대조합니다. 준비 API·노드·GHCR·Backend를
호출하거나 이미지를 다운로드하지 않습니다. 정보 조회·준비 worker·Scheduler·릴리스
활성화 구현을 대체하지 않으며, 기존 생성 fallback이나 준비 선호 정책을 변경하지 않습니다.

## 입력과 범위

- 공식 성공 발행에서 가져온 `artifact-v2.json`: schema2.0/2.1의 일반 Linux K3s 문제.
- Runtime `POST /v1/image-readiness/query`가 실제 반환한 JSON. operation의 SUCCEEDED
이력이나 카톡 요약문으로 대신하지 않습니다.
- 운영 담당자가 확인한 **예상 target ID 전체 목록**. 노드명으로 추측하지 않습니다.
- 판정 기준 시각. 생략하면 실행 PC의 현재 UTC이며, 과거 증거 재현에는 `--as-of`를 씁니다.

기존 `generate_node_image_plan.py`를 재사용해 main 출처 형식·revision·검사 증거·
전체 컨테이너의 고정 GHCR 참조를 검사합니다. KOTH·VM·DOCKER는 제외합니다.
이는 **입력 자료의 계약 검사**입니다. GitHub run/artifact의 진위·출처나 Backend의
현재 active release를 독립 조회한 것이 아니므로 기존 출처 검증을 먼저 거쳐야 합니다.
schema2.1의 env·비밀값 참조도 보고서에 복사하지 않습니다.

## 검사 내용

1. 공개 컨테이너뿐 아니라 DB 등 보조 컨테이너를 포함한 전체 이미지 집합을 사용합니다.
2. architecture와 전체 참조 집합으로 Runtime canonical `image_set_id`를 재계산해
응답과 비교합니다. JSON 파일 hash·줄 단위 이미지 목록 checksum과는 다릅니다.
3. 예상 target 누락은 UNKNOWN입니다. 중복·예상 밖 target이나 모순된 개수/타입은
잘못된 응답으로 거절합니다.
4. `observed_at <= 판정 시각 < valid_until`을 확인하고 RFC3339Nano를 나노초까지
비교합니다. 미래 관측·만료·시각 누락/오류를 준비 완료로 표시하지 않습니다.
5. 최대 관측 나이는 기본60초이며 현재 Scheduler 기본값과 같습니다. 운영 설정이
다르면 승인된 값으로 `--max-observation-age-seconds`를 지정합니다. 이 옵션은
실제 Runtime·Scheduler 설정이나 증거의 시각을 바꾸지 않습니다.
6. 만료·미관측 target의 개수를 현재 준비된 노드 합계에 포함하지 않습니다.

`ready=true`는 적합한 같은 노드 **한 대 이상**에 전체 이미지가 있다는 힌트입니다.
`ready_node_count=1, eligible_node_count=2`는 준비 선호에 사용할 수 있어도
전체 노드 준비 완료가 아닙니다. 이 경우 `PARTIAL`로 기록합니다.

명세·identity 기준:
[Runtime B안 계약](https://github.com/MSG-CTF/secure-provisioner/blob/619423a35876d3e823df17b812cb0b1539001c13/docs/api/image-preparation-b-contract.md),
[canonical 구현](https://github.com/MSG-CTF/secure-provisioner/blob/619423a35876d3e823df17b812cb0b1539001c13/internal/imageprep/model.go#L265-L275),
[Scheduler 조회 시각 기준](https://github.com/MSG-CTF/instance-scheduler/blob/692be04aabab0addfbce251c81c1da16b8c2c1e8/docs/image-readiness.md#L91-L111).
공식 query/response 예제는 `tests/fixtures/runtime-readiness/`에 원문으로 보관합니다.

## 실행

```bash
python3 -B -m scripts.audit_node_image_readiness \
--artifact /absolute/path/to/artifact-v2.json \
--readiness-response /absolute/path/to/runtime-readiness.json \
--target-id target-a \
--target-id target-b \
--output-dir /absolute/path/to/new-private-audit
```

과거 증거를 재현할 때만 `--as-of 2026-10-24T00:00:30Z`처럼 실제 기준 시각을 지정합니다.
보고서는 생성 시각과 판정 기준 시각을 따로 기록합니다. 과거 기준의 성공 결과를 현재
준비 상태로 재사용하지 않습니다. 입력 시각을 수정하거나 만료를 연장하지 않습니다.

새 출력 디렉터리에 `readiness-audit.json` 하나만 만듭니다. 디렉터리는0700,
보고서는0600이며 기존 출력은 덮어쓰지 않습니다. target ID 등 운영 정보가 있으므로
공개 저장소·공개 Actions artifact에 원본 보고서를 업로드하지 않습니다.
표준 출력에는 상태·집계만 쓰고 입력 원문·env·token·오류 응답 본문은 출력하지 않습니다.
파일 크기는 각1MiB, 이미지32개·target50개까지입니다.

## 판정과 종료 코드

| 상태 | 의미 | 종료 코드 |
|---|---|---:|
| ALL_ELIGIBLE_READY | 모든 요청 target에서 ready_node_count=eligible_node_count>0이며 관측이 fresh | 0 |
| PARTIAL | 일부 target/적합 노드만 fresh READY | 1 |
| NOT_READY | 모든 요청 target이 fresh 관측됐으나 준비된 노드 없음 | 1 |
| UNKNOWN | 누락·미관측·만료·시각 오류 등으로 전체 준비를 판단할 수 없음 | 1 |
| 잘못된 입력/응답·I/O 오류 | 이미지 집합·architecture·target·개수·파일 등이 계약과 다름 | 2 |

종료1은 **대조 증거가 전체 완료를 보장하지 못한다는 뜻**입니다. 생성 API를 차단하거나
준비 요청·재시도를 실행하지 않습니다. 기존 발행 workflow의 필수 gate로 연결하지 않았으며
검사 실패로 정상 bundle을 Backend Poller가 수집하지 못하게 만들지도 않습니다.

## 증명하지 않는 것

- API의 실제 호출·응답 인증, Backend 현재 active, 노드 UID/boot generation의 독립 검증
- Backend 준비 operation 성공, 실제 Pod 생성·HTTP 접속·imageID, cold pull 소요 시간
- 새 노드 자동 준비, 운영 버전 전환·기존 인스턴스 hotfix 교체·롤백 성공
- 요청 목록 밖의 모든 운영 노드 준비와 물리 노드 UID별 중복 없는 총수

보고서의 개수는 fresh target 응답에 있는 수의 합입니다. 유일한 물리 노드 수로
취급하지 않습니다. `image_set_id`도 서명이나 실행 승인 증명이 아닙니다.
`readinessCache=miss`는 Scheduler 조회 응답 캐시의 상태이므로 이 도구의 이미지
준비 판정이나 cold pull 증거로 사용하지 않습니다.
8 changes: 8 additions & 0 deletions scripts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,14 @@ Provisioner API 요청으로 변환합니다. 생성 Operation을 조회한 뒤

## 파일

### `audit_node_image_readiness.py`

기존 발행 bundle과 저장된 Runtime readiness JSON을 오프라인에서 대조합니다.
전체 이미지·architecture·예상 target·관측 시각/만료를 검사하고, ready1/2 같은
부분 준비와 전체 적합 노드 준비를 구분합니다. 별도 HTTP 호출·다운로드·활성화는
하지 않으며 운영 정보를 담은 보고서는0700/0600의 새 비공개 경로에만 기록합니다.
[판정 범위와 실행 방법](../docs/node-readiness-audit.md)을 참고합니다.

### `collect_node_image_plans.py`

현재 main과 성공한 실제 bundle을 대조해 일반 Linux K3s 문제의 전체 다운로드
Expand Down
273 changes: 273 additions & 0 deletions scripts/audit_node_image_readiness.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,273 @@
#!/usr/bin/env python3
"""Compare a publish bundle with a saved Runtime readiness response, offline."""

import argparse
from datetime import datetime, timezone
import hashlib
import json
import os
from pathlib import Path
import re
import sys

if __package__:
from .generate_node_image_plan import generate_plan, MAX_ARTIFACT_BYTES
else:
from generate_node_image_plan import generate_plan, MAX_ARTIFACT_BYTES


MAX_TARGETS = 50
MAX_IMAGES = 32
MAX_COUNT = 2**31 - 1
EPOCH = datetime(1970, 1, 1, tzinfo=timezone.utc)
RFC3339 = re.compile(
r"^([0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2})"
r"(?:\.([0-9]{1,9}))?(Z|[+-][0-9]{2}:[0-9]{2})$"
)


def _time_ns(value):
if not isinstance(value, str):
raise ValueError("timestamp must be RFC3339")
matched = RFC3339.fullmatch(value)
if matched is None or matched[3] == "-00:00":
raise ValueError("timestamp must have a known offset")
zone = matched[3]
if zone != "Z" and (int(zone[1:3]) > 23 or int(zone[4:6]) > 59):
raise ValueError("invalid timestamp offset")
base = datetime.fromisoformat(matched[1] + ("+00:00" if zone == "Z" else zone))
delta = base.astimezone(timezone.utc) - EPOCH
# Keep Runtime RFC3339Nano boundaries instead of truncating to microseconds.
return ((delta.days * 86400 + delta.seconds) * 10**9
+ int((matched[2] or "").ljust(9, "0")))


def calculate_image_set_id(architecture, images):
canonical = {
"schema_version": 1,
"architecture": architecture,
"images": sorted(set(images)),
}
raw = json.dumps(canonical, separators=(",", ":"), ensure_ascii=True).encode()
return "sha256:" + hashlib.sha256(raw).hexdigest()


def _validate_targets(target_ids):
if not isinstance(target_ids, list) or not 1 <= len(target_ids) <= MAX_TARGETS:
raise ValueError("expected targets are required")
seen = set()
for target in target_ids:
if (not isinstance(target, str) or not 1 <= len(target) <= 128
or target.strip() != target
or any(ord(character) < 32 or ord(character) == 127 for character in target)
or target in seen):
raise ValueError("invalid or duplicate expected target")
seen.add(target)
return seen


def _observation(entry, now_ns, max_age_seconds):
result = {
"target_id": entry["target_id"],
"state": "UNKNOWN",
"reason": "NO_OBSERVATION",
"ready_node_count_as_reported": entry["ready_node_count"],
"eligible_node_count_as_reported": entry["eligible_node_count"],
"observed_at": None,
"valid_until": None,
}
observed, until = entry.get("observed_at"), entry.get("valid_until")
if observed is None or until is None:
return result
try:
observed_ns, until_ns = _time_ns(observed), _time_ns(until)
except (ValueError, OverflowError):
result["reason"] = "INVALID_TIMESTAMPS"
return result
result.update(observed_at=observed, valid_until=until)
if until_ns <= observed_ns:
result["reason"] = "INVALID_TIME_WINDOW"
elif observed_ns > now_ns:
result["reason"] = "FUTURE_OBSERVATION"
elif now_ns >= until_ns:
result["reason"] = "EXPIRED"
elif now_ns - observed_ns >= max_age_seconds * 10**9:
result["reason"] = "OBSERVATION_TOO_OLD"
elif not entry["ready"]:
result.update(state="NOT_READY", reason="NO_READY_NODE_AS_REPORTED")
elif entry["ready_node_count"] < entry["eligible_node_count"]:
result.update(state="SOME_NODES_READY", reason="PARTIAL_NODE_COVERAGE")
else:
result.update(state="ALL_NODES_READY", reason="FRESH_AS_REPORTED")
return result


def audit_readiness(artifact, artifact_sha256, response, target_ids, *, as_of,
max_age_seconds=60):
expected_targets = _validate_targets(target_ids)
if type(max_age_seconds) is not int or not 1 <= max_age_seconds <= 86400:
raise ValueError("invalid maximum observation age")
now_ns = _time_ns(as_of)
generated = generate_plan(artifact, artifact_sha256)
if generated is None:
raise ValueError("only general Linux Kubernetes bundles are supported")
plan, _ = generated
images = [container["image"] for container in plan["containers"]]
if len(images) > MAX_IMAGES:
raise ValueError("the Runtime image limit was exceeded")
identity = calculate_image_set_id(plan["architecture"], images)
if (not isinstance(response, dict)
or response.get("architecture") != plan["architecture"]
or response.get("image_set_id") != identity):
raise ValueError("response image set or architecture does not match")
targets = response.get("targets")
if not isinstance(targets, list) or len(targets) > MAX_TARGETS:
raise ValueError("a readiness target array is required")
by_id = {}
for entry in targets:
if not isinstance(entry, dict):
raise ValueError("invalid readiness target")
target = entry.get("target_id")
if (not isinstance(target, str) or target not in expected_targets
or target in by_id):
raise ValueError("unexpected or duplicate response target")
ready, count, eligible = (
entry.get("ready"), entry.get("ready_node_count"),
entry.get("eligible_node_count"),
)
if (type(ready) is not bool or type(count) is not int or type(eligible) is not int
or not 0 <= count <= eligible <= MAX_COUNT or ready != (count > 0)):
raise ValueError("invalid readiness counts")
by_id[target] = entry

audited = []
for target in target_ids:
if target not in by_id:
audited.append({
"target_id": target, "state": "UNKNOWN", "reason": "MISSING_TARGET",
"ready_node_count_as_reported": None,
"eligible_node_count_as_reported": None,
"observed_at": None, "valid_until": None,
})
else:
audited.append(_observation(by_id[target], now_ns, max_age_seconds))
fresh = [entry for entry in audited if entry["state"] != "UNKNOWN"]
positive = [entry for entry in fresh if entry["state"] != "NOT_READY"]
all_nodes = all(entry["state"] == "ALL_NODES_READY" for entry in audited)
if all_nodes:
status = "ALL_ELIGIBLE_READY"
elif positive:
status = "PARTIAL"
elif len(fresh) != len(audited):
status = "UNKNOWN"
else:
status = "NOT_READY"
return {
"schema_version": "1.0",
"scope": "SUPPLIED_BUNDLE_REQUESTED_TARGETS_ONLY",
"status": status,
"as_of": as_of,
"max_observation_age_seconds": max_age_seconds,
"bundle": {
"challenge_slug": plan["challenge_slug"],
"registry_revision": plan["registry_revision"],
"architecture": plan["architecture"],
"artifact_sha256": plan["artifact_sha256"],
"container_count": len(images),
"image_set_id": identity,
},
"all_requested_targets_have_ready_hint": len(positive) == len(audited),
"all_reported_eligible_nodes_ready": all_nodes,
"counts": {
"requested_targets": len(audited), "fresh_targets": len(fresh),
"unknown_targets": len(audited) - len(fresh),
"ready_nodes_in_fresh_reports": sum(
entry["ready_node_count_as_reported"] for entry in fresh),
"eligible_nodes_in_fresh_reports": sum(
entry["eligible_node_count_as_reported"] for entry in fresh),
},
"targets": audited,
"limits": {
"live_api_queried": False,
"backend_active_verified": False,
"node_identity_independently_verified": False,
"operation_success_proven": False,
"pod_execution_proven": False,
"cold_pull_proven": False,
"rollout_proven": False,
"all_operating_nodes_verified": False,
},
}


def _unique_object(pairs):
result = {}
for key, value in pairs:
if key in result:
raise ValueError("duplicate JSON key")
result[key] = value
return result


def _invalid_constant(_value):
raise ValueError("nonfinite JSON number")


def _read_json(path):
path = Path(path)
if path.is_symlink() or not path.is_file() or path.stat().st_size > MAX_ARTIFACT_BYTES:
raise ValueError("invalid input file")
with path.open("rb") as stream:
raw = stream.read(MAX_ARTIFACT_BYTES + 1)
if len(raw) > MAX_ARTIFACT_BYTES:
raise ValueError("input size limit exceeded")
return raw, json.loads(raw, object_pairs_hook=_unique_object,
parse_constant=_invalid_constant)


def write_audit(artifact_path, response_path, target_ids, output_dir, *, as_of=None,
max_age_seconds=60):
raw, artifact = _read_json(artifact_path)
_, response = _read_json(response_path)
generated_at = datetime.now(timezone.utc).isoformat()
report = audit_readiness(
artifact, hashlib.sha256(raw).hexdigest(), response, target_ids,
as_of=generated_at if as_of is None else as_of,
max_age_seconds=max_age_seconds,
)
report["generated_at"] = generated_at
report["time_basis"] = "EXPLICIT_AS_OF" if as_of is not None else "SYSTEM_UTC_NOW"
output_dir = Path(output_dir)
output_dir.mkdir(mode=0o700, parents=True, exist_ok=False)
descriptor = os.open(output_dir / "readiness-audit.json",
os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
json.dump(report, stream, ensure_ascii=True, indent=2, allow_nan=False)
stream.write("\n")
return report


def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--artifact", required=True, type=Path)
parser.add_argument("--readiness-response", required=True, type=Path)
parser.add_argument("--target-id", required=True, action="append")
parser.add_argument("--output-dir", required=True, type=Path)
parser.add_argument("--as-of", help="RFC3339 audit time; omitted for current UTC")
parser.add_argument("--max-observation-age-seconds", type=int, default=60)
args = parser.parse_args()
try:
report = write_audit(
args.artifact, args.readiness_response, args.target_id, args.output_dir,
as_of=args.as_of, max_age_seconds=args.max_observation_age_seconds,
)
except (ValueError, OSError, TypeError, RecursionError, OverflowError):
print("Readiness audit failed: check inputs, time and output path.", file=sys.stderr)
return 2
print(json.dumps({"status": report["status"], "counts": report["counts"],
"live_api_queried": False}))
return 0 if report["all_reported_eligible_nodes_ready"] else 1


if __name__ == "__main__":
raise SystemExit(main())
Loading
Loading