Wiki home › 한국어 문서 · 영어 원문

문서 안내 · 소스 저장소

이 문서는 버전 3 YAML 형식, 피어 프로파일, 프로토콜 설정, 네트워크 조건과 백그라운드 잡을 설명합니다. 대시보드에서 재사용할 YAML을 저장하는 방법은 시나리오 라이브러리를 참고하십시오.

시나리오 형식 버전은 K-P2PLab release 버전과 독립적입니다. 새 시나리오에는 version: 3을 사용하십시오. 이 버전은 mesh-freeze, 모델 기반 topology 형성과 그룹/ID 선택자를 추가합니다. 기존 시나리오의 버전 1과 2도 계속 허용하며 version을 생략하거나 0으로 설정하면 1로 처리합니다. 기존 action의 동작은 유지하고 두 메시 제어 action에는 버전 3이 필요합니다. 알 수 없는 YAML 필드 이름은 거부합니다.

실행 schema와 검증은 internal/scenario/scenario.go, scheduling은 internal/controller/runner.go에 있습니다.

role은 Kademlia bootstrap discovery를 제어합니다. boot 노드는 Controller가 bootstrap peer로 제공하지만 worker 노드는 제공하지 않습니다. Topic transport discovery는 별도이며 동일 run·정확한 topic의 ready PubSub 참가자를 대상으로 합니다. type은 노드의 libp2p, Kademlia, PubSub 동작을 제어합니다. 이 개념들은 서로 독립적이므로 bootstrap 역할을 오용하지 않고 여러 종류의 worker를 한 실험에서 사용할 수 있습니다. type과 profile을 모두 생략하면 role: boot는 boot preset을, 그 밖의 role은 full을 선택합니다.

재사용할 노드 설정은 최상위 profiles 맵에 정의합니다. join phase의 설정 결합 순서는 내장 type, 이름이 지정된 profile, phase 안의 node override 순서입니다. Phase의 type을 생략하면 지정 profile의 type으로 preset을 선택하고, 이것도 없으면 role에 따른 기본값을 사용합니다. profile은 정의된 프로필이나 내장 preset의 이름이어야 하며, type을 명시해도 알 수 없는 이름은 검증에 실패합니다. Pointer 기반 boolean과 숫자 제어값은 명시적인 false와 0도 보존하므로 historyGossip: 0처럼 lazy gossip을 끄는 실험도 표현할 수 있습니다. Legacy flat 숫자 필드에서는 0이 생략을 뜻하므로 명시적으로 0으로 override하려면 중첩 제어값을 사용하십시오.

내장 boot type은 gossipsub.enabled: false를 설정합니다. bootstrap 노드도 PubSub에 참여시킬 때는 profile이나 phase의 node 블록에서 이를 명시적으로 true로 설정하십시오. 활성화한 boot 노드에는 아래에서 설명하는 해당 router에 맞는 parameter, scoring, inspection 옵션을 사용할 수 있습니다. examples/mixed-workers.yaml이 이 opt-in 구성을 보여 줍니다. PubSub가 활성화된 Peer는 시작 직후 동일 run·정확한 topic의 Controller registry를 조회하고 이후 3초 loop로 polling합니다. 각 Peer가 조건에 맞는 전체 후보를 rendezvous hash로 정렬하고 전체 connection budget과 retry backoff 범위에서 현재 topic Peer 수와 DHigh의 차이를 채웁니다. 주기와 대체 후보 동작은 bootstrap과 topic discovery를 참고하십시오. 실제 GRAFT mesh는 GossipSub가 구성하므로 DHT bootstrap, transport 후보, mesh 구성원은 서로 구분됩니다.

version: 2
name: mixed-workers
seed: 42
onExit: cancel
jobShutdownTimeout: 3m

profiles:
  tuned-mesh:
    type: full
    libp2p:
      connectionLimit: 128
      connectionManager:
        lowWater: 64
        highWater: 96
        gracePeriod: 30s
    kademlia:
      mode: server
      protocolPrefix: /k-p2p-lab/v3
      bucketSize: 20
      concurrency: 10
    gossipsub:
      router: gossipsub
      topics: [kpl/default]
      floodPublish: false
      peerExchange: true
      params:
        d: 8
        dLow: 6
        dHigh: 12
        dOut: 3
        dLazy: 8
        heartbeatInterval: 500ms

phases:
  - action: join
    group: tuned
    role: worker
    profile: tuned-mesh
    count: 100
    parallel: true
    parallelism: 16

중첩된 node 설정에서 현재 고정된 버전의 libp2p 패키지가 지원하는 매개변수를 조정할 수 있습니다. 모든 duration 필드는 250ms, 30s, 5m 같은 Go duration 문자열을 사용합니다. 전체 프로토콜 레퍼런스에 mesh·score·PeerGater·filter·validation·discovery·publication·Kademlia의 모든 필드를 정리했습니다. 프로토콜 예제도 참고하십시오.

