@bifos/nhncloud-cli 0.13.0 → 0.14.0

package/package.json

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

package/skills/nhncloud-cli/SKILL.md

@@ -38,4 +38,5 @@ description: >-
 | Kubernetes Service | [nks.md](references/nks.md) |
 | Container Service | [ncs.md](references/ncs.md) |
 | API Gateway 서비스·리소스·스테이지·배포 조회와 Swagger export | [apigateway.md](references/apigateway.md) |
+| API Gateway `stage update`·`stage import-resources`·`stage deploy create`·`stage deploy rollback`, `resource set-path-plugin`·`set-method-plugin` | [apigateway.md](references/apigateway.md) |
 | 인증·profile·region·출력·검색 제한 문제 해결 | [troubleshooting.md](references/troubleshooting.md) |

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

@@ -1,13 +1,12 @@
-# API Gateway 조회 안내
+# API Gateway 조회·변경 안내
 
 `apigateway` 명령군은 API Gateway 서비스, 리소스, 스테이지, 배포 이력을 조회하고 스테이지의 Swagger를 내보낸다.
-현재는 조회만 지원하며 플러그인 적용, 스테이지 수정, 배포, 롤백 같은 쓰기 작업은 지원하지 않는다.
+스테이지의 백엔드 URL·설명 수정과 리소스 경로·메서드 플러그인 설정도 지원한다.
 
 ## 인증과 설정
 
 공통 UAK와 API Gateway `appKey`가 필요하다.
-`nhncloud configure --apigateway-appkey <appkey>`로 `profile`의 `apigateway.appkey`를 설정하거나, 명령마다 `--app-key <appkey>`를 넘긴다.
-`--app-key`가 `profile` 설정보다 우선한다.
+`nhncloud configure --apigateway-appkey <appkey>`로 `profile`의 `apigateway.appkey`를 설정한다.
 
 API 요청은 공통 UAK로 발급한 Bearer 토큰을 `X-NHN-Authorization` 헤더에 담는다.
 표준 `Authorization` 헤더가 아니므로 직접 API를 호출할 때 혼동하지 않는다.
@@ -15,12 +14,12 @@ API 요청은 공통 UAK로 발급한 Bearer 토큰을 `X-NHN-Authorization` 헤
 지원 `region`은 `kr1`, `kr2`, `kr3`이며 기본값은 `kr1`이다.
 
 ```bash
-nhncloud apigateway service list --region kr1 --app-key <appkey> --json
+nhncloud apigateway service list --region kr1 --json
 ```
 
 ## 명령
 
-아래 표의 공통 옵션은 `--region <region>`, `--app-key <key>`, `--profile <name>`이다.
+아래 표의 공통 옵션은 `--region <region>`, `--profile <name>`이다.
 루트 전역 옵션인 `--json`과 `--quiet`도 사용할 수 있다.
 
 | 명령 경로 | 인수 | 명령 옵션 |
@@ -30,11 +29,17 @@ nhncloud apigateway service list --region kr1 --app-key <appkey> --json
 | `nhncloud apigateway resource list` | `<service-id>` | 공통 옵션 |
 | `nhncloud apigateway resource parameters` | `<service-id> <resource-id>` | 공통 옵션 |
 | `nhncloud apigateway resource responses` | `<service-id> <resource-id>` | 공통 옵션 |
+| `nhncloud apigateway resource set-path-plugin` | `<service-id> <resource-id>` | 공통 옵션, `--config-file <path>`, `--dry-run`, `--yes` |
+| `nhncloud apigateway resource set-method-plugin` | `<service-id> <resource-id>` | 공통 옵션, `--config-file <path>`, `--dry-run`, `--yes` |
 | `nhncloud apigateway stage list` | `<service-id>` | 공통 옵션 |
 | `nhncloud apigateway stage swagger` | `<service-id> <stage-id>` | 공통 옵션, `--output <file>`, `--force` |
 | `nhncloud apigateway stage resources` | `<service-id> <stage-id>` | 공통 옵션 |
+| `nhncloud apigateway stage update` | `<service-id> <stage-id>` | 공통 옵션, `--backend-endpoint-url <url>`, `--description <text>`, `--yes` |
+| `nhncloud apigateway stage import-resources` | `<service-id> <stage-id>` | 공통 옵션, `--yes` |
+| `nhncloud apigateway stage deploy create` | `<service-id> <stage-id>` | 공통 옵션, `--description <text>`, `--no-wait`, `--timeout <sec>`, `--yes` |
 | `nhncloud apigateway stage deploy list` | `<service-id> <stage-id>` | 공통 옵션 |
 | `nhncloud apigateway stage deploy latest` | `<service-id> <stage-id>` | 공통 옵션 |
