@bifos/nhncloud-cli 0.10.1 → 0.12.0

package/README.md

@@ -6,8 +6,9 @@
 [![license](https://img.shields.io/npm/l/@bifos/nhncloud-cli.svg)](https://github.com/jon890/nhncloud-cli/blob/main/LICENSE)
 
 NHN Cloud 서비스를 AWS CLI 방식으로 호출하는 통합 CLI.
-현재 106개 command catalog 항목을 지원한다.
-`configure`, `commands`, `logncrash search/send/export`, `deploy`, `instance`, `network`, `volume`, `floatingip`, `ncr`, `nks`, `ncs` 명령으로 NHN Cloud 서비스를 조회·운영할 수 있다.
+현재 147개 command catalog 항목을 지원한다.
+`configure`, `commands`, `logncrash search/send/export`, `deploy`, `instance`, `network`, `volume`, `floatingip` 명령을 지원한다.
+`loadbalancer`, `ncr`, `nks`, `ncs` 명령으로 NHN Cloud 서비스를 조회·운영할 수 있다.
 `skills`/`doctor` 로 Claude Code 스킬 설치와 상태 진단을 지원한다.
 
 ## 설치
@@ -24,17 +25,17 @@ npm install -g @bifos/nhncloud-cli
 nhncloud configure
 ```
 
-- profile → UAK(id/secret) → logncrash appkey/secret → iaas 자격증명 → ncr appkey → ncs appkey 순으로 입력한다.
+- profile → 공통 UAK(id/secret) → logncrash appkey → iaas 자격증명 → ncr appkey → ncs appkey 순으로 입력한다.
 - profile 은 프로젝트 단위다 — 여러 NHN Cloud 프로젝트를 쓰면 profile 을 분리하되, 같은 UAK 를 쓴다면
   대화형 마법사가 기존 profile 의 UAK 재사용 여부를 먼저 물어 재입력을 줄여준다.
 - 저장 전 연결 테스트를 자동으로 수행한다 (`--no-verify` 로 생략 가능).
 - CI/자동화는 flag 로 비대화형 설정이 가능하다.
 
 ```bash
-# UAK + logncrash + ncs 비대화형 설정
+# 공통 UAK + logncrash + ncs 비대화형 설정
 nhncloud configure \
-  --uak-id <id> --uak-secret <secret> \
-  --logncrash-appkey <key> --logncrash-secret <secret> \
+  --uak-id <uak-id> --uak-secret <uak-secret> \
+  --logncrash-appkey <appkey> \
   [--ncs-appkey <appkey>] \
   --no-verify
 
@@ -142,6 +143,11 @@ nhncloud deploy download <target> --binary-group <key> --binary-key <binary-key>
 
 ### 로그 검색
 
+Log & Crash Search v3는 profile의 logncrash appkey와 공통 UAK를 사용한다.
+CLI가 UAK를 OAuth 토큰으로 교환해 `X-NHN-Authorization: Bearer <token>`으로 인증한다.
+기존 logncrash secret은 검색에 사용하거나 새 설정에 저장하지 않는다.
+전환 호환 옵션 `nhncloud configure --logncrash-secret`은 경고 후 무시한다.
+
 ```bash
 # 최근 1시간 NORMAL 로그
 nhncloud logncrash search \
@@ -160,6 +166,15 @@ nhncloud logncrash search \
   --query 'body:*request_received*' \
   --from 1h \
   --to now
+
+# 다음 페이지 조회: 직전 JSON의 nextCursor를 그대로 전달
+next_cursor="$(nhncloud logncrash search \
+  --query '*' --from 1h --to now --json | jq -r '.nextCursor // empty')"
+if [ -n "$next_cursor" ]; then
+  nhncloud logncrash search \
+    --query '*' --from 1h --to now \
+    --cursor "$next_cursor" --json
+fi
 ```
 
 `--query` 는 콘솔의 간편 검색어가 아니라 Log & Crash Search API 의 Lucene 쿼리다.
@@ -169,6 +184,9 @@ body 검색 의도가 명확하면 `body:<keyword>` 또는 `body:*<keyword>*`
 API 제약상 검색 시작은 최근 90일 이내, 검색 범위는 31일 이하여야 한다 (초과 시 입력 오류로 거절).
 전송 직후에는 인덱싱 지연으로 잠시 0건이 나올 수 있다.
 반복 검색이나 넓은 wildcard 검색은 API rate limit 에 걸릴 수 있으므로 시간 범위를 좁혀 확인한다.
+검색 결과는 `logTime DESC`로 고정 정렬한다.
+`--page`는 전환 호환을 위해 남아 있지만 `0`만 허용한다.
+다음 페이지는 JSON 응답에 `nextCursor`가 있을 때 그 값을 `--cursor`로 변형 없이 전달한다.
 
 ### 로그 대량 추출 (export)
 
@@ -186,7 +204,9 @@ nhncloud logncrash export --query 'logType:"ERROR"' --from 1h --to now \
 
 단발 검색(`search`)과 달리 scroll API 로 전체 결과(최대 10만 건)를 순회해 파일로 저장한다.
 진행 상황은 stderr, 데이터는 파일에만 기록된다(stdout 비움).
-scrollKey 유효기간은 1분이므로 데이터가 많을 때는 `--size` 를 키워 페이지 수를 줄이는 것을 권장한다.
+중간 요청이 실패하면 원본 오류를 확인하고 검색 시간 범위를 좁혀 다시 실행한다.
+기존 `--size`는 전환 호환 옵션이다.
+명시하면 10~100 범위를 검증하고 폐기 예정 경고를 출력하지만 Search v3 요청에는 전달하지 않는다.
 시간 범위 제한은 search 와 동일(90일 이내·31일 이하).
 
 #### export 옵션
@@ -198,7 +218,7 @@ scrollKey 유효기간은 1분이므로 데이터가 많을 때는 `--size` 를
 | `--to <time>` | 예 | 검색 끝 |
 | `--output <file>` | 예 | 출력 파일 경로 |
 | `--format <fmt>` | 아니오 | `jsonl`(기본, 한 줄당 한 로그) 또는 `json`(배열) |
-| `--size <n>` | 아니오 | scroll pageSize — 범위 10~100, 기본 100 |
+| `--size <n>` | 아니오 | 폐기 예정 호환 옵션. 10~100 검증 후 경고하고 v3 요청에서는 무시 |
 | `--force` | 아니오 | 출력 파일이 있으면 덮어쓴다 (기본 거부) |
 | `--profile <name>` | 아니오 | 사용할 profile 이름 |
 
@@ -218,7 +238,9 @@ echo "배치 작업 종료" | nhncloud logncrash send --level INFO
 nhncloud logncrash send --body "deploy 시작" --app-version 2.3.0 --source batch
 ```
 
-> logncrash send 는 검색과 다른 collector 로 전송하며 appkey 만 사용한다 (secret 불요). 단일 로그 본문은 8MB 까지.
+> `logncrash send`는 Search v3 전환의 영향을 받지 않는다.
+> 검색과 다른 collector로 전송하며 appkey만 사용한다.
+> 단일 로그 본문은 8MB까지 허용한다.
 
 ### 출력 모드
 
@@ -246,7 +268,7 @@ root와 주요 service group의 `--help`에는 짧은 agent hint가 포함된다
 | 명령 | `--json` 출력 shape |
 |------|---------------------|
 | `commands` | `{ commands: [{ path, description, arguments, options, subcommands }] }` |
-| `logncrash search` | `{ totalItems, pageNumber, pageSize, data }` 객체 |
+| `logncrash search` | `{ totalItems, pageNumber, pageSize, data, nextCursor? }` 객체 |
 | `logncrash export` | 파일 출력 전용. stdout JSON 없음 |
 | `deploy artifacts` | Deploy API `body` 객체 |
 | `deploy server-groups` | Deploy API `body` 객체 |
@@ -269,6 +291,14 @@ root와 주요 service group의 `--help`에는 짧은 agent hint가 포함된다
 | `volume create` | 단일 volume 객체 |
 | `floatingip list` | floating IP 배열 |
 | `floatingip create` | 단일 floating IP 객체 |
+| `loadbalancer list` | Load Balancer 배열 |
+| `loadbalancer get` | 단일 Load Balancer 객체 |
+| `loadbalancer ipacl list` | IP ACL 그룹 배열 |
+| `loadbalancer ipacl get` | 단일 IP ACL 그룹 객체 |
+| `loadbalancer ipacl target list` | IP ACL 대상 배열 |
+| `loadbalancer ipacl create/delete` | 작업 상태와 IP ACL 그룹 UUID 객체 |
+| `loadbalancer ipacl target add/remove` | 대상 UUID와 재바인딩 결과 객체 |
+| `loadbalancer set-ipacl/clear-ipacl` | 작업 상태와 Load Balancer UUID·그룹 UUID 객체 |
 | `ncr list` | `registries` 래퍼를 언랩한 registry 배열 |
 | `ncr get` | `registry` 래퍼를 언랩한 단일 registry 객체 |
 | `ncr images` | repository 배열 |
@@ -309,8 +339,9 @@ nhncloud logncrash search --query '*' --from 1d --to now --json | jq '.totalItem
 | `--query <lucene>` | 예 | Lucene 질의 문자열 |
 | `--from <time>` | 예 | 검색 시작 (ISO8601 또는 상대시간) |
 | `--to <time>` | 예 | 검색 끝 |
-| `--page <n>` | 아니오 | pageNumber (기본 0) |
-| `--size <n>` | 아니오 | pageSize (기본 10, 최대 100) |
+| `--page <n>` | 아니오 | 전환 호환용 pageNumber. 기본 0이며 0만 허용 |
+| `--size <n>` | 아니오 | pageSize (기본 10, 범위 1~100) |
+| `--cursor <value>` | 아니오 | 직전 JSON 응답의 불투명한 `nextCursor` |
 | `--profile <name>` | 아니오 | 사용할 profile |
 
 전역 옵션: `--json` / `--quiet` / `--no-color`.
@@ -553,6 +584,106 @@ nhncloud floatingip delete <floatingip-id> --yes
 > **associate**: `floatingip associate <floatingip-id> <instance-id>` 는 instance→port_id 매핑 경로 미확정으로 보류 중.
 > 실측으로 경로가 확정되면 후속 task 에서 추가한다.
 
+### Load Balancer와 IP ACL
+
+Load Balancer와 IP ACL 그룹·대상을 조회하고 관리한다.
+`loadbalancer` 명령군은 `network`와 같은 `iaas` 자격증명·Keystone 토큰·network endpoint를 공유한다.
+
+자동화에서는 profile과 region을 명시하고 `--json`으로 조회한다.
+
+```bash
+# Load Balancer 목록과 단건 조회
+nhncloud loadbalancer list --profile <profile> --region <region> --json
+nhncloud loadbalancer get <loadbalancer> --profile <profile> --region <region> --json
+
+# IP ACL 그룹 목록과 단건 조회
+nhncloud loadbalancer ipacl list --profile <profile> --region <region> --json
+nhncloud loadbalancer ipacl get <group> --profile <profile> --region <region> --json
+
+# 그룹에 속한 IP ACL 대상 조회
+nhncloud loadbalancer ipacl target list <group> \
+  --profile <profile> \
+  --region <region> \
+  --json
+
+# IP ACL 그룹 생성과 삭제
+nhncloud loadbalancer ipacl create \
+  --name <group-name> \
+  --action ALLOW \
+  --description <description> \
+  --profile <profile> \
+  --region <region> \
+  --json
+nhncloud loadbalancer ipacl delete <group> \
+  --profile <profile> \
+  --region <region> \
+  --yes \
+  --json
+
+# Load Balancer의 IP ACL 그룹 전체 교체와 전체 해제
+nhncloud loadbalancer set-ipacl <loadbalancer> \
+  --group <group> \
+  --group <other-group> \
+  --profile <profile> \
+  --region <region> \
+  --yes \
+  --json
+nhncloud loadbalancer clear-ipacl <loadbalancer> \
+  --profile <profile> \
+  --region <region> \
+  --yes \
+  --json
+
+# IP ACL 대상 추가와 삭제
+nhncloud loadbalancer ipacl target add <group> \
+  --cidr <ip-or-cidr> \
+  --profile <profile> \
+  --region <region> \
+  --yes \
+  --json
+nhncloud loadbalancer ipacl target remove <target-id> \
+  --profile <profile> \
+  --region <region> \
+  --yes \
+  --json
+```
+
+`<loadbalancer>`와 `<group>`에는 이름 또는 UUID를 넣는다.
+UUID가 정확히 일치하면 바로 선택하고, 이름은 정확히 하나만 일치해야 한다.
+같은 이름이 여러 개면 오류에 표시되는 후보 UUID를 사용한다.
+
+기본 테이블의 Load Balancer 목록 컬럼은 `id`, `name`, `vip_address`, `provisioning_status`, `operating_status`, `ipacl_group_action`이다.
+IP ACL 그룹 목록 컬럼은 `id`, `name`, `action`, `ipacl_target_count`, `loadbalancer_count`다.
+IP ACL 대상 목록 컬럼은 `id`, `cidr_address`, `description`, `ipacl_group_id`다.
+`--json`은 응답 래퍼를 제거한 객체 또는 배열을 stdout에 출력하고, `--quiet`는 리소스 UUID만 한 줄에 하나씩 stdout에 출력한다.
+진행 상황, 운영 경고, 오류는 stderr로 분리된다.
+
+쓰기 명령은 대화형 확인을 열지 않는다.
+삭제, 연결 교체, 대상 변경에는 `--yes`가 필수다.
+`set-ipacl`은 지정한 그룹 목록으로 기존 연결을 전체 교체하고, `clear-ipacl`은 모든 연결을 해제한다.
+
+대상 추가·삭제는 변경 전에 연결 상태를 수집한 뒤 관련 Load Balancer를 순차 재바인딩한다.
+`--no-rebind`를 쓰면 재바인딩을 생략하지만 데이터 영역에 규칙이 즉시 반영되지 않을 수 있다.
+대상 변경은 반영까지 약 10–20초가 걸릴 수 있다.
+`ALLOW` 그룹에는 Load Balancer가 속한 VPC의 private CIDR을 사용한다.
+
+재바인딩이 일부 실패하면 대상 변경은 되돌리지 않는다.
+명령은 `status: "partial"`과 `rebind.failed[].retry_argv`를 stdout JSON에 먼저 출력한 뒤 종료 코드 1을 반환한다.
+AI 에이전트는 문자열인 `retry_command`보다 배열인 `retry_argv`를 우선 사용한다.
+사용자가 명시한 `--profile`과 `--region`도 복구 배열에 보존된다.
+
+```bash
+result_file="$(mktemp)"
+if ! nhncloud loadbalancer ipacl target add <group> \
+  --cidr <ip-or-cidr> \
+  --profile <profile> \
+  --region <region> \
+  --yes \
+  --json >"$result_file"; then
+  jq '.rebind.failed[] | {error, retry_argv}' "$result_file"
+fi
+```
+
 ### NHN Container Registry (NCR)
 
 NCR Management API 로 레지스트리를 조회한다.
@@ -702,8 +833,19 @@ nhncloud ncs workload list --app-key <appkey>
 nhncloud ncs workload get <workload-id> --app-key <appkey>
 
 # task 컨테이너 로그/이벤트 조회 (--task는 workload get 응답의 tasks[].id)
-nhncloud ncs workload logs <workload-id> --task <task-id> --container <name> --app-key <appkey>
-nhncloud ncs workload events <workload-id> --task <task-id> --app-key <appkey>
+nhncloud ncs workload logs <workload-id> \
+  --task <task-id> \
+  --container <name> \
+  --from 1h \
+  --to now \
+  --profile <profile> \
+  --json
+nhncloud ncs workload events <workload-id> \
+  --task <task-id> \
+  --from 1h \
+  --to now \
+  --profile <profile> \
+  --json
 
 # 실행 히스토리 / 예약 실행 히스토리 조회
 nhncloud ncs workload history <workload-id> --app-key <appkey>
@@ -711,6 +853,19 @@ nhncloud ncs workload history get <workload-id> <history-id> --app-key <appkey>
 nhncloud ncs workload schedule-history <workload-id> --app-key <appkey>
 ```
 
+`workload logs`와 `workload events`의 `--from`·`--to`는 다음 입력을 받는다.
+
+- 시간대와 초를 포함한 RFC3339 절대시간
+- `now`
+- 0 이상의 정수 뒤에 `m`, `h`, `d` 중 하나를 붙인 상대시간
+
+상대시간 예시는 `30m`, `1h`, `2d`다.
+
+입력은 API 호출 전에 UTC 초 단위 `Z` 문자열로 정규화된다.
+두 옵션을 모두 생략하면 API 기본 범위를 사용하고, 한쪽만 지정할 수도 있다.
+잘못된 날짜, 시간대 없는 절대시간, 역전된 범위는 자격증명과 API에 접근하기 전에 종료 코드 3으로 거부한다.
+조회 데이터는 stdout, 진행 상황과 오류는 stderr에 출력한다.
+
 template 생성·버전 생성처럼 복잡한 입력은 공식 API payload를 JSON 파일로 전달한다.
 삭제 명령은 비대화형 환경에서 `--yes`가 필요하다.