GossipSub 전용 설정(params, hopwave, meshFreeze, 활성 score/inspection, floodPublish, peerExchange, directPeers, peerGater)은 gossipsub router에서만 적용됩니다. FloodSub와 RandomSub에서는 활성 scoring을 거부하지만 비활성 tuning 블록은 보존할 수 있습니다.

기본 mesh 설정은 D=6, DLow=5, DHigh=12, DScore=4, DOut=2, DLazy=6, history 5/3, gossip factor 0.25, heartbeat 1s입니다. PubSub를 활성화한 boot preset은 DScore=3을 사용합니다. full/worker와 역할별 GossipSub worker preset은 v2에서 가져온 DLow=5, DScore=3, maxIHaveLength=5500, 초기 heartbeat 1s를 상속합니다. 대부분의 worker preset은 v2의 hard connection limit 55도 사용하며 light는 32를 사용합니다. Kademlia의 기본 bucket size는 20, protocol prefix는 /k-p2p-lab/v3입니다. 적용되는 기본값은 internal/model/config.go, 분리된 typed schema는 프로토콜 설정 구현 위치를 참고하십시오.

libp2p.connectionLimit는 전체 연결 수에 적용되는 resource manager hard cap일 뿐이며 soft connection manager를 암묵적으로 생성하지 않습니다. soft low-water/high-water 정리는 libp2p.connectionManager 블록을 명시했을 때만 설치되며 그 블록의 lowWater, highWater, gracePeriod를 사용합니다. 따라서 profile마다 hard cap, soft manager 또는 둘 다를 독립적으로 선택할 수 있습니다.

v2 설정을 이식할 때는 이름과 달리 prefix로 사용됐던 v2 protocol_id를 v3 kademlia.protocolPrefix로 옮기십시오. v3의 kademlia.protocolId는 Kademlia V1 wire protocol ID 전체를 정확히 override하며 protocolPrefix, protocolExtension과 함께 사용할 수 없으므로 v2 prefix 값을 이 필드에 복사하면 안 됩니다. 기본 prefix /k-p2p-lab/v3는 의도적으로 새로 분리한 protocol namespace입니다. v2 namespace 호환이 필요한 실험에서만 protocolPrefix: /k-p2p-lab/kad-dht를 사용하십시오.

RandomSub에서 randomDegree는 libp2p의 process-global RandomSubD를 통해 최소 연결/degree 목표를 설정합니다. KPL은 Peer마다 별도 컨테이너를 사용하므로 이 global 값은 Peer 하나에만 적용됩니다. randomNetworkSize는 NewRandomSub에 별도로 전달되는 추정 전체 네트워크 크기입니다.

스코어링은 기본 비활성입니다. gossipsub.score.enabled: true로만 활성화하며 score 블록이나 관측 주기만으로 켜지지 않습니다. 명시적으로 켜면 scoreInspectInterval의 기본값은 1s이며 0s는 관측을 끕니다. inspection이 실행될 때마다 노드의 peerScores 맵이 갱신됩니다. 이 값은 /api/v1/nodes, /api/v1/network, /api/v1/snapshot, SSE snapshot stream에서 제공되며 topology의 노드를 선택하면 세부 정보에 관측한 score 수와 평균이 표시됩니다.

appSpecificScore는 고정 default와 선택적인 libp2p Peer ID별 peers map으로 P5를 제공합니다. 명시적 Peer 값은 0을 포함하여 기본값보다 우선합니다. 활성 appSpecificWeight가 0이 아니면 이 정책이 필요하며 모든 값과 가중치를 적용한 P5 결과는 유한해야 합니다. 활성 selective validation은 생략한 decay group에 1s/0.01, 생략한 비활성 P1 quantum에 1s를 적용하고 명시적 0 ticker·제수 duration은 거부합니다. Profile에서 inline으로 score를 덮어쓰면 전체 블록을 교체하여 명시적 0·false를 보존합니다. 점수 설정을 참고하십시오.

Profile 또는 join 단계의 node 블록에 network를 추가할 수 있습니다. 기본 scope: p2p는 각 Peer 컨테이너 안에서 포트 20000의 송신 P2P TCP에만 적용합니다. v2처럼 제어 API·telemetry까지 포함한 전체 송신을 제한하려면 scope: all을 지정하십시오. delay는 편도 egress 추가 지연이며 왕복 지연의 목표값이 아닙니다. rateMbps와 tbf.rateMbps는 송신 제한을 설정하고 Bandwidth 측정은 실제 libp2p 스트림 사용량을 별도로 기록합니다.

node:
  network:
    delay: 100ms
    jitter: 10ms
    lossPercent: 1
    duplicatePercent: 0.1
    corruptPercent: 0.1
    reorderPercent: 1
    rateMbps: 10
    queueLimit: 1000

