[Argo CD 오픈소스 기여] CLI help에 뜨는 kubectl REST 플래그가 실제로는 동작하지 않는 문제 (#25875)

대외활동/오픈소스 기여

[Argo CD 오픈소스 기여] CLI help에 뜨는 kubectl REST 플래그가 실제로는 동작하지 않는 문제 (#25875)

rngPwns 2026. 1. 25. 20:26

1. Argo CD를 첫 오픈소스 기여 프로젝트로 선택한 이유

클라우드 엔지니어를 목표로 준비하면서 토이 프로젝트나 개인 실습보다 실제 운영 환경에서 쓰이는 오픈소스에 직접 기여해보는 경험이 중요하다고 느꼈다. 그 기준에서 Argo CD는 꽤 매력적인 프로젝트였다.

Kubernetes 기반 GitOps 도구로 실무 사용 빈도가 높고
CLI / Server / Controller / UI 역할이 비교적 명확히 분리돼 있어 코드 흐름을 추적하기 쉬우며
이슈와 PR에 메인테이너 피드백이 꾸준히 달려 초보 기여자도 접근 가능한 편이다

그래서 Argo CD 이슈 중에서도 재현이 명확하고 영향 범위가 분명한 CLI 관련 이슈를 중심으로 살펴보게 됐다.

2. 선택한 이슈: CLI help에는 보이지만 실제로는 동작하지 않는 플래그

Issue: CLI shows kubectl REST flags (e.g. --disable-compression) that are not supported
Issue #25875

문제는 간단했다.

Argo CD CLI에서 -h 또는 --help를 보면 kubectl의 REST 관련 플래그들이 노출되지만, 실제로 해당 플래그를 사용하면 실행 단계에서 에러가 발생한다.

예를 들면,

argocd cluster -h

help 출력에는 다음과 같은 플래그가 보인다.

--disable-compression
--client-certificate
--client-key

하지만 실제로 실행하면,

argocd cluster --disable-compression list

결과는 unknown flag 에러다.

지원하지 않으면서 help에는 노출되는 플래그였고, CLI 사용자 입장에서는 꽤 혼란스러운 UX였다.

3. 원인 분석: 플래그 하나의 문제가 아니다.

처음에는 단순히 플래그 등록이 빠진 건가? 정도로 생각했다.

하지만 이슈 댓글과 코드를 같이 따라가다 보니,

이건 특정 플래그 하나의 문제가 아니라 CLI 초기화 구조에서 발생한 정합성 문제라는 걸 알게 됐다.

4. 구조 이해의 출발점: 다른 기여자의 분석

이 이슈에서 중요한 힌트를 준 건 기여자 kwentine의 코멘트였다.

요지는 다음과 같았다.

Argo CD CLI는 일부 커맨드에서 kubectl의 persistent flags를 초기화 과정에서 복사한다
하지만 모든 커맨드가 동일한 초기화 경로를 거치지는 않는다

다만 이 코멘트를 그대로 해답으로 쓰지는 않았다.

이 코멘트를 출발점으로 삼아,

실제 코드가 어디에 있는지
어떤 커맨드가 이 초기화 경로를 타는지
help 출력과 실행 경로가 어디서 갈라지는지

를 직접 코드로 확인했다.

5. 실제 문제 지점: InitCommand

문제의 코드는 다음 파일에 있었다.

cmd/argocd/commands/initialize/cmd.go

여기서는 kubectl의 persistent flags를 가져와
Argo CD 커맨드의 flags로 그대로 복사한다.

flags.VisitAll(func(flag *pflag.Flag) {
    if flag.Name == "server" {
        return
    }
    cmd.Flags().AddFlag(flag)
})

이 구조 때문에,

kubectl에는 있지만 Argo CD에서는 실제로 처리하지 않는 REST 플래그들이 help 출력에는 노출되는 상황이 발생했다.

6. 문제 정리

이 문제는 단순히 플래그 하나가 빠졌다가 아니라,

커맨드마다 초기화 경로가 다르고
help 단계에서는 kubectl 플래그를 일괄 노출하지만
실행 단계에서는 처리하지 못하는 플래그가 존재하는

CLI 초기화 흐름의 정합성 문제라고 판단했다.

7. 해결 전략: 범위를 의도적으로 제한하기

해결 방향에는 두 가지 선택지가 있었다.

모든 서브커맨드별로
이 플래그가 실제로 지원되는지를 판단하도록 구조를 리팩터링
InitCommand를 통해 복사되는 kubectl REST 플래그 중 명백히 지원되지 않는 것만 help에서 숨기기

1번이 더 이상적인 설계일 수는 있지만,

변경 범위가 커지고
CLI 전반에 영향을 주며
리뷰 부담이 커지고
첫 기여로는 리스크가 크다고 판단했다

그래서 이번 PR에서는 기존 구조는 유지한 채,

InitCommand 기반 커맨드에서
실제로 지원하지 않는 kubectl REST 플래그만 명시적으로 제외한다

라는 전략을 택했다.

8. PR 과정

https://github.com/argoproj/argo-cd/pull/25977

이 PR은 혼자 코드 고쳐서 끝나는 작업이 아니었다.
여러 기여자와 메인테이너가 각자 다른 관점에서 피드백을 주고, 그걸 반영하면서 점점 다듬어지는 과정이었다.

PR에서는 다음을 명확히 했다.

변경 범위를 InitCommand 기반 커맨드로 제한
unsupported kubectl REST 플래그만 명시적으로 필터링
UX 문제 해결이 목적임을 명확히 설명

리뷰 피드백 ①: Unit test 추가

Is it possible to add some unit tests?

단순한 필터링 로직이었지만, 회귀 방지 측면에서 테스트를 추가하는 게 맞다고 판단했다.

unsupported kubectl REST 플래그가 실제로 제거되는지 검증하는 테스트 추가

테스트 추가 이후, 리뷰어에게서 명확한 승인(LGTM)을 받을 수 있었다.

리뷰 피드백 ②: 테스트 누락 지적

certificate-authority 플래그 검증이 빠져 있다

단순 누락이었고, 모든 unsupported 플래그를 테스트에 포함하도록 수정했다.

9. 최종 수정 코드

10. 트러블슈팅 – 실제로 막혔던 지점들

가장 오래 걸린 건 CI였다. 문제는 로직이 아니라 생성 코드 검증 단계였다.

Argo CD는 CLI help 문서를 자동 생성된 결과물로 관리한다.
CI에서는 다음을 검사한다.

CLI 동작을 바꿨다면, 자동 생성되는 문서도 함께 업데이트됐는가?

처음에는 코드만 수정하고 docs/user-guide/commands/* 문서를 갱신하지 않아 CI가 실패했다.

이 경험을 통해,

오픈소스에서는 코드뿐 아니라 생성물까지 책임져야 한다는 걸 배웠다.

리뷰 피드백 ③: 구조적 질문 - 미해결

가장 인상 깊었던 질문은 이 부분이었다.

-tls-server-name 플래그는 argocd app에는 없고 argocd admin notifications에는 있다
- 그렇다면 플래그 관리를 초기화 경로 기준이 아니라
  서브커맨드별 실제 지원 여부 기준으로 해야 하는 것 아니냐?

여기서 핵심은 이 PR의 목적이었다.

이 PR은

unknown flag 에러를 없애는 것이 아니라
지원되지 않는 kubectl REST 플래그가 help에 노출되는 문제를 해결하는 것

서브커맨드별 실제 플래그 지원 여부를 추적하려면 플래그 정의 구조 전반을 재설계해야 하고,
이는 이번 PR의 범위를 명확히 초과한다고 판단했다.

그래서

InitCommand를 사용하는 커맨드 트리에 한정된 수정임을 설명했고
admin 계열은 의도적으로 범위 밖임을 명확히 했다.

11. 기여하면서 배운 점

DCO(Sign-off)
단순히 코드만 맞는 게 아니라, 기여자의 책임과 출처를 명확히 남기는 절차라는 걸 처음으로 체감했다.
리뷰는 개인이 아니라 팀의 작업
PR 하나가 여러 리뷰어를 거치며 점점 단단해지는 구조라는 점이 인상적이었다.
작은 PR이 왜 중요한지
변경 범위를 명확히 제한해야 리뷰도, 머지도 가능하다는 걸 배웠다.
오픈소스가 안정적으로 유지되는 이유
개인의 실력보다 프로세스가 실수를 걸러내도록 설계돼 있다는 걸 느꼈다.

12. 첫 후원도 진행 🤩

이번 기여는 단순한 CLI 버그 수정이었지만,

코드 구조를 이해하고
리뷰를 통해 설계 범위를 조율하고
테스트와 CI까지 책임지는

오픈소스 기여의 전체 흐름을 경험할 수 있었다.

이 과정에서 가장 많은 도움과 명확한 피드백을 준 nitishfy에게 GitHub Sponsors로 후원을 남겼다.

코드를 쓰는 사람뿐 아니라, 리뷰하고 방향을 잡아주는 사람들이 있어 이 생태계가 유지된다는 걸 실감한 경험이었다.

현재글[Argo CD 오픈소스 기여] CLI help에 뜨는 kubectl REST 플래그가 실제로는 동작하지 않는 문제 (#25875)

hyejun CSlog