나의 첫 오픈소스 기여 경험: Kubetail kubectl 플러그인 이슈 해결기
저의 첫 오픈소스 기여 여정을 기록합니다. Kubetail 프로젝트의 Issue #687을 해결하면서 겪은 시행착오와 배운 점들을 공유합니다.
🔍 오픈 소스 탐색
다들 누구나 처음 오픈소스 기여할 때 막막함을 느낄 것이다. 이때 추천할만한 사이트가 있다.
해결하기 쉬운 이슈에는 “good first issue” 라벨이 종종 붙는데, 첫 오픈소스 기여를 하고자 하는 이들을 위해 이 라벨이 붙은 이슈만 아카이빙하는 사이트들도 있다. 이 사이트들을 이용하면 빠르게 난이도가 낮은 이슈를 찾을 수 있다. 하지만 동시에 많은 이들이 빠르게 이 이슈에 접근하기 용이하기 때문에, 이슈에 대한 경쟁률(?)이 높기도 하다.
따라서 첫 기여를 하기에 맛있게 생긴 이슈에 대해서는 어느 정도는 빠르게 캐치하는 것도 중요하다고 할 수 있을 것 같다.
나는 위 사이트를 이용하여 이슈들을 둘러보았다. 사이트에선 3일 내의 이슈만 아카이빙 하기 때문에 아직 할당되지 않은 이슈를 찾기에 좋았다.
💡 Tip
가벼운 마음으로 시작하면 좋을 것 같다.
“나는 꼭 이 이슈를 해결할거야” 혹은 “이 오픈소스에 꼭 기여할거야” 같은 생각보다는 가볍게 본인이 관심있는 프로젝트 위주로 여러 이슈를 둘러보며, 어떤 문제들이 있는지 그리고 사람들은 어떻게 그 문제들을 해결하는지 이런 것들을 둘러보다 보면 본인이 흥미를 느끼고 해결할 수 있을 것 같은 이슈가 분명 보일 것이다.
나는 그렇게 2시간 정도 이슈를 둘러보다가 kubetail이라는 오픈소스의 한 이슈를 읽어보았다.
📋 배경 파악
kubetail은 웹 대시보드를 통해 쿠버네티스에서 생성되는 실시간 로그를 확인할 수 있는 편의성을 제공하는 도구인데 이슈를 살펴보니 최근에 쿠버네티스의 플러그인 저장소인 krew에 추가가 되었고 이 과정에서 krew의 관리자가 krew를 통해 플러그인으로 실행될 때, 나오는 CLI 가이드를 변경해달라는 요청이 있었다.
이에 따라 생성된 이슈였던 것이고, 충분히 나도 어렵지 않게 해결할 수 있을 것이라는 생각이 들어 관리자에게 방향성을 물어보며 이슈 할당을 요청했다.
💡 Tip: 관리자는 이 프로젝트에 대해 훨씬 깊은 이해도를 갖고 있기 때문에, 관리자에게 방향성을 요청하는 것을 매우 추천👍
감사하게도 이슈를 할당해줌과 동시에 방향성을 제시해주었다.
🛠️ 문제 해결 과정
이 이슈는 꽤 간단한 문제다. kubetail이 krew로 실행될 때를 감지하여 이때 기존의 help 가이드 앞에 kubectl을 추가해주면 된다.
핵심 포인트
어떻게 krew로 실행되는 것을 감지할지인데 관리자에게 힌트를 얻어 명령어의 첫 번째 인자에 따라 구분하는 방향으로 구현하기로 했다.
처음엔 간단하게 명령어 인자를 비교하여 kubectl로 시작 시에 분기하여 안내하는 것으로 코드를 작성하였는데, 막상 코드를 작성하고 직접 CLI로 테스트를 해보니 첫 번째 명령어인 kubectl만 나오고 뒤의 인자인 kubetail이 나오지 않았다.
따라서 기존에 CLI를 만드는 도구인 cobra의 사용법에 대해서 좀 더 찾아보다 보니 같은 이슈를 찾을 수 있었다.
해결 방법
이미 해결된 이슈로, 플러그인처럼 공백이 포함된 명령어 이름을 사용하는 도구에서 표시되는 명령어는 CommandDisplayNameAnnotation를 통해 따로 지정할 수 있었다.
DisplayName 설정 시 CommandPath 내부에서 지정된 값을 help 텍스트에 반영하는 것이다.
1
2
3
4
5
6
rootCmd := &cobra.Command{
Use: "Plugin",
Annotations: map[string]string{
cobra.CommandDisplayNameAnnotation: "kubectl plugin",
},
}
root.go와 logs.go 파일에 이 패턴을 적용하여 동적으로 메시지를 나타낼 수 있게 하여 작업을 마무리하였고, 제대로 명령어가 나오는지 테스트까지 완료했다.
궁금증 해소
이쯤에서 ‘테스트 코드도 따로 작성해야 하나?’, ‘커밋 메시지는 어떻게 작성하지?’ 등 궁금한 점이 생겨 관리자에게 직접 문의하기로 했다.
아까 관리자가 처음에 알려준 디스코드 채널방에 들어가서 여러 가지 궁금한 점들을 물어보았고, 이에 대해서 또 친절하게 답변해주었다.
브랜치 이름에 대해서는 따로 규칙은 없었고, 내 경우엔 간단한 이슈였기 때문에 테스트도 코드를 작성하기보단 명령어를 한번 실행해보는 정도면 충분하다고 했다. PR과 Commit은 지정된 템플릿이 있었으며 그에 따른 가이드 페이지도 .github 내부에 존재했었다.
여담
내가 가이드에 대한 질문을 올려서일까? CONTRIBUTING 가이드에 대한 이슈가 하나 새로 생겼다.
📝 PR 작성 및 피드백
PR은 템플릿이 존재하여 이에 맞추어 작성하면 됐기 때문에 어렵지 않았다. 템플릿에서 작성한 정보 이외에도 내가 마주한 이슈에 대해서도 공유하고 싶어서 <details> 태그로 구현 노트를 추가하여 cobra 이슈에 대해서 짧게 작성하였다.
이후 몇 시간 만에 관리자의 코멘트가 달렸다. 수천 킬로미터나 떨어져 있는 사람과의 피드백을 받는다는 느낌이 들어 뭔가 신기하고 재밌었다.
관리자의 피드백은 모두 타당한 것들이었고
- 함수 일관성 있는 네이밍
- 더 가독성 좋은 함수 제시
- 함수의 용이성 의문 제시
이에 대해 코멘트하고 모두 반영하여 다시 커밋하고 코멘트를 남겼다.
얼마 지나지 않아 관리자가 이를 승인하여 코드가 반영이 되었고 첫 오픈 소스 기여를 성공적으로 마치게 됐다. 🎊
💭 느낀점
오픈 소스를 기여하면서 내가 얻은 것은 무엇인지를 생각해보았다.
먼저 아주 특별한 기능은 아니지만 수천, 수만 명의 사람들이 도구를 사용하면서 많이 보게 될 명령어 가이드에 나의 코드가 반영이 되었다는 사실 자체가 기분이 좋다. 이것만으로도 충분히 나에게 많은 영감을 주었다.
배운점
물론 이와는 별개로 또 배워가는 것들도 많았다.
krew: 쿠버네티스 플러그인 패키지 매니저
kubectl플러그인들을brew처럼 관리한다.- 생각보다 많은 플러그인들이 존재한다 (100+개)
kubectl 플러그인 구조: kubectl-* 네이밍만으로 플러그인이 된다
- PATH에 있는
kubectl-myplugin바이너리를kubectl myplugin으로 실행 가능하다.
cobra 라이브러리: kubectl, kubetail, stern 모두 같은 CLI 프레임워크 사용
CommandDisplayNameAnnotation처럼 플러그인 특화 기능까지 지원한다.- Go 생태계에서 CLI 도구 개발의 사실상 표준
비슷한 도구(로그 조회)들의 공존: stern, kubetail (bash), kubetail (2024 웹)
- 터미널 vs 웹, 단순함 vs 풍부한 기능
- 왜 여러 도구가 공존하는지 이해하게 됐다 (사용자의 워크플로우가 다르기 때문)
이외에도 여러가지 배운점이 많으며, 앞으로도 이 kubetail 프로젝트에 좀 더 기여하고자 하는 마음이 생겼다. 첫번째는 오픈소스의 재미, 두번째는 비전에 대한 공감? 세번째는 관리자의 열정에 대한 영감?(정말 열심히 활동하신다..) 정도가 이유인듯 하다.
kubetail에 대해 좀 더 이해도를 높이고 다음에는 좀 더 깊이있는 이슈를 다루는 글을 남겨봐도 좋을 것 같다.
읽어주셔서 감사합니다.