v2 실험을 옮기실 때는 재현 검토와 설정 대응표, churn 예제를 참고하십시오. 여기에는 배치(balanced, 노드별 random, batch별 single-agent, 명시적 agentId), churn을 위한 onError: continue, 정확한 PubSub 데이터 크기를 위한 payloadEncoding: raw, 전체 topic 발행을 위한 topic: '*'를 설명합니다. Network scope와 payload encoding은 기존 기본값을 유지합니다. Worker bootstrap은 seed 기반 첫 연결 성공 선택을 사용하며 transport stack은 TCP/Noise/Yamux로 명시합니다.

네트워크 조건을 적용하는 Peer에는 Linux NET_ADMIN과 호스트 커널의 sch_netem 지원이 필요합니다. Docker 런타임은 version 3 schedule로 네트워크 변경을 받을 join에도 첫 제한 적용 전부터 NET_ADMIN을 부여합니다. 커널 지원이 없거나 tc 명령이 실패하면 노드 시작도 명시적인 오류로 실패합니다.

examples/network-conditions.yaml은 bootstrap 노드 두 개와 네트워크 조건이 적용된 worker 네 개를 생성하고, 초기화 대기와 메시지 발행 후 모든 노드를 종료합니다. 대시보드에서 실행하거나 다음과 같이 제출할 수 있습니다.

control-node:8080은 access가 표시한 Controller 주소로 바꾸고, 먼저 API 인증으로 KPL_COOKIE_JAR를 생성하십시오.

curl -X POST http://control-node:8080/api/v1/experiments \
  -H 'Content-Type: application/yaml' \
  -b "${KPL_COOKIE_JAR:?Log in first}" -H 'X-KPL-Request: dashboard' \
  --data-binary @examples/network-conditions.yaml

version 2와 version 3 모두 profile과 inline node 설정에서 network.schedule을 사용할 수 있습니다. 기존 정적 설정은 초기 조건으로 유지합니다. 현재 실험이 시작된 지 10분 후 delay를 10 ms에서 100 ms로 바꾸고, 15분 후 복원하려면 다음과 같이 작성합니다.

network:
  delay: 10ms
  schedule:
    reference: experiment-start
    changes:
      - after: 10m
        set:
          delay: 100ms
      - after: 15m
        set:
          delay: 10ms

각 Peer마다 별도의 시간을 적용하려면 reference를 peer-join으로 바꿉니다(생략 시 기본값). 다음 예제는 각 Peer가 초기화를 시작할 때 10 ms로 시작하고, 3분 후 100 ms로 변경합니다.

network:
  delay: 10ms
  schedule:
    reference: peer-join
    changes:
      - after: 3m
        set:
          delay: 100ms

delay: 0s, lossPercent: 0, rateMbps: 0처럼 명시적인 값으로 상속한 조건을 해제합니다. 기존 delay에 jitter나 재정렬이 있었다면 delay를 없애는 같은 단계에서 해당 종속 설정도 해제해야 합니다. 새 delay는 기존 delayDistribution을 대체하며 반대도 동일합니다. 분포는 Agent가 Peer별 seed로 확정합니다. 변경 단계에서 새로 명시한 분포만 한 번 추출하며, 이미 추출한 delay를 상속할 때는 다시 뽑지 않습니다.

Profile을 덮어쓰면 schedule 전체를 교체하며 변경 목록을 이어 붙이지 않습니다. 초기 network 설정을 유지하면서 상속한 예약만 없애려면 schedule: {changes: []}를 지정합니다. 초기 조건을 모두 생략하여 제한 없이 시작하고 예약 시점부터 조건을 적용할 수도 있으며, 이 Peer에도 NET_ADMIN을 부여합니다.

실험 기준 예약은 초기 네트워크 조건을 적용하기 전에 Controller와 시계를 동기화합니다. 시작 시각이 없거나 동기화에 실패하면 Peer 시작을 실패 처리합니다. 이후 각 Peer 내부에서 단조 시계 기준 타이머를 실행하므로 Controller polling이나 후속 시계 보정으로 카운트다운이 밀리지 않습니다. OS 스케줄링과 tc 실행에 따른 지연은 생길 수 있으며, 여러 시점을 지나서 타이머가 실행되면 현재 시점의 최신 누적 조건을 적용합니다. scope: all로 telemetry 전달이 지연돼도 이 로컬 타이머는 계속 동작합니다.

Delay만 바꾸면 기존 netem qdisc를 그대로 갱신합니다. 다른 설정을 바꾸면 이전 제한이 남지 않도록 KPL qdisc 구성을 다시 만들며, 이때 대기 패킷이 비워지거나 shaping이 잠시 끊길 수 있습니다. 성공 시 network_config_applied에 적용 조건·revision·지연 시간을 기록하고, 실행 중 tc 오류가 발생하면 network_config_failed를 기록한 뒤 해당 Peer를 실패 처리합니다. 적용 조건과 실제 트래픽 측정값의 차이는 모니터링을 참고하십시오.

