English · 한국어

pqcota-provisioning: 이관 산출물 생성(3단계)¶

확정된 계획(FinalizedPlan)을 입력으로 받아 PQC 이관 산출물을 생성합니다. 설정 조각, Ansible 플레이북(어디까지 할지는 사용자가 고릅니다. L1은 모듈을 스테이징하고, L2는 설정을 더하고, L3은 활성화와 재시작까지 합니다. 적용과 되돌림 모두 생성합니다), 그리고 되돌릴 근거(변경 전 기록, 되돌림 기록)입니다.

무엇을 바꿀지는 사용자가 쓴 계획이 정하고, 생성기는 그 계획에서 적용 파일과 되돌림 파일을 결정적으로 만듭니다. 생성된 플레이북은 사용자 자신의 Ansible로 실행합니다 → 샘플과 필드.

범위: 런타임은 openssl과 jca 둘입니다. 그 밖의 것은 산출물을 만들지 않고 그렇다고 적습니다(# (unknown runtime)). 출력은 POSIX 방식의 파일 배치(스테이징과 Ansible copy/absent)를 전제하므로 노드는 Linux입니다. CNG 전환물 생성은 로드맵(영문)에 있습니다.

pqcota를 이루는 리포지터리 다섯 개 가운데 하나입니다. 나머지는 pqcota-common, pqcota-inventory, pqcota-discovery, 그리고 통합 리포지터리 pqcota(데모, 예제, 릴리스 번들, 기여 안내)입니다.

한눈에 보기¶

flowchart LR
    P["plan.json<br/>finalized plan"] --> G["pqcota-provision"] --> Y["provision.yml"]
    Y --> A["the user's<br/>ansible-playbook"] --> M["applied on the machine"]

도구는 플레이북과 설정을 생성하고 되돌릴 근거를 남깁니다. 실제 적용은 사용자가 자신의 Ansible로 실행합니다.

flowchart TD
    P["plan.json<br/>(finalized plan)"] --> G{"gate<br/>Executable()"}
    G -- "not FINALIZED<br/>no signature<br/>no remediation" --> X["execution refused"]
    G -- passes --> R["render artifacts per remediation<br/>Render()"]
    R --> B{"crypto_runtime"}
    B -- openssl --> O["openssl.cnf fragment"]
    B -- jca --> J["java.security fragment"]
    O --> L{"automation_level"}
    J --> L
    L -- L1 --> S1["playbook: staging only"]
    L -- L2 --> S2["playbook: module + config fragment staged"]
    L -- L3 --> S3["playbook: staging + activation hook<br/>pre → stage → activate → restart"]
    S1 --> U["the user runs ansible-playbook"]
    S2 --> U
    S3 --> U
    U --> M["files land on the machine<br/>(at L3, activation and restart too)"]
    R -.-> RC["before capture → rollback record<br/>(when --dsn is given)"]

구성 요소¶

빠르게 해 보기¶

# ⓪ approve — raise the judged plan (IN_REVIEW) to FINALIZED while signing it, and register the key it will be checked with.
#    With no key to check, the generator refuses: an approval is where responsibility sits,
#    and one nobody can verify leaves that place empty.
eval "$(pqcota-keygen | grep '^PQCOTA_')"          # SIGN_KEY (private) · VERIFY_KEY (public)
PQCOTA_APPROVAL_KEY="$PQCOTA_SIGN_KEY" \
  pqcota-approve --approver reviewer-1 plan.json > plan.signed.json
export PQCOTA_APPROVAL_KEYS="reviewer-1=$PQCOTA_VERIFY_KEY"

# ① generate — build a playbook from the approved plan
pqcota-provision --level l2 plan.signed.json > provision.yml

# ② apply — reuse the same targets.ini you used for discovery
ansible-playbook -i targets.ini provision.yml

# ③ undo — generate the reverse playbook from the same plan and run it
pqcota-provision --level l2 --rollback plan.signed.json > provision-rollback.yml
ansible-playbook -i targets.ini provision-rollback.yml

모든 옵션과 provider 모듈을 둘 곳은 cmd/README에 있습니다. 무엇이든 실행하기 전에 계획이 게이트를 통과해야 합니다. status가 PLAN_STATUS_FINALIZED가 아니거나, 승인 서명이 없거나, 조치가 하나도 없으면 아무것도 생성하지 않습니다. 판정이 끝난 계획은 IN_REVIEW로 도착하고 pqcota-approve가 이를 FINALIZED로 올립니다. 그래서 승인을 건너뛴 계획은 상태에서 먼저 걸립니다.

출력을 정하는 두 축¶

kind는 「무엇을」을 정하고 automationLevel은 「어디까지」를 정합니다. 둘의 조합이 출력을 결정합니다.

첫 행이 L1에서 비어 있는 것과 마지막 행이 비어 있는 것은 뜻이 다릅니다. 첫 행은 「아직」이고, 마지막 행은 「영원히 아님」입니다. 그래서 마지막 행만 비어 있는 까닭을 설명하는 주석을 플레이북에 남깁니다.

활성화와 재시작 명령은 계획의 activation 훅에서 가져옵니다. 훅이 없으면 L3에서도 그 단계를 생성하지 않습니다.

    # remediation a2 (REMEDIATION_KIND_FORK_REPLACE): cannot be deployed via config — manual step

동작하지 않을 때: 증상과 원인¶

이 리포지터리의 구성¶

의존하는 것¶

pqcota-common과 pqcota-inventory입니다. discovery에는 의존하지 않습니다.

빌드와 테스트¶

make            # every check of this repository
go test ./...   # unit tests only

go.mod는 replace 지시문으로 형제 리포지터리를 ../에서 읽으므로(../pqcota-common 등) 리포지터리를 나란히 클론하세요. replace 줄은 그대로 둡니다. 리포지터리 사이의 로컬 연결이고, require 줄은 릴리스 태그(현재 v0.10.6)를 가리키며 이 작업 공간 밖의 소비자가 받는 것은 이쪽입니다. 빌드 안내를 보세요.

함께 보기¶

• 실행할 수 있는 최소 예제: examples/provisioning
• 처음부터 끝까지의 데모: demo

기여 · 보안 · 라이선스¶

기여와 보안 신고 방법은 pqcota 리포지터리(영문)에 있습니다.

Copyright 2026 Great Honor randyinthedev@gmail.com. 라이선스는 Apache License 2.0(영문)입니다.