+| `nhncloud apigateway stage deploy rollback` | `<service-id> <stage-id> <deploy-id>` | 공통 옵션, `--yes` |
 
 `--quiet`가 식별자를 출력하는 명령은 다음과 같다.
 
@@ -42,12 +47,101 @@ nhncloud apigateway service list --region kr1 --app-key <appkey> --json
 - `resource list`: `resourceId`
 - `stage list`: `stageId`
 - `stage resources`: `stageResourceId`
+- `stage import-resources`·`stage deploy rollback`: `stageResourceId`
 - `stage deploy list`·`stage deploy latest`: `deployId`
+- `stage deploy create`: 대기 경로는 `deployId`, `--no-wait`는 출력 없음
 
 `resource parameters`와 `resource responses`는 식별자 출력이 없어 `--quiet`에서 아무것도 출력하지 않는다.
 `stage swagger`는 `--output`을 생략하면 Swagger JSON을 stdout에 출력하고, 지정하면 파일을 새로 만든 뒤 경로를 출력한다.
 기존 파일을 덮어쓰려면 `--force`를 함께 지정한다.
 
+## 플러그인 설정 파일
+
+`set-path-plugin`과 `set-method-plugin`은 API 요청 본문 형태의 JSON 파일을 `--config-file`로 받는다.
+경로 플러그인의 `applyChildPath`와 공통 필드인 `delete`는 모두 각 플러그인 항목에 넣는다.
+
+`path-plugins.json` 예시:
+
+```json
+{
+  "pathPluginList": [
+    {
+      "pluginType": "ADD_REQUEST_QUERY_PARAMETER",
+      "pluginConfigJson": {},
+      "applyChildPath": true,
+      "delete": false
+    }
+  ]
+}
+```
+
+`method-plugins.json` 예시:
+
+```json
+{
+  "methodPluginList": [
+    {
+      "pluginType": "HTTP",
+      "pluginConfigJson": {
+        "url": "https://backend.example.com"
+      },
+      "delete": false
+    }
+  ]
+}
+```
+
+`delete` 가 `true`면 해당 플러그인을 삭제하므로 `pluginConfigJson`을 생략할 수 있다.
+`applyChildPath`는 경로 플러그인에만 사용하며 메서드 설정에 넣으면 입력 오류로 거부된다.
+
+`set-path-plugin`과 `set-method-plugin`만 `--dry-run`을 제공한다.
+하위 적용 범위를 서버가 판정하고 CORS 플러그인이 기존 OPTIONS 메서드를 삭제·대체하므로,
+다른 위험 명령의 `--yes` 확인만으로는 되돌릴 수 없는 범위를 적용 전에 확인할 수 없기 때문이다.
+
+리소스 플러그인 변경을 스테이지에 반영하려면 별도의 리소스 반영과 배포가 필요하다.
+
+## 반영·배포·롤백
+
+리소스 변경이 트래픽에 적용되려면 서비스 리소스를 스테이지로 반영한 뒤 스테이지를 배포하는 두 단계를 거친다.
+반영·배포·롤백 명령은 모두 API 호출 전에 `--yes`가 필요하다.
+
+```text
+nhncloud apigateway stage import-resources <service-id> <stage-id> --yes
+nhncloud apigateway stage deploy create <service-id> <stage-id> [--description <text>] [--no-wait] [--timeout <sec>] --yes
+nhncloud apigateway stage deploy rollback <service-id> <stage-id> <deploy-id> --yes
+```
+
+배포 요청과 배포 결과 조회는 별도 API이므로 `deploy create`는 기본적으로 최신 배포 결과를 조회하며 완료까지 기다린다.
+요청 직후 반환하려면 `--no-wait`를 사용하고, 기다리는 시간의 상한은 `--timeout <sec>`로 지정한다.
+
+**대기가 끊겨 명령이 실패해도 배포 요청은 취소되지 않는다.**
+`--timeout` 초과나 결과 조회 실패로 끝나면 명령은 아래 경고를 함께 낸다.
+
+```text
+주의: 배포 요청은 이미 접수됐습니다. 재실행하지 말고 apigateway stage deploy latest 로 결과를 확인하세요.
+```
+
+이 경고가 나오면 재실행하지 않는다. 같은 스테이지에 두 번째 배포가 나간다.
+`deploy latest`로 결과를 확인한 뒤 다음 동작을 정한다.
+
+배포가 `FAILURE`로 끝난 경우에는 이 경고가 나오지 않는다.
+결과가 이미 확정됐으므로 원인을 고쳐 다시 배포하면 된다.
+
+바꿀 것이 없으면 반영과 배포 모두 오류로 끝난다(종료 코드 1). 빈 결과를 돌려주지 않는다.
+
+```text
+반영: API 오류: The latest resource has already been applied.
+배포: API 오류: Failed to deploy because stage is not changed.
+```
+
+반복 실행하는 자동화는 이 오류를 실패로 볼지 "이미 최신"으로 볼지 미리 정해 둔다.
+현재 상태만 알고 싶다면 `deploy latest`로 조회한다.
+
+`deploy rollback`은 선택한 배포 이력으로 스테이지 설정만 되돌린다.
+되돌린 설정을 트래픽에 적용하려면 `deploy create`를 다시 실행해야 한다.
+되돌리면 직전까지의 스테이지 설정은 남지 않는다.
+명령은 실행 후 `완료: 직전까지의 스테이지 설정은 이 배포 이력의 내용으로 대체됐습니다.`라고 알린다.
+
 ## JSON 구조
 
 API 응답 봉투의 `header`를 검사한 뒤 CLI는 아래 데이터를 꺼내 `--json`으로 출력한다.