타이머는 Peer 종료 시 함께 끝나며 취소·반복 실행 정리에도 동일하게 적용됩니다. 자연스럽게 완료된 단일 Run은 Peer를 유지할 수 있으므로 해당 Peer를 종료할 때까지 예약도 계속됩니다. 원하는 관측 구간까지 시나리오를 실행하고 stop-all로 명시적으로 종료하십시오. 전체 examples/network-schedule.yaml은 두 기준, 조건 복원, 시간차 입장과 종료를 보여 줍니다. 이 문법을 사용하기 전에 Controller·Agent·Peer 이미지를 함께 업데이트하십시오.

권장 시나리오 형식은 version 3 YAML입니다. version 2의 실행 제어, job 추적과 readiness barrier를 유지하며 메시 동결·그래프 형성·런타임 profile schedule을 추가합니다. 기존 줄 단위 .kpl DSL 자체를 직접 읽지는 않으므로 해당 명령을 phase로 변환해야 합니다.

join에서 count는 정확한 생성 작업 수입니다. publish와 leave에서는 조건에 맞는 후보 노드 수로 제한되는 최댓값이며, publish 후보는 PubSub와 발행이 활성화되어 있고 요청한 topic에 참여해야 합니다. repeat는 phase 전체를 반복합니다. 이 세 action에서 parallel은 replica의 순차 또는 동시 실행을 선택하며 parallelism으로 최대 동시 작업 수를 제한할 수 있습니다. await의 기본값은 true입니다. false로 설정하면 job 이름으로 추적되는 background job이 시작되어 churn이나 publish가 진행되는 동안 다음 phase를 실행할 수 있습니다. 이후 wait-jobs에서 이름으로 선택해 기다릴 수 있습니다.

Version 3의 schedule은 선택한 Peer와 같은 Run 세대에서 이후 입장하는 Peer의 유효 profile 설정을 변경합니다. group, profile, type, role, nodeIds, peerIds는 교집합으로 적용하며 group·profile·ID 목록 중 하나 이상이 필요합니다. Profile 선택은 여러 그룹을 선택할 수 있고, group 선택은 같은 profile을 쓰는 다른 그룹에 영향을 주지 않습니다. Profile 원본과 저장 시나리오 YAML은 유지합니다. 명시적 ID는 활성 Peer에 대응해야 하며, group/profile에 현재 Peer가 없어도 이후 입장 설정은 변경합니다. 이미 접수되어 시작 중인 컨테이너도 준비 상태를 확인합니다.

- action: schedule
  group: workers
  profile: baseline
  job: conditions
  await: false
  timeout: 2m
  schedule:
    reference: phase-start
    changes:
      - after: 10s
        set:
          gossipsub: {params: {d: 8}}
          network: {delay: 100ms}
      - after: 30s
        set:
          gossipsub: {params: {d: 6}}
          network: {delay: 10ms}

나열한 런타임 설정을 지원하며 router·topics·heartbeat timer·queue 크기·scoring 등의 생성 설정은 이 액션으로 바꿀 수 없습니다. GossipSub 변경에는 활성 GossipSub가 필요합니다. Degree 조정은 일반 heartbeat를 따르며 이미 동결된 메시 멤버십은 유지합니다. 설정 변경이 즉시 목표 degree 달성을 보장하지는 않습니다. HopWave factor/interval 변경은 기존 활성화 상태를 유지합니다.

Group/profile 선택은 validation에서 현재 세대의 이후 join을 포함한 모든 해당 join과 이 schedule의 누적 설정을 검사합니다. ID 선택은 실제 대상을 runtime에서 검사합니다. 네트워크 변경 대상이 될 수 있는 join에는 초기 제한이 없어도 NET_ADMIN을 자동 준비합니다. 활성 network.schedule이 있는 Peer에는 schedule의 네트워크 패치를 함께 적용할 수 없으며 GossipSub만 바꾸는 경우에는 기존 로컬 네트워크 타이머와 병행할 수 있습니다. Delay만 바꾸면 qdisc 구조를 유지하고 구조적 변경은 기존 netem 교체 동작을 따릅니다.

Controller는 기존 대상 전체를 검사하고 모든 prepare 응답을 받은 다음 같은 준비 값을 적용합니다. 동시 요청은 최대 16개입니다. 이 작업과 신규 입장을 조정하여 이미 접수한 Peer는 대상에 포함하고 이후 입장 Peer에는 성공한 패치를 적용합니다. 개별 요청 한도는 Peer 8초·Agent 10초·Controller 12초입니다. HTTP·OS 스케줄링과 네트워크 조건으로 적용이 늦어질 수 있으며 클러스터 전체의 동시 적용을 보장하지 않습니다. Apply가 시작된 후 실패하거나 응답이 누락되면 일부만 적용됐을 수 있습니다. 액션과 Run은 실패하며 자동 apply 재시도나 분산 롤백은 수행하지 않습니다. 적용 실패 Peer는 후속 profile 변경을 거부합니다. Agent가 네트워크 적용을 확인하지 못하면 다시 관측될 때까지 현재 조건을 pending으로 표시합니다.

