Move directory
This commit is contained in:
wbsong111
@@ -0,0 +1,189 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user