@bifos/nhncloud-cli 0.10.1 → 0.11.0

package/package.json

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

package/skills/nhncloud-cli/SKILL.md

@@ -1,6 +1,14 @@
 ---
 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 Container Service(ncs template/workload 조회·생성·변경·실행제어, malware 검사 설정·결과 조회) 등 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),
+  Load Balancer와 IP ACL(loadbalancer 조회·쓰기·재바인딩 복구), 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
@@ -18,9 +26,10 @@ NHN Cloud 서비스를 AWS CLI 방식으로 호출하는 TypeScript CLI다.
 | Log & Crash 검색, scroll export, 로그 전송 | [logncrash.md](references/logncrash.md) |
 | Deploy 실행, 배포 조회, 바이너리 업로드/다운로드 | [deploy.md](references/deploy.md) |
 | Compute instance, network, volume, floatingip | [iaas.md](references/iaas.md) |
+| Load Balancer와 IP ACL 그룹·대상 조회·쓰기·재바인딩 복구 | [loadbalancer.md](references/loadbalancer.md) |
 | NCR 레지스트리, 이미지, 태그 조회 | [ncr.md](references/ncr.md) |
 | NKS 클러스터, 노드 그룹, 애드온, kubeconfig | [nks.md](references/nks.md) |
-| NCS template, workload 조회·생성·변경·실행제어, malware 검사 설정·결과 조회 | [ncs.md](references/ncs.md) |
+| NCS template, workload 조회·UTC 시간 필터·생성·변경·실행제어, malware 검사 설정·결과 조회 | [ncs.md](references/ncs.md) |
 | 인증 실패, profile 누락, region mismatch, JSON shape 혼동, scroll 제한 | [troubleshooting.md](references/troubleshooting.md) |
 
 ## 공통 우선 규칙
@@ -28,10 +37,16 @@ NHN Cloud 서비스를 AWS CLI 방식으로 호출하는 TypeScript CLI다.
 - 구조화 출력이 필요하면 `--json`을 우선 사용한다.
 - 스크립트 체이닝은 해당 명령이 `--quiet` 식별자 출력을 문서화했는지 확인한 뒤 사용한다.
 - profile은 기본값에 의존하지 말고 가능하면 `--profile <name>`을 명시한다.
-- IaaS 계열(`instance`, `network`, `volume`, `floatingip`, `nks`)은 region이 중요하면 `--region <region>`을 명시한다.
+- IaaS 계열(`instance`, `network`, `volume`, `floatingip`, `loadbalancer`, `nks`)은 region이 중요하면 `--region <region>`을 명시한다.
 - 삭제, 제거, 비용 발생, 리소스 생성 같은 파괴적/쓰기 명령은 `--yes` 없으면 대화형 confirm이 있을 수 있다.
-- 데이터는 stdout, 진행 상황과 에러는 stderr에 출력한다.
+- 데이터는 stdout, 진행 상황·운영 경고·에러는 stderr에 출력한다.
 - 비밀값, appkey, tenantId, 실제 instance/network id는 문서나 이슈에 그대로 쓰지 않고 placeholder를 사용한다.
+- Load Balancer IP ACL 쓰기는 `--profile`, `--region`, `--json`을 명시하고, 삭제·연결 교체·대상 변경에는 `--yes`도 명시한다.
+- IP ACL 대상 변경은 기본 재바인딩을 유지한다.
+- 대상 변경의 종료 코드가 1이면 stdout JSON의 `rebind.failed[]`를 확인한다.
+- 복구에는 `retry_argv` 배열을 그대로 사용하고, `retry_command`는 사람 확인용으로만 사용한다.
+- NCS workload logs·events 시간 필터는 시간대 포함 RFC3339, `now`, 0 이상의 정수와 `m`·`h`·`d` 단위를 사용한다.
+- 잘못된 NCS 시간 입력은 종료 코드 3이므로 자격증명 문제로 재시도하지 말고 입력을 수정한다.
 
 ## 빠른 시작
 
@@ -52,9 +67,10 @@ nhncloud logncrash search --query '*' --from 1h --to now --json
 | `network` | VPC와 subnet 조회 |
 | `volume` | Block Storage volume 조회·생성 |
 | `floatingip` | Floating IP 조회·발급·삭제 |
