Ground Control 가이드
사용자님 · 주요 기능과 사용법
Ground Control이란?
Spacewalk 통합 인프라 관제 플랫폼입니다. AWS 리소스(EC2, EB, RDS)와 jay-dev 서버 상태를 실시간으로 모니터링하고, 이상 감지 시 Claude AI가 자동으로 원인을 진단하여 인시던트로 기록합니다. 웹 대시보드에서 인시던트 이력을 확인하고, AI와 대화하여 운영 작업을 수행할 수 있습니다.
Phase 9부터는 자율 지식 에이전트가 추가되어 인프라 변경·비용·Notion 문서를 자동 수집하고, 주간 리포트를 생성합니다. Slack 봇은 응답에 출처 파일과 줄 번호를 함께 인용합니다.
3가지 핵심 기능
어떻게 동작하나요?
모니터 (60초 주기)
jay-dev 서버에서 로컬 상태(디스크/메모리/SSM)와 AWS 리소스(EC2/EB/RDS)를 주기적으로 점검합니다. RDS 자동 백업 등 정상적인 임시 상태는 화이트리스트로 제외해 불필요한 알림을 줄입니다.
이상 감지 + 중복 제거
이상 감지 시 동일 리소스에 대한 최근 인시던트를 확인해 중복 진단을 건너뜁니다. EB 환경은 연속 2회 이상 Red일 때만 인시던트로 승격합니다.
자동 진단 (Claude CLI)
이상이 확정되면 Claude가 관련 로그와 설정을 분석해 원인/영향/조치안을 정리합니다. 동시 진단 3건 제한.
인시던트 기록 + 자동 정리
진단 결과를 DB에 저장. 이후 15분 연속 정상으로 돌아오면 자동으로 해결(auto_resolved) 처리합니다.
AI 채팅으로 빠른 분석
인시던트 상세에서 'AI에게 물어보기'를 누르면 채팅으로 이동. 원인 정보가 프롬프트에 자동 입력되어 즉시 다음 조치를 물어볼 수 있습니다.
자율 지식 에이전트 (Phase 9)
백그라운드에서 자동으로 동작하는 4단계 파이프라인입니다. Slack 봇이 더 정확한 답변을 제공하는 기반이 됩니다.
수집
Git 커밋 이력, 인프라 스냅샷(PM2/AWS diff), 비용 변화, Notion 문서를 주기적으로 수집합니다.
분류 + 보안 스캔
수집된 이벤트를 4가지 유형(인프라/비용/코드/문서)으로 분류하고, 9가지 패턴으로 시크릿 유출 여부를 검사합니다.
지식 PR 자동 생성
중요 변경 사항을 docs/knowledge/auto-observed/ 에 기록하고 GitHub PR을 자동으로 만듭니다. (기본값: 비활성, 일 5건 상한)
주간 리포트
인용 빈도, 응답 신뢰도, 지식 공백을 분석해 주간 리포트를 docs/weekly-reports/YYYY-WNN.md 에 저장합니다.
AI Token Usage Observer — LLM 호출 비용/토큰 사용량 실시간 추적 기능이 Sprint B-1로 병행 개발 중입니다.
인시던트 탭과 상태 필드
인시던트 페이지는 3개 탭으로 구분됩니다.
활성 (active)
최근 15분 이내에 이상 신호가 감지된 진행 중 장애. 즉시 확인이 필요합니다.
최근 (recent)
최근 24시간 이내에 생성된 인시던트. 해결된 것도 포함됩니다.
전체 (all)
모든 인시던트 이력. severity 필터와 함께 사용할 수 있습니다.
status 필드 의미
왜 알림이 줄었나요?
Sprint A (2026-04-20) 에서 두 가지 오탐 감소 기능이 추가되어 주말 기준 39건이던 신규 인시던트가 배포 후 즉시 0건으로 줄었습니다.
RDS 화이트리스트
RDS는 자동 백업(backing-up), 리부팅, 유지보수 등 일시적인 정상 상태가 있습니다. 이전에는 이 상태들이 모두 이상으로 감지되어 하루 9건씩 반복 알림이 발생했습니다. 지금은 GC_RDS_NORMAL_STATUSES 환경변수로 정의된 7개 정상 상태를 자동으로 제외합니다.
EB 히스테리시스
Elastic Beanstalk 환경이 잠깐 Red가 됐다가 빠르게 복귀하는 경우가 있습니다. 이제 연속 2회 이상 Red 상태일 때만 인시던트로 승격합니다.GC_EB_HYSTERESIS_N=2 (기본값, 조정 가능).
권한 (Role)
✓ 가능
- • 서버 상태 확인 (df, free, docker ps)
- • 로그 분석 (Read, Grep, Glob)
- • AWS 리소스 조회 (대시보드 데이터 참조)
- • 원인 설명 요청
✗ 불가
- • AWS CLI 명령 실행
- • 컨테이너 재시작
- • 설정 변경, 배포
✓ 가능
- • viewer의 모든 기능
- • Bash 명령 실행 (AWS CLI, docker, systemctl)
- • 컨테이너 재시작, 큐 재등록
- • 안전한 변경 작업
✗ 불가
- • PROD 배포 (사전 확인 필수)
- • DB 스키마 변경
- • 서버 종료/생성
- • SSH 키 변경
💡 권한 변경: 기본값은 viewer입니다. admin이 필요하면 config/roles.json에 이메일을 추가하세요. 서버에서 최대 60초 후 반영됩니다.
AI 채팅 — 질문 예시
“EC2 인스턴스 중 비용이 많이 나가는 것 3개 알려줘”“jay-dev 서버 디스크 사용률이 왜 78%로 높아?”“RDS 중 db.r6g.xlarge 이상 인스턴스 목록”“lbd-fe-prod 환경의 인스턴스 타입이 뭐야?”“EB lbd-fe-me 환경의 최근 배포 이벤트 조회”“데이터 파이프라인 컨테이너 재시작해줘”Slack 봇 — 근거 인용 형식
Slack에서 봇에게 질문하면 답변 출처를 파일:줄번호 형식으로 함께 표시합니다. 인용된 파일을 직접 확인해 정확도를 검증할 수 있습니다.
질문 예시
@봇 lbd-fe-prod 인스턴스 타입이 뭐야?
봇 답변 예시
lbd-fe-prod 환경의 인스턴스 타입은 t3.micro입니다.
출처: docs/knowledge/infra.md:175
docs/knowledge/ — infra.md, projects.md, engineering.md 등. 자율 에이전트가 자동으로 업데이트하는docs/knowledge/auto-observed/도 참조합니다.비용 페이지 용어 사전
비용 페이지에서 자주 보이는 용어를 풀어 설명합니다.
- 메가존
- AWS 결제를 대행하는 MSP(매니지드 서비스) 사업자. 이 화면의 금액은 메가존이 청구한 실제 AWS 비용입니다.
- 활성
- AWS에 실제로 존재함이 확인된 리소스.
- 잔영
- AWS에서는 이미 삭제됐지만 메가존 청구서에 며칠 더 남아 있는 리소스. 곧 0원으로 사라집니다.
- 범위 밖
- Tag 동기화가 닿지 않는 리소스(S3·NAT 게이트웨이·스냅샷·CloudWatch 로그 등). 실재 여부를 자동 검증할 수 없어 활성·잔영과 분리해 표시합니다.
- 안전 모드 / 운영 모드
- 안전 모드는 자동화가 탐지만 하고 Slack 알림·실제 조치는 보내지 않는 관찰 단계입니다. 운영 모드로 전환되면 알림이 발송됩니다.
- 태그 커버리지
- Owner·Project·Environment 태그가 부착된 리소스 비율. 태그가 없으면 어느 팀·프로젝트 비용인지 가릴 수 없습니다.
- 절감 후보
- 유휴 인스턴스·과대 사양·미사용 디스크 등 비용을 줄일 수 있는 리소스.
알아두세요
- • 세션 TTL: 24시간. 이후 새 대화로 시작됩니다.
- • 대화당 최대 5턴, 최대 $1 예산 제한.
- • 위험 명령(배포/삭제/종료)은 admin도 같은 메시지 재전송으로 확인해야 실행됩니다.
- • 모든 요청은 서버의
roles.json에서 역할이 결정됩니다 (클라이언트 위조 불가). - • 주간 Reflector 리포트:
docs/weekly-reports/YYYY-WNN.md— 매주 자동 생성.