플러그인

플러그인 (Plugins)

이 가이드는 argocd CLI 도구용 플러그인을 작성하는 방법을 보여줍니다. 플러그인은 argocd CLI를 새 하위 명령으로 확장하여 기본 배포에 포함되지 않은 커스텀 기능을 허용하는 방법입니다.

출처: 문서

본문

플러그인

개요

이 가이드는 argocd CLI 도구용 플러그인을 작성하는 방법을 보여줍니다. 플러그인은 argocd CLI를 새 하위 명령으로 확장하여 argocd CLI의 기본 배포에 포함되지 않은 커스텀 기능을 허용하는 방법입니다.

원래 제안을 보고 싶다면 이 개선 제안(enhancement proposal)으로 이동하세요. 플러그인 메커니즘이 어떻게 작동하는지, 그 이점, 동기, 달성하려는 목표를 다룹니다.

전제 조건

로컬에 작동하는 argocd 바이너리가 설치되어 있어야 합니다. 바이너리를 설치하려면 cli 설치 문서를 따를 수 있습니다.

argocd 플러그인 생성

플러그인은 이름이 argocd-로 시작하는 독립 실행형 실행 파일입니다. 플러그인을 설치하려면 실행 파일을 PATH에 포함된 아무 디렉터리로 이동하세요. PATH 구성이 실행 파일의 전체 절대 경로를 지정하는지 확인하세요. 상대 경로가 아니어야 합니다. argocd는 PATH에서 argocd-my-plugin 바이너리를 실행하여 argocd my-plugin arg1 arg2 --flag1 같은 커스텀 명령을 추가할 수 있게 합니다.

제한 사항

• 현재 기존 argocd 명령을 덮어쓰는 플러그인을 만들 수 없습니다. 예를 들어 argocd-version 같은 플러그인을 만들면 기존 argocd version 명령이 항상 우선하므로 플러그인이 실행되지 않습니다. 이 제한 때문에 플러그인을 사용해 기존 argocd 명령에 새 하위 명령을 추가하는 것도 불가능합니다. 예를 들어 플러그인 이름을 argocd-cluster로 지정해 argocd cluster upgrade 하위 명령을 추가하면 플러그인이 무시됩니다.
• 현재 argocd CLI가 설정한 전역 플래그를 파싱하는 것은 불가능합니다. 예를 들어 --logformat 값 같은 전역 플래그 값을 text로 설정했다면, 플러그인은 전역 플래그를 파싱하지 않고 --logformat 플래그에 기본값 json을 전달합니다. 플래그 파싱은 기존 argocd 명령과 정확히 동일하게 작동합니다. 즉, argocd cluster list 같은 기존 argocd 명령을 실행하면 플래그 값을 text로 올바르게 파싱합니다.

argocd 플러그인의 조건

argocd 플러그인으로 실행하려는 모든 바이너리는 다음 세 가지 조건을 충족해야 합니다:

• 바이너리는 접두사 이름으로 argocd-로 시작해야 합니다. 예를 들어 argocd-demo-plugin이나 argocd-demo_plugin은 유효한 바이너리 이름이지만 argocd_demo-plugin이나 argocd_demo_plugin은 아닙니다.
• 바이너리는 실행 권한이 있어야 합니다. 그렇지 않으면 무시됩니다.
• 바이너리는 시스템의 절대 PATH 어디에든 있어야 합니다.

argocd 플러그인 작성

플러그인 이름 지정

Argo CD 플러그인의 파일 이름은 argocd-로 시작해야 합니다. 플러그인이 구현하는 하위 명령은 파일 이름에서 argocd- 접두사 다음의 부분으로 결정됩니다. argocd- 다음의 모든 것은 argocd의 하위 명령이 됩니다.

예를 들어, 사용자가 다음을 입력하면 argocd-demo-plugin이라는 플러그인이 호출됩니다:

argocd demo-plugin [args] [flags]

argocd CLI는 제공된 하위 명령을 기반으로 호출할 플러그인을 결정합니다.

예를 들어 다음 명령을 실행하면:

argocd my-custom-command [args] [flags]

PATH에 argocd-my-custom-command라는 플러그인이 있으면 그 플러그인이 실행됩니다.

플러그인 작성

플러그인은 명령줄 명령을 작성할 수 있는 모든 프로그래밍 언어나 스크립트로 작성할 수 있습니다.