@@ -96,3 +190,20 @@ diff -u specs/apigateway-swagger.json /tmp/apigateway-swagger.json
 
 `service list --quiet`과 `stage list --quiet`은 결과가 없으면 아무것도 출력하지 않는다.
 자동화에서는 빈 식별자를 다음 명령에 넘기기 전에 검사한다.
+
+플러그인 일괄 적용은 같은 설정 파일로 영향 범위를 먼저 확인한 뒤 실행한다.
+
+```bash
+nhncloud apigateway resource set-path-plugin <service-id> <resource-id> \
+  --config-file path-plugins.json --dry-run --json
+
+nhncloud apigateway resource set-path-plugin <service-id> <resource-id> \
+  --config-file path-plugins.json --yes
+```
+
+변경된 서비스 리소스를 스테이지에 반영하고 배포 완료까지 기다릴 수 있다.
+
+```bash
+nhncloud apigateway stage import-resources <service-id> <stage-id> --yes
+nhncloud apigateway stage deploy create <service-id> <stage-id> --yes
+```

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

@@ -27,8 +27,8 @@ nhncloud logncrash search \
 | 옵션 | 필수 | 설명 |
 |------|:---:|------|
 | `--query <lucene>` | 예 | Lucene 질의 문자열. API에 그대로 전달 |
-| `--from <time>` | 예 | 검색 시작. ISO8601 또는 상대시간 |
-| `--to <time>` | 예 | 검색 끝. ISO8601, 상대시간, `now` |
+| `--from <time>` | 예 | 검색 시작. 초와 시간대를 갖춘 ISO8601 또는 상대시간 |
+| `--to <time>` | 예 | 검색 끝. 초와 시간대를 갖춘 ISO8601, 상대시간, `now` |
 | `--page <n>` | 아니오 | 전환 호환용 pageNumber. 기본 0이며 0만 허용 |
 | `--size <n>` | 아니오 | pageSize. 기본 10, 범위 1~100 |
 | `--cursor <value>` | 아니오 | 직전 JSON 응답의 불투명한 `nextCursor` |
@@ -49,12 +49,20 @@ Lucene 예시:
 시간 입력:
 
 - `1h`, `30m`, `2d`, `now`
-- `2024-01-01T00:00:00+09:00` 같은 ISO8601 직접 입력
+- `2024-01-01T00:00:00+09:00` 이나 `2024-01-01T00:00:00Z` 같은 ISO8601 직접 입력
+- 초와 시간대를 모두 지정해야 한다. 날짜만 주거나(`2024-01-01`) 초·시간대가 빠지면
+  서버가 받지 않으므로 CLI 가 먼저 거부한다
 
 API 제약:
 
 - 검색 시작은 최근 90일 이내여야 한다.
 - 검색 범위는 31일 이하여야 한다.
