@bifos/nhncloud-cli 0.6.0 → 0.8.0

package/skills/nhncloud-cli/references/common.md

@@ -0,0 +1,134 @@
+# Common Reference
+
+설치, configure, profile, 출력 모드, 에러 코드를 다룬다.
+서비스별 세부 명령은 각 reference를 읽는다.
+
+## 설치
+
+```bash
+npm install -g @bifos/nhncloud-cli
+```
+
+## 초기 설정
+
+첫 설정은 `nhncloud configure`로 한다.
+대화형 마법사가 profile, UAK, 서비스별 자격증명을 묻고 저장 전 연결을 테스트한다.
+
+```bash
+nhncloud configure
+nhncloud configure --profile staging
+```
+
+CI나 자동화에서는 flag로 비대화형 저장을 한다.
+
+```bash
+nhncloud configure \
+  --uak-id <uak-id> --uak-secret <uak-secret> \
+  --logncrash-appkey <appkey> --logncrash-secret <secret> \
+  --ncr-appkey <appkey> \
+  --no-verify
+```
+
+주요 옵션:
+
+| 옵션 | 설명 |
+|------|------|
+| `--profile <name>` | 대상 profile. 기본값은 `default` |
+| `--uak-id <id>` / `--uak-secret <secret>` | 공통 User Access Key |
+| `--logncrash-appkey <key>` / `--logncrash-secret <secret>` | Log & Crash 검색 자격증명 |
+| `--ncr-appkey <key>` | NCR appkey |
+| `--iaas-tenant-id <id>` / `--iaas-username <name>` / `--iaas-password <password>` | IaaS/NKS 자격증명 |
+| `--iaas-region <region>` | IaaS 기본 region |
+| `--no-verify` | 연결 테스트 생략 |
+
+저장 파일은 `~/.nhncloud/credentials.json`이고 mode 0600으로 관리된다.
+기본 profile은 선택적으로 `~/.nhncloud/config.json`의 `defaultProfile`로 지정한다.
+
+## Profile 우선순위
+
+profile 해석 순서:
+
+1. `--profile <name>`
+2. `NHNCLOUD_PROFILE`
+3. `config.defaultProfile`
+4. `"default"`
+
+자동화에서는 `--profile`을 명시해 실행 환경 차이를 줄인다.
+
+## 출력 모드
+
+| 플래그 | 출력 | 용도 |
+|--------|------|------|
+| 없음 | 사람이 읽기 좋은 table | 터미널 확인 |
+| `--json` | JSON stdout | 파싱, 자동화, AI 에이전트 |
+| `--quiet` | 핵심 식별자만 stdout | 단순 체이닝 |
+
+`--json`은 CLI 출력 계약이다.
+API 원본 wrapper를 항상 보존하지 않는다.
+예를 들어 `nhncloud instance get <instance-id> --json`은 `.server.status`가 아니라 `.status`를 읽는다.
+
+## Command catalog
+
+`nhncloud commands`는 Commander tree에서 command path, argument, option, description을 출력한다.
+외부 API를 호출하지 않는 read-only metadata 명령이다.
+
+```bash
+nhncloud commands
+nhncloud commands --json
+nhncloud commands --json | jq '.commands[] | select(.path=="nks cluster list")'
+```
+
+AI 에이전트는 먼저 `commands --json`으로 실제 command path와 option 이름을 확인하고, 그다음 서비스 reference를 읽는다.
+
+## JSON shape 요약
+
+| 명령 | `--json` 출력 shape |
+|------|---------------------|
+| `commands` | `{ commands: [{ path, description, arguments, options, subcommands }] }` |
+| `logncrash search` | `{ totalItems, pageNumber, pageSize, data }` |
+| `deploy binary-groups` | `binaryGroups` wrapper를 언랩한 배열 |
+| `deploy binaries` | `{ totalCount, binaries }` |
+| `instance list` | `servers` wrapper를 언랩한 server 배열 |
+| `instance get` | `server` wrapper를 언랩한 단일 server |
+| `instance flavors` | `flavors` wrapper를 언랩한 flavor 배열 |
+| `instance images` | `images` wrapper를 언랩한 image 배열 |
+| `instance availability-zones` | `availabilityZoneInfo` wrapper를 언랩한 배열 |
+| `instance keypairs` | `keypairs[].keypair`를 flatten한 keypair 배열 |
+| `network list` | VPC 배열 |
+| `network subnet list` | subnet 배열 |
+| `volume list` | volume 배열 |
+| `volume get` | 단일 volume 객체 |
+| `floatingip list` | Floating IP 배열 |
+| `ncr list` | `registries` wrapper를 언랩한 registry 배열 |
+| `ncr get` | `registry` wrapper를 언랩한 단일 registry |
+| `ncr images` | repository 배열 |
+| `ncr tags` | tag 배열 |
+| `nks supports` | 지원 Kubernetes version / event type 객체 |
+| `nks cluster list` | cluster 배열 |
+| `nks cluster events` | event 배열 |
+| `nks nodegroup list` | nodegroup 배열 |
+| `nks addon-type list` | addon type 배열 |
+| `nks addon list` | addon 배열 |
+| `nks cluster addon list` | cluster addon 배열 |
+
+NKS 단건 조회와 일부 설정 조회는 table 출력용 최소 컬럼을 만들고 `--json`에서는 raw 객체를 보존한다.
+NKS 쓰기 명령 중 생성, resize, 설정 변경, 노드 action, 애드온 변경은 `{ uuid }` 응답을 반환한다.
+삭제 명령은 성공 메시지를 stderr에 쓰고 stdout은 비운다.
+`nks cluster kubeconfig`는 kubeconfig 문자열을 stdout 또는 파일로 저장한다.
+
+## 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| API 오류 / 봉투 실패 | 1 |
+| 인증 실패 | 2 |
+| 입력 오류 / 필수 옵션 누락 / confirm 누락 | 3 |
+| 자격증명 또는 config 오류 | 4 |
+
+## Agent 기본 규칙
+
+- 조회는 먼저 `--json`으로 실행하고 필요한 id를 추출한다.
+- 쓰기 명령 전에 `--profile`, `--region`, 대상 id를 명시한다.
+- `--quiet`는 해당 명령이 식별자 출력을 문서화한 경우에만 사용한다.
+- 삭제 명령은 비대화형 환경에서 `--yes`를 명시한다.
+- stdout은 데이터로만 취급하고, 진행 메시지는 stderr로 분리된다고 가정한다.

