@bifos/nhncloud-cli 0.5.0 → 0.6.0

package/README.md

@@ -1,7 +1,8 @@
 # nhncloud-cli
 
 NHN Cloud 서비스를 AWS CLI 방식으로 호출하는 통합 CLI.
-현재 `configure`, `logncrash search/send` (Log & Crash 로그 검색·전송), `deploy` (배포·바이너리 조회·업로드·다운로드), `instance` (Compute 인스턴스 목록·발급·전원 제어·타입 변경·키페어 관리·이미지·가용성 영역 조회·볼륨 연결 포함), `network` (VPC·서브넷 목록 조회), `volume` (Block Storage 볼륨 목록·조회·생성), `ncr` (NHN Container Registry 레지스트리 목록·조회·이미지 목록·태그 목록) 명령을 지원한다.
+현재 81개 명령을 지원한다.
+`configure`, `logncrash search/send/export`, `deploy`, `instance`, `network`, `volume`, `floatingip`, `ncr`, `nks` 명령으로 NHN Cloud 서비스를 조회·운영할 수 있다.
 
 ## 설치
 
@@ -116,10 +117,27 @@ nhncloud logncrash search \
   --query 'logType:"NORMAL"' \
   --from 1h \
   --to now
+
+# body 필드 키워드 검색
+nhncloud logncrash search \
+  --query 'body:request_received' \
+  --from 1h \
+  --to now
+
+# body 부분 문자열 검색
+nhncloud logncrash search \
+  --query 'body:*request_received*' \
+  --from 1h \
+  --to now
 ```
 
+`--query` 는 콘솔의 간편 검색어가 아니라 Log & Crash Search API 의 Lucene 쿼리다.
+body 검색 의도가 명확하면 `body:<keyword>` 또는 `body:*<keyword>*` 처럼 필드를 지정한다.
+
 시간은 상대시간 (`1h` / `30m` / `2d` / `now`) 또는 ISO8601 (`2026-05-01T00:00:00+09:00`) 로 입력한다.
 API 제약상 검색 시작은 최근 90일 이내, 검색 범위는 31일 이하여야 한다 (초과 시 입력 오류로 거절).
+전송 직후에는 인덱싱 지연으로 잠시 0건이 나올 수 있다.
+반복 검색이나 넓은 wildcard 검색은 API rate limit 에 걸릴 수 있으므로 시간 범위를 좁혀 확인한다.
 
 ### 로그 대량 추출 (export)
 
@@ -179,9 +197,60 @@ nhncloud logncrash send --body "deploy 시작" --app-version 2.3.0 --source batc
 | JSON | `--json` | 자동화·AI 에이전트용 raw 데이터 + 페이지 메타 |
 | quiet | `--quiet` | 행별 최소 출력 |
 
+`--json`은 CLI가 가공한 출력 계약이다.
+NHN Cloud 또는 OpenStack 원본 응답의 최상위 래퍼를 그대로 보존하지 않을 수 있다.
+
+| 명령 | `--json` 출력 shape |
+|------|---------------------|
+| `logncrash search` | `{ totalItems, pageNumber, pageSize, data }` 객체 |
+| `logncrash export` | 파일 출력 전용. stdout JSON 없음 |
+| `deploy artifacts` | Deploy API `body` 객체 |
+| `deploy server-groups` | Deploy API `body` 객체 |
+| `deploy histories` | Deploy API `body` 객체 |
+| `deploy binary-groups` | `binaryGroups` 래퍼를 언랩한 배열 |
+| `deploy binaries` | `{ totalCount, binaries }` 객체 |
+| `deploy upload` | `{ downloadUrl, binaryKey }` 객체 |
+| `instance list` | `servers` 래퍼를 언랩한 server 배열 |
+| `instance get` | `server` 래퍼를 언랩한 단일 server 객체 |
+| `instance create --wait` | `server` 래퍼를 언랩한 단일 server 객체 |
+| `instance flavors` | `flavors` 래퍼를 언랩한 flavor 배열 |
+| `instance images` | `images` 래퍼를 언랩한 image 배열 |
+| `instance availability-zones` | `availabilityZoneInfo` 래퍼를 언랩한 배열 |
+| `instance keypairs` | `keypairs[].keypair`를 flatten한 keypair 배열 |
+| `instance volumes` | `volumeAttachments` 래퍼를 언랩한 attachment 배열 |
+| `network list` | VPC 배열 |
+| `network subnet list` | subnet 배열 |
+| `volume list` | volume 배열 |
+| `volume get` | 단일 volume 객체 |
+| `volume create` | 단일 volume 객체 |
+| `floatingip list` | floating IP 배열 |
+| `floatingip create` | 단일 floating IP 객체 |
+| `ncr list` | `registries` 래퍼를 언랩한 registry 배열 |
+| `ncr get` | `registry` 래퍼를 언랩한 단일 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의 단건 조회는 API 객체를 그대로 반환한다.
+예를 들어 `nks cluster get`, `nks cluster event`, `nks nodegroup get`, `nks addon-type get`, `nks addon get`, `nks cluster addon get`, `nks cluster ipacl`, `nks nodegroup autoscale` 은 table 출력용 최소 컬럼을 만들고 `--json` 에서는 raw 객체를 보존한다.
+NKS 쓰기 명령 중 생성·resize·설정 변경·노드 action·애드온 변경은 `{ uuid }` 응답을 반환한다.
+삭제 명령은 성공 메시지만 stderr에 쓰고 stdout은 비운다.
+`nks cluster kubeconfig` 는 kubeconfig 문자열을 stdout 또는 파일로 저장한다.
+
+예를 들어 `instance get --json`은 `.server.status`가 아니라 `.status`를 읽는다.
+
 ### 체이닝 예시
 
 ```bash
