@bifos/nhncloud-cli 0.6.0 → 0.8.0

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 |

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

@@ -0,0 +1,95 @@
+# NKS Reference
+
+`nks` 명령군은 NHN Kubernetes Service를 관리한다.
+IaaS 자격증명으로 Keystone token을 발급하고 `container-infra` API를 호출한다.
+지원 region은 `kr1`, `kr2`, `kr3`이다.
+
+## Discovery 순서
+
+```bash
+nhncloud commands --json | jq '.commands[] | select(.path|startswith("nks"))'
+nhncloud nks supports --json
+nhncloud nks cluster list --json
+nhncloud nks cluster get <cluster> --json
+nhncloud nks nodegroup list <cluster> --json
+```
+
+클러스터 생성이나 변경 전에는 지원 Kubernetes version, flavor, network, 기존 cluster/nodegroup 상태를 먼저 조회한다.
+
+## Cluster 조회
+
+```bash
+nhncloud nks cluster list --json
+nhncloud nks cluster get <cluster> --json
+nhncloud nks cluster events <cluster> --json
+nhncloud nks cluster event <cluster> <event> --json
+nhncloud nks cluster ipacl <cluster> --json
+nhncloud nks cluster kubeconfig <cluster>
+nhncloud nks cluster kubeconfig <cluster> --output ./kubeconfig
+```
+
+`kubeconfig`는 문자열을 stdout으로 출력하거나 `--output` 파일에 저장한다.
+
+## Nodegroup 조회와 변경
+
+```bash
+nhncloud nks nodegroup list <cluster> --json
+nhncloud nks nodegroup get <cluster> <nodegroup> --json
+nhncloud nks nodegroup autoscale <cluster> <nodegroup> --json
+nhncloud nks nodegroup create <cluster> --file ./nodegroup-create.json
+nhncloud nks nodegroup delete <cluster> <nodegroup> --yes
+nhncloud nks nodegroup stop-node <cluster> <nodegroup> --nodes node-1,node-2
+nhncloud nks nodegroup start-node <cluster> <nodegroup> --nodes node-1,node-2
+nhncloud nks nodegroup set-autoscale <cluster> <nodegroup> --file ./autoscale.json
+nhncloud nks nodegroup set-metric-autoscale <cluster> <nodegroup> --file ./metric-autoscale.json
+nhncloud nks nodegroup upgrade <cluster> <nodegroup> --version v1.30.1
+nhncloud nks nodegroup set-userscript <cluster> <nodegroup> --file ./userscript.sh
+nhncloud nks nodegroup update-flavor <cluster> <nodegroup> --flavor <flavor-uuid>
+nhncloud nks nodegroup set-fip-auto-bind <cluster> <nodegroup> --file ./fip-auto-bind.json
+nhncloud nks nodegroup set-labels <cluster> <nodegroup> --file ./labels.json
+```
+
+## Addon 조회와 변경
+
+```bash
+nhncloud nks addon-type list --json
+nhncloud nks addon-type get <addon-type> --json
+nhncloud nks addon list --k8s-version v1.30.1 --json
+nhncloud nks addon get <addon> --json
+nhncloud nks cluster addon list <cluster> --json
+nhncloud nks cluster addon get <cluster> <addon> --json
+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
+```
+
+## Cluster 생성과 변경
+
+복잡한 생성/설정 작업은 공식 API payload를 JSON 파일로 전달한다.
+payload에는 민감값이 들어갈 수 있으므로 로그나 이슈에 그대로 붙이지 않는다.
+
+```bash
+nhncloud nks cluster create --file ./cluster-create.json
+nhncloud nks cluster delete <cluster> --yes
+nhncloud nks cluster resize <cluster> --nodegroup worker --node-count 3
+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
+```
+
+## JSON 출력
+
+목록 조회는 배열 또는 목록 객체로 출력한다.
+단건 조회와 설정 조회는 API raw 객체를 보존하는 쪽을 우선한다.
+생성, resize, 설정 변경, 노드 action, 애드온 변경은 `{ uuid }` 응답을 반환한다.
+삭제 명령은 성공 메시지만 stderr에 쓰고 stdout은 비운다.
+
+## 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| IaaS 자격증명 누락 또는 불완전 | 4 |
+| Keystone 또는 NKS 인증 실패 | 2 |
+| 지원하지 않는 region, payload JSON 파싱 실패, `--yes` 누락 | 3 |
+| NKS API 오류 또는 응답 형식 불일치 | 1 |

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

