AI 기반 쿠버네티스 운영, 4계층 문서 체계로 표준을 만들다
AI 코파일럿(Copilot) 활용 과정에서 발견된 문제점을 해결하기 위해 4계층 문서 체계(Four-Layer Document Architecture)와 Command Guardrails 패턴을 도입
4계층 구조는 사람이 읽는 상세 계획서, AI가 프로젝트 상태를 파악하는 work-plans, AI 실행 가이드인 command-guardrails, helm-values 파일로 구성
Command Guardrails는 AI가 실행할 수 있는 명령어를 제한하고, V1 시스템 보호를 위해 get, describe, logs만 허용
GitAIOps 개념을 통해 AI가 문서를 이해하고 실행하는 계층을 추가하여 일관성 및 감사 추적 가능
DEV 환경에서 검증된 Guardrail을 PROD에 재사용하여 구축 시간 단축 및 DevOps/SRE의 역할 변화를 이끌어냄
4계층 문서 체계의 구조와 각 계층의 역할
4계층 문서 체계는 AI 기반 인프라 운영을 위한 핵심 아키텍처로, 각 계층은 AI의 한계를 보완하기 위해 진화했다.
Layer 1 (work-plans): 사람이 읽고 판단하기 위한 상세 계획서로, 한국어로 작성되어 각 컴포넌트의 Why, How, 트레이드오프를 문서화한다.
Layer 2 (claude-context): AI가 프로젝트 상태를 파악하는 영어 기반의 요약 문서로, 토큰 효율성, 기술 용어 일관성, 명령어 연결성을 높인다.
Layer 3 (command-guardrails): AI가 실행하는 마크다운 기반의 실행 가이드로, bash 블록을 포함하며, AI의 행동 범위를 제한한다.
Layer 4 (helm-values): helm 명령어의 파라미터를 관리하는 파일로, AI의 해석 여지를 없애고 재현성을 확보한다. 이러한 구조는 AI와 사람의 역할을 분담하고, 인프라 운영의 안정성을 높이는 데 기여한다.
Command Guardrails 패턴의 설계 원칙
Command Guardrails 패턴은 AI가 인프라를 안전하게 운영하도록 돕는 핵심 요소이다. 이 패턴은 AI가 실행할 수 있는 명령어를 제한하고, 시스템의 안정성을 확보하는 데 중점을 둔다.
V1 시스템 보호: get, describe, logs 명령어만 허용하여, 무분별한 변경을 방지하고 기존 시스템의 안정성을 유지한다.
순서 강제: 00, 10, 20, 30, 40과 같이 단계별 실행 순서를 강제하여, AI가 예상치 못한 방식으로 명령어를 실행하는 것을 막는다.
설정 파일 활용: helm upgrade prometheus-stack --set 플래그와 같이, AI가 임의로 생성할 수 있는 파라미터를 helm-values 파일로 관리하여, 재현 가능한 배포를 보장한다.
이러한 설계 원칙은 AI의 잠재적 위험을 최소화하고, 인프라 운영의 신뢰성을 높이는 데 기여한다.
AI 기반 운영 도입에 따른 생산성 변화
AI 기반 운영 도입은 DevOps/SRE의 역할 변화와 함께, 인프라 구축 및 운영의 효율성을 크게 향상시킨다.
DevOps/SRE 역할 변화: kubectl을 직접 실행하는 대신, AI가 실행할 가이드를 설계하고, AI가 감사한 결과를 검증하는 역할로 전환된다.
생산성 향상: DEV 환경에서 검증된 Guardrail을 PROD에 재사용하여, PROD 환경 구축 시간을 단축하고, 반복적인 작업을 줄인다.
GitAIOps: AI를 위한 문서가 팀 전체의 운영 표준이 되면서, 일관성 및 감사 추적 가능성을 확보한다.
이러한 변화는 제한된 리소스로 더 넓은 범위의 인프라를 관리할 수 있게 하며, 조직의 DevOps 역량을 강화한다.
4계층 문서 체계의 언어 선택 전략
4계층 문서 체계에서 언어 선택은 AI의 효율적인 이해와 실행을 돕기 위한 전략적 결정이다.
Layer 1 (work-plans): 사람이 읽는 문서이므로 한국어 사용
Layer 2 (claude-context): AI의 컨텍스트 윈도우 효율성을 위해 영어 사용
기술 용어의 일관성: 쿠버네티스 생태계의 용어를 영어로 통일하여, AI의 매칭 오류를 방지
명령어와의 직접 연결: 영어 context는 명령어 생성 경로를 단축하여, 오류 발생 가능성을 줄임
이러한 언어 선택 전략은 AI의 이해도를 높이고, 인프라 운영의 정확성을 향상시키는 데 기여한다.
AI의 기억 관리와 MEMORY.md
4계층 문서 체계와 더불어, AI의 기억 관리는 AI 기반 운영의 효율성을 높이는 중요한 요소이다.
MEMORY.md: AI의 컨텍스트 압축(compaction) 문제를 해결하기 위해, 4계층과 동일한 원리를 적용한 메모리 시스템을 도입
맥락 보존: compaction에서 살아남는 맥락을 보존하고, 금지 사항을 누적(guardrail 보완)
작업 상태 추적: 대화가 끊어져도 작업 상태를 추적하고, 매 세션마다 재탐색 없이 시작하는 콜드 스타트 방지
크기 관리: MEMORY.md의 크기를 200줄 이하로 유지하여, AI의 지시 준수율을 높임
이러한 기억 관리 시스템은 AI의 효율적인 작업 수행을 돕고, 인프라 운영의 안정성을 향상시킨다.
4계층 문서 체계의 단계적 도입 전략
4계층 문서 체계는 조직의 상황에 맞춰 단계적으로 도입하는 것이 효과적이다.
Level 0 (1주): 기존 runbook을 구조화된 마크다운 형식으로 정리하여, 문서 가독성을 향상시킨다.
Level 1 (2~4주): Claude Code를 활용하여 DEV 환경에서 실험하고, 충분한 테스트를 거친다.
Level 2 (1~2개월): Context + Guardrails 2계층 체계를 구축하고, 실제 운영에서 발생하는 문제들을 반영하여 완성도를 높인다.
Level 3 (지속): DEV에서 PROD로의 패턴을 정착시키고, helm-values(IaC)를 추가하여, guardrail을 팀의 표준 운영 절차(SOP)로 만든다.
이러한 단계적 접근은 조직의 변화 수용 능력을 높이고, AI 기반 운영의 성공적인 도입을 돕는다.