stop-all/reset은 schedule 잡을 취소하고 종료를 기다린 뒤 다음 세대의 상속 패치를 비웁니다. 중지·실패·자연 종료의 onExit: cancel은 남은 타이머를 취소합니다. 자연 완료 후 유지되는 Peer는 마지막 적용 설정을 유지하고 Controller 예약 잡은 남지 않습니다. 재시도·이어하기·반복 Run은 원래 profile과 새 예약 상태로 시작합니다. 여러 schedule은 적용 시 직렬화하며 같은 기한에 겹치는 선택자의 순서를 seed로 고정하지 않습니다. 순서가 중요하면 하나의 변경 목록이나 명시적 잡 장벽을 사용합니다.

Controller schedule_change는 요청 패치·revision·단계·응답 수·지연을 보존합니다. Peer profile_config_applied는 확인한 유효 설정을, profile_config_failed는 불완전 적용을 기록합니다. 이는 설정 관측이며 측정 지연이나 메시 수렴을 의미하지 않습니다. 내부 명령 API와 전체 예제를 참고하십시오. Controller·Agent·Peer 이미지를 함께 재빌드·배포해야 합니다.

대상 Peer를 생성할 때 gossipsub.meshFreeze: true를 켜고 준비 확인과 적절한 안정화 대기 뒤에 mesh-freeze를 실행하십시오. 준비 확인만으로 메시 수렴을 보장하지 않습니다. 고정 구성원, 연결 끊김, topic 변경과 계속되는 메시지 트래픽의 의미는 프로토콜 레퍼런스에서 정의합니다.

version: 3
name: fixed-mesh
profiles:
  fixed:
    type: full
    gossipsub:
      meshFreeze: true
phases:
  - action: join
    group: workers
    profile: fixed
    count: 8
    parallel: true
  - action: wait-ready
    group: workers
  - action: wait
    duration: 15s
  - action: mesh-freeze
    group: workers
    timeout: 30s
  - action: stop-all

다음 중 하나 이상의 선택자가 필요합니다.

한 목록의 ID는 OR 조건이고 서로 다른 필드는 교집합입니다. 명시한 모든 ID가 현재 Run·generation의 교집합 안에서 확인되어야 합니다. 알 수 없는 ID, group/type/role 필터 불일치, 중복되거나 빈 ID, 빈 선택 결과는 오류입니다. 그룹 선택에서는 종료되거나 실패한 노드를 제외합니다. 선택된 모든 Peer가 ready 상태이고 meshFreeze: true를 켠 GossipSub를 사용하며 해당 Agent가 online이어야 합니다. 사전 검사가 실패하면 전체 선택 대상에 명령을 보내지 않습니다. 나중에 입장한 Peer는 후속 명령으로 동결하십시오. 앞선 그룹 명령이 미래 구성원에게 적용되지는 않습니다.

Phase는 선택한 모든 Peer의 적용 응답을 기다립니다. timeout은 전체 선택 대상의 전송과 적용 응답을 함께 제한하며 기본 30s, 양수여야 합니다. 각 Agent→Peer 요청과 Peer handler의 제한은 계속 10초이므로 phase timeout을 늘려도 개별 요청의 제한시간은 늘어나지 않습니다. 반복 동결은 멱등이므로 repeat를 허용합니다. 이 action에는 await: false, parallel: true, parallelism, count, interval, lifetime, topic, onError를 지원하지 않습니다. 동시 요청 수를 제한하여 대상을 처리합니다. 전송 시작 뒤 오류나 시간 초과가 발생하면 일부만 동결될 수 있으며, 성공 응답도 여러 Peer의 동시 적용을 뜻하지 않습니다. 동결 해제 action은 없습니다.

examples/scenario-v3-mesh-freeze.yaml은 동결 후 발행까지 보여 줍니다. 실행 중 HTTP 요청 형식은 내부 API 레퍼런스를 참고하십시오.

도메인은 선택한 기존 Peer의 집합입니다. Mesh freeze와 같은 group, nodeIds, peerIds, type, role 교집합 선택자를 사용합니다. 각 대상은 현재 Run·generation에서 ready 상태이며 연결 주소가 있고, GossipSub와 meshFreeze: true를 활성화하며 명시한 topic을 구독하거나 relay해야 합니다. count는 선택적이며 양수이면 선택한 Peer 수가 정확히 일치해야 합니다. Peer를 새로 만들거나 일부를 추출하는 값이 아니므로 앞선 join과 wait-ready로 개체 수를 준비하십시오.

