Apollo CLI 시작하기

Apollo CLI인 apollo-cli는 허브의 제품과 배포 환경을 조회하고 제품 릴리스를 등록하는 명령행 도구입니다. 주요 명령 그룹은 다음과 같습니다.

CLI 다운로드와 실행

Apollo 왼쪽 탐색 막대에서 Settings를 선택합니다. Settings & Configuration 페이지 왼쪽의 Download로 CLI를 다운로드할 수 있습니다.

다운로드 창에서 운영체제에 맞는 바이너리를 선택합니다.

받은 파일을 사용할 위치로 옮깁니다. Linux와 macOS에서는 다음과 같이 실행 권한을 부여할 수 있습니다.

chmod +x apollo-cli

이하 명령은 실행 파일이 현재 디렉터리에 있다고 가정하여 ./apollo-cli로 호출합니다. 어느 디렉터리에서나 실행하려면 실행 파일을 PATH에 포함된 디렉터리에 배치할 수 있습니다.

./apollo-cli --help
./apollo-cli environment --help
./apollo-cli environment list

--help 또는 -h는 개별 명령에도 사용할 수 있습니다. 먼저 명령 그룹의 도움말을 확인하고, 그 안의 하위 명령 도움말로 필요한 인수를 확인합니다.

셸 자동 완성

Bash, Fish, PowerShell과 Zsh 등에서 명령과 옵션의 Tab 자동 완성을 사용할 수 있습니다. 해당 셸의 설정 절차는 completion 하위 명령으로 확인합니다. Zsh의 경우 다음 명령을 사용합니다.

./apollo-cli completion zsh --help

인증 방식

CLI가 인증 토큰을 얻는 방식은 Apollo token provider로 선택합니다.

기본값은 auto입니다. Bearer 토큰과 클라이언트 ID 또는 클라이언트 비밀값을 함께 설정하면 오류가 발생합니다. 한 인증 방식만 구성해야 합니다.

SSO는 토큰이 필요한 명령을 처음 실행하고 유효한 캐시 토큰이 없을 때 로그인 절차를 시작합니다. 로그인 결과는 프로필별로 캐시되며 이후 사용자 조작 없이 토큰을 갱신할 수 있습니다. 사람이 브라우저로 로그인할 수 없는 CI에서는 Bearer 토큰이나 서비스 계정 인증을 사용합니다.

Bearer 토큰 만들기

허브의 Multipass 화면인 https://<Hub>.palantircloud.com/multipass/app으로 이동합니다. <Hub>는 해당 허브의 고유 이름입니다.

1. 사이드바의 User Settings → Tokens를 선택합니다.
2. 오른쪽 위의 + Create token을 선택합니다.
3. 토큰 이름, 간단한 설명과 만료일을 지정합니다.

CI에서 사용할 토큰은 APOLLO_TOKEN이라는 비밀 정보로 등록하여 작업 스크립트에 제공합니다.

인증 방식 변경

apollo-cli configure를 다시 실행하여 방식을 변경할 수 있습니다. 기존 값을 제거할 때는 대화형 프롬프트에 작은따옴표 두 개 ''를 그대로 입력합니다. Enter만 누르면 현재 값이 유지됩니다. Bearer 토큰을 사용할 때는 클라이언트 ID와 클라이언트 비밀값을 제거하고, 서비스 계정을 사용할 때는 Bearer 토큰을 제거해야 합니다.

허브와 프로필 설정

처음 허브에 연결하기 전에 다음 명령을 실행합니다.

./apollo-cli configure

설정은 로컬 ~/.palantir/apollo-cli.config에 저장됩니다. 기본 프로필 이름은 default입니다. configure는 현재 활성 프로필을 설정하며, --profile로 다른 프로필을 지정하면 그 프로필을 설정합니다. 지정한 이름이 없으면 새로 생성합니다. 자세한 입력 동작은 configure, 여러 연결의 관리는 프로필 관리에서 설명합니다.

필요하지 않은 값은 비워 둘 수 있습니다. 기본 배포 환경과 공간을 지정하지 않았다면 각 명령에서 --environment, --space-id로 지정할 수 있습니다.

CLI는 필요한 값을 설정 파일에서 읽을 수 있으며, 환경 변수나 명령행 옵션으로 제공하는 방법도 지원합니다.

전역 명령 설정

연결 프로필을 설정한 뒤에는 모든 프로필이 공유하는 전역 옵션을 설정할 수 있습니다.

Experimental 또는 Deprecated 표지가 붙은 명령의 사용 여부를 이 설정에서 선택합니다.

연결 확인

다음 조회 명령으로 허브 연결과 인증 구성을 확인할 수 있습니다.

./apollo-cli environment list

기본 출력은 배포 환경 ID, 이름, 연락 담당 팀, 설정과 보고 상태의 기준, 공간 ID를 담은 표입니다. 프로그램에서 처리할 때는 -o json을 사용합니다.

./apollo-cli environment list -o json

다음은 가상의 조회 결과입니다.