package/skills/nhncloud-cli/references/deploy.md

@@ -0,0 +1,112 @@
+# Deploy Reference
+
+`deploy` 명령군은 NHN Cloud Deploy v2.1 API를 호출한다.
+UAK를 OAuth `client_credentials`로 교환한 Bearer token으로 인증하고, token은 만료 전까지 캐시한다.
+
+## 설정
+
+`~/.nhncloud/credentials.json`에 profile 공통 `userAccessKey`가 필요하다.
+`nhncloud configure` 사용을 권장한다.
+
+`~/.nhncloud/config.json`에는 named deploy target을 둔다.
+
+Discovery:
+
+```bash
+nhncloud commands --json | jq '.commands[] | select(.path|startswith("deploy"))'
+```
+
+```json
+{
+  "version": 1,
+  "defaultProfile": "default",
+  "deploy": {
+    "targets": {
+      "my-service": {
+        "appKey": "<appKey>",
+        "artifactId": "<artifactId>",
+        "serverGroupId": "<serverGroupId>",
+        "scenarioIds": "<id1,id2>"
+      }
+    }
+  }
+}
+```
+
+## 배포 실행
+
+```bash
+nhncloud deploy run my-service
+nhncloud deploy run my-service --async
+nhncloud deploy run my-service --target-hosts <host1,host2>
+```
+
+`<target>`은 config의 deploy target 이름이다.
+
+| 옵션 | 설명 |
+|------|------|
+| `--app-key <k>` | target의 appKey override |
+| `--artifact-id <id>` | target의 artifactId override |
+| `--server-group-id <id>` | target의 serverGroupId override |
+| `--scenario-ids <csv>` | target의 scenarioIds override |
+| `--target-hosts <csv>` | 대상 호스트. 생략 시 서버그룹 전체 |
+| `--concurrent <n>` | 병렬 배포 수. 기본 1 |
+| `--next-when-fail` | 시나리오 실패 시에도 진행 |
+| `--note <s>` | 배포 메모 |
+| `--async` | 즉시 반환. 기본은 완료 대기 |
+| `--profile <name>` | 사용할 profile |
+
+동기 모드는 서버가 배포 완료까지 응답을 보류한다.
+비동기 모드는 `deploying` 상태를 즉시 반환하고, 완료 확인은 `deploy histories`로 한다.
+
+## 조회 명령
+
+```bash
+nhncloud deploy artifacts my-service --json
+nhncloud deploy server-groups my-service --json
+nhncloud deploy histories my-service --json
+nhncloud deploy binary-groups my-service --json
+nhncloud deploy binaries my-service --binary-group <key> --json
+```
+
+의도별 명령:
+
+| 의도 | 명령 |
+|------|------|
+| 아티팩트 목록 | `deploy artifacts <target>` |
+| 서버그룹 목록 | `deploy server-groups <target>` |
+| 배포 이력 | `deploy histories <target>` |
+| 바이너리 그룹 목록 | `deploy binary-groups <target>` |
+| 바이너리 목록 | `deploy binaries <target> --binary-group <key>` |
+
+`deploy binary-groups --json`은 `binaryGroups` wrapper를 언랩한 배열이다.
+`deploy binaries --json`은 `{ totalCount, binaries }` 객체다.
+
+## 바이너리 전송
+
+```bash
+nhncloud deploy upload <target> --file ./app.tgz --binary-group <key>
+nhncloud deploy download <target> --binary-group <key> --binary-key <key> -o ./app.tgz
+```
+
+`upload`는 multipart로 로컬 파일을 업로드한다.
+`--quiet`이면 `binaryKey`만 출력한다.
+
+`download`는 바이너리를 파일로 저장한다.
+대상 파일이 이미 있으면 기본 거부하고, `--force`가 있을 때만 덮어쓴다.
+
+## 체이닝 예시
+
+```bash
+nhncloud deploy artifacts my-service --json | jq -r '.[0].artifactId'
+nhncloud deploy run my-service --artifact-id <artifactId>
+nhncloud deploy histories my-service --json | jq '.[0] | {deployKey, deployStatus}'
+```
+
+## 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| UAK 누락 또는 config target 없음 | 4 또는 3 |
+| OAuth 인증 실패 | 2 |
+| Deploy API 오류 또는 봉투 실패 | 1 |