+# 인스턴스 상태 확인
+nhncloud instance get <instance-id> --json | jq -r '.status'
+
 # 검색 결과에서 logBody 만 추출
 nhncloud logncrash search --query '*' --from 1h --to now --json | jq -r '.data[].logBody'
 
@@ -489,6 +558,82 @@ nhncloud ncr tags <registry> <repository>
 nhncloud ncr tags <registry> <repository> --json
 ```
 
+### NHN Kubernetes Service (NKS)
+
+NKS는 `iaas` 자격증명으로 Keystone 토큰을 발급하고 `container-infra` API를 호출한다.
+지원 region은 `kr1`, `kr2`, `kr3` 이다.
+
+```bash
+# 지원 Kubernetes version / event type 조회
+nhncloud nks supports
+
+# 클러스터와 노드 그룹 조회
+nhncloud nks cluster list
+nhncloud nks cluster get <cluster>
+nhncloud nks cluster events <cluster>
+nhncloud nks cluster event <cluster> <event>
+nhncloud nks cluster ipacl <cluster>
+nhncloud nks nodegroup list <cluster>
+nhncloud nks nodegroup get <cluster> <nodegroup>
+nhncloud nks nodegroup autoscale <cluster> <nodegroup>
+
+# kubeconfig stdout 출력 또는 mode 0600 파일 저장
+nhncloud nks cluster kubeconfig <cluster>
+nhncloud nks cluster kubeconfig <cluster> --output ./kubeconfig
+nhncloud nks cluster kubeconfig <cluster> --output ./kubeconfig --force
+
+# 애드온 조회
+nhncloud nks addon-type list
+nhncloud nks addon-type get <addon-type>
+nhncloud nks addon list --k8s-version v1.30.1
+nhncloud nks addon get <addon>
+nhncloud nks cluster addon list <cluster>
+nhncloud nks cluster addon get <cluster> <addon>
+```
+
+복잡한 쓰기 작업은 공식 API payload를 JSON 파일로 전달한다.
+삭제·제거 명령은 비대화형 환경에서 `--yes` 가 필요하다.
+
+```bash
+# 클러스터 / 노드 그룹 생성
+nhncloud nks cluster create --file ./cluster-create.json
+nhncloud nks nodegroup create <cluster> --file ./nodegroup-create.json
+
+# resize / upgrade
+nhncloud nks cluster resize <cluster> --nodegroup worker --node-count 3
+nhncloud nks nodegroup upgrade <cluster> worker --version v1.30.1
+
+# 삭제 / 노드 action
+nhncloud nks cluster delete <cluster> --yes
+nhncloud nks nodegroup delete <cluster> worker --yes
+nhncloud nks nodegroup stop-node <cluster> worker --nodes node-1,node-2
+nhncloud nks nodegroup start-node <cluster> worker --nodes node-1,node-2
+
+# 애드온 설치 / 업데이트 / 제거
+nhncloud nks cluster addon install <cluster> \
+  --name coredns \
+  --version 1.0.0 \
+  --resolve-conflicts overwrite
+
+nhncloud nks cluster addon update <cluster> coredns \
+  --version 1.0.1 \
+  --resolve-conflicts preserve
+
+nhncloud nks cluster addon remove <cluster> coredns --yes
+
+# payload 파일 기반 변경
+nhncloud nks cluster set-ipacl <cluster> --file ./ipacl.json
+nhncloud nks cluster renew-certificate <cluster> --term-of-validity 3
+nhncloud nks cluster update-sgw <cluster> --ncr-sgw <uuid> --obs-sgw <uuid>
+nhncloud nks cluster set-control-plane-log <cluster> --file ./control-plane-log.json
+nhncloud nks nodegroup set-autoscale <cluster> worker --file ./autoscale.json
+nhncloud nks nodegroup set-metric-autoscale <cluster> worker --file ./metric-autoscale.json
+nhncloud nks nodegroup set-userscript <cluster> worker --file ./userscript.sh
+nhncloud nks nodegroup update-flavor <cluster> worker --flavor <flavor-uuid>
+nhncloud nks nodegroup set-fip-auto-bind <cluster> worker --file ./fip-auto-bind.json
+nhncloud nks nodegroup set-labels <cluster> worker --file ./labels.json
+```
+
 ## 개발
 
 ```bash
@@ -498,4 +643,5 @@ pnpm tsc --noEmit     # 타입 체크
 node dist/index.js instance --help
 node dist/index.js logncrash search --help
 node dist/index.js ncr --help
+node dist/index.js nks --help
 ```