iop/agent-test/dev/control-plane-smoke.md

---
test_env: dev
test_profile: control-plane-smoke
domain: control-plane
verification_type: smoke
last_rule_updated_at: 2026-06-12
---

# control-plane-smoke dev 테스트

## 읽기 조건

- `apps/control-plane/**` 변경 또는 Control Plane health/readiness, config loading, wire endpoint dev 검증 판단이 필요한 경우

## 적용 범위

- `apps/control-plane/cmd/control-plane/**`
- `apps/control-plane/internal/wire/**`
- `apps/control-plane/Dockerfile`
- Control Plane HTTP health/readiness와 proto-socket WebSocket hello baseline
- Control Plane-Edge TCP wire endpoint, Edge outbound hello, disconnect baseline
- dev compose host publish와 DB/Redis 분리

## 분류

- domain: control-plane
- verification_type: smoke
- scope: control-plane HTTP와 wire baseline

## 환경

- host: Docker compose 또는 Flutter client가 포함된 runtime evidence는 원격 runner `ssh toki@toki-labs.com`의 `/Users/toki/agent-work/iop-dev` 기준으로 수행한다.
- port: Control Plane HTTP `18001` (host-facing), Portal/Control Plane wire test endpoint `19001`, CP-Edge wire `19002`, Edge-Node TCP transport `19003`, web/dev preview `13001`, Control Plane metrics `19103`, Prometheus `19111`, Grafana `19121`.
- runtime: Go `1.24`, Docker compose
- package manager: Go modules / Makefile
- docker: `docker-compose.yml`에 postgres, redis, control-plane, web, prometheus, grafana service가 Control Plane 관측 그룹으로 정의되어 있다. edge service는 Control Plane-Edge 연결 검증을 위한 인접 runtime service다. dev 검증은 `docker compose --env-file .env.dev.example ...`로 수행한다.
- external service: postgres host publish `15401`, redis host publish `16301`
- model endpoint:
- operator notice: 기존 dev Control Plane/UI/Edge 접속 포트는 유지하고 Control Plane metrics `19103`, Prometheus `19111`, Grafana `19121`만 관측용으로 추가한다. Grafana/Prometheus는 원격 runner 내부 또는 SSH 터널 기준이다.
- credential: DB/Redis credential 원문은 문서에 기록하지 않는다.

## 명령

- setup: `IOP_EDGE_NODE_TOKEN=<token> docker compose --env-file .env.dev.example up -d postgres redis control-plane web prometheus grafana`
- lint:
- unit: `go test ./apps/control-plane/...`
- smoke: `curl -fsS http://127.0.0.1:18001/healthz`, `curl -fsS http://127.0.0.1:18001/readyz`
- e2e: `make test-control-plane-edge-wire`는 보조 smoke이며 기본 포트를 쓰는 스크립트이므로 dev 포트 override 가능 여부를 먼저 확인한다.
- model:
- full-cycle: Control Plane command, health/readiness, wire hello 수동 검증

## 최소 검증

- 변경한 control-plane 패키지 또는 `go test ./apps/control-plane/...`를 실행한다.
- HTTP lifecycle 변경 시 dev port `/healthz`와 `/readyz`를 확인한다.
- Client-Control Plane wire protocol 변경 시 proto-socket WebSocket hello baseline을 dev wire port `19001` 기준으로 확인한다.
- Control Plane-Edge TCP wire, Edge outbound connector, registry lifecycle 변경 시 dev `19002` 기준으로 hello accepted, Edge connected, Edge disconnected marker를 확인한다.

## 보조 검증

- docker compose control-plane service healthcheck를 확인한다.
- Edge 포함 compose 검증에서는 `IOP_EDGE_NODE_TOKEN`을 원격 runner 환경에서 주입하고, token 원문은 tracked 파일에 기록하지 않는다.

## 판정 기준

- control-plane service가 dev stack으로 기동되고 health endpoint가 성공 응답을 반환한다.
- Prometheus와 Grafana가 같은 dev compose project에서 올라오며, Prometheus는 compose 내부 DNS로 `control-plane:9093`과 dev native Edge metrics `host.docker.internal:19101`을 scrape한다.
- wire endpoint는 Control Plane 브라우저/앱 경계로 유지되고 Node 직접 연결/스케줄링 경로로 확장되지 않는다.
- dev stack은 local/test stack의 host publish 포트(`13000`, `18000`, `19080`, `19081`, `15400`, `16300`)를 점유하지 않는다.

## 기준 출력 예시

```text
curl -fsS http://127.0.0.1:18001/healthz
curl -fsS http://127.0.0.1:18001/readyz
```

## 차단 기준

- docker compose 실행 권한 또는 postgres/redis service 기동이 불가능하다.
- 현재 작업 컨테이너에서 Docker-in-Docker가 필요해지는 검증은 수행하지 않고 원격 runner 차단으로 보고한다.
- 실제 DB/Redis credential 확인이 필요한데 안전하게 제공되지 않았다.
- dev 포트가 이미 점유되어 있어 local/test stack과 공존할 수 없다.

## 보고 항목

- 실행한 명령:
- 성공한 검증:
- 실패/차단된 검증:
- 생략 사유:
- 남은 위험:

## 금지 사항

- Control Plane에서 Node 직접 연결이나 직접 스케줄링을 제품 기본 계약으로 만들지 않는다.
- 실제 DB/Redis credential이나 private endpoint를 tracked docs/rules에 기록하지 않는다.
- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다.