명시적인 ID 없이 그룹으로 선택하면 시나리오 검증은 마지막 stop-all/reset 이후에 조건에 맞는 선행 join이 있는지 확인합니다. 해당하는 모든 join의 preset·profile·개별 override를 결합한 설정에 gossipsub.meshFreeze: true가 있어야 합니다. 생략하거나 false이면 topology phase, 그룹, 문제가 있는 join 이름을 포함한 오류로 검증에 실패합니다. type/role 필터를 반영하고 background join도 검사합니다. 검증 단계에서는 어떤 Peer가 살아남는지 예측하지 않으므로 leave나 lifetime 설정이 있어도 같은 reset 구간의 해당 join을 모두 보수적으로 검사합니다. ID 선택(group과 ID를 함께 지정한 경우 포함)은 실행 시 대상을 확정하고, 모든 선택 Peer를 검사한 뒤 명령을 보냅니다. topology가 이 기능을 자동으로 활성화하지는 않습니다.

선택한 Peer 500개에 Erdős–Rényi 그래프를 만드는 예입니다.

- action: topology
  group: domain-a
  count: 500
  topic: kpl/graph
  timeout: 5m
  topology:
    model: er
    p: 0.05
    seed: 1001

전체 500-Peer 예제는 생성·준비·발행·정리를 포함합니다. Worker와 bootstrap Peer를 수용할 Swarm 용량이 필요합니다. topology가 그래프 설치와 동결을 함께 수행하므로 별도 mesh-freeze phase는 필요하지 않습니다. 이미 동결한 다른 메시는 교체할 수 없으며, 다른 그래프에는 새 Peer 프로세스를 사용합니다.

topology 블록의 모델 키는 아래 소문자이며 표시된 파라미터를 모두 지정해야 합니다. 다른 모델의 파라미터는 거부합니다.

모두 자기 간선과 중복이 없는 단순 무방향 그래프입니다. 연결성은 모델의 결과이며, 분리된 성분을 합치기 위한 간선을 임의로 추가하지 않습니다. Grid·삼각 격자는 열린 경계입니다. 기하 좌표는 간선을 결정하고 계획과 함께 저장하지만 netem 지연이나 Dashboard 배치를 설정하지 않습니다. 확률 모델은 공식 NetworkX의 ER, WS, BA, RGG, Waxman 정의를 따릅니다. KPL 자체 생성기를 사용하므로 다른 라이브러리에 같은 seed를 넣었을 때 간선까지 같다는 뜻은 아닙니다.

대상은 KPL node ID 순으로 정렬합니다. topology.seed는 0을 포함해 명시한 경우 Run seed보다 우선합니다. 같은 순서의 개체 집합·파라미터·seed는 같은 그래프를 재현합니다. 생성 상한은 Peer 10,000개와 무방향 간선 1,000,000개이며, 취소를 확인하고 상한 초과 시 명령 전송 전에 실패합니다. 개별 제어 요청은 1 MiB로 제한합니다.

timeout은 대상 선택·그래프 생성·준비·적용을 합쳐 제한합니다. 생략하면 선택한 Peer 수 N에 따라 2m + 5s × (ceil(N / 16) − 1)로 계산합니다. 16개 이하는 2m, 500개는 4m35s, 1,000개는 7m10s입니다. 양수 timeout을 명시하면 그 값이 그대로 전체 상한이 됩니다. 기존 시나리오의 timeout: 2m도 자동으로 연장하지 않습니다. 선택 인원에 따른 기본값을 사용하려면 필드를 지우고, 그래프와 네트워크에 시간이 더 필요하면 더 긴 값을 지정하십시오.

Peer 명령은 최대 16개를 동시에 실행하며 각 Peer의 동시 연결 시도는 최대 4개입니다. Controller는 일시적인 준비 실패만 같은 전체 제한시간 안에서 같은 생성 계획으로 재시도합니다. 적용은 자동 재시도하지 않습니다. 개별 요청 제한시간과 재시도 조건·간격은 토폴로지 API에 정의합니다.

모든 대상의 준비 응답을 받은 뒤에만 적용을 시작합니다. 각 Peer는 정확한 이웃을 다시 검사하고 한 번의 Router 작업에서 설치와 메시 동결을 수행합니다. 지정 토픽을 교체하며 다른 기존 토픽의 멤버십은 유지한 채 함께 동결합니다. 기존 degree·score·backoff 선택 규칙으로 다른 그래프를 만들지 않습니다. Direct peer, blacklist·filter로 거절한 이웃과 mesh 미지원 프로토콜은 거부합니다.

