# On-Cluster AI Agent 설계 (Step 2~3)

## 1. 개요

Skills(Step 1)를 **클러스터 위에서 상시 동작하는 자율 에이전트**로 오케스트레이션한다.
OpenClaw 또는 Nanobot을 오케스트레이터로 삼아, Step 1에서 구현한 Skill들을 등록하여 Helm 업그레이드 자동화 전체를 수행한다.

> **전제**: Skills(Step 1) 구현 완료 + 인터페이스 버전 `1.0` 확정 이후 진행.

---

## 2. 아키텍처

```
[OpenClaw / Nanobot on K8s]
       │
       ├── Skill: helm_diff          →  Structured Diff JSON 생성
       ├── Skill: breaking_check     →  Breaking Change 판단
       ├── Skill: generate_doc       →  업그레이드 주의사항 문서 생성 (항상 실행)
       ├── Skill: update_docs        →  CUSTOM-README.md 업그레이드 주의사항 섹션 추가
       ├── Skill: create_pr          →  GitHub PR 생성
       # deploy_validate: Phase 2 예정
       ├── Skill: k8s_event_watch    →  클러스터 이벤트 감지
       └── Channel: Slack / Telegram →  알림 발송
```

트리거:
- Cron 스케줄 (신규 chart 버전 주기 감지)
- K8s Event Watch (ArgoCD App 상태 변화 등)

---

## 3. OpenClaw vs Nanobot

| 항목 | OpenClaw | Nanobot |
|------|---------|---------|
| 코드 규모 | 430K+ lines | ~4,000 lines |
| 성숙도 | 높음 (100K+ GitHub stars) | 낮음 (신생) |
| Skills 생태계 | 풍부 (ClawHub) | 기본 지원 |
| K8s 배포 | 공식 Helm chart + K8s Operator | 직접 구성 필요 |
| 수평 확장 | 불가 (Recreate 전략) | 미정 |
| LLM 지원 | Claude, OpenAI, 로컬 모델 | Claude, OpenAI, Qwen 등 |
| 커스터마이징 | TypeScript / YAML 워크플로 | 코드 직접 수정 용이 |
| 보안 이슈 | 커뮤니티 이슈 있음 (Cisco, Palo Alto 조사) | 미검증 |

**권장**:
- 운영 안정성 우선 → **OpenClaw** (K8s Operator, 성숙한 생태계)
- 경량 커스터마이징 우선 → **Nanobot** (코드 소규모, 직접 수정)

---

## 4. Skills → Agent 연결 전략

Step 1에서 Skill 인터페이스를 표준으로 구현해두면 Agent 연결이 매끄럽다.

```
Step 1 (Skills)                  Step 2~3 (Agent)
─────────────────────────────    ─────────────────────────────
helm_diff, breaking_check 등      OpenClaw/Nanobot Agent가
Skill로 구현 완료               →  동일한 Skill들을 등록 후
                                  워크플로로 오케스트레이션
```

Agent 연결 시 추가되는 부분:
- 실행 환경: K8s Pod (Agent)
- 오케스트레이션: Agent 워크플로 정의 (Cron 스케줄 + 조건 분기)
- 스케줄링: Agent 내장 스케줄러

변경되지 않는 부분:
- Skill 구현체 (helm_diff, breaking_check 등)
- Structured Diff JSON 포맷
- Breaking Change 규칙

---

## 5. 보안 고려사항

## 4.1 운영 정책

- `breaking=true` PR에는 `needs-review` 레이블을 부착한다. 담당자가 `custom-values.yaml` 수정 후 merge 여부를 판단한다.
- `breaking=false` PR은 `auto-update` 레이블을 부착하며, 자동 merge가 가능하다.
- Agent는 PR 생성까지만 수행한다. merge 책임은 담당자에게 있다.

## 4.2 실패 처리

- Skill 실패 시: 알림 전송 + 자동 중단. 재시도는 최대 3회.
- `deploy_validate`는 Phase 2에서 구현 예정 (현재 스코프 밖).

## 4.3 관찰성

- 모든 Skill 호출은 audit log에 남긴다 (input hash + output status).
- Prometheus metrics: 성공/실패 카운트, 평균 처리 시간, 재시도 횟수.
- LLM 호출은 request_id를 부여하여 추적 가능해야 한다.

On-Cluster AI Agent는 구조적 위험이 있다.

| 위험 | 내용 | 대응 |
|------|------|------|
| 과도한 K8s 권한 | helm upgrade 권한 남용 | RBAC: test namespace만 허용, ServiceAccount 최소 권한 |
| Skill 취약점 | 3rd-party Skill의 26%가 취약 (Cisco 조사) | 허용 Skill allowlist 관리, ClawHub Skill 검토 필수 |
| Prompt Injection | PR comment, webhook 등 외부 콘텐츠로 에이전트 조작 | 입력 sanitization, 신뢰 범위(trust boundary) 명확화 |
| 외부 통신 데이터 유출 | GitHub API, Slack 등 외부 전송 | NetworkPolicy: 허용 egress 목록 명시, 민감 데이터 마스킹 |
| Shell 접근 | RCE 가능성 | shell skill 비활성화, read-only root filesystem, UID 1000 |

> Palo Alto Networks 평가: "Shell 접근 + 개인 데이터 + 외부 통신" = **"lethal trifecta"**

### 최소 보안 요구사항 (운영 투입 전 필수)

```yaml
# RBAC 예시: test namespace만 허용
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: helm-test
rules:
  - apiGroups: ["apps"]
    resources: ["deployments", "statefulsets"]
    verbs: ["get", "list", "create", "update", "delete"]
  - apiGroups: [""]
    resources: ["pods", "services", "configmaps"]
    verbs: ["get", "list", "create", "update", "delete"]
```

```yaml
# NetworkPolicy: 허용 egress만 통과
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: agent-egress-policy
spec:
  podSelector:
    matchLabels:
      app: helm-upgrade-agent
  policyTypes: ["Egress"]
  egress:
    - to:  # GitHub API
        - ipBlock:
            cidr: 140.82.112.0/20
    - to:  # Slack API
        - ipBlock:
            cidr: 35.190.0.0/16
    - ports:
        - port: 443
```

---

## 6. K8s 배포 구성

```yaml
# OpenClaw Helm values 예시
image:
  tag: latest

skills:
  allowlist:
    - helm_diff
    - breaking_change_check
    - generate_upgrade_doc
    - update_docs_file
    - create_pr
    # deploy_validate: Phase 2에서 추가 예정

securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  readOnlyRootFilesystem: true

resources:
  limits:
    memory: "1Gi"
    cpu: "500m"
```

---

## 7. 도입 순서 권장

1. Staging 클러스터에서 먼저 검증
2. 보안 정책 확립 (RBAC, NetworkPolicy, Skill allowlist)
3. Skill을 하나씩 추가하며 동작 확인
4. 운영 클러스터 투입 시 `breaking=true` PR은 사람이 직접 머지 승인 유지

---

## 8. 관련 문서

- [04-skill-interface.md](04-skill-interface.md) — Agent가 호출하는 Skill 인터페이스
- [../implementation/02-agent.md](../implementation/02-agent.md) — Agent 구현 계획 (Step 2~4)