+| `loadbalancer` | Load Balancer와 IP ACL 그룹·대상 조회·쓰기·재바인딩 복구 |
 | `ncr` | Container Registry registry/image/tag 조회 |
 | `nks` | Kubernetes cluster/nodegroup/addon/kubeconfig 관리 |
-| `ncs` | Container Service template/workload 조회·생성·변경·실행제어, malware 검사 설정·결과 조회 |
+| `ncs` | Container Service template/workload 조회·UTC 시간 필터·생성·변경·실행제어, malware 검사 설정·결과 조회 |
 
 ## 안전한 탐색 순서
 

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

@@ -0,0 +1,237 @@
+# Load Balancer Reference
+
+`loadbalancer` 명령군은 Load Balancer와 IP ACL 그룹·대상을 조회하고 관리한다.
+`network`와 같은 IaaS 자격증명, Keystone 토큰, network endpoint를 공유한다.
+region이 중요하면 `--region <region>`을 명시한다.
+
+## 탐색 순서
+
+자동화와 AI 에이전트는 실제 명령 표면을 확인한 뒤 목록에서 UUID를 찾는다.
+
+```bash
+nhncloud commands --json \
+  | jq '.commands[] | select(.path|startswith("loadbalancer"))'
+
+nhncloud loadbalancer list --profile <profile> --region <region> --json
+nhncloud loadbalancer ipacl list --profile <profile> --region <region> --json
+nhncloud loadbalancer ipacl target list <group> \
+  --profile <profile> \
+  --region <region> \
+  --json
+```
+
+## 명령
+
+| 명령 | 용도 | 기본 테이블 컬럼 |
+|------|------|------------------|
+| `loadbalancer list` | Load Balancer 목록 조회 | `id`, `name`, `vip_address`, `provisioning_status`, `operating_status`, `ipacl_group_action` |
+| `loadbalancer get <loadbalancer>` | 이름 또는 UUID로 단건 조회 | `field`, `value` |
+| `loadbalancer ipacl list` | IP ACL 그룹 목록 조회 | `id`, `name`, `action`, `ipacl_target_count`, `loadbalancer_count` |
+| `loadbalancer ipacl get <group>` | 이름 또는 UUID로 IP ACL 그룹 단건 조회 | `field`, `value` |
+| `loadbalancer ipacl target list <group>` | 그룹의 IP ACL 대상 목록 조회 | `id`, `cidr_address`, `description`, `ipacl_group_id` |
+| `loadbalancer ipacl create` | IP ACL 그룹 생성 | `field`, `value` |
+| `loadbalancer ipacl delete <group>` | IP ACL 그룹과 하위 대상·연결 규칙 삭제 | `field`, `value` |
+| `loadbalancer ipacl target add <group>` | 대상 추가 후 관련 Load Balancer 재바인딩 | `field`, `value` |
+| `loadbalancer ipacl target remove <target-id>` | 대상 삭제 후 관련 Load Balancer 재바인딩 | `field`, `value` |
+| `loadbalancer set-ipacl <loadbalancer>` | IP ACL 그룹 연결 전체 교체 | `field`, `value` |
+| `loadbalancer clear-ipacl <loadbalancer>` | IP ACL 그룹 연결 전체 해제 | `field`, `value` |
+
+단건 Load Balancer 테이블에는 `id`, `name`, `vip_address`, `provisioning_status`, `operating_status`, `ipacl_group_action`, `ipacl_group_ids`가 행으로 출력된다.
+단건 IP ACL 그룹 테이블에는 `id`, `name`, `action`, `ipacl_target_count`, `loadbalancer_ids`가 행으로 출력된다.
+
+## 이름과 UUID 해석
+
+`<loadbalancer>`와 `<group>`에는 이름 또는 UUID를 넣는다.
+
+1. UUID가 정확히 일치하면 해당 리소스를 선택한다.
+2. UUID가 아니면 정확히 일치하는 이름을 찾는다.
+3. 이름이 하나만 일치하면 해당 리소스를 선택한다.
+4. 같은 이름이 여러 개면 입력 오류와 후보 UUID를 출력한다.
+5. 일치하는 리소스가 없으면 입력 오류로 종료한다.
+
+중복 이름으로 자동화가 불안정해지는 것을 막으려면 목록에서 UUID를 확인한 뒤 다음 명령에 전달한다.
+
+```bash
+profile_name="<profile>"
+region_name="<region>"
+loadbalancer_id="<loadbalancer-id>"
+
+nhncloud loadbalancer list \
+  --profile "$profile_name" \
+  --region "$region_name" \
+  --json \
+  | jq -r '.[] | [.name, .id] | @tsv'
+
+nhncloud loadbalancer get "$loadbalancer_id" \
+  --profile "$profile_name" \
+  --region "$region_name" \
+  --json
+```
+
+`target remove`의 `<target-id>`는 이름 해석을 하지 않는다.
+`target list` 또는 이전 쓰기 결과에서 확인한 UUID를 그대로 전달한다.
+
+## 쓰기 절차
+
+쓰기 전에 현재 리소스를 `--json`으로 조회한다.
+명령에는 `--profile`, `--region`, `--json`을 명시한다.
+삭제·연결 교체·대상 변경에는 `--yes`도 명시한다.
+
+```bash
+# 그룹 생성
+nhncloud loadbalancer ipacl create \
+  --name <group-name> \
+  --action ALLOW \
+  --description <description> \
+  --profile <profile> \
+  --region <region> \
+  --json
+
+# 그룹 삭제: 대상과 Load Balancer 연결 규칙도 함께 제거
+nhncloud loadbalancer ipacl delete <group> \
+  --profile <profile> \
+  --region <region> \
+  --yes \
+  --json
+
+# 연결 전체 교체: --group은 반복 가능하며 action이 모두 같아야 함
+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
+
+# 대상 추가와 삭제
+nhncloud loadbalancer ipacl target add <group> \
+  --cidr <ip-or-cidr> \
+  --description <description> \
+  --profile <profile> \
+  --region <region> \
+  --yes \
+  --json
+nhncloud loadbalancer ipacl target remove <target-id> \
+  --profile <profile> \
+  --region <region> \
+  --yes \
+  --json
+```
+
+`set-ipacl`은 기존 연결에 그룹을 추가하는 명령이 아니다.
+전달한 그룹 목록으로 기존 연결 전체를 교체한다.
+모든 연결을 없애려면 그룹을 생략하지 말고 `clear-ipacl`을 사용한다.
+
+대상 추가·삭제는 변경 전에 연결 상태를 모두 수집한다.
+수집이 하나라도 실패하면 대상을 변경하지 않는다.
+대상 변경 후에는 관련 Load Balancer를 ID 순서로 재바인딩하고, 한 건이 실패해도 나머지를 계속 처리한다.
+자동 되돌리기는 수행하지 않는다.
+
+`--no-rebind`는 재바인딩만 생략한다.
+데이터 영역에 규칙이 즉시 반영되지 않을 수 있으므로 의도적으로 지연을 감수할 때만 사용한다.
+대상 변경의 반영에는 약 10–20초가 걸릴 수 있다.
+`ALLOW` 그룹 대상에는 Load Balancer가 속한 VPC의 private CIDR을 사용한다.
+
+## 출력 모드
+
+| 명령 | `--json` 출력 | `--quiet` 출력 |
+|------|----------------|----------------|
+| `loadbalancer list` | Load Balancer 배열 | Load Balancer UUID를 한 줄에 하나씩 출력 |
+| `loadbalancer get` | 단일 Load Balancer 객체 | 선택한 Load Balancer UUID 한 줄 |
+| `loadbalancer ipacl list` | IP ACL 그룹 배열 | IP ACL 그룹 UUID를 한 줄에 하나씩 출력 |
+| `loadbalancer ipacl get` | 단일 IP ACL 그룹 객체 | 선택한 IP ACL 그룹 UUID 한 줄 |
+| `loadbalancer ipacl target list` | IP ACL 대상 배열 | IP ACL 대상 UUID를 한 줄에 하나씩 출력 |
+| `loadbalancer ipacl create/delete` | 작업 상태와 IP ACL 그룹 UUID 객체 | IP ACL 그룹 UUID 한 줄 |
+| `loadbalancer ipacl target add/remove` | 대상과 재바인딩 결과 객체 | IP ACL 대상 UUID 한 줄 |
+| `loadbalancer set-ipacl/clear-ipacl` | 작업 상태와 Load Balancer·그룹 UUID 객체 | Load Balancer UUID 한 줄 |
+
+옵션을 생략하면 사람이 읽기 좋은 테이블을 출력한다.
+목록이 비어 있으면 기본 모드는 `결과 없음`을 stdout에 출력하고, `--json`은 빈 배열을 출력하며, `--quiet`는 출력하지 않는다.
+`--json`은 NHN Cloud 응답의 최상위 래퍼를 제거한 객체 또는 배열이다.
+
+## 공통 옵션
+
+| 옵션 | 설명 |
+|------|------|
+| `--region <region>` | region override. 생략하면 IaaS 자격증명의 region을 사용 |
+| `--profile <name>` | 사용할 profile |
+| `--json` | 객체 또는 배열을 JSON으로 stdout에 출력 |
+| `--quiet` | 리소스 UUID만 stdout에 출력 |
+
+## 쓰기 전용 옵션
+
+| 옵션 | 적용 명령 | 설명 |
+|------|-----------|------|
+| `--yes` | `ipacl delete`, `ipacl target add/remove`, `set-ipacl`, `clear-ipacl` | 삭제·연결 교체·대상 변경을 비대화형으로 확인 |
+| `--no-rebind` | `ipacl target add/remove` | 대상 변경 후 자동 재바인딩 생략 |
+
+## stdout과 stderr
+
+- 테이블, JSON, UUID, 정상 빈 결과는 stdout에 출력한다.
+- 진행 상황, 운영 경고, 오류는 stderr에 출력한다.
+- 파이프라인에서는 stdout만 다음 명령에 전달하고 stderr는 진단 로그로 분리한다.
+- 부분 실패에서도 JSON 또는 UUID를 stdout에 먼저 출력한 뒤 stderr에 복구 안내를 출력한다.
+
+## 부분 실패 복구
+
+대상 변경이 성공했지만 일부 Load Balancer 재바인딩이 실패하면 종료 코드 1을 반환한다.
+stdout JSON의 `status`는 `partial`이며, 실패마다 기계 실행용 `retry_argv`와 사람 확인용 `retry_command`를 제공한다.
+사용자가 명시한 profile과 region은 `retry_argv`에 보존된다.
+
+```json
+{
+  "operation": "ipacl-target-add",
+  "status": "partial",
+  "target": {
+    "id": "<target-id>",
+    "ipacl_group_id": "<group-id>"
+  },
+  "rebind": {
+    "skipped": false,
+    "succeeded": [],
+    "failed": [
+      {
+        "loadbalancer_id": "<loadbalancer-id>",
+        "ipacl_group_ids": ["<group-id>"],
+        "error": "<message>",
+        "retry_argv": [
+          "nhncloud",
+          "loadbalancer",
+          "set-ipacl",
+          "<loadbalancer-id>",
+          "--group",
+          "<group-id>",
+          "--profile",
+          "<profile>",
+          "--region",
+          "<region>",
+          "--yes",
+          "--json"
+        ],
+        "retry_command": "'nhncloud' 'loadbalancer' 'set-ipacl' '<loadbalancer-id>' '--group' '<group-id>' '--profile' '<profile>' '--region' '<region>' '--yes' '--json'"
+      }
+    ]
+  }
+}
+```
+
+AI 에이전트는 `retry_command`를 셸에서 다시 해석하지 말고 `retry_argv` 배열을 직접 실행한다.
+빈 그룹 snapshot의 복구 배열은 `clear-ipacl`을 사용한다.
+복구 명령이 성공한 뒤 원래 대상 추가·삭제를 반복하지 않는다.
+
+## 에러 코드
+
+| 상황 | exit code |
+|------|-----------|
+| Load Balancer 또는 IP ACL API 오류 | 1 |
+| 대상 변경 후 재바인딩 부분 실패 | 1 |
+| Keystone 인증 실패 | 2 |
+| 빈 이름·UUID, 리소스 없음, 중복 이름 | 3 |
+| IaaS 자격증명 누락 또는 미등록 region | 4 |

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

