@bifos/nhncloud-cli 0.13.0 → 0.15.0

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

@@ -8,23 +8,22 @@ template 의 생성·삭제, workload 의 생성·변경(update/patch)·실행
 공통 UAK와 NCS appkey가 필요하다.
 인증은 Deploy 와 같은 UAK OAuth Bearer 토큰을 재사용한다(profile 토큰 캐시 공유).
 
-`nhncloud configure` (대화형 또는 `--ncs-appkey`) 로 설정하거나, `--app-key` 옵션으로 직접 넘긴다.
+`nhncloud configure` (대화형 또는 `--ncs-appkey`) 로 설정한다.
 
 ```bash
-nhncloud ncs template list --app-key <appkey>
+nhncloud ncs template list
 ```
 
-`--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
+nhncloud ncs template list --json
+nhncloud ncs template list --region kr3 --json
+nhncloud ncs template get <template-id> --json
+nhncloud ncs template version list <template-id> --json
+nhncloud ncs template version get <template-id> <version> --json
 ```
 
 ## Template(설계도) 생성/삭제
@@ -33,33 +32,33 @@ nhncloud ncs template version get <template-id> <version> --app-key <appkey> --j
 삭제는 위험 명령이라 비대화형 환경에서 `--yes` 가 필수이고, TTY 에서는 확인 프롬프트가 뜬다.
 
 ```bash
-nhncloud ncs template create --file ./template-create.json --app-key <appkey>
-nhncloud ncs template delete <template-id> --yes --app-key <appkey>
+nhncloud ncs template create --file ./template-create.json
+nhncloud ncs template delete <template-id> --yes
 ```
 
 버전 생성도 동일하게 `--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>
+nhncloud ncs template version create <template-id> --file ./version-create.json
+nhncloud ncs template version delete <template-id> <version> --yes
 ```
 
 ## 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
+nhncloud ncs workload list --json
+nhncloud ncs workload list --q <워크로드 이름> --json
+nhncloud ncs workload get <workload-id> --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
+nhncloud ncs workload logs <workload-id> --task <task-id> --container <name> --json
+nhncloud ncs workload logs <workload-id> --task <task-id> --container <name> --from 1h --to now
+nhncloud ncs workload events <workload-id> --task <task-id> --json
+nhncloud ncs workload events <workload-id> --task <task-id> --type Warning --json
 ```
 
 ### logs·events 시간 필터
@@ -102,9 +101,9 @@ AI 에이전트는 같은 입력으로 인증 재시도를 반복하지 말고
 실행 히스토리와 예약 실행 히스토리는 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
+nhncloud ncs workload history <workload-id> --json
+nhncloud ncs workload history get <workload-id> <history-id> --json
+nhncloud ncs workload schedule-history <workload-id> --json
 ```
 
 ## Workload 실행제어
@@ -112,10 +111,10 @@ nhncloud ncs workload schedule-history <workload-id> --app-key <appkey> --json
 일시정지·재개는 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>
+nhncloud ncs workload pause <workload-id>
+nhncloud ncs workload resume <workload-id>
+nhncloud ncs workload restart <workload-id> --task <task-id>
+nhncloud ncs workload delete <workload-id> --yes
 ```
 
 ## Workload 생성/변경
@@ -125,11 +124,11 @@ nhncloud ncs workload delete <workload-id> --yes --app-key <appkey>
 변경은 `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 create --file ./workload-create.json --json
+nhncloud ncs workload create --file ./workload-create.json --wait --timeout 600 --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
+nhncloud ncs workload update <workload-id> --file ./workload-update.json --json
+nhncloud ncs workload patch <workload-id> --file ./workload-patch.json --json
 ```
 
 `patch`의 `--file`은 JSON Patch(RFC 6902) 배열이다.
@@ -146,20 +145,20 @@ nhncloud ncs workload patch <workload-id> --file ./workload-patch.json --app-key
 `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 config get --json
+nhncloud ncs malware config set --enabled true
+nhncloud ncs malware config set --enabled false
 
-nhncloud ncs malware result <workload-id> <history-id> --app-key <appkey> --json
+nhncloud ncs malware result <workload-id> <history-id> --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
+nhncloud ncs template list --json | jq -r '.[].id'
+nhncloud ncs workload list --json | jq -r '.[] | select(.status=="Failed") | .id'
+nhncloud ncs workload get <workload-id> --json | jq -r '.tasks[].id'
+nhncloud ncs workload history <workload-id> --json | jq -r '.[0].id' # 최신 historyId
 ```
 
 ## 옵션
@@ -167,7 +166,6 @@ nhncloud ncs workload history <workload-id> --app-key <appkey> --json | jq -r '.
 | 옵션 | 설명 |
 |------|------|
 | `--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 필터 |

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

