@bifos/nhncloud-cli 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bifos/nhncloud-cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "CLI tool for NHN Cloud services — AI agent & terminal friendly",
   "keywords": [
     "nhncloud",

package/skills/nhncloud-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nhncloud-cli
-description: NHN Cloud 서비스 CLI. commands --json catalog, configure, Log & Crash(logncrash search/send/export), Deploy(deploy run/artifacts/server-groups/histories/binary-groups/binaries/upload/download), Compute(instance), VPC/network, Block Storage(volume), Floating IP(floatingip), NHN Container Registry(ncr), NHN Kubernetes Service(nks supports/cluster/nodegroup/addon/kubeconfig) 등 NHN Cloud API를 터미널과 AI 에이전트에서 호출한다.
+description: NHN Cloud 서비스 CLI. commands --json catalog, configure, Log & Crash(logncrash search/send/export), Deploy(deploy run/artifacts/server-groups/histories/binary-groups/binaries/upload/download), Compute(instance), VPC/network, Block Storage(volume), Floating IP(floatingip), NHN Container Registry(ncr), NHN Kubernetes Service(nks supports/cluster/nodegroup/addon/kubeconfig), NHN Container Service(ncs template/workload 조회·생성·변경·실행제어, malware 검사 설정·결과 조회) 등 NHN Cloud API를 터미널과 AI 에이전트에서 호출한다.
 ---
 
 # nhncloud-cli
@@ -20,6 +20,7 @@ NHN Cloud 서비스를 AWS CLI 방식으로 호출하는 TypeScript CLI다.
 | Compute instance, network, volume, floatingip | [iaas.md](references/iaas.md) |
 | NCR 레지스트리, 이미지, 태그 조회 | [ncr.md](references/ncr.md) |
 | NKS 클러스터, 노드 그룹, 애드온, kubeconfig | [nks.md](references/nks.md) |
+| NCS template, workload 조회·생성·변경·실행제어, malware 검사 설정·결과 조회 | [ncs.md](references/ncs.md) |
 | 인증 실패, profile 누락, region mismatch, JSON shape 혼동, scroll 제한 | [troubleshooting.md](references/troubleshooting.md) |
 
 ## 공통 우선 규칙
@@ -53,6 +54,7 @@ nhncloud logncrash search --query '*' --from 1h --to now --json
 | `floatingip` | Floating IP 조회·발급·삭제 |
 | `ncr` | Container Registry registry/image/tag 조회 |
 | `nks` | Kubernetes cluster/nodegroup/addon/kubeconfig 관리 |
+| `ncs` | Container Service template/workload 조회·생성·변경·실행제어, malware 검사 설정·결과 조회 |
 
 ## 안전한 탐색 순서
 

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

@@ -0,0 +1,167 @@
+# NCS Reference
+
+`ncs` 명령군은 NHN Container Service 의 template(설계도)과 workload(런타임 실행)를 조회·관리한다.
+template 의 생성·삭제, workload 의 생성·변경(update/patch)·실행제어(일시정지/재개/재시작/삭제), 악성코드 검사(malware) 설정·결과 조회를 지원한다.
+
+## 설정
+
+공통 UAK와 NCS appkey가 필요하다.
+인증은 Deploy 와 같은 UAK OAuth Bearer 토큰을 재사용한다(profile 토큰 캐시 공유).
+
+`configure` 마법사는 아직 ncs를 지원하지 않는다.
+`--app-key` 옵션 또는 `~/.nhncloud/credentials.json` 의 `profiles.<profile>.ncs.appkey` 를 직접 추가한다.
+
+```bash
+nhncloud ncs template list --app-key <appkey>
+```
+
+`--app-key <key>`는 profile의 `ncs.appkey`보다 우선한다.
+기본 region은 `kr1`이고, `kr1`, `kr3`만 지원한다(판교·광주).
+
+## Template(설계도) 조회
+
+```bash
+nhncloud ncs template list --app-key <appkey> --json
+nhncloud ncs template list --region kr3 --app-key <appkey> --json
+nhncloud ncs template get <template-id> --app-key <appkey> --json
+nhncloud ncs template version list <template-id> --app-key <appkey> --json
+nhncloud ncs template version get <template-id> <version> --app-key <appkey> --json
+```
+
+## Template(설계도) 생성/삭제
+
+복잡한 생성 입력은 공식 API payload 를 JSON 파일로 전달한다(`--file`).
+삭제는 위험 명령이라 비대화형 환경에서 `--yes` 가 필수이고, TTY 에서는 확인 프롬프트가 뜬다.
+
+```bash
+nhncloud ncs template create --file ./template-create.json --app-key <appkey>
+nhncloud ncs template delete <template-id> --yes --app-key <appkey>
+```
+
+버전 생성도 동일하게 `--file` 을 쓰며, payload 의 `sourceVersion` 필드가 필수다(어느 버전을 기준으로 새 버전을 만들지 지정).
+
+```bash
+nhncloud ncs template version create <template-id> --file ./version-create.json --app-key <appkey>
+nhncloud ncs template version delete <template-id> <version> --yes --app-key <appkey>
+```
+
+## Workload(런타임 실행) 조회
+
+```bash
+nhncloud ncs workload list --app-key <appkey> --json
+nhncloud ncs workload list --q <워크로드 이름> --app-key <appkey> --json
+nhncloud ncs workload get <workload-id> --app-key <appkey> --json
+```
+
+컨테이너 로그와 이벤트는 특정 task 를 지정해야 한다.
+`--task`는 `workload get` 응답의 `tasks[].id`에서 얻는다.
+
+```bash
+nhncloud ncs workload logs <workload-id> --task <task-id> --container <name> --app-key <appkey> --json
+nhncloud ncs workload logs <workload-id> --task <task-id> --container <name> --from 1h --to now --app-key <appkey>
+nhncloud ncs workload events <workload-id> --task <task-id> --app-key <appkey> --json
+nhncloud ncs workload events <workload-id> --task <task-id> --type Warning --app-key <appkey> --json
+```
+
+실행 히스토리와 예약 실행 히스토리는 workload 단위로 조회한다.
+
+```bash
+nhncloud ncs workload history <workload-id> --app-key <appkey> --json
+nhncloud ncs workload history get <workload-id> <history-id> --app-key <appkey> --json
+nhncloud ncs workload schedule-history <workload-id> --app-key <appkey> --json
+```
+
+## Workload 실행제어
+
+일시정지·재개는 workload 단위, 재시작은 task 단위(`--task` 필수), 삭제는 위험 명령이라 `--yes` 필수(비대화형) 또는 확인 프롬프트(TTY)를 거친다.
+
+```bash
+nhncloud ncs workload pause <workload-id> --app-key <appkey>
+nhncloud ncs workload resume <workload-id> --app-key <appkey>
+nhncloud ncs workload restart <workload-id> --task <task-id> --app-key <appkey>
+nhncloud ncs workload delete <workload-id> --yes --app-key <appkey>
+```
+
+## Workload 생성/변경
+
+생성은 비동기다.
+`--wait`를 주면 `Running` 상태가 될 때까지 폴링하고, `--timeout <sec>`(기본 300)으로 대기 시간을 조절한다.
+변경은 `update`(PUT, 전체 교체)와 `patch`(PATCH, JSON Patch 배열 부분 변경) 두 가지다.
+
+```bash
+nhncloud ncs workload create --file ./workload-create.json --app-key <appkey> --json
+nhncloud ncs workload create --file ./workload-create.json --wait --timeout 600 --app-key <appkey> --json
+
+nhncloud ncs workload update <workload-id> --file ./workload-update.json --app-key <appkey> --json
+nhncloud ncs workload patch <workload-id> --file ./workload-patch.json --app-key <appkey> --json
+```
+
+`patch`의 `--file`은 JSON Patch(RFC 6902) 배열이다.
+
+```json
+[
+  { "op": "replace", "path": "/workload/desired", "value": 2 }
+]
+```
+
+## 악성코드 검사(malware)
+
+설정은 appkey 단위, 결과는 workload 실행 히스토리 단위로 조회한다.
+`historyId`는 `workload history` 목록 또는 `workload history get`의 `id`를 사용한다.
+
+```bash
+nhncloud ncs malware config get --app-key <appkey> --json
+nhncloud ncs malware config set --enabled true --app-key <appkey>
+nhncloud ncs malware config set --enabled false --app-key <appkey>
+
+nhncloud ncs malware result <workload-id> <history-id> --app-key <appkey> --json
+```
+
+## 체이닝 예시
+
+```bash
+nhncloud ncs template list --app-key <appkey> --json | jq -r '.[].id'
+nhncloud ncs workload list --app-key <appkey> --json | jq -r '.[] | select(.status=="Failed") | .id'
+nhncloud ncs workload get <workload-id> --app-key <appkey> --json | jq -r '.tasks[].id'
+nhncloud ncs workload history <workload-id> --app-key <appkey> --json | jq -r '.[0].id' # 최신 historyId
+```
+
+## 옵션
+
+| 옵션 | 설명 |
+|------|------|
+| `--region <region>` | NCS region. 기본 `kr1`. `kr1`·`kr3`만 지원 |
+| `--app-key <key>` | NCS appkey |
+| `--profile <name>` | 사용할 profile |
+| `--page <page>` / `--size <size>` | 페이지네이션 (기본 size는 명령별 상이 — `--help` 확인) |
+| `--q <query>` | workload list·events 필터 |
+| `--task <taskId>` | `workload logs`·`workload events`·`workload restart` 필수 |
+| `--container <name>` | `workload logs` 필수 |
+| `--sort <sort>` | `workload history` 정렬 (역순은 필드명 앞에 `-`) |
+| `--file <path>` | `template create`·`template version create`·`workload create`·`workload update`·`workload patch` 필수 — JSON payload 파일 경로 (`patch`는 JSON Patch 배열) |
+| `--wait` / `--timeout <sec>` | `workload create` — Running 상태 폴링(`--timeout` 기본 300초) |
+| `--enabled <value>` | `malware config set` 필수. `true` 또는 `false` |
+| `--yes` | `template delete`·`template version delete`·`workload delete` — 비대화형 환경 필수, TTY 는 생략 시 확인 프롬프트 |
+
+## 주의사항
+
+- appkey는 NCS service appkey다. 인증 secret은 공통 UAK secret을 사용한다.
+- `workload logs`·`workload events`는 task 단위 조회라 `--task` 없이는 입력 오류다.
+- `workload restart`도 task 단위라 `--task` 없이는 입력 오류다.
+- `workload schedule-history`는 page/size를 아직 노출하지 않는다(대량 이력 시 첫 페이지만 반환될 수 있음 — ADR-020).
+- template/workload id, history id 인수가 공백이면 입력 오류다.
+- `template version create`의 `--file` payload 는 `sourceVersion` 필드가 필수다 — 누락 시 API 오류로 반환된다(클라이언트가 사전 검증하지 않음).
+- `--file` 로 지정한 JSON payload 파일은 1MB 를 넘거나 디렉터리면 입력 오류다.
+- 삭제 명령(`template delete`·`template version delete`·`workload delete`)은 비대화형 환경에서 `--yes` 없이 실행하면 입력 오류다.
+- `workload create --wait`는 타임아웃까지 `Running` 상태에 도달하지 못하면 마지막 상태를 메시지에 포함해 API 오류로 반환한다.
+- `workload patch`는 `Content-Type: application/json-patch+json`으로 전송된다 — `--file`에는 JSON Patch 배열(`op`/`path`/`value`)을 담아야 한다.
+- `malware config set --enabled`는 `true`·`false` 외의 값이면 입력 오류다.
+
+## 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| UAK 누락 또는 NCS appkey 미설정 | 4 |
+| UAK 인증 실패 | 2 |
+| 지원하지 않는 region, 빈 id 인수, `--task`/`--container` 누락, `--file` 파일 오류(누락·디렉터리·크기초과·JSON 파싱 실패), `--enabled` 값 오류(`true`/`false` 외), 비대화형 삭제 시 `--yes` 누락 | 3 |
+| NCS API 오류 (payload 필수값 누락, `workload create --wait` 타임아웃 등 서버측 검증·폴링 실패 포함) | 1 |