@bifos/nhncloud-cli 0.10.1 → 0.11.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 스킬 설치와 상태 진단을 지원한다.
 
 ## 설치
@@ -269,6 +270,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 배열 |
@@ -553,6 +562,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 +811,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 +831,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`가 필요하다.