@@ -62,6 +62,43 @@ nhncloud ncs workload events <workload-id> --task <task-id> --app-key <appkey> -
 nhncloud ncs workload events <workload-id> --task <task-id> --type Warning --app-key <appkey> --json
 ```
 
+### logs·events 시간 필터
+
+`--from`과 `--to`는 다음 두 형식을 받는다.
+
+- 시간대와 초를 포함한 RFC3339 절대시간
+- `now`
+- 0 이상의 정수 뒤에 `m`, `h`, `d` 중 하나를 붙인 상대시간
+
+상대시간 예시는 `30m`, `1h`, `2d`다.
+
+```bash
+# 같은 현재 시각을 기준으로 최근 1시간 조회
+nhncloud ncs workload events <workload-id> \
+  --task <task-id> \
+  --from 1h \
+  --to now \
+  --profile <profile> \
+  --json
+
+# 시간대 오프셋을 포함한 절대시간 조회
+nhncloud ncs workload logs <workload-id> \
+  --task <task-id> \
+  --container <name> \
+  --from 2026-05-01T09:00:00+09:00 \
+  --to 2026-05-01T10:00:00+09:00 \
+  --profile <profile> \
+  --json
+```
+
+CLI는 입력을 API 호출 전에 `YYYY-MM-DDTHH:mm:ssZ` 형식으로 정규화하고 소수 초를 제거한다.
+두 옵션을 모두 생략하면 API 기본 범위를 사용한다.
+한쪽만 지정하면 지정한 필드만 API에 전달한다.
+
+존재하지 않는 날짜, 시간대 없는 절대시간, 지원하지 않는 상대시간 단위, `from > to`는 종료 코드 3으로 거부한다.
+검증은 profile·자격증명 조회와 API 호출보다 먼저 실행된다.
+AI 에이전트는 같은 입력으로 인증 재시도를 반복하지 말고 오류에 표시된 옵션 값을 수정한다.
+
 실행 히스토리와 예약 실행 히스토리는 workload 단위로 조회한다.
 
 ```bash