repeat는 1이어야 하며 background job, parallel, parallelism, 간격·수명 및 onError는 지원하지 않습니다. 준비가 실패하면 생성한 메시를 설치하지 않지만, 준비 중 transport 연결은 생길 수 있고 기존 GossipSub는 계속 동작합니다. 적용은 Peer별로 원자적이므로 네트워크 실패 시 일부만 동결되거나 응답 유실로 성공이 확인되지 않을 수 있습니다. 모든 대상의 정확한 계획 응답이 있어야 phase가 성공합니다. 적용한 계획은 같은 내용으로 재시도할 수 있으며 rollback이나 동결 해제는 없습니다.

이 그래프는 GossipSub 메시를 고정합니다. Transport·DHT 연결, direct·flood 발행과 lazy gossip은 기존 규칙을 따르므로 메시 밖 경로를 사용할 수 있습니다. 그래프와 함께 활성화한 프로토콜을 수용하도록 연결 예산을 설정하십시오. 예제는 추가 연결을 줄이기 위해 Worker의 DHT·topic discovery를 끄고 bootstrap과 기존 lazy 복구를 유지합니다.

저장되는 topology_generated, 노드별 topology_assignment, topology_stage 이벤트에는 생성기 버전·seed·예정 이웃과 응답 수를 보존합니다. Peer의 topology_applied는 로컬 설치를 기록합니다. 예정 간선은 실제 활성 링크의 증거가 아니며 라이브 토폴로지는 계속 활성 메시 멤버를 보고합니다. 전체 이웃 목록은 최근 이벤트 목록에서 제외합니다. 런타임 API를 참고하십시오.

phase 목록이 자연스럽게 끝났을 때 background job을 처리하는 방식은 최상위 onExit으로 결정합니다. 기본값 cancel은 남은 job을 취소한 다음 종료될 때까지 기다립니다. onExit: drain은 job이 자연스럽게 완료될 때까지 기다립니다. 단일 실행의 자연스러운 성공에는 이 job 정책만 적용하며, 명시적인 stop-all phase가 없으면 Peer 컨테이너는 계속 실행됩니다. Dashboard/API에서 repetitions > 1로 제출한 배치는 마지막 iteration을 포함한 매 iteration 종료 때 Peer를 자동으로 fence하고 정리하여 다음 실행과 겹치지 않게 합니다. 이는 YAML phase의 repeat와 별개의 기능입니다.

jobShutdownTimeout의 기본값은 3m입니다. 사용자 또는 API 요청이 scenario를 취소하거나 phase 또는 background job이 실패하면 Controller는 남은 job을 취소하고 이 제한 안에서 종료를 기다린 뒤, 모든 Agent에 현재 generation까지 generation fence를 설정하고 Peer를 정리하도록 요청합니다. 명시적인 stop-all도 같은 제한 시간 내 job 종료를 적용하고 job 추적 상태를 초기화한 뒤 현재 run generation을 fence로 설정합니다. Agent는 일치하는 컨테이너를 종료하기 전에 단조 증가하는 fence를 기록합니다. 따라서 generation N의 늦은 create는 fence보다 먼저 완료되어 cleanup에 포함되거나, generation이 fence 이하이므로 거부됩니다. stop-all이 성공하면 scenario는 generation N+1로 진행하므로 이후 phase에서 같은 run ID로 새 노드를 만들고 job ID도 다시 사용할 수 있습니다.

wait-ready는 실패, 종료 중, 종료된 노드를 포함하여 현재 run generation에서 조건에 맞는 전체 cohort를 검사하며 이전 generation의 노드는 무시합니다. cohort에 실패한 노드가 하나라도 있으면 barrier는 성공하지 않으며, 준비 상태로 보고된 노드도 해당 Agent가 online일 때만 ready 수에 포함됩니다. 이 cohort 역시 지금까지 관측된 노드로만 구성되므로 await: false join 다음의 wait-ready에는 jobs: [job-id] 또는 minCount 중 하나가 필요합니다. jobs는 지정 producer job이 완료된 뒤 readiness를 검사합니다. minCount는 producer를 계속 실행하면서 일부만 생성된 그룹이 준비율을 너무 일찍 만족하지 못하게 합니다.

v2 호환을 위해 interval을 생략한 publish phase에는 특수 기본값을 적용합니다. parallel: true이면 각 작업에 phase 시작 기준 1s offset을 주며, 순차 publish의 delay는 0입니다. 이 규칙은 await 값과 무관합니다.

순차 join, publish, leave는 첫 작업을 즉시 실행하고, 이후 작업은 batch 시작 시각에 앞서 sample된 interval을 누적한 시각에 예약합니다. 요청 처리·접수 대기 시간은 interval 안에 포함되며 매번 추가되지 않습니다. 예약보다 늦어진 작업은 건너뛰지 않고 순서대로 실행하며 원래 일정에 따라잡을 때까지 추가로 쉬지 않습니다. 취소·오류는 여전히 실행을 중단하며 Agent 용량 제한도 적용됩니다. 병렬 join과 leave는 interval을 무시합니다. 병렬 publish는 각 sample interval을 batch 시작 기준의 독립적인 offset으로 사용하고 그 후 동시 실행 slot을 확보합니다. Offset은 누적하지 않으며 동시 실행 용량에 따라 dispatch가 더 늦어질 수 있습니다.