package/skills/nhncloud-cli/references/iaas.md

@@ -0,0 +1,126 @@
+# IaaS Reference
+
+`instance`, `network`, `volume`, `floatingip`은 IaaS 자격증명과 Keystone token을 공유한다.
+region이 중요하면 `--region <region>`을 명시한다.
+
+## IaaS 설정
+
+`nhncloud configure`에서 IaaS 자격증명을 저장하거나 flag로 입력한다.
+
+```bash
+NHNCLOUD_IAAS_PASSWORD=<password> nhncloud configure \
+  --iaas-tenant-id <tenant-id> \
+  --iaas-username <username> \
+  --iaas-region kr1 \
+  --no-verify
+```
+
+`--iaas-password`는 NHN Cloud 로그인 비밀번호가 아니라 IAM API 비밀번호다.
+`--iaas-username`은 계정 이메일 또는 IAM 계정 ID다.
+
+## Discovery 순서
+
+인스턴스 생성 전에는 조회 명령으로 id를 확인한다.
+
+```bash
+nhncloud commands --json | jq '.commands[] | select(.path|test("^(instance|network|volume|floatingip)"))'
+nhncloud instance images --json
+nhncloud instance flavors --detail --json
+nhncloud network list --json
+nhncloud instance keypairs --json
+nhncloud instance availability-zones --json
+```
+
+생성/삭제/attach 전에는 profile과 region을 명시한다.
+
+## Instance 조회와 생성
+
+```bash
+nhncloud instance list --json
+nhncloud instance get <instance-id> --json
+nhncloud instance create \
+  --name web \
+  --flavor <flavor-id> \
+  --image <image-id> \
+  --network <network-uuid> \
+  --wait --json
+```
+
+`instance create --wait --quiet`는 ACTIVE 상태와 IP 할당을 기다린 뒤 IP를 출력한다.
+GPU flavor 등 일부 flavor는 `--boot-volume-size <gb>`가 필요할 수 있다.
+`--user-data <path>`는 cloud-init user-data를 base64로 인코딩해 주입하며, 인코딩 후 65535 byte 한도가 있다.
+
+## Instance 작업
+
+```bash
+nhncloud instance delete <instance-id> --yes
+nhncloud instance start <instance-id>
+nhncloud instance stop <instance-id>
+nhncloud instance reboot <instance-id> --hard
+nhncloud instance resize <instance-id> --flavor <flavor-id>
+nhncloud instance resize-confirm <instance-id>
+nhncloud instance resize-revert <instance-id>
+```
+
+`resize` 후에는 `VERIFY_RESIZE`에서 멈춘다.
+`resize-confirm`으로 확정하거나 `resize-revert`로 롤백한다.
+
+## Keypair
+
+```bash
+nhncloud instance keypairs --json
+nhncloud instance keypair get <name> --json
+nhncloud instance keypair create <name> --output ./key.pem
+nhncloud instance keypair delete <name>
+```
+
+`--public-key` 없이 생성하면 private key는 생성 시 한 번만 반환된다.
+자동화에서는 `--output`으로 mode 0600 파일 저장을 권장한다.
+
+## Network
+
+```bash
+nhncloud network list --json
+nhncloud network subnet list --json
+```
+
+`instance create --network <uuid>`에는 `network list`의 VPC id를 사용한다.
+subnet id가 아니다.
+
+## Volume
+
+```bash
+nhncloud volume list --json
+nhncloud volume get <volume-id> --json
+nhncloud volume create --size 50 --name my-volume
+nhncloud volume create --size 50 --volume-type "General SSD" --availability-zone kr-pub-a
+nhncloud instance volumes <instance-id> --json
+nhncloud instance volume attach <instance-id> --volume <volume-id>
+nhncloud instance volume detach <instance-id> <volume-id>
+```
+
+`volume create`, `attach`, `detach`는 쓰기 작업이다.
+`--availability-zone <az>`에는 `instance availability-zones`의 `zoneName`을 지정한다.
+인스턴스와 같은 AZ에 볼륨을 만들어 attach 시 AZ 불일치 400을 피할 수 있다.
+`attach`는 `--volume <id>` 플래그를 쓰고, `detach`는 `<instanceId> <volumeId>` 위치 인수를 쓴다.
+
+## Floating IP
+
+```bash
+nhncloud floatingip list --json
+nhncloud floatingip create --json
+nhncloud floatingip create --network <network-uuid> --json
+nhncloud floatingip delete <floatingip-id> --yes
+```
+
+`floatingip create --quiet`는 발급된 Floating IP id를 출력한다.
+`floatingip associate`는 instance→port_id 매핑 경로 미확정으로 아직 제공하지 않는다.
+
+## 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| IaaS 자격증명 누락 또는 불완전 | 4 |
+| Keystone 인증 실패 | 2 |
+| 미등록 region, 필수 옵션 누락, `--yes` 누락 | 3 |
+| API 오류 또는 wait timeout | 1 |