@@ -136,6 +173,7 @@ nhncloud ncs workload history <workload-id> --app-key <appkey> --json | jq -r '.
 | `--q <query>` | workload list·events 필터 |
 | `--task <taskId>` | `workload logs`·`workload events`·`workload restart` 필수 |
 | `--container <name>` | `workload logs` 필수 |
+| `--from <time>` / `--to <time>` | `workload logs`·`workload events` 시간 필터. 시간대 포함 RFC3339, `now`, 0 이상의 정수와 `m`·`h`·`d` 단위 |
 | `--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초) |
@@ -146,6 +184,8 @@ nhncloud ncs workload history <workload-id> --app-key <appkey> --json | jq -r '.
 
 - appkey는 NCS service appkey다. 인증 secret은 공통 UAK secret을 사용한다.
 - `workload logs`·`workload events`는 task 단위 조회라 `--task` 없이는 입력 오류다.
+- `workload logs`·`workload events` 데이터는 stdout, 진행 상황과 오류는 stderr에 출력한다.
+- 시간 필터를 생략하면 CLI가 임의 기본값을 만들지 않고 API 기본 범위를 유지한다.
 - `workload restart`도 task 단위라 `--task` 없이는 입력 오류다.
 - `workload schedule-history`는 page/size를 아직 노출하지 않는다(대량 이력 시 첫 페이지만 반환될 수 있음 — ADR-020).
 - template/workload id, history id 인수가 공백이면 입력 오류다.
@@ -162,5 +202,7 @@ nhncloud ncs workload history <workload-id> --app-key <appkey> --json | jq -r '.
 |------|-----------|
 | UAK 누락 또는 NCS appkey 미설정 | 4 |
 | UAK 인증 실패 | 2 |
-| 지원하지 않는 region, 빈 id 인수, `--task`/`--container` 누락, `--file` 파일 오류(누락·디렉터리·크기초과·JSON 파싱 실패), `--enabled` 값 오류(`true`/`false` 외), 비대화형 삭제 시 `--yes` 누락 | 3 |
+| 지원하지 않는 region, 빈 id 인수, `--task`·`--container` 누락 | 3 |
+| 잘못된 logs·events 시간 필터 | 3 |
+| `--file` 파일 오류, 잘못된 `--enabled`, 비대화형 삭제 시 `--yes` 누락 | 3 |
 | NCS API 오류 (payload 필수값 누락, `workload create --wait` 타임아웃 등 서버측 검증·폴링 실패 포함) | 1 |