순차 join이 예약보다 1초 이상 늦어지면 Controller는 job 실행별 최대 10초에 한 번 churn join schedule delayed를 기록합니다. 실행 ID, 그룹, 작업 번호, 예약 시각, 지연 시간이 포함됩니다. 지속적인 용량·API 병목을 확인할 수 있지만 과부하 상황의 Docker 시작·ready 시각까지 보장하지는 않습니다. Agent heartbeat는 이벤트 전송과 독립적으로 실행하므로 느린 telemetry 요청이 생존 신호 전송을 막지 않습니다.

wait duration과 readiness/job timeout은 양수여야 합니다. join의 lifetime을 생략하면 자동 leave를 하지 않지만 명시적으로 sample된 0s lifetime은 v2와 같이 새 노드를 즉시 종료합니다.

수명 만료는 컨테이너 생성 성공 직후 기록한 단조 시계를 기준으로 계산합니다. Agent metadata 잠금이나 타이머 goroutine 실행을 기다리는 시간도 sample된 수명에 포함됩니다. 이미 지난 마감은 대기 코드가 실행되는 즉시 종료를 요청하지만, CPU 경합과 cleanup 때문에 실제 제거는 늦어질 수 있습니다. 프로세스 취소 시 타이머를 해제하고, 이미 취소된 프로세스에는 수명 종료를 다시 호출하지 않습니다.

phases:
  - name: background churn
    action: join
    job: churn
    await: false
    parallel: false
    group: churners
    role: worker
    type: light
    count: 100
    interval: {model: exponential, mean: 250ms}
    lifetime: {model: pareto, xm: 45s, alpha: 2.5, max: 3m}

  - action: wait
    duration: 10s

  - action: wait-ready
    group: churners
    jobs: [churn]
    readyRatio: 1
    timeout: 5m

간격과 수명에는 다음 분포를 사용할 수 있습니다. duration 값은 Go duration 문자열을 사용하며 선택적인 min/max duration 범위로 결과를 제한할 수 있습니다. 선택적 분포는 생략하거나 비워 둘 수 있습니다. 매개변수를 입력했다면 model이 필요합니다. 예를 들어 lifetime: {value: 5s}는 잘못된 설정이며 model: fixed를 명시해야 합니다.

0이 아닌 scenario seed는 초기 상태, 조건에 맞는 후보 집합, readiness/job barrier가 같을 때 sample된 delay와 분포 sample, 무작위 선택 및 순서를 재현합니다. Peer identity는 (run ID, 노드별 seed) 조합마다 결정됩니다. 같은 조합은 같은 Peer ID를 만들지만, run ID가 다르면 실행 간 identity 충돌을 막기 위해 의도적으로 다른 Peer ID를 만듭니다. 따라서 같은 scenario seed는 실행 간 sampling과 순서를 재현하지만 run ID가 다르면 Peer ID까지 같아지지는 않습니다. seed: 0은 의도적으로 실행 시각 기반 seed를 선택합니다. 먼저 examples/smoke.yaml을 확인하고, custom profile, 이종 worker type, 제한된 병렬 batch, background paced job은 examples/mixed-workers.yaml을 참고하십시오.

Docker 런타임은 Peer마다 네트워크를 격리하고 노드별 P2P egress 조건을 지원합니다. wait-ready는 Peer 초기화와 API 준비 완료를 확인하며 mesh 수렴을 검증하지 않습니다. 주기적 topic discovery가 churn 중 transport 후보를 보강하지만 GossipSub heartbeat와 GRAFT 처리에는 여전히 수렴 시간이 필요합니다. 필요한 실험에는 별도 안정화 대기 단계를 추가하십시오. scenario seed는 앞서 설명한 조건에서 애플리케이션 sampling과 순서를 재현하지만, 커널의 packet impairment나 네트워크 타이밍까지 동일하게 재현하지는 않습니다. 선택적 HopWave 전달은 호환 빌드와 명시적 활성화가 필요합니다.

Agent는 확인된 종료 이력을 제한된 메모리 캐시에 남기고 오래된 기록은 로컬에 보관하며, 재등록 시 제한된 페이지로 다시 전송합니다. 한도와 복구 규칙은 Agent 이력 보존을 참고하십시오. Controller의 전체 snapshot에는 보존 중인 노드 이력이 계속 포함됩니다. 평상시 부분 heartbeat, discovery, dashboard SSE는 활성 노드와 전송할 변경 사항을 사용하여 전체 이력의 반복 처리를 피합니다. 대규모 parallel phase에는 parallelism을 명시하십시오. 생략하면 여전히 batch 전체의 동시 실행을 허용합니다.