wbsong111
6.3 KiB
6.3 KiB
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=truePR에는needs-review레이블을 부착한다. 담당자가custom-values.yaml수정 후 merge 여부를 판단한다.breaking=falsePR은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"
최소 보안 요구사항 (운영 투입 전 필수)
# 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"]
# 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 배포 구성
# 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. 도입 순서 권장
- Staging 클러스터에서 먼저 검증
- 보안 정책 확립 (RBAC, NetworkPolicy, Skill allowlist)
- Skill을 하나씩 추가하며 동작 확인
- 운영 클러스터 투입 시
breaking=truePR은 사람이 직접 머지 승인 유지
8. 관련 문서
- 04-skill-interface.md — Agent가 호출하는 Skill 인터페이스
- ../implementation/02-agent.md — Agent 구현 계획 (Step 2~4)