[
  {
    "apolloEnvironmentID": "test-spoke",
    "environmentName": "Test Spoke",
    "contactTeamName": "My Team",
    "declaredStateSource": "Authoritative",
    "reportedStateSource": "Relayed",
    "spaceID": "ri.apollo.main.space.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
]

허브에 배포 환경을 아직 만들지 않았다면 목록이 비어 있을 수 있습니다. 허브 URL이나 인증 토큰이 잘못되면 명령이 오류로 종료됩니다.

Helm 차트 제품 등록

Helm 차트 제품을 등록할 때는 차트 저장소 URL, 차트 이름과 버전이 필요합니다. Apollo는 설치 시 이 정보로 저장소에서 차트를 가져옵니다.

product-release helm-chart init은 Helm 차트로부터 Apollo 전용 제품 메타데이터와 매니페스트를 만듭니다. product-release create는 이를 제품 카탈로그에 등록합니다. 이 등록만으로 차트나 컨테이너 이미지가 레지스트리에 게시되지는 않습니다. 배포할 아티팩트는 별도로 저장소에 존재해야 합니다.

다음 예시는 공개 Traefik 차트 41.0.2를 Apollo 제품 io.traefik:traefik:41.0.2로 등록하는 구성입니다. 실행 전에 허브 인증을 설정해야 합니다.

원격 차트 저장소 사용

OCI 저장소의 원격 차트에는 --name으로 차트까지 포함한 전체 OCI URL을 지정합니다.

./apollo-cli product-release helm-chart init \
  --as-tgz \
  --name "oci://ghcr.io/traefik/helm/traefik" \
  --version 41.0.2 \
  --repository-url "oci://ghcr.io/traefik/helm" \
  --maven-coordinate "io.traefik:traefik:41.0.2" \
  --output-dir "./chart"

./apollo-cli product-release create \
  --product-tgz "./chart/traefik-41.0.2.config.tgz"

--as-tgz는 제품 릴리스 등록에 필요한 파일을 Apollo 제품 TGZ에 묶습니다. 작업 컴퓨터에서 차트 저장소에 접근할 수 있다면 원격 차트 정보를 사용하는 방식이 일반적으로 간단합니다.

로컬 차트 파일 사용

작업 컴퓨터에서 원격 저장소에 접근하기 어렵다면 이미 받은 차트 파일을 사용할 수 있습니다. 단, Apollo가 배포할 때는 지정한 차트 저장소를 사용하므로 차트가 그 저장소에도 있어야 합니다.

차트를 내려받는 명령은 다음과 같습니다.

helm pull oci://ghcr.io/traefik/helm/traefik --version 41.0.2

생성된 traefik-41.0.2.tgz를 CLI와 함께 작업할 디렉터리에 두고 다음과 같이 처리합니다.

tar -xzf traefik-41.0.2.tgz

./apollo-cli product-release helm-chart init \
  --chart-path "traefik-41.0.2.tgz" \
  --repository-url "oci://ghcr.io/traefik/helm" \
  --maven-coordinate "io.traefik:traefik:41.0.2" \
  --output-dir "./chart"

./apollo-cli product-release create \
  --manifest "./chart/manifest.yml" \
  --default-config "./traefik/values.yaml"

--chart-path를 사용하면 이름과 버전을 차트 메타데이터에서 읽으므로 --name, --version을 별도로 지정하지 않아도 됩니다. --repository-url은 여전히 필요합니다. 로컬 파일로 초기화하는 동안에는 이 URL을 조회하지 않지만, 실제 배포 시 Apollo가 사용합니다.

차트에 values.schema.json이 있다면 마지막 product-release create 명령에 --config-schema "./traefik/values.schema.json"을 추가할 수 있습니다. --config-schema를 사용하려면 --default-config도 함께 지정해야 합니다.

등록한 제품 설치

배포 환경을 만든 뒤 Settings → Install Entities를 선택하고 Select product에서 traefik을 선택합니다. 이후 배포 환경에 맞는 설정을 입력하여 설치합니다.

파일을 Asset 제품으로 게시

Asset 제품은 사용자 지정 파일을 묶어 Apollo에 게시할 때 사용합니다. 다음은 가상의 my-product 디렉터리입니다.

my-product/
├── taxi_info.csv
└── test_data.zip

제품 tarball은 제품 이름과 버전을 포함한 루트 아래에 파일과 배포 매니페스트를 배치하는 구조입니다.

my-product-0.0.2/
├── asset/
│   ├── taxi_info.csv
│   └── test_data.zip
└── deployment/
    └── manifest.yml

매니페스트의 product-type은 asset.v1입니다. 다음 명령으로 파일 디렉터리를 묶어 com.my-org:my-product:0.0.2 제품 릴리스로 게시할 수 있습니다.

./apollo-cli product-release asset publish \
  --maven-coordinate "com.my-org:my-product:0.0.2" \
  --asset-path my-product

제품에서 필요한 컨테이너 이미지도 지정할 수 있습니다. 다음 이미지 URI는 구성 예시이며 실제 사용할 이미지의 URI를 지정해야 합니다.

./apollo-cli product-release asset publish \
  --maven-coordinate "com.my-org:my-product:0.0.2" \
  --asset-path my-product \
  --images docker.io/bitnami/postgresql:16.0.0-debian-11-r10

전체 옵션은 ./apollo-cli product-release asset publish --help로 확인할 수 있습니다.