영어로 배우는 Cluster API: KubeVirt 위에 클러스터 찍어 내기

Speak upstream: logs, commits, reviews, release notes

목표

이 코스를 만들며 실제로 찍힌 Cluster API 출력(Machine phase 시간표, 컨트롤러 로그, 적용 경고, 조건 나무)을 영어로 읽어 정리하고, 같은 버그를 두고 커밋 메시지·리뷰 답글·릴리스 노트를 영어로 씁니다.

왜 중요한가

오픈소스 기여에서 코드를 고치는 시간보다 글을 읽고 쓰는 시간이 깁니다. 메인테이너는 재현 가능한 사실을 원하고, 리뷰어는 결론과 근거를 원하고, 사용자는 결과를 원합니다. 같은 사실을 세 독자에게 맞게 다르게 쓰는 연습을 합니다. 채점은 문법이 아니라 필요한 정보가 들어 있는지를 봅니다.

🏓 티티: 이 실습은 VM 없이 가벼운 파드에서 해요. 대신 읽을 거리는 전부 진짜 출력이에요. 문장을 지어내기 전에 출력부터 정확히 읽어 봐요!

단계

/opt/lab/capk_english/machines-timeline.txt 는 매니페스트를 적용한 뒤 10초마다 kubectl get machines 를 찍은 실제 출력입니다. /root/capk-en/phases.json 에 control_plane, worker(각 Machine 이 거친 phase 를 처음 나온 순서대로 담은 목록), control_plane_running_sec, worker_running_sec(각각 처음 Running 으로 찍힌 경과 초, 정수)를 적으세요.
/opt/lab/capk_english/log-lines.txt 의 네 줄을 분류해 /root/capk-en/triage.json 에 적으세요. levels 는 줄 번호(문자열 "1"에서 "4")마다 klog 머리 글자로 정해지는 수준 (info, warning, error 가운데 하나)이고, error_controller 는 오류 줄을 낸 컨트롤러의 이름(controller= 값), error_field 는 그 오류가 가리키는 필드 경로입니다.
/opt/lab/capk_english/apply-output.txt 에는 ... is deprecated; use ... instead 꼴의 경고가 있습니다. 경고가 붙은 종류(kind)마다 옮겨 갈 apiVersion 을 /root/capk-en/deprecations.json 에 {"Kind": "group/version"} 꼴로 적으세요. 경고가 없는 종류는 넣지 않습니다.
/opt/lab/capk_english/describe-cluster.txt 는 워커가 생기지 않던 때의 조건 나무입니다. /root/capk-en/conditions.json 에 cluster_available(Available 조건의 status, 불리언), blocking_condition(Available 을 False 로 만든 하위 조건 이름), control_plane_initialized(불리언), available_worker_replicas(메시지에 적힌 정수)를 적으세요.
버그를 고치는 커밋(워커 KubeadmConfigTemplate 의 nodeRegistration 에 criSocket 을 적는 변경)의 메시지를 /root/capk-en/commit.txt 에 쓰세요. 첫 줄(제목)은 72자 이하, 대문자로 시작하는 명령형 동사(예: Set, Fix, Add)로 시작하고 마침표로 끝내지 않습니다. 둘째 줄은 비우고, 셋째 줄부터 본문에 왜 바꾸는지를 15단어 이상 쓰되 nodeRegistration 과 v1beta2 를 넣으세요.
/opt/lab/capk_english/review-thread.md 의 메인테이너 질문 세 개에 답하는 영어 댓글을 /root/capk-en/reply.md 에 쓰세요. 반드시 들어갈 것: 정확한 CAPK 태그 v0.11.2, lb flavor 를 확인했는지(했다면 결과, 안 했다면 안 했다고: tested, checked, tried 가운데 한 낱말과 함께), 그리고 오류 문구 should have at least 1 properties 를 백틱이나 코드 블록 안에 그대로. 영어로(라틴 문자 90% 이상) 40단어 이상.
고치는 PR 에 붙일 릴리스 노트를 /root/capk-en/release-note.md 에 쓰세요. Kubernetes 계열 저장소의 형식대로 ```release-note 로 여는 코드 블록 하나 안에, 사용자가 알아야 할 변화를 한두 문장(300자 이하)으로 씁니다. KubeadmConfigTemplate 을 넣고, 1인칭(I, we)으로 쓰지 않으며, NONE 이 아니어야 합니다.

참고

읽을 파일은 /opt/lab/capk_english 에 있고(README.txt 에 목록), 답은 /root/capk-en 에 씁니다. review-thread.md 만 지어낸 예이고 나머지는 실측 출력입니다.
판: CAPI v1.14.3, CAPK v0.11.2, 워크로드 쿠버네티스 v1.34.1.
흔한 실수: 오류 메시지를 문법에 맞게 고쳐 옮기는 것. 검색 열쇠가 사라집니다.
흔한 실수: 확인하지 않은 것을 확인한 것처럼 쓰는 것. "I haven't tested X yet" 은 약점이 아니라 정확한 정보입니다.
문서: Kubernetes community: commit message guidelines · Release notes

Read the Machine phases

/opt/lab/capk_english/machines-timeline.txt 는 매니페스트를 적용한 뒤 10초마다 kubectl get machines 를 찍은 실제 출력입니다. /root/capk-en/phases.json 에 control_plane, worker(각 Machine 이 거친 phase 를 처음 나온 순서대로 담은 목록), control_plane_running_sec, worker_running_sec(각각 처음 Running 으로 찍힌 경과 초, 정수)를 적으세요.

같은 phase 가 여러 줄 이어지면 한 번만 셉니다. 워커가 처음에 Pending 에 머문 이유를 생각해 보세요. 컨트롤 플레인이 초기화되기 전에는 워커가 join 할 곳이 없습니다. phase 이름은 대소문자까지 출력 그대로 씁니다.

Triage four log lines

/opt/lab/capk_english/log-lines.txt 의 네 줄을 분류해 /root/capk-en/triage.json 에 적으세요. levels 는 줄 번호(문자열 "1"에서 "4")마다 klog 머리 글자로 정해지는 수준 (info, warning, error 가운데 하나)이고, error_controller 는 오류 줄을 낸 컨트롤러의 이름(controller= 값), error_field 는 그 오류가 가리키는 필드 경로입니다.

Kubernetes 계열 컨트롤러의 로그 줄은 I1026 ... 처럼 한 글자로 시작합니다. I 는 Info, W 는 Warning, E 는 Error 입니다. 메시지 안에 Warning 이라는 낱말이 있어도 머리 글자가 I 면 그 줄의 수준은 info 입니다. 로그를 걸러 볼 때 무엇을 기준으로 삼는지가 이 단계의 요점입니다.

Follow the deprecation warnings

/opt/lab/capk_english/apply-output.txt 에는 ... is deprecated; use ... instead 꼴의 경고가 있습니다. 경고가 붙은 종류(kind)마다 옮겨 갈 apiVersion 을 /root/capk-en/deprecations.json 에 {"Kind": "group/version"} 꼴로 적으세요. 경고가 없는 종류는 넣지 않습니다.

경고 문장은 <옛 group/version> <Kind> is deprecated; use <새 group/version> <Kind> 입니다. use 다음이 옮겨 갈 판입니다. KubevirtCluster 처럼 경고가 붙지 않은 종류는 인프라 프로바이더의 API(v1alpha1)라 이 경고와 관계가 없습니다.

Which condition is blocking?

/opt/lab/capk_english/describe-cluster.txt 는 워커가 생기지 않던 때의 조건 나무입니다. /root/capk-en/conditions.json 에 cluster_available(Available 조건의 status, 불리언), blocking_condition(Available 을 False 로 만든 하위 조건 이름), control_plane_initialized(불리언), available_worker_replicas(메시지에 적힌 정수)를 적으세요.

Cluster 의 Available 은 여러 하위 조건을 요약한 것이고, 메시지의 * 이름: 이 어느 하위 조건 때문인지 알려 줍니다. 같은 나무에서 ControlPlaneInitialized 가 True 라는 것은 '컨트롤 플레인 문제는 아니다' 를 말해 줍니다. 조건을 읽을 때는 False 인 것부터, 그 메시지의 첫 별표부터 봅니다.

Write the commit message

버그를 고치는 커밋(워커 KubeadmConfigTemplate 의 nodeRegistration 에 criSocket 을 적는 변경)의 메시지를 /root/capk-en/commit.txt 에 쓰세요. 첫 줄(제목)은 72자 이하, 대문자로 시작하는 명령형 동사(예: Set, Fix, Add)로 시작하고 마침표로 끝내지 않습니다. 둘째 줄은 비우고, 셋째 줄부터 본문에 왜 바꾸는지를 15단어 이상 쓰되 nodeRegistration 과 v1beta2 를 넣으세요.

제목은 '이 커밋을 적용하면 무엇을 하는가' 를 명령형으로 씁니다(If applied, this commit will ...). Fixed·Fixing·Fixes 는 명령형이 아닙니다. 본문은 무엇보다 왜를 씁니다. 코드 diff 가 무엇을 바꿨는지는 이미 보여 주기 때문입니다. 블로그 「오늘의 영어 표현」의 「Fixes #123」 편(/blog/english-daily-07-fixes-issue-keyword)이 이슈와 커밋을 잇는 법을 다룹니다.

Answer the reviewer

/opt/lab/capk_english/review-thread.md 의 메인테이너 질문 세 개에 답하는 영어 댓글을 /root/capk-en/reply.md 에 쓰세요. 반드시 들어갈 것: 정확한 CAPK 태그 v0.11.2, lb flavor 를 확인했는지(했다면 결과, 안 했다면 안 했다고: tested, checked, tried 가운데 한 낱말과 함께), 그리고 오류 문구 should have at least 1 properties 를 백틱이나 코드 블록 안에 그대로. 영어로(라틴 문자 90% 이상) 40단어 이상.

질문이 번호로 왔으면 번호로 답하는 것이 읽기 쉽습니다. 확인하지 않은 것은 확인하지 않았다고 쓰는 것이 가장 도움이 됩니다(I haven't tested ... yet). 오류는 고치거나 줄이지 말고 코드 형식으로 붙입니다. 블로그 「오늘의 영어 표현」의 「As far as I can tell」 편(/blog/english-daily-04-as-far-as-i-can-tell)이 확신의 정도를 말하는 표현을 다룹니다.

Write the release note

고치는 PR 에 붙일 릴리스 노트를 /root/capk-en/release-note.md 에 쓰세요. Kubernetes 계열 저장소의 형식대로 ```release-note 로 여는 코드 블록 하나 안에, 사용자가 알아야 할 변화를 한두 문장(300자 이하)으로 씁니다. KubeadmConfigTemplate 을 넣고, 1인칭(I, we)으로 쓰지 않으며, NONE 이 아니어야 합니다.

릴리스 노트는 코드를 보지 않는 사용자가 읽습니다. '무엇이 고쳐져서 이제 무엇이 된다' 를 결과 중심으로 씁니다. 사용자에게 보이는 변화가 없는 PR 이면 NONE 을 적지만, 이 버그는 사용자가 겪은 것이라 적어야 합니다. 블로그 「오늘의 영어 표현」의 「Backport」 편(/blog/english-daily-30-backport)이 고친 것을 옛 판에 옮기는 이야기를 다룹니다.