+- 문서상 제약보다 짧은 기간에서도 서버가 500 응답을 낼 수 있다. 처리 가능한 기간의
+  경계는 프로젝트의 로그 양에 따라 달라진다.
+
+`search`는 기간을 자동으로 나누지 않는다. 서버가 500 응답을 반환하면 기간을 줄여
+다시 시도하라는 안내와 서버 응답의 `requestId`를 보여 준다. 넓은 기간을 훑어야 하면
+자동으로 기간을 나누는 `logncrash export`를 사용한다.
 
 ## 검색 출력
 
@@ -81,7 +89,24 @@ cursor는 파싱하거나 인코딩을 바꾸지 않고 받은 문자열 그대
 임의 페이지 이동은 지원하지 않으므로 `--page 1` 이상은 입력 오류다.
 
 전송 직후에는 인덱싱 지연으로 잠시 0건이 나올 수 있다.
-반복 검색이나 넓은 wildcard 검색은 시간 범위를 좁혀 확인한다.
+
+## 조회 횟수 제한
+
+짧은 시간에 여러 번 조회하면 조회 횟수 제한에 걸린다.
+이 응답은 HTTP 200에 봉투 오류로 오며 500과는 다른 원인이다.
+CLI는 둘을 구분해 안내한다.
+
+```text
+조회 횟수 제한에 걸렸습니다. 시간을 두고 다시 실행하세요. 검색 기간을 좁혀도 풀리지 않습니다.
+```
+
+**검색 기간을 좁히는 것은 해법이 아니다.**
+호출 한 번의 비용이 조회 기간에 거의 비례하지 않기 때문이다.
+같은 구간을 여러 창으로 나누면 오히려 제한을 더 빨리 소모한다.
+시간을 두고 다시 실행해야 한다.
+
+CLI는 자동으로 다시 시도하지 않는다.
+서버가 남은 시간을 알려주지 않아 얼마나 기다릴지 알 수 없고, 회복이 느려 대기가 실효를 갖기 어렵다.
 
 ## 대량 export
 
@@ -105,10 +130,35 @@ nhncloud logncrash export \
 | `--force` | 기존 파일 덮어쓰기 |
 | `--size <n>` | 폐기 예정 호환 옵션. 10~100 검증 후 경고하고 v3 요청에는 미전달 |
 
-scroll 계속 요청이 실패하면 CLI가 원본 오류를 보존한다.
-오류를 확인한 뒤 검색 시간 범위를 좁혀 다시 실행한다.
+scroll 시작이나 계속 요청에서 서버가 500 응답을 반환하면 CLI가 해당 기간을 절반으로
+줄여 자동으로 다시 시도한다. 성공한 기간 크기는 남은 구간에도 재사용하므로 사용자가
+직접 기간을 나눠 호출할 필요가 없다.
+
+더 나눌 수 없는 기간에서도 500 응답이 계속되거나 다른 오류가 발생하면 CLI가 원본
+오류를 보존한다.
 `--size`는 v3 scroll의 페이지 크기를 제어하지 않는다.
 
+조회 횟수 제한을 만나면 기간을 나누지 않고 즉시 멈춘다.
+나눌수록 호출이 늘어 제한을 더 소모하기 때문이다.
+
+### 중단된 추출 이어받기
+
+추출이 실패하면 `--output`은 만들어지지 않는다.
+대신 그때까지 받은 결과가 `<output>.partial`에 남고, 위치와 이어받는 방법을 stderr로 알린다.
+
+```text
+안내: 여기까지 받은 3000건을 logs.jsonl.partial 에 남겼습니다.
+안내: 이어받으려면 --from "<시각>" --to "<시각>" 로 다시 실행하세요. 경계 구간의 로그가 중복될 수 있습니다.
+```
+
+안내에 나온 `--from` 값과 원래 `--to`를 그대로 넘겨 다시 실행한다.
+그 값은 아직 받지 못한 구간의 시작이며, 이미 받은 부분과 경계에서 겹칠 수 있다.
+
+`--format json`이면 부분 파일도 배열을 닫아 그대로 파싱된다.
+한 건도 받지 못하고 실패하면 부분 파일을 만들지 않는다.
+
+부분 결과를 남기지 못하면 CLI가 그 사실을 경고로 알리고 원래 오류를 그대로 낸다.
+
 ## 로그 전송
 
 `logncrash send`는 collector host로 로그 한 건을 전송한다.

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
 ```