package/skills/nhncloud-cli/references/logncrash.md

@@ -0,0 +1,126 @@
+# Log & Crash Reference
+
+`logncrash` 명령군은 Log & Crash Search 검색, scroll export, collector 전송을 다룬다.
+
+## 검색
+
+Discovery:
+
+```bash
+nhncloud commands --json | jq '.commands[] | select(.path|startswith("logncrash"))'
+```
+
+```bash
+nhncloud logncrash search \
+  --query 'logType:"ERROR"' \
+  --from 1h \
+  --to now \
+  --json
+```
+
+옵션:
+
+| 옵션 | 필수 | 설명 |
+|------|:---:|------|
+| `--query <lucene>` | 예 | Lucene 질의 문자열. API에 그대로 전달 |
+| `--from <time>` | 예 | 검색 시작. ISO8601 또는 상대시간 |
+| `--to <time>` | 예 | 검색 끝. ISO8601, 상대시간, `now` |
+| `--page <n>` | 아니오 | pageNumber. 기본 0 |
+| `--size <n>` | 아니오 | pageSize. 기본 10, 최대 100 |
+| `--profile <name>` | 아니오 | 사용할 profile |
+
+Lucene 예시:
+
+| 의도 | 쿼리 |
+|------|------|
+| 전체 검색 | `*` |
+| body 단어 검색 | `body:request_received` |
+| body 부분 문자열 검색 | `body:*request_received*` |
+| logType 검색 | `logType:"ERROR"` |
+
+시간 입력:
+
+- `1h`, `30m`, `2d`, `now`
+- `2024-01-01T00:00:00+09:00` 같은 ISO8601 직접 입력
+
+API 제약:
+
+- 검색 시작은 최근 90일 이내여야 한다.
+- 검색 범위는 31일 이하여야 한다.
+
+## 검색 출력
+
+`--json` 출력은 `{ totalItems, pageNumber, pageSize, data }` 객체다.
+
+```bash
+nhncloud logncrash search \
+  --query '*' \
+  --from 1h --to now \
+  --json | jq '.totalItems'
+```
+
+전송 직후에는 인덱싱 지연으로 잠시 0건이 나올 수 있다.
+반복 검색이나 넓은 wildcard 검색은 시간 범위를 좁혀 확인한다.
+
+## 대량 export
+
+`logncrash export`는 검색 결과 전체를 scroll로 순회해 파일로 저장한다.
+데이터는 stdout이 아니라 파일에 쓰고, 진행 상황은 stderr에 출력한다.
+
+```bash
+nhncloud logncrash export \
+  --query '<lucene>' \
+  --from 1h \
+  --to now \
+  --output logs.jsonl
+```
+
+옵션:
+
+| 옵션 | 설명 |
+|------|------|
+| `--output <file>` | 필수. 출력 파일 |
+| `--format json` | JSON 배열로 저장. 기본은 JSON Lines |
+| `--force` | 기존 파일 덮어쓰기 |
+| `--size <n>` | scroll pageSize. 10~100 |
+
+scrollKey는 1분 만료다.
+데이터가 많아 다음 호출까지 1분을 넘기면 만료될 수 있다.
+이 경우 검색 범위를 좁히거나 `--size`를 키워 페이지 수를 줄인다.
+
+## 로그 전송
+
+`logncrash send`는 collector host로 로그 한 건을 전송한다.
+검색과 달리 secret 헤더를 쓰지 않고, body의 `projectName`에 appkey를 넣는다.
+
+```bash
+nhncloud logncrash send --body "batch finished" --level INFO
+echo "batch finished" | nhncloud logncrash send --level INFO
+nhncloud logncrash send --file ./error.log --level ERROR
+```
+
+입력 우선순위는 `--body` > `--file` > stdin이다.
+본문이 없거나 비어 있으면 입력 오류다.
+단일 로그 본문은 8MB 한도이며 초과 시 전송 전 차단된다.
+
+옵션:
+
+| 옵션 | 설명 |
+|------|------|
+| `--body <text>` | 로그 본문 |
+| `--file <path>` | 본문 파일 |
+| `--level <level>` | DEBUG, INFO, WARN, ERROR, FATAL |
+| `--app-version <ver>` | projectVersion |
+| `--source <s>` / `--type <t>` / `--host <h>` | 부가 필드 |
+| `--profile <name>` | 사용할 profile |
+
+`--json`이면 `{ ok: true, bytes }`를 stdout에 출력한다.
+
+## 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| appkey 또는 secret 누락 | 4 |
+| 인증 실패 | 2 |
+| 시간 범위 초과, 본문 없음, 8MB 초과 | 3 |
+| API 오류 또는 봉투 실패 | 1 |

