Qdrant Cloud CLI

Qdrant Cloud CLI (cloud-cli)

qcloud는 Qdrant Cloud를 관리하기 위한 공식 커맨드라인 인터페이스예요. 클러스터 관리, 인증, 그리고 Qdrant Cloud API가 제공하는 모든 기능을 터미널에서 그대로 다룰 수 있죠. GUI를 열지 않고도 스크립트나 자동화 안에서 클라우드 자원을 제어하고 싶을 때 아주 유용해요.

출처: Qdrant 공식문서

설치 (Installation)

GitHub Releases에서 설치하기

최신 릴리스를 GitHub Releases에서 다운로드해요.

본인의 OS와 CPU 아키텍처에 맞는 압축 파일을 고른 뒤, 압축을 풀고 qcloud 바이너리를 PATH에 포함된 어딘가(예: ~/.local/bin 또는 /usr/local/bin)에 넣으면 돼요.

macOS: 현재 이 바이너리는 서명(sign)이 되어 있지 않아요. macOS가 차단한다면 압축을 푼 뒤 xattr -d com.apple.quarantine qcloud를 실행해 주세요.

소스에서 설치하기

Go가 설치되어 있다면 소스에서 바로 빌드해 설치할 수 있어요:

go install github.com/qdrant/qcloud-cli/cmd/qcloud@latest

설치 확인

qcloud version

빠른 시작 (Quick Start)

qcloud를 사용하기 전에 management API 키를 만들고 Qdrant Cloud Console에서 본인의 계정 ID를 확인해 두세요.

# 1. 본인의 자격증명(credentials)으로 컨텍스트 만들기
qcloud context set my-cloud \
  --api-key <YOUR_API_KEY> \
  --account-id <YOUR_ACCOUNT_ID>

# 2. 사용 가능한 클라우드 공급자와 리전 나열하기
qcloud cloud-provider list
qcloud cloud-region list --cloud-provider aws

# 3. 리소스를 지정해 클러스터 만들기 (healthy가 될 때까지 대기)
# --cpu, --ram, --disk를 사용하면 일치하는 패키지를 자동으로 골라줘요.
qcloud cluster create \
  --cloud-provider aws \
  --cloud-region us-east-1 \
  --cpu 2000m \
  --ram 8GiB \
  --disk 50GiB \
  --name my-cluster \
  --wait

# 4. 새 클러스터 정보 확인하기
qcloud cluster describe <CLUSTER_ID>

# 5. 클러스터용 API 키 만들기
qcloud cluster key create <CLUSTER_ID> --name my-key

구성 (Configuration)

qcloud는 세 가지 방식으로 구성할 수 있어요. 우선순위가 낮은 것부터 높은 순으로 나열할게요.

구성 파일 (Config File)

구성 파일은 기본적으로 ~/.config/qcloud/config.yaml에 저장돼요. --config 플래그로 위치를 바꿀 수 있고요. 이 파일에는 이름이 붙은 컨텍스트(named contexts) 가 저장되어 계정과 환경을 손쉽게 전환할 수 있어요.

이름이 붙은 컨텍스트 (Named Contexts)

이름이 붙은 컨텍스트는 자격증명 묶음을 저장하고, 그 사이를 전환할 수 있게 해줘요:

qcloud context set my-cloud --api-key <KEY> --account-id <ID>
qcloud context use my-cloud
qcloud context show

환경 변수 (Environment Variables)

환경 변수는 활성 컨텍스트를 덮어쓰며, 가장 높은 우선순위를 가져요:

변수 설명
QDRANT_CLOUD_API_KEY 인증에 사용하는 API 키
QDRANT_CLOUD_ACCOUNT_ID 연동 대상 계정 ID
QDRANT_CLOUD_ENDPOINT API 엔드포인트 URL (기본값: Qdrant Cloud)
QDRANT_CLOUD_CONTEXT 사용할 컨텍스트 이름

어떤 명령에도 --json을 붙이면 머신이 읽기 쉬운(machine-readable) 출력을 받을 수 있어요.

도움말 보기 (Getting Help)

사용 가능한 모든 명령의 전체 목록은 다음을 실행하면 돼요:

qcloud --help

더 알아보기 (Learn more)