@@ -0,0 +1,91 @@
+# Troubleshooting Reference
+
+실패 시 exit code, 인증 모델, profile/region, JSON shape를 먼저 확인한다.
+
+## 빠른 진단 순서
+
+1. 명령에 `--profile <name>`을 명시했는지 확인한다.
+2. IaaS/NKS/NCR 명령이면 `--region <region>`이 의도와 맞는지 확인한다.
+3. 조회 명령을 `--json`으로 다시 실행해 stdout shape를 확인한다.
+4. `nhncloud commands --json`으로 실제 command path와 option 이름을 확인한다.
+5. exit code를 확인한다.
+6. 서비스별 인증 모델을 대조한다.
+
+## 인증 모델
+
+| 서비스 | 비밀 | 인증 방식 |
+|--------|------|-----------|
+| Log & Crash 검색/export | appkey + secret | `X-LNCS-SECRET` |
+| Log & Crash send | appkey | body `projectName=appkey`, 인증 헤더 없음 |
+| Deploy | UAK id + secret | OAuth Bearer token |
+| Instance/network/volume/floatingip | tenantId + username + API password | Keystone `X-Auth-Token` |
+| NKS | tenantId + username + API password | Keystone `X-Auth-Token` + container-infra API version |
+| NCR registry | UAK id + secret + NCR appkey | `X-TC-AUTHENTICATION-*` |
+| NCR images/tags | UAK id + secret | HTTP Basic Auth to Harbor REST |
+
+## Exit code
+
+| exit code | 의미 | 대표 원인 |
+|-----------|------|-----------|
+| 1 | API 오류 | 4xx/5xx, 봉투 실패, wait timeout |
+| 2 | 인증 실패 | UAK/secret/password 오류, 권한 부족 |
+| 3 | 입력 오류 | 필수 옵션 누락, region 미지원, 시간 범위 초과, `--yes` 누락 |
+| 4 | config 오류 | profile 없음, 자격증명 블록 누락 |
+
+## Profile 누락
+
+profile은 다음 순서로 해석된다.
+
+1. `--profile <name>`
+2. `NHNCLOUD_PROFILE`
+3. `~/.nhncloud/config.json`의 `defaultProfile`
+4. `default`
+
+자동화에서 의도와 다른 profile이 쓰이면 `--profile`을 명시한다.
+
+## Region mismatch
+
+IaaS/NKS/NCR은 region별 endpoint를 사용한다.
+리소스가 보이지 않으면 같은 profile에서 다른 region을 조회했을 수 있다.
+
+```bash
+nhncloud instance list --region kr1 --json
+nhncloud instance list --region kr2 --json
+nhncloud nks cluster list --region kr1 --json
+nhncloud ncr list --region kr2 --json
+```
+
+## JSON shape 혼동
+
+CLI는 API wrapper를 일관되게 언랩한다.
+예를 들어 `instance get --json`은 `.server.status`가 아니라 `.status`다.
+목록과 단건의 shape가 다를 수 있으므로 jq path를 쓰기 전에 `--json` 원문을 확인한다.
+
+```bash
+nhncloud instance get <instance-id> --json | jq keys
+nhncloud ncr list --json | jq '.[0] | keys'
+```
+
+## Log & Crash 검색 제한
+
+- `--from`은 최근 90일 이내여야 한다.
+- `--to - --from` 범위는 31일 이하여야 한다.
+- scrollKey는 1분 만료다.
+- export가 중간 실패하면 검색 범위를 좁히거나 `--size`를 키운다.
+
+## 쓰기 명령 confirm
+
+삭제, 제거, 비용 발생 가능 명령은 비대화형 환경에서 `--yes`가 필요할 수 있다.
+
+```bash
+nhncloud instance delete <instance-id> --yes
+nhncloud floatingip delete <floatingip-id> --yes
+nhncloud nks cluster delete <cluster> --yes
+nhncloud nks cluster addon remove <cluster> <addon> --yes
+```
+
+## stdout/stderr 분리
+
+데이터는 stdout에 출력된다.
+진행 상황, 저장 완료, 성공 메시지, 에러는 stderr에 출력된다.
+스크립트에서 stdout만 파싱하고 stderr는 로그로 분리한다.