package/skills/nhncloud-cli/references/ncr.md

@@ -0,0 +1,73 @@
+# NCR Reference
+
+`ncr` 명령군은 NHN Container Registry 레지스트리, 이미지, 태그를 조회한다.
+Management API는 공통 UAK 정적 헤더를 사용한다.
+이미지와 태그 조회는 Harbor REST `/api/v2.0` 데이터플레인을 직접 호출하고 UAK Basic Auth를 사용한다.
+
+## 설정
+
+공통 UAK와 NCR appkey가 필요하다.
+
+```bash
+nhncloud configure --uak-id <uak-id> --uak-secret <uak-secret> --ncr-appkey <appkey>
+```
+
+`--app-key <key>`는 profile의 `ncr.appkey`보다 우선한다.
+기본 region은 `kr1`이고, `kr1`, `kr2`, `kr3`를 지원한다.
+
+## Registry 조회
+
+```bash
+nhncloud commands --json | jq '.commands[] | select(.path|startswith("ncr"))'
+nhncloud ncr list --app-key <appkey> --json
+nhncloud ncr list --region kr2 --app-key <appkey> --json
+nhncloud ncr get <registry> --app-key <appkey> --json
+```
+
+`ncr list --json`은 `registries` wrapper를 언랩한 registry 배열이다.
+`ncr get --json`은 `registry` wrapper를 언랩한 단일 registry 객체다.
+
+## Image와 tag 조회
+
+```bash
+nhncloud ncr images <registry> --json
+nhncloud ncr tags <registry> <repository> --json
+```
+
+`ncr images --json`은 repository 배열이다.
+`ncr tags --json`은 tag 배열이다.
+
+## 체이닝 예시
+
+```bash
+nhncloud ncr list --app-key <appkey> --json | jq -r '.[].name'
+nhncloud ncr get <registry> --app-key <appkey> --json
+nhncloud ncr images <registry> --json | jq -r '.[].repository'
+nhncloud ncr images <registry> --json | jq '.[] | {repository, artifact_count}'
+nhncloud ncr tags <registry> <repository> --json | jq -r '.[].tag'
+nhncloud ncr tags <registry> <repository> --json | jq 'sort_by(.push_time) | last | .tag'
+```
+
+## 옵션
+
+| 옵션 | 설명 |
+|------|------|
+| `--region <region>` | NCR region. 기본 `kr1` |
+| `--app-key <key>` | NCR appkey |
+| `--profile <name>` | 사용할 profile |
+
+## 주의사항
+
+- appkey는 NCR service appkey다.
+- 인증 secret은 공통 UAK secret을 사용한다.
+- Harbor REST 경로는 NHN 공통 봉투가 아니므로 wrapper unwrap을 기대하지 않는다.
+- registry나 repository 인수는 공백 또는 빈값이면 입력 오류다.
+
+## 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| UAK 누락 또는 NCR appkey 미설정 | 4 |
+| UAK 인증 실패 | 2 |
+| 지원하지 않는 region, 빈 registry/repository 인수 | 3 |
+| NCR API 또는 Harbor API 오류 | 1 |