gcube-cli 0.1.0__tar.gz

gcube_cli-0.1.0/PKG-INFO

@@ -0,0 +1,505 @@
+Metadata-Version: 2.4
+Name: gcube-cli
+Version: 0.1.0
+Summary: Official command-line tool for the gcube AI GPU cloud platform
+Author-email: Data Alliance <support@data-alliance.com>
+License: Apache-2.0
+Project-URL: Homepage, https://gcube.ai
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+
+# gcube CLI
+
+gcube 플랫폼(AI GPU 클라우드) 공식 커맨드라인 도구.
+브라우저 없이 터미널만으로 GPU 워크로드를 등록하고, 리소스를 모니터링하고, 사용자를 관리한다.
+
+---
+
+## Overview
+
+```
+gcube <service> <operation> [options]
+```
+
+`gcube`는 [gcube 플랫폼](https://gcube.ai)의 REST API를 직접 호출하는 Python CLI다.
+
+| 특징 | 설명 |
+|---|---|
+| pip 설치 | `pip install gcube-cli`로 설치, Python 3.10+ |
+| AWS CLI 스타일 | `gcube <service> <operation>` 구조, `--output table\|json\|yaml` |
+| 웹 토큰 인증 | gcube 웹 프론트에서 토큰 발급 후 CLI에 설정 |
+| 주요 의존성 | click · httpx · rich · pyyaml |
+
+---
+
+## Installation
+
+### pip 설치 (권장)
+
+```bash
+pip install gcube-cli
+```
+
+### 소스 설치
+
+```bash
+git clone https://github.com/data-alliance/gcube-cli.git
+cd gcube-cli
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+핵심 워크플로우를 4개 명령어로 완료한다.
+
+```bash
+# 1. 토큰 설정 (gcube 웹 프론트에서 복사한 토큰)
+gcube configure set --token "eyJ..."
+
+# 2. GPU 워크로드 등록
+gcube workload register -f workload.yaml
+
+# 3. 상태 확인
+gcube workload list
+
+# 4. 로그 조회
+gcube workload logs my-train-job
+```
+
+---
+
+## Configuration
+
+### 토큰 발급 및 설정
+
+1. [gcube 웹 프론트](https://gcube.ai)에 로그인
+2. "API 토큰 발급" 메뉴에서 토큰 복사
+3. CLI에서 토큰 설정:
+
+```bash
+gcube configure set --token "eyJ..."
+```
+
+### 설정 파일
+
+`gcube configure` 이후 `~/.gcube/config.yaml`에 자동 생성된다.
+
+```yaml
+platform_url: https://console.gcube.ai
+ws_url: wss://console.gcube.ai:61443
+auth:
+  access_token: "eyJ..."
+  expires_at: "2026-04-03T10:00:00Z"
+output: table          # table | json | yaml
+```
+
+### Commands
+
+```
+gcube configure                                     # 대화형 설정
+gcube configure set --token <token>                 # 토큰 설정
+gcube configure set --platform-url <url>            # 플랫폼 URL 설정
+gcube configure set --ws-url <url>                  # WebSocket URL 설정 (로그 스트리밍용)
+gcube configure set --output <format>               # 기본 출력 형식 설정
+gcube configure get <key>                           # 설정값 조회 (token, platform-url, ws-url, output)
+gcube configure status                              # 현재 설정 및 토큰 유효 여부 표시
+```
+
+### 환경변수
+
+환경변수는 설정 파일보다 우선 적용된다.
+
+| 환경변수 | 설명 | 예시 |
+|---|---|---|
+| `GCUBE_PLATFORM_URL` | 플랫폼 Base URL | `https://gcube.ai` |
+| `GCUBE_ACCESS_TOKEN` | Bearer 토큰 (CI/CD용) | `eyJ...` |
+| `GCUBE_OUTPUT` | 기본 출력 형식 | `json` |
+| `GCUBE_CONFIG` | 설정 파일 경로 override | `/etc/gcube/config.yaml` |
+
+### 다중 프로파일
+
+`--profile` 플래그로 여러 플랫폼 환경(dev/prod 등)을 전환한다.
+
+```bash
+# 개발 환경 토큰 설정
+gcube configure set --token "eyJ..." --platform-url https://dev.gcube.ai --profile dev
+
+# dev 프로파일로 명령 실행
+gcube workload list --profile dev
+```
+
+프로파일별 설정은 `~/.gcube/profiles/<profile>/config.yaml`에 저장된다.
+
+---
+
+## Command Reference
+
+### Workload
+
+GPU 워크로드 수명주기를 관리한다.
+
+| 명령 | 설명 |
+|---|---|
+| `gcube workload register -f <yaml>` | YAML 파일로 워크로드 등록 |
+| `gcube workload register --image <img> ...` | 인라인 플래그로 워크로드 등록 |
+| `gcube workload update <ser> -f <yaml>` | 중지된 워크로드 수정 |
+| `gcube workload list` | 워크로드 목록 조회 |
+| `gcube workload describe <name>` | 워크로드 상세 조회 |
+| `gcube workload start <name>` | 워크로드 시작 |
+| `gcube workload stop <name>` | 워크로드 중지 |
+| `gcube workload delete <name>` | 워크로드 삭제 |
+| `gcube workload logs <ser>` | 컨테이너 로그 실시간 스트리밍 (WebSocket) |
+| `gcube workload logs <ser> --pod <idx>` | 특정 pod 로그 스트리밍 |
+| `gcube workload logs <ser> --pod <idx> --container <idx>` | 특정 컨테이너 로그 스트리밍 |
+| `gcube workload pods <name>` | Pod 목록 조회 |
+
+**주요 플래그**
+
+| 플래그 | 설명 | 기본값 |
+|---|---|---|
+| `-f, --file <path>` | 워크로드 YAML 파일 경로 | — |
+| `--image <image>` | 컨테이너 이미지 | — |
+| `--gpu <code>` | GPU 코드 (예: `029`, `gcube gpu list`의 CODE 컬럼) | — |
+| `--cuda <version>` | CUDA 버전 코드 | — |
+| `--category <type>` | 워크로드 유형: `infer\|learn` | — |
+| `--owner <email>` | 워크로드 소유자 (list 필터) | — |
+| `--container <name>` | 컨테이너명 (logs용) | — |
+| `--backend astrago` | AstraGo 백엔드 사용 | — |
+| `--namespace gai` | GAI 네임스페이스 사용 | — |
+
+**CUDA 버전 코드** (형식: major×1000 + minor×10)
+
+| 코드 | CUDA 버전 |
+|---|---|
+| `12000` | 12.0 |
+| `12020` | 12.2 |
+| `12030` | 12.3 |
+| `12040` | 12.4 |
+| `12050` | 12.5 |
+| `12060` | 12.6 |
+| `12080` | 12.8 |
+| `12090` | 12.9 |
+| `13000` | 13.0 |
+
+**워크로드 YAML 형식** (`register -f` / `update -f` 공통)
+
+```yaml
+# workload.yaml
+description: "My ML training job"  # 필수, 2-80자
+cuda: "12020"                      # CUDA 버전 코드 (선택)
+sharedMemory: 1                    # GB
+
+containers:
+  - containerImage: "pytorch/pytorch:2.0"  # 필수
+    repo: docker.io
+    port: 0                        # 0 = 자동 감지
+    maxConnection: 4
+    containerCommand: "python train.py"
+    isCredential: false
+    containerEnvs:
+      - EPOCHS: "100"
+      - BATCH_SIZE: "32"
+
+gpuSpecs:
+  - gpuCode: "029"                 # 필수 — 'gcube gpu list'의 CODE 컬럼 값
+  # 레플리카 추가: 항목 반복
+  # - gpuCode: "029"
+```
+
+> `gcube workload register --skeleton` 으로 빈 템플릿을 출력할 수 있습니다.
+> `gcube workload update <ser> --skeleton > workload.yaml` 으로 현재 워크로드 설정을 내보낸 후 gpuCode를 채워 `-f`로 전달합니다.
+
+---
+
+### GPU
+
+사용 가능한 GPU 목록과 스펙·가격을 조회한다.
+
+| 명령 | 설명 |
+|---|---|
+| `gcube gpu list` | 가용 GPU 목록 (CODE·스펙·시간당 가격 범위) |
+| `gcube gpu list --all` | 전체 GPU 목록 (비가용 포함, AVAIL 컬럼 표시) |
+
+```bash
+gcube gpu list                        # 가용 GPU만 (CODE 포함)
+gcube gpu list --all                  # 전체 (비가용 포함)
+gcube -o json gpu list        # JSON 출력
+gcube -o yaml gpu list        # YAML 출력
+```
+
+> CODE는 API 응답 순서 기반 3자리 순번(001, 002, ...)이며, 워크로드 등록 시 GPU 특정에 사용된다.
+
+---
+
+### Resource
+
+워크로드의 CPU·GPU·메모리 사용량을 조회한다. workload 이름을 입력하면 내부적으로 pod를 resolve하여 리소스를 조회한다.
+
+| 명령 | 설명 |
+|---|---|
+| `gcube resource workload <name>` | 워크로드 리소스 사용량 (시간 평균) |
+
+---
+
+### Point
+
+포인트 잔액과 일별 지출 내역을 조회한다.
+
+| 명령 | 설명 |
+|---|---|
+| `gcube point status` | 포인트 현황 (잔액·충전·지출 요약, 잔액 부족 경고) |
+| `gcube point spending` | 당월 일별 지출 내역 |
+| `gcube point spending --month 2026-03` | 특정 월 일별 지출 내역 |
+| `gcube point spending --workload <ser>` | 특정 워크로드 지출 필터 |
+
+---
+
+### User
+
+사용자 계정과 크레덴셜을 관리한다.
+
+| 명령 | 설명 |
+|---|---|
+| `gcube user list [--keyword <search>]` | 사용자 목록 조회 |
+| `gcube user describe <email>` | 사용자 상세 조회 |
+| `gcube user create --email <e> --name <n> [--role <r>]` | 사용자 생성 |
+| `gcube user update <email> [--name <n>]` | 사용자 정보 수정 |
+| `gcube user delete <email>` | 사용자 삭제 |
+| `gcube user credentials list <email>` | 크레덴셜 목록 |
+| `gcube user credentials create <email> --name <n>` | 크레덴셜 생성 |
+| `gcube user credentials delete <email> --cred-id <id>` | 크레덴셜 삭제 |
+| `gcube user token <email>` | 플랫폼 토큰 발급/조회 |
+
+---
+
+## Output Formats
+
+`--output` 플래그(또는 `GCUBE_OUTPUT` 환경변수)로 출력 형식을 선택한다.
+
+### table (기본값)
+
+```
+$ gcube workload list
+
+NAME              CATEGORY   TARGET   GPU          GPU COUNT   STATE
+my-train-job      learn      any      RTX4090      2           running
+my-infer-svc      infer      svr      A100         1           stopped
+```
+
+### json
+
+```
+$ gcube -o json workload list
+
+[
+  {"ser":"abc123","owner":"user@example.com","category":"learn","gpu":"RTX4090","gpuCount":2,"state":"running"},
+  {"ser":"def456","owner":"admin@example.com","category":"infer","gpu":"A100","gpuCount":1,"state":"stopped"}
+]
+```
+
+### yaml
+
+```
+$ gcube -o yaml workload list
+
+- ser: abc123
+  owner: user@example.com
+  category: learn
+  gpu: RTX4090
+  gpuCount: 2
+  state: running
+- ser: def456
+  owner: admin@example.com
+  category: infer
+  gpu: A100
+  gpuCount: 1
+  state: stopped
+```
+
+---
+
+## Global Options
+
+모든 명령에서 사용 가능한 플래그.
+
+| 플래그 | 설명 | 기본값 |
+|---|---|---|
+| `--platform-url <url>` | gcube 플랫폼 Base URL | `config.yaml` 값 |
+| `--output <format>` | 출력 형식: `table\|json\|yaml` | `table` |
+| `--profile <name>` | 사용할 프로파일 이름 | `default` |
+| `--debug` | HTTP 요청/응답 상세 출력 | `false` |
+| `--help`, `-h` | 도움말 출력 | — |
+
+---
+
+## Exit Codes
+
+| 코드 | 의미 | 예시 |
+|---|---|---|
+| `0` | 성공 | 정상 출력 |
+| `1` | 잘못된 인수 또는 플래그 | 필수 플래그 누락 |
+| `2` | gcube API 오류 | `API Error [NOT_FOUND]: workload not found` |
+| `3` | 인증 실패 또는 토큰 만료 | `Token expired or invalid. Please get a new token from https://gcube.ai` |
+| `4` | 네트워크 오류 | `Cannot connect to https://gcube.ai. Check network.` |
+
+스크립트에서 활용:
+
+```bash
+gcube workload start my-job
+if [ $? -eq 3 ]; then
+  echo "Token expired. Please get a new token from https://gcube.ai"
+  echo "Then run: gcube configure set --token <new-token>"
+fi
+```
+
+---
+
+## Environment Variables
+
+| 변수 | 설명 |
+|---|---|
+| `GCUBE_PLATFORM_URL` | 플랫폼 Base URL (`--platform-url` override) |
+| `GCUBE_ACCESS_TOKEN` | Bearer 토큰 직접 지정 (CI/CD 환경) |
+| `GCUBE_OUTPUT` | 기본 출력 형식 (`--output` override) |
+| `GCUBE_PROFILE` | 기본 프로파일 이름 (`--profile` override) |
+| `GCUBE_CONFIG` | 설정 파일 경로 override |
+| `GCUBE_DEBUG` | `1` 로 설정 시 `--debug` 활성화 |
+
+---
+
+## Examples
+
+### 토큰 설정
+
+```bash
+# gcube 웹 프론트에서 복사한 토큰 설정
+gcube configure set --token "eyJ..."
+
+# 설정 상태 확인
+gcube configure status
+
+# 대화형 설정 (플랫폼 URL, 토큰, 출력 형식을 순서대로 입력)
+gcube configure
+```
+
+### 워크로드 등록 및 관리
+
+```bash
+# YAML 파일로 학습 잡 등록
+gcube workload register -f train.yaml
+
+# 인라인 플래그로 인퍼런스 서비스 등록 (GPU CODE는 gcube gpu list에서 확인)
+gcube workload register \
+  --image pytorch/pytorch:2.0-cuda12.0 \
+  --gpu 029 \
+  --cuda 12020 \
+  --category infer
+
+# 내 워크로드만 조회
+gcube workload list --owner me@example.com
+
+# 특정 워크로드 상세 + JSON 출력
+gcube -o json workload describe my-train-job
+
+# 실시간 로그 스트리밍 (단일 pod/컨테이너)
+gcube workload logs 2041
+
+# 멀티 pod/컨테이너 — 목록 확인 후 지정
+gcube workload logs 2095
+gcube workload logs 2095 --pod 0 --container 1
+
+# 워크로드 중지 후 삭제
+gcube workload stop my-train-job
+gcube workload delete my-train-job
+```
+
+### 리소스 모니터링
+
+```bash
+# 워크로드 리소스 사용량 (시간 평균)
+gcube resource workload my-train-job
+
+# JSON 출력
+gcube -o json resource workload my-train-job
+```
+
+### 사용자 및 크레덴셜 관리
+
+```bash
+# 사용자 검색
+gcube user list --keyword kim
+
+# 사용자 생성
+gcube user create --email new@example.com --name "Kim Gildong" --role user
+
+# 크레덴셜 발급
+gcube user credentials create kim@example.com --name "dev-key"
+
+# 플랫폼 토큰 발급 (다른 도구 연동용)
+gcube user token kim@example.com
+```
+
+### CI/CD 파이프라인
+
+```bash
+# 환경변수로 인증 (토큰 사전 발급)
+export GCUBE_ACCESS_TOKEN="eyJ..."
+export GCUBE_OUTPUT=json
+
+# 파이프라인에서 워크로드 등록 후 상태 확인
+gcube workload register -f pipeline.yaml
+gcube workload describe pipeline-job-001 | jq '.state'
+```
+
+### GAI / AstraGo 백엔드
+
+```bash
+# GAI 네임스페이스 워크로드 목록
+gcube workload list --namespace gai
+
+# AstraGo 백엔드 워크로드 상세
+gcube workload describe my-job --backend astrago
+```
+
+---
+
+## Development
+
+```bash
+# 소스 클론 및 개발 환경 설치
+git clone https://github.com/data-alliance/gcube-cli.git
+cd gcube-cli
+pip install -e ".[dev]"
+
+# 테스트
+pytest --cov=gcube_cli --cov-report=term-missing
+
+# 빌드
+python -m build
+```
+
+---
+
+## Contributing
+
+버그 리포트 및 기능 요청은 [GitHub Issues](https://github.com/data-alliance/gcube-cli/issues)를 이용한다.
+
+---
+
+## License
+
+Apache License 2.0 — [LICENSE](LICENSE) 참조