2년 전에 사용 중단된 spec.running 을 문서가 아직 첫 줄에 쓸 때: KubeVirt 사용자 가이드 PR 이 열흘 만에 병합되기까지

결과: 병합 (2026-10-27 00:04, kubevirt/user-guide#1040). 사실은 GitHub 의 PR·리뷰·댓글·타임라인·검사 기록과 관련 이슈·PR, 사용자 가이드 소스(PR 의 바탕 커밋 0ca33477), KubeVirt 소스(태그 v1.9.0), 기여 원장의 초안, TT Lab 저장소의 VM 생성 코드에서 가져왔습니다. 시각은 한국 시간입니다.

목차

• 한 줄 요약
• 1. 무엇이 문제였나: 경고는 나오는데 문서는 조용하다
• 2. 원인: 문서의 어느 줄인가
  • Run Strategies 페이지
  • 아키텍처 페이지
• 3. 무엇을 바꿨나: diff 요지
• 4. 반응: approve 는 1시간 37분, lgtm 은 9일
• 5. 배운 것: 오픈소스 기여 요령
• 링크

한 줄 요약

1. 무엇이 문제였나: 경고는 나오는데 문서는 조용하다

KubeVirt 의 VirtualMachine 은 VM 을 켤지 말지를 예전에는 참/거짓 필드 spec.running 으로, 지금은 spec.runStrategy(Always·Halted·Manual· RerunOnFailure 등)로 정합니다. spec.running 은 kubevirt/kubevirt#12578(2024-09-30 병합)에서 사용 중단으로 표시되었고, 사용자 가이드의 v1.4.0 릴리스 노트 「Deprecation」 에도 실렸습니다.

API 는 이것을 분명히 말합니다. PR 본문에 적은, v1.9.0 클러스터에서 확인한 내용입니다.

• kubectl explain vm.spec.running 은 Deprecated: VirtualMachineInstance field "Running" is now deprecated, please use RunStrategy instead. 를 보여 줍니다.
• virtualmachine-validator.kubevirt.io 웹훅이 VM 의 생성·수정에 걸려 있고, spec.running 이 있으면 경고 spec.running is deprecated, please use spec.runStrategy instead. 를 돌려줍니다 (vms-admitter.go 175–178행).

kubectl explain 의 출력은 PR 본문에만 있고, 원장에 출력 원본 파일은 남기지 않았습니다.

그런데 사용자 가이드의 Run Strategies 페이지는 첫 문장이 「VirtualMachine 에는 guest 를 돌릴지 정하는 Running 설정이 있다」였고, 사용 중단을 한 번도 말하지 않았습니다. runStrategy 를 찾아 그 페이지에 온 사람도 첫 문단에서 running: true 를 배우고 돌아가게 됩니다.

TT Lab 에도 같은 모습이 있습니다. 수강생 VM 을 만드는 코드(TT Lab 저장소 backend/app/vms.py)는 지금도 매니페스트에 "running": True 를 넣고, 실행 여부도 그 필드로 읽습니다. 바로 위 주석에는 「running 은 deprecated 다, runStrategy 로 옮기는 편이 맞지만 지금 도는 VM 과 동작을 맞추려고 그대로 둔다」 고 적혀 있습니다. 기여 원장에도 「TT Lab 이 사용 중단된 필드로 학생 VM 을 만들고 읽는다, 이 PR 과 같은 주제」라고 적혀 있고, 옮기는 작업은 별도로 띄워 두었습니다. 2026-10-29 현재 아직 옮기지 못했습니다. 남의 문서를 고치는 동안 우리 코드도 같은 빚을 지고 있다는 것을 솔직히 적어 둡니다.

2. 원인: 문서의 어느 줄인가

줄 번호는 PR 의 바탕 커밋 0ca33477 기준입니다.

Run Strategies 페이지

• docs/compute/run_strategies.md 5–12행: Running 설정을 먼저 소개하고, 그것만으로는 부족한 경우를 설명한 뒤 RunStrategy 로 넘어갑니다. 사용 중단 이야기는 없습니다.
• 47행: associated ith the VM 오타.

아키텍처 페이지

• 이 페이지의 예제 VM 은 #849(2024-10-30 병합, 「spec.running 참조를 runStrategy 로」)에서 runStrategy: Halted 로 바뀌었습니다. 그런데 둘레의 문장 셋은 그대로였습니다. 195–197행(「spec.running 이 true 이면 다시 만든다」), 357행(「spec.running 이 false 라 vmi 가 안 생긴다」), 388행(kubectl describe 출력의 Running: true).
• 367행 은 virtctl start vm vm-cirros 입니다. virtctl start 는 VM 이름 하나만 받습니다(start.go 46–49행, v1.9.0).
• Halted 인 VM 을 virtctl start 하면 runStrategy 가 Always 로 바뀝니다(lifecycle.go 632–649행, v1.9.0). 그래서 시작한 뒤의 describe 출력은 Run Strategy: Always 여야 맞습니다.

이 사용 중단을 고치려는 시도가 전에도 있었습니다. 이슈 #923(2025-09-15)은 VM 수명 주기와 RunStrategy 문서를 고치자고 했고, PR #927(2025-09-17)은 사용 중단 표기를 관계없는 tolerations 변경과 함께 담았습니다. 둘 다 리뷰 없이 봇에 의해 비활성으로 닫혔습니다(2026-02-14, 2026-03-22).

3. 무엇을 바꿨나: diff 요지

 # docs/compute/run_strategies.md, Overview
-VirtualMachines have a `Running` setting that determines whether or not
-there should be a guest running or not. ...
+VirtualMachines have a `spec.runStrategy` field that determines whether
+or not there should be a guest running, and what KubeVirt should do when
+the guest stops.
+
+Older manifests use the boolean `spec.running` field instead. ... (기존 설명은 이 문단으로 옮김)
+
+!!! warning
+    `spec.running` is deprecated since KubeVirt v1.4.0. Use
+    `spec.runStrategy` instead: `spec.running: true` corresponds to
+    `runStrategy: Always`, and `spec.running: false` corresponds to
+    `runStrategy: Halted`. The API server still accepts `spec.running`,
+    but returns the warning ... when a VirtualMachine that sets it is created or updated.
-    associated ith the VM.
+    associated with the VM.

 # docs/architecture/architecture.md
-If a VirtualMachineInstance reaches a final state but the `spec.running`
-equals `true`, ...
+If a VirtualMachineInstance reaches a final state but the
+`spec.runStrategy` equals `Always`, ...
-Since `spec.running` is set to `false`, no vmi will be created:
+Since `spec.runStrategy` is set to `Halted`, no vmi will be created:
-$ virtctl start vm vm-cirros
+$ virtctl start vm-cirros
-  Running:  true
+  Run Strategy:  Always

설명을 지우지는 않았습니다. 「참/거짓 하나로는 guest 안에서 끄는 경우를 표현하지 못한다」는 기존 설명은 runStrategy 가 왜 생겼는지 알려 주는 좋은 문단이라 「옛 매니페스트는 spec.running 을 쓴다」 뒤로 옮겼습니다. 그리고 새로 쓰는 사람이 처음 만나는 문장을 runStrategy 로 바꾸고, 옛 필드에서 새 필드로 옮기는 대응표(true → Always, false → Halted)와 API 서버가 내는 경고 문구를 경고 상자에 넣었습니다. 경고 문구를 그대로 적은 것은 검색으로 이 페이지를 찾게 하려는 뜻입니다.

PR 본문 끝에는 #923·#927 이 같은 주제를 다뤘지만 리뷰 전에 닫혔고, 이 PR 은 사용 중단만 다룬다고 적었습니다. AI 사용은 커밋 꼬리말 Co-Authored-By: Claude Opus 5.5 와 Signed-off-by, 본문 끝의 「AI 의 도움으로 초안을 쓰고 내가 검토했다」 한 문장으로 밝혔습니다. KubeVirt 의 AI 기여 정책이 받아들이는 꼴입니다. 커밋에는 SSH 서명이 붙어 있습니다. 문서 빌드(mkdocs)는 로컬에서 돌리지 않았고, 병합 전에 Netlify 미리보기가 만들어졌습니다.

4. 반응: approve 는 1시간 37분, lgtm 은 9일

이 저장소에는 PR 마다 도는 시험 잡이 없어서, needs-ok-to-test 라벨이 끝까지 붙어 있었지만 병합에는 상관이 없었습니다(원장 기록). 남은 검사는 DCO, Netlify 미리보기, tide 셋이었습니다. 필요한 것은 사람의 /approve 와 /lgtm 둘뿐이었고, 첫째는 바로 왔습니다.

둘째가 오지 않은 9일 동안 우리는 원장에 「10/26 무렵 조용하면 /cc 하자」고 날짜를 적어 두고 기다렸습니다. 그날 한 번 부탁했고, 6시간 35분 뒤 /lgtm 이 왔습니다.

나중에 보니 /lgtm 을 준 메인테이너는 1년 전 이슈 #923 을 연 사람이었습니다. 같은 문제를 알고 있었고 누군가 고쳐 주기를 기다리던 사람에게 PR 이 닿은 것으로 보입니다. PR 본문에 #923 을 적어 둔 것도 그 연결을 쉽게 한 것으로 보입니다.

5. 배운 것: 오픈소스 기여 요령

• 「사용 중단은 API 가 말하는 것을 문서가 따라 말하게 합니다.」 kubectl explain 과 웹훅 경고가 이미 같은 말을 하고 있었습니다. 그 문구를 문서에 그대로 옮기면 사용자가 경고를 검색해 문서에 닿고, 메인테이너는 문구가 맞는지 따로 확인할 필요가 없습니다.
• 「예제를 고친 PR 은 둘레 문장까지 봅니다.」 #849 는 예제의 YAML 만 바꾸고 그 YAML 을 설명하는 문장은 두었습니다. 코드 블록과 그 앞뒤 문장은 한 덩어리로 읽어야 어긋남이 보입니다. 같은 자리의 virtctl 명령도 그렇게 해서 찾았습니다.
• 「앞선 시도를 찾아 범위를 좁힙니다.」 #927 은 관계없는 변경과 묶여 리뷰를 받지 못했습니다. 이번 PR 은 사용 중단 하나만 다룬다고 본문에 밝혔습니다. 앞선 이슈를 본문에 걸어 두면, 그 이슈를 기억하는 사람에게 알림이 갈 수도 있습니다.
• 「고친 것을 우리 코드에도 적용합니다.」 TT Lab 의 VM 생성 코드는 아직 spec.running 을 씁니다. 업스트림 문서를 고친 것과 별개로, 우리 코드를 runStrategy 로 옮기는 것이 남은 숙제입니다.

티티 한마디. 놀이터 안내판 첫 줄에 「그네는 빨간 단추로 켜요」라고 적혀 있었어요. 그런데 빨간 단추를 누르면 「이 단추는 곧 없어져요, 파란 손잡이를 쓰세요」 하는 소리가 나요. 2년째요! 안내판 첫 줄을 파란 손잡이로 바꾸고, 빨간 단추 이야기는 「예전에는」 칸으로 옮겼어요. 아홉 밤을 기다렸더니 1년 전에 「안내판 좀 고쳐 주세요」 쪽지를 썼던 선생님이 오셔서 「어서 와!」 하고 도장을 찍어 주셨어요. 그런데 우리 놀이터 그네도 아직 빨간 단추로 켜고 있어요. 이건 곧 고칠게요.

링크

모든 자료는 2026-10-29 에 열람했습니다.

• PR: kubevirt/user-guide#1040 (병합 커밋 a30126d0)
• 고친 문서(바탕 커밋): run_strategies.md, architecture.md
• KubeVirt 소스(v1.9.0): vms-admitter.go, start.go, lifecycle.go
• 사용 중단: kubevirt/kubevirt#12578
• 앞선 시도: 이슈 #923, PR #927, 예제를 바꾼 #849