플러그인은 이름에 따라 구현하려는 명령 경로를 결정합니다.

예를 들어 argocd-demo-plugin이라는 바이너리가 시스템의 절대 PATH에 있고 사용자가 다음 명령을 실행하면:

argocd demo-plugin subcommand1 --flag=true

Argo CD는 해당 플러그인을 다음 명령으로 변환해 실행합니다:

argocd-demo-plugin subcommand1 --flag=true

마찬가지로 argocd-demo-demo-plugin이라는 플러그인이 절대 PATH에 있고 사용자가 다음을 호출하면:

argocd demo-demo-plugin subcommand2 subcommand3 --flag=true

Argo CD는 플러그인을 다음과 같이 실행합니다:

argocd-demo-demo-plugin subcommand2 subcommand3 --flag=true

예시 플러그인

#!/bin/bash

# Check if the argocd CLI is installed
if ! command -v argocd &> /dev/null; then
    echo "Error: Argo CD CLI (argocd) is not installed. Please install it first."
    exit 1
fi

if [[ "$1" == "version" ]]
then
    echo "displaying argocd version..."
    argocd version
    exit 0
fi

echo "I am a plugin named argocd-foo"

플러그인 사용

플러그인을 사용하려면 플러그인을 실행 가능하게 만드세요:

sudo chmod +x ./argocd-foo

그리고 PATH 어디에나 배치하세요:

sudo mv ./argocd-foo /usr/local/bin

이제 플러그인을 argocd 명령으로 호출할 수 있습니다:

argocd foo

그러면 다음 출력이 나옵니다:

I am a plugin named argocd-foo

모든 인자와 플래그는 실행 파일에 그대로 전달됩니다:

argocd foo version

그러면 다음 출력이 나옵니다:

DEBU[0000] command does not exist, looking for a plugin... 
displaying argocd version...
2025/01/16 13:24:36 maxprocs: Leaving GOMAXPROCS=16: CPU quota undefined
argocd: v2.13.0-rc2+0f083c9
  BuildDate: 2024-09-20T11:59:25Z
  GitCommit: 0f083c9e58638fc292cf064e294a1aa53caa5630
  GitTreeState: clean
  GoVersion: go1.22.7
  Compiler: gc
  Platform: linux/amd64
argocd-server: v2.13.0-rc2+0f083c9
  BuildDate: 2024-09-20T11:59:25Z
  GitCommit: 0f083c9e58638fc292cf064e294a1aa53caa5630
  GitTreeState: clean
  GoVersion: go1.22.7
  Compiler: gc
  Platform: linux/amd64
  Kustomize Version: v5.4.3 2024-07-19T16:40:33Z
  Helm Version: v3.15.2+g1a500d5
  Kubectl Version: v0.31.0
  Jsonnet Version: v0.20.0

argocd 플러그인 배포

다른 사람이 사용할 Argo CD 플러그인을 개발했다면 사용자에게 원활한 설치와 업그레이드 절차를 보장하기 위해 패키징, 배포, 업데이트 전달 방법을 신중히 고려해야 합니다.

네이티브 / 플랫폼별 패키지 관리

Linux용 apt나 yum, Windows용 Chocolatey, macOS용 Homebrew 같은 전통적인 패키지 관리자로 플러그인을 배포할 수 있습니다. 이러한 패키지 관리자는 실행 파일을 사용자의 PATH에 직접 배치하여 쉽게 접근할 수 있게 하므로 플러그인 배포에 적합합니다.

그러나 플러그인 작성자로서 이 접근 방식을 선택하면 매 릴리스마다 여러 플랫폼에서 플러그인의 배포 패키지를 유지보수하고 업데이트해야 하는 책임이 생깁니다. 여기에는 호환성 테스트, 시기적절한 업데이트 보장, 사용자에게 매끄러운 경험을 제공하기 위한 버전 관리가 포함됩니다.

소스 코드

플러그인의 소스 코드를 예를 들어 Git 저장소에 게시할 수 있습니다. 이는 사용자가 코드에 직접 접근하고 검사할 수 있게 합니다. 플러그인을 설치하려는 사용자는 코드를 가져오고 적절한 빌드 환경을 설정한 다음(플러그인이 컴파일이 필요하다면) 수동으로 배포해야 합니다.

더 알아보기 (Learn more)

• 구성 관리 플러그인
• 사용자 가이드 개요