@@ -22,12 +22,19 @@ nhncloud nks nodegroup list <cluster> --json
 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 event <cluster> <event-uuid> --json
 nhncloud nks cluster ipacl <cluster> --json
 nhncloud nks cluster kubeconfig <cluster>
 nhncloud nks cluster kubeconfig <cluster> --output ./kubeconfig
 ```
 
+`events`는 `<cluster>`에 이름과 UUID를 모두 받는다.
+NKS 이벤트 API 자체는 UUID만 받지만 CLI가 이름을 UUID로 해석한다.
+
+`event` 단건 조회는 `events` 출력의 `uuid` 열 값을 넘긴다.
+정수 `id`로는 조회되지 않는다.
+`details`는 표에서 줄여 보여 주므로 전문은 `--json`으로 본다.
+
 `kubeconfig`는 문자열을 stdout으로 출력하거나 `--output` 파일에 저장한다.
 
 ## Nodegroup 조회와 변경
@@ -42,13 +49,65 @@ 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 upgrade <cluster> <nodegroup> --kube-version v1.31.4
 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
 ```
 
+`upgrade` 는 control plane 업그레이드에도 쓴다. 아래 "Cluster 업그레이드" 를 본다.
+
+## Cluster 업그레이드
+
+클러스터 버전 업그레이드에 별도 명령은 없다.
+`nodegroup upgrade` 하나로 control plane 과 워커를 모두 올린다.
+
+```bash
+# 1. control plane — 노드그룹 이름을 default-master 로 지정한다
+nhncloud nks nodegroup upgrade <cluster> default-master --kube-version v1.31.4
+
+# 2. 워커 노드그룹 — 노드그룹마다 한 번씩 실행한다
+nhncloud nks nodegroup upgrade <cluster> <nodegroup> --kube-version v1.31.4
+```
+
+순서는 정해져 있다.
+control plane 을 먼저 올린 뒤에야 워커를 올릴 수 있다.
+
+`default-master` 는 CLI 로 존재를 확인할 수 없다.
+
+- `nodegroup list` 응답에 나오지 않는다.
+- `nodegroup get <cluster> default-master` 는 403 으로 막혀 있다.
+
+### 업그레이드 대상 판단
+
+워커 노드그룹만 보면 최신인 것처럼 보인다.
+control plane 이 먼저 올라가야 워커의 대상 버전이 생기기 때문이다.
+그래서 `cluster get` 의 `labels` 를 함께 본다.
+
+| 조회 대상 | `kube_version_status` | `upgradable_kube_versions` |
+|---|---|---|
+| 워커 노드그룹 | `LATEST` | `[]` |
+| 클러스터 | `NEED_K8S_UPGRADE` | `["v1.33.4"]` |
+
+위 값은 실측이다.
+공식 문서는 `kube_version_status` 의 값 목록을 정의하지 않으므로 다른 값이 올 수 있다.
+
+### 워커 업그레이드 중 서비스 영향 조절
+
+두 옵션은 워커 업그레이드에만 의미가 있고 기본값은 모두 1이다.
+
+- `--num-buffer-nodes <n>`: 축출된 파드를 다시 받아 줄 여유 노드 수. 업그레이드가 끝나면 자동 삭제되지만 그동안 인스턴스 요금이 청구된다. 0으로 두면 기존 노드만으로 재배치해야 해 실패 위험이 커진다.
+- `--num-max-unavailable-nodes <n>`: 한 번에 서비스 불가 상태로 둘 노드 수. 크게 잡으면 빨라지고 가용성이 낮아진다.
+
+### 사전 조건
+
+- control plane 과 모든 워커 노드그룹의 Kubernetes 버전이 일치해야 한다.
+- 마이너 버전 기준 한 단계씩만 올린다. 건너뛰기와 다운그레이드는 지원하지 않는다.
+- 클러스터가 다른 작업으로 업데이트 중이면 업그레이드가 안 된다.
+- NKS 레지스트리가 활성화되지 않은 클러스터는 업그레이드가 안 된다.
+- 데몬셋 파드는 축출되지 않고, PodDisruptionBudget 설정 때문에 축출이 실패하면 업그레이드도 실패한다.
+
 ## Addon 조회와 변경
 
 ```bash
@@ -58,8 +117,8 @@ 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 install <cluster> --name coredns --addon-version 1.0.0 --resolve-conflicts overwrite
+nhncloud nks cluster addon update <cluster> coredns --addon-version 1.0.1 --resolve-conflicts preserve
 nhncloud nks cluster addon remove <cluster> coredns --yes
 ```