wero90

AI 서비스 비용 거버넌스: 팀별 할당, 예산 알림, 사용량 대시보드 설계

wero90 — Tue, 9 Jun 2026 18:03:23 +0900

AI 서비스 비용은 토큰 단위로 과금되며, 사용량이 예측하기 어렵습니다. 팀 단위 비용 가시성 없이 운영하면, 월말 청구서를 받고서야 어떤 팀이 얼마를 썼는지 파악하게 됩니다. 이 글은 AI 서비스 비용을 팀별로 할당하고, 예산 초과를 사전에 감지하며, 사용량을 대시보드로 가시화하는 거버넌스 아키텍처를 설계 관점에서 정리합니다.

핵심 요약

AI 서비스 비용은 전통적인 인프라 비용과 달리 토큰 수, 모델 종류, 요청 패턴에 따라 크게 변동합니다.
팀별 비용 귀속(Cost Attribution)을 위해 LLM Gateway 계층에서 요청을 식별하고, 메타데이터로 태깅하는 구조가 필요합니다.
예산 알림은 임계값 기반 단계별 알림과 자동 차단을 조합하여 설계합니다.
사용량 대시보드는 팀별, 모델별, 기간별 토큰 소비량과 비용을 실시간으로 보여줘야 운영 판단이 가능합니다.
Chargeback(실비 청구)과 Showback(비용 가시화) 중 조직 성숙도에 맞는 모델을 선택합니다.

AI 비용 구조의 특수성

전통 인프라 비용과의 차이

전통적인 클라우드 인프라는 인스턴스 유형과 가동 시간으로 비용이 결정됩니다. EC2 m5.large를 720시간 운영하면 월 비용은 대체로 예측 가능합니다.

AI 서비스 비용은 다릅니다. 같은 API를 호출하더라도 프롬프트 길이, 응답 길이, 사용 모델에 따라 비용이 수십 배 차이가 납니다.

비용 변수	전통 인프라	AI 서비스
과금 단위	시간, vCPU, GB	토큰(입력/출력 별도)
예측 가능성	높음 (고정 스펙)	낮음 (요청마다 다름)
비용 증폭 요인	트래픽 증가	프롬프트 길이, 멀티턴, Reasoning 토큰
비용 가시성	태깅으로 즉시 확인	별도 계측 필요
비용 누수 패턴	미사용 리소스	실패 요청, Agent 루프, 불필요한 재시도

AI 비용 구조의 특수성

비용 예측이 어려운 이유

운영 환경에서 AI 서비스 비용이 급증하는 패턴은 대체로 세 가지입니다.

Agent 루프: AI Agent가 도구를 반복 호출하면서 한 요청당 수십 회 API 호출이 발생합니다. 단일 사용자 요청이 수만 토큰을 소비하는 경우가 생깁니다.
멀티턴 대화 누적: 대화 이력을 매 요청에 포함하면, 대화가 길어질수록 입력 토큰이 기하급수적으로 증가합니다.
Reasoning 토큰: 일부 모델(예: OpenAI o3, Claude Opus 계열)은 사고 과정에 별도 토큰을 사용하며, 이는 출력 토큰보다 비용이 높을 수 있습니다.

비용 귀속 아키텍처: 누가 얼마를 썼는지 식별하기

LLM Gateway 중심 설계

팀별 비용을 추적하려면, 모든 LLM API 호출이 단일 게이트웨이를 통과하도록 설계합니다. 애플리케이션이 LLM Provider에 직접 호출하면 비용 귀속이 불가능합니다.

LLM Gateway 기반 비용 귀속 아키텍처

Gateway가 수행하는 역할:

요청 식별: 팀 ID, 프로젝트 ID, 사용자 ID를 요청 메타데이터에서 추출합니다.
토큰 계측: Provider 응답에서 실제 토큰 수(입력/출력/Reasoning)를 파싱합니다.
비용 계산: 모델별 단가 × 토큰 수로 실시간 비용을 산출합니다.
예산 검증: 팀/프로젝트 예산 한도를 확인하고, 초과 시 요청을 차단하거나 저비용 모델로 라우팅합니다.

실무 구현 옵션

방식	설명	적합한 상황
LiteLLM Proxy	오픈소스. Virtual Key + Team 기반 예산 관리. PostgreSQL로 사용량 저장	스타트업, 중소 규모 팀
자체 Gateway	Kong/Envoy 기반 커스텀 플러그인으로 토큰 계측과 라우팅 구현	대규모 엔터프라이즈, 커스텀 요구사항
Provider 내장 기능	OpenAI Projects, AWS Bedrock Projects 등 Provider별 비용 분리	단일 Provider 환경, 빠른 시작

태깅 전략

비용 귀속의 핵심은 모든 요청에 일관된 메타데이터를 부착하는 것입니다.

{
  "metadata": {
    "team_id": "platform-team",
    "project_id": "customer-chatbot",
    "environment": "production",
    "feature": "ticket-classification",
    "cost_center": "CC-4200"
  }
}

태깅 설계 원칙:

필수 태그: team_id, project_id, environment는 모든 요청에 반드시 포함합니다.
선택 태그: feature, user_id, session_id는 세부 분석용으로 추가합니다.
태그 검증: Gateway에서 필수 태그가 누락된 요청은 거부합니다. 태그 없는 요청은 비용 귀속이 불가능하기 때문입니다.
태그 표준화: 태그 값은 중앙에서 관리하는 목록(Allow List)으로 제한합니다. 자유 입력을 허용하면 오타와 불일치로 집계가 깨집니다.

예산 할당과 알림 설계

예산 모델 선택: Chargeback vs Showback

모델	설명	장점	단점
Showback	팀별 비용을 가시화하되, 실제 과금하지 않음	도입 저항 낮음, 비용 인식 향상	직접적인 비용 절감 동기 부족
Chargeback	팀별 사용량을 실제 부서 예산에서 차감	강한 비용 절감 동기, 정확한 ROI 산출	도입 복잡, 비용 산정 분쟁 가능

대부분의 조직은 Showback에서 시작해서, 비용이 일정 규모를 넘기면 Chargeback으로 전환합니다. AI 비용이 월 $10,000 미만인 단계에서는 Showback으로 비용 인식을 먼저 확립하는 것이 실용적입니다.

팀별 예산 할당 구조

예산은 계층적으로 설계합니다:

Organization Budget ($50,000/월)
├── Platform Team ($20,000/월)
│   ├── Customer Chatbot ($12,000)
│   └── Internal Tools ($8,000)
├── Data Team ($15,000/월)
│   ├── Document Processing ($10,000)
│   └── Analytics Agent ($5,000)
├── Product Team ($10,000/월)
│   └── Recommendation Engine ($10,000)
└── Reserve ($5,000/월)
    └── 실험/PoC용 공유 예산

설계 시 고려사항:

리저브 풀: 전체 예산의 10~15%는 예비 풀로 유지합니다. 새 프로젝트 PoC나 예기치 않은 사용량 증가에 대응합니다.
예산 주기: 월 단위가 기본이지만, AI 프로젝트 초기에는 주 단위 리뷰가 필요할 수 있습니다.
모델별 분리: 고비용 모델(GPT-4o, Claude Opus 4)과 저비용 모델(GPT-4o mini, Claude Haiku)의 예산을 분리하면 비용 최적화 동기를 부여할 수 있습니다.

임계값 기반 알림 설계

단순히 "예산 초과" 알림 하나로는 운영 대응이 어렵습니다. 단계별 임계값을 설계합니다.

임계값	알림 대상	액션
50% 도달	팀 리드 (Slack)	정보 제공, 추세 확인
75% 도달	팀 리드 + FinOps (Slack + Email)	사용 패턴 리뷰, 최적화 검토
90% 도달	팀 리드 + FinOps + 관리자 (PagerDuty)	저비용 모델 자동 전환 검토
100% 도달	전체 이해관계자	요청 차단 또는 Fallback 모델 강제 적용

100% 초과 시 즉시 차단할지, Fallback 모델로 전환할지는 서비스 중요도에 따라 결정합니다. 고객 대면 서비스라면 차단보다 Fallback이 적합합니다. 내부 도구라면 차단이 단순하고 효과적입니다.

예산 초과 대응 자동화

# 예산 정책 예시 (Gateway 설정)
budget_policies:
  - team_id: platform-team
    monthly_budget: 20000
    alerts:
      - threshold: 0.5
        channels: [slack]
        message: "Platform Team AI 예산 50% 도달"
      - threshold: 0.75
        channels: [slack, email]
        message: "Platform Team AI 예산 75% 도달 — 사용 패턴 리뷰 필요"
      - threshold: 0.9
        channels: [slack, pagerduty]
        action: downgrade_model
        fallback_model: gpt-4o-mini
      - threshold: 1.0
        channels: [slack, pagerduty, email]
        action: block_requests
        exceptions: [critical-customer-chatbot]

사용량 대시보드 설계

대시보드가 보여줘야 하는 지표

대시보드는 "얼마나 썼는가"와 "왜 그만큼 썼는가"를 모두 답할 수 있어야 합니다.

계층	핵심 지표	목적
조직 전체	총 비용, 전월 대비 증감률, 예산 소진율	경영진 보고, 전체 추세
팀별	팀별 비용, 예산 대비 사용률, 일별 추세	팀 리드 비용 관리
프로젝트별	프로젝트별 비용, 모델별 분포, 토큰 효율	최적화 대상 식별
요청 단위	p50/p95/p99 토큰 수, 비용 아웃라이어	비용 이상 탐지, 디버깅

대시보드 구조 설계

사용량 대시보드 구조

실무에서 효과적인 대시보드는 다음 세 가지 뷰로 구성합니다.

1. Executive View (경영진/FinOps)

월간 총 AI 비용과 예산 대비 진행률
팀별 비용 비중 (파이 차트)
전월 대비 증감과 예상 월말 비용 (선형 예측)

2. Team View (팀 리드/엔지니어)

일별 비용 추세 (막대 그래프)
모델별 비용 분포 (어떤 모델이 비용 비중이 높은지)
예산 잔액과 소진 속도 (며칠 후 예산 소진 예상인지)
Top 5 비용 요청 (이상 탐지용)

3. Optimization View (엔지니어)

캐시 히트율 (Semantic Cache 활용도)
평균 토큰 수 추세 (프롬프트가 점점 길어지고 있는지)
실패 요청 비용 (실패했지만 입력 토큰 비용은 발생한 요청)
모델별 비용 효율 (비용 대비 품질 지표)

데이터 파이프라인 설계

대시보드를 구동하려면 아래 데이터 흐름이 필요합니다.

LLM Gateway → 이벤트 스트림 (Kafka/Kinesis)
  → 실시간 집계 (Flink/Lambda) → 대시보드 (Grafana/Datadog)
  → 배치 적재 (S3/BigQuery) → 월간 리포트, 예측 모델

각 요청 이벤트에 포함해야 하는 필드:

{
  "timestamp": "2026-06-09T14:30:00Z",
  "team_id": "platform-team",
  "project_id": "customer-chatbot",
  "model": "gpt-4o",
  "input_tokens": 2340,
  "output_tokens": 856,
  "reasoning_tokens": 0,
  "cached_tokens": 1200,
  "cost_usd": 0.0287,
  "latency_ms": 1842,
  "status": "success",
  "user_id": "user-12345",
  "session_id": "sess-abc"
}

클라우드 Provider별 비용 관리 기능

AWS Bedrock

AWS Bedrock은 2026년 4월부터 IAM 주체별 세분화된 비용 귀속 기능을 제공합니다. CUR 2.0의 line_item_iam_principal 컬럼과 Cost Explorer의 IAM 주체 태그 필터링이 추가되어, 동일 계정 내에서도 팀별 비용을 직접 분리할 수 있게 되었습니다.

Bedrock Projects: 프로젝트 ID를 API 호출에 전달하면, Cost Explorer에서 프로젝트별 필터링이 가능합니다.
Cost Allocation Tags: 리소스 태그를 활성화하면 AWS Billing에서 팀/부서별 비용을 분리할 수 있습니다.
AWS Budgets: Bedrock 서비스에 대한 예산을 생성하고, 임계값 초과 시 SNS 알림을 발송합니다.
Budget Controls: 예산 초과 시 자동으로 리소스를 중지하거나 삭제하는 액션을 설정할 수 있습니다.

# AWS Budgets로 Bedrock 비용 예산 설정 예시
aws budgets create-budget \
  --account-id 123456789012 \
  --budget '{
    "BudgetName": "bedrock-platform-team",
    "BudgetLimit": {"Amount": "20000", "Unit": "USD"},
    "TimeUnit": "MONTHLY",
    "BudgetType": "COST",
    "CostFilters": {
      "Service": ["Amazon Bedrock"],
      "TagKeyValue": ["user:team$platform-team"]
    }
  }' \
  --notifications-with-subscribers '[
    {
      "Notification": {
        "NotificationType": "ACTUAL",
        "ComparisonOperator": "GREATER_THAN",
        "Threshold": 75
      },
      "Subscribers": [{"SubscriptionType": "SNS", "Address": "arn:aws:sns:..."}]
    }
  ]'

OpenAI Platform

OpenAI는 Organization 내에서 Project 단위로 비용을 분리할 수 있습니다.

Projects: 팀별 Project를 생성하고, 각 Project에 별도 API Key를 발급합니다.
Usage Dashboard: Project별 토큰 사용량과 비용을 확인할 수 있습니다.
Budget Limits: Project별 월간 예산 한도를 설정할 수 있습니다. 다만 2025년 이후 OpenAI 지원팀에 따르면 Project 예산은 하드 리밋이 아닌 알림 전용으로 동작합니다. 따라서 Provider 자체 예산 기능에만 의존하면 실제 차단이 되지 않을 수 있으므로, LLM Gateway에서 별도로 예산 제어를 구현하는 것이 안전합니다.
Rate Limits: TPM(Tokens Per Minute), RPM(Requests Per Minute) 제한을 Project별로 설정합니다.

Azure OpenAI Service

Azure는 기존 Azure 비용 관리 체계와 통합되는 장점이 있습니다.

Resource Group/Subscription 분리: 팀별 Resource Group이나 Subscription으로 물리적 비용 분리가 가능합니다.
Azure Cost Management: 태그 기반 비용 분석, 예산 알림, 이상 탐지를 기본 제공합니다.
Azure Monitor: 토큰 사용량 메트릭을 기반으로 커스텀 알림 규칙을 설정합니다.

LLM Gateway 기반 거버넌스 구현

LiteLLM을 이용한 팀별 예산 관리

LiteLLM Proxy는 오픈소스로, 팀과 Virtual Key 기반의 예산 관리를 제공합니다.

# LiteLLM config.yaml 예시
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY

  - model_name: gpt-4o-mini
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

general_settings:
  master_key: sk-master-key-1234
  database_url: os.environ/DATABASE_URL

litellm_settings:
  max_budget: 50000        # 조직 전체 월 예산 ($)
  budget_duration: 30d     # 예산 리셋 주기

팀 생성 및 예산 할당:

# 팀 생성 (API 호출)
curl -X POST http://gateway:4000/team/new \
  -H "Authorization: Bearer sk-master-key-1234" \
  -d '{
    "team_alias": "platform-team",
    "max_budget": 20000,
    "budget_duration": "30d",
    "models": ["gpt-4o", "gpt-4o-mini"],
    "metadata": {"cost_center": "CC-4200"}
  }'

# 팀 멤버용 Virtual Key 발급
curl -X POST http://gateway:4000/key/generate \
  -H "Authorization: Bearer sk-master-key-1234" \
  -d '{
    "team_id": "platform-team",
    "key_alias": "chatbot-service-key",
    "max_budget": 12000,
    "models": ["gpt-4o", "gpt-4o-mini"]
  }'

이 구조에서 각 팀은 할당된 Virtual Key로만 API를 호출하므로, 예산 소진 시 자동으로 요청이 거부됩니다.

자체 Gateway 구축 시 고려사항

상용 Gateway나 LiteLLM으로 부족한 요구사항이 있다면 자체 구축을 검토합니다. 다만 아래 복잡도를 감수해야 합니다.

구성 요소	구현 내용
Reverse Proxy	Kong/Envoy 기반, 요청 라우팅 + 인증
Token Counter	Provider 응답 파싱, 모델별 과금 단위 매핑
Budget Engine	Redis/DB 기반 실시간 잔액 확인 + 차감
Alert Publisher	임계값 확인 → Slack/PagerDuty 발송
Dashboard Backend	집계 데이터 API → Grafana/커스텀 UI

자체 구축은 멀티 Provider(OpenAI + Anthropic + AWS Bedrock) 환경에서 통합 비용 관리가 필요하거나, Provider별 과금 모델 변경에 즉시 대응해야 하는 경우에 적합합니다.

비용 최적화와 거버넌스의 조합

비용 거버넌스는 단순히 "예산을 넘기지 마라"가 아닙니다. 예산 내에서 최대 가치를 뽑아내는 구조를 만드는 것이 목적입니다.

모델 Tiering 전략

모든 요청에 최고 성능 모델을 사용할 필요는 없습니다. 요청 복잡도에 따라 모델을 분류합니다.

Tier	용도	모델 예시	비용 수준
Tier 1	단순 분류, 요약, 포맷 변환	GPT-4o mini, Claude Haiku	$
Tier 2	일반 대화, 코드 생성, 분석	GPT-4o, Claude Sonnet 4	$$
Tier 3	복잡한 추론, 의사결정, 전문 분석	GPT-4o + Reasoning, Claude Opus 4	$$$

Gateway에서 요청 특성을 분석하여 자동으로 적절한 Tier 모델로 라우팅하면, 품질 저하 없이 비용을 줄일 수 있습니다.

캐싱과 비용 절감

동일하거나 유사한 요청이 반복되는 경우, Semantic Cache를 적용하면 토큰 비용을 크게 줄일 수 있습니다.

Exact Match Cache: 동일한 프롬프트에 대해 캐시된 응답을 반환합니다. FAQ 봇처럼 정형화된 질문에 효과적입니다.
Semantic Cache: 의미적으로 유사한 질문에 대해 캐시를 활용합니다. 임베딩 유사도 기반으로 동작합니다.
Provider Cache: OpenAI의 Prompt Caching, Anthropic의 Prompt Caching 등 Provider 자체 캐싱 기능을 활용합니다.

대시보드에서 캐시 히트율을 추적하면, 캐싱이 실제로 비용 절감에 기여하는지 정량적으로 확인할 수 있습니다.

실무 시나리오: 50인 규모 팀의 AI 비용 거버넌스

상황

3개 팀(Platform, Data, Product)이 AI 서비스를 사용합니다.
월 AI API 비용이 $30,000~$50,000 수준입니다.
각 팀이 별도 Provider API Key를 직접 사용하고 있어, 팀별 비용 추적이 불가능합니다.
월말에 청구서를 받고서야 예산 초과를 인지합니다.

설계 방안

LLM Gateway 도입: LiteLLM Proxy를 배포하고, 모든 팀이 Gateway를 통해서만 API를 호출하도록 합니다.
팀별 Virtual Key 발급: 각 팀에 예산이 설정된 Virtual Key를 발급합니다.
태그 강제화: Gateway에서 team_id, project_id 태그가 없는 요청은 거부합니다.
단계별 알림: 50%, 75%, 90%, 100% 임계값에서 Slack과 Email 알림을 발송합니다.
Grafana 대시보드: Gateway 메트릭을 Prometheus로 수집하고, 팀별/모델별 대시보드를 구성합니다.
월간 비용 리뷰: FinOps 담당자가 팀별 비용 보고서를 작성하고, 최적화 기회를 식별합니다.

기대 효과

팀별 비용 가시성 확보: "어떤 팀이 왜 이만큼 썼는지" 즉시 확인 가능
예산 초과 사전 차단: 90% 도달 시 자동 모델 다운그레이드
비용 30~40% 절감: 모델 Tiering + 캐싱 + 불필요한 요청 제거

거버넌스 도입 단계별 로드맵

모든 조직에 동일한 거버넌스 구조가 필요한 것은 아닙니다. AI 비용 규모와 조직 성숙도에 따라 단계적으로 도입합니다.

단계	AI 비용 규모	핵심 활동	도구
1단계: 가시화	< $5,000/월	Provider 대시보드로 비용 확인, 기본 예산 알림	Provider Dashboard, AWS Budgets
2단계: 귀속	$5,000~$20,000/월	LLM Gateway 도입, 팀별 Key 분리, 태깅	LiteLLM, 태그 정책
3단계: 제어	$20,000~$100,000/월	자동 예산 차단, 모델 Tiering, 캐싱	Gateway + Budget Engine
4단계: 최적화	> $100,000/월	Chargeback, 예측 모델, 자동 Right-sizing	FinOps 플랫폼, ML 예측

운영 시 주의사항

비용 데이터 지연

Provider별로 비용 데이터 반영 시점이 다릅니다.

OpenAI: Usage Dashboard는 최대 5분 지연, Billing은 최대 24시간 지연이 있을 수 있습니다.
AWS Bedrock: Cost Explorer는 최대 24시간 지연. 실시간 추적이 필요하면 CloudWatch 메트릭을 사용합니다.
자체 Gateway: 실시간 계측이 가능하지만, Provider 청구서와의 차이(반올림, 캐시 할인 등)가 발생할 수 있습니다.

실시간 대시보드와 월말 청구서 사이에 5~10% 수준의 차이는 정상입니다. 이 차이를 줄이려면 Provider별 과금 규칙(최소 과금 단위, 반올림 방식)을 정확히 파악해야 합니다.

예산 차단의 부작용

예산 100% 소진 시 요청을 차단하면 서비스 장애로 이어질 수 있습니다.

고객 대면 서비스: 차단 대신 Fallback 모델(저비용) 전환을 기본으로 설정합니다.
내부 도구: 차단 후 예산 증액 요청 프로세스를 마련합니다.
긴급 상황: 특정 Key나 서비스에 대해 예산 제한을 우회할 수 있는 Override 메커니즘을 준비합니다.

조직 저항 관리

초기에는 Showback으로 비용 가시성만 제공하고, 즉시 차단하지 않습니다.
팀별 예산을 설정할 때 현재 사용량 + 20~30% 여유분으로 시작합니다.
비용 절감이 아닌 "예측 가능한 비용 운영"을 목표로 커뮤니케이션합니다.

마무리

AI 서비스 비용 거버넌스의 핵심은 세 가지입니다.

식별: 누가, 무엇에, 얼마를 쓰는지 알아야 합니다 (LLM Gateway + 태깅).
통제: 예산을 설정하고, 초과 전에 대응해야 합니다 (임계값 알림 + 자동 차단/전환).
최적화: 같은 비용으로 더 많은 가치를 뽑아야 합니다 (모델 Tiering + 캐싱).

비용 거버넌스를 도입한다고 AI 혁신이 느려지는 것은 아닙니다. 오히려 비용 예측이 가능해야 조직이 AI 투자를 지속할 수 있습니다. "이번 달 AI 비용이 얼마나 나올지 모르겠다"는 상태가 지속되면, 경영진은 결국 AI 예산 자체를 줄이게 됩니다.

GitOps란 무엇인가: Argo CD와 Flux 중심으로

wero90 — Mon, 8 Jun 2026 16:18:52 +0900

Terraform으로 인프라를 코드로 관리하는 건 익숙해졌는데, Kubernetes 배포는 여전히 CI 파이프라인에서 kubectl apply를 실행합니다. 어느 날 누군가 클러스터에 직접 kubectl edit으로 설정을 바꿨고, 다음 배포에서 그 변경이 덮어씌워져 장애가 발생합니다. GitOps는 이 문제를 구조적으로 해결하는 운영 모델입니다.

핵심 요약

GitOps는 Git을 Single Source of Truth로 사용하여, 선언적으로 정의된 상태를 클러스터에 지속적으로 동기화하는 운영 모델입니다.
전통적인 CI/CD의 Push 방식과 달리, GitOps는 Pull 방식으로 동작합니다. 클러스터 내부의 Agent가 Git 상태를 감시하고 자동으로 조정합니다.
Argo CD는 Web UI와 멀티 클러스터 관리에 강점이 있어 플랫폼 팀에 적합합니다.
Flux는 컨트롤러 조합 방식의 경량 아키텍처로, Kustomize 기반 워크플로우와 이미지 자동 업데이트에 강점이 있습니다.
두 도구 모두 CNCF Graduated 프로젝트이며, 선택 기준은 팀 규모, UI 필요 여부, 매니페스트 관리 방식에 따라 달라집니다.

1. 왜 GitOps가 필요한가

팀에서 Kubernetes 기반 서비스를 운영하고 있다고 가정합니다. CI/CD 파이프라인은 GitHub Actions로 구축되어 있고, 배포 단계에서 kubectl apply나 helm upgrade를 실행합니다.

이 구조에서 흔히 발생하는 문제들:

문제	상황
Configuration Drift	운영자가 긴급 대응으로 클러스터에 직접 변경을 적용했지만, Git에는 반영하지 않음
배포 추적 어려움	"현재 클러스터에 어떤 버전이 떠 있는지"를 확인하려면 클러스터에 직접 접속해야 함
롤백 복잡성	이전 상태로 돌아가려면 어떤 커밋, 어떤 Helm values가 적용됐는지 추적해야 함
보안 리스크	CI 파이프라인에 클러스터 admin 권한 kubeconfig를 넣어야 배포가 가능함
멀티 클러스터 일관성	dev, staging, prod 환경 간 설정 차이가 누적되어 "staging에서 되는데 prod에서 안 됨" 발생

GitOps는 이 문제들을 하나의 원칙으로 해결합니다. Git에 있는 상태가 곧 클러스터의 상태여야 한다.

2. GitOps의 4대 원칙 (OpenGitOps)

CNCF OpenGitOps Working Group이 정의한 GitOps의 핵심 원칙은 4가지입니다.

GitOps Reconciliation Loop와 4대 원칙

원칙	설명	실무 의미
Declarative	시스템의 원하는 상태를 선언적으로 정의	Kubernetes YAML, Helm values, Kustomize overlay
Versioned & Immutable	선언된 상태를 버전 관리 시스템에 저장	Git 커밋 = 배포 이력. 모든 변경이 추적됨
Pulled Automatically	Agent가 원하는 상태를 자동으로 가져옴	클러스터 내부에서 Git을 polling하거나 webhook으로 감지
Continuously Reconciled	Agent가 실제 상태를 원하는 상태와 지속적으로 비교하고 조정	Drift 자동 감지 + 자동 복구 또는 알림

이 4가지 원칙의 조합이 만드는 핵심 가치는 자동 복구(Self-healing)입니다. 누군가 클러스터에서 직접 설정을 변경하더라도, Agent가 Git 상태로 되돌립니다.

3. Push 기반 vs Pull 기반 배포

GitOps를 이해하려면 기존 CI/CD와의 구조적 차이를 먼저 파악해야 합니다.

Push 기반 배포와 Pull 기반 배포(GitOps) 비교

Push 기반 (전통적 CI/CD)

# GitHub Actions 배포 단계 예시
- name: Deploy to EKS
  run: |
    aws eks update-kubeconfig --name my-cluster
    kubectl apply -f k8s/

CI 파이프라인이 클러스터에 직접 명령을 보냅니다.

장점: 구현이 단순하고, 기존 파이프라인에 배포 단계만 추가하면 됨
단점: CI 서버에 클러스터 접근 권한 필요, Drift 감지 불가, 배포 실패 시 상태 불확실

Pull 기반 (GitOps)

# Argo CD Application 정의 예시
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  source:
    repoURL: https://github.com/team/k8s-manifests
    targetRevision: main
    path: apps/my-app/production
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

클러스터 내부의 Agent가 Git을 감시하고, 변경이 감지되면 스스로 동기화합니다.

장점: 클러스터 자격 증명이 외부에 노출되지 않음, Drift 자동 감지/복구, Git 이력이 곧 배포 이력
단점: 별도 Agent 설치/운영 필요, 초기 학습 곡선 존재

실무에서의 조합 패턴

대부분의 팀은 순수한 Push 또는 Pull 중 하나만 사용하지 않습니다.

CI (Push 영역): 코드 빌드 → 테스트 → 이미지 빌드 → 레지스트리 Push → 매니페스트 업데이트
CD (Pull 영역): GitOps Agent가 매니페스트 변경 감지 → 클러스터 동기화

CI는 여전히 GitHub Actions/Jenkins가 담당하고, CD 부분만 GitOps 도구가 담당하는 구조가 일반적입니다.

4. Argo CD 아키텍처

Argo CD는 2022년 12월 CNCF Graduated 프로젝트가 되었으며, 현재 v3.3이 최신 안정 버전입니다. GitOps 도구 중 가장 높은 채택률을 보이며, CNCF 2025 End User Survey 기준 Kubernetes 클러스터의 약 60%에서 사용되고 있습니다.

Argo CD 아키텍처

핵심 컴포넌트

컴포넌트	역할
API Server	Web UI, CLI, gRPC API를 제공. 사용자 인터페이스의 진입점
Repo Server	Git 리포지토리를 클론하고, Helm/Kustomize/Jsonnet 등을 렌더링하여 최종 매니페스트 생성
Application Controller	실제 클러스터 상태를 원하는 상태와 비교하고, Sync를 실행하는 핵심 컨트롤러
Redis	캐시 레이어. 매니페스트 캐싱, 세션 관리 등에 활용

Argo CD의 강점

1. Web UI / 토폴로지 뷰

Argo CD의 가장 눈에 띄는 차별점은 Web UI입니다. Application 단위로 리소스 트리를 시각화하고, 각 리소스의 상태(Healthy/Degraded/Progressing)를 실시간으로 확인할 수 있습니다.

운영 중 장애 대응 시 "어떤 리소스가 문제인지"를 빠르게 파악할 수 있어, 특히 온콜 엔지니어에게 유용합니다.

2. 멀티 클러스터 중앙 관리

하나의 Argo CD 인스턴스에서 여러 클러스터를 관리할 수 있습니다. 관리 클러스터에 Argo CD를 설치하고, 대상 클러스터를 등록하는 방식입니다.

# 외부 클러스터 등록
argocd cluster add my-prod-cluster --kubeconfig ~/.kube/prod-config

3. ApplicationSet으로 대규모 배포 관리

수십 개의 Application을 개별 정의하는 대신, 템플릿 기반으로 대량 생성할 수 있습니다.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-app-set
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            env: production
  template:
    metadata:
      name: "my-app-#"
    spec:
      source:
        repoURL: https://github.com/team/k8s-manifests
        path: "apps/my-app/{{metadata.labels.region}}"
      destination:
        server: "#"
        namespace: production

4. Sync Waves & Hooks

배포 순서를 제어할 수 있습니다. 예를 들어 "DB 마이그레이션 → 앱 배포 → 테스트 실행" 순서를 보장합니다.

Argo CD의 운영 고려사항

리소스 사용량: API Server + Repo Server + Application Controller + Redis로 구성되어, 소규모 클러스터에서도 기본적으로 상당한 리소스를 소비합니다.
Repo Server 병목: 관리하는 Application 수가 많아지면 Repo Server의 Git 클론과 매니페스트 렌더링이 병목이 될 수 있습니다. sharding이나 수평 확장이 필요할 수 있습니다.
RBAC 설계: Argo CD 자체의 RBAC(프로젝트 기반)과 Kubernetes RBAC을 별도로 관리해야 합니다.

5. Flux 아키텍처

Flux는 2022년 11월 CNCF Graduated 프로젝트가 되었으며, 현재 v2.8이 최신 안정 버전입니다. Argo CD와 달리 단일 모놀리식 서비스가 아니라, 독립적인 컨트롤러의 조합으로 구성됩니다.

Flux 아키텍처

핵심 컨트롤러

컨트롤러	역할
Source Controller	Git, Helm, OCI 등 소스 리포지토리를 관리하고, 아티팩트를 다운로드
Kustomize Controller	Kustomize 빌드를 실행하고 결과를 클러스터에 적용
Helm Controller	HelmRelease CR을 관리하며 Helm 차트를 설치/업그레이드
Notification Controller	이벤트를 외부 시스템(Slack, Teams, webhook)으로 전달
Image Automation Controller	컨테이너 레지스트리에서 새 이미지 태그를 감지하고, Git에 자동 커밋

Flux의 강점

1. 경량 아키텍처

필요한 컨트롤러만 선택적으로 설치할 수 있습니다. Helm을 사용하지 않는 팀은 Helm Controller를 설치하지 않아도 됩니다.

# 기본 설치 (Source + Kustomize + Notification)
flux bootstrap github \
  --owner=my-org \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/production

2. 네이티브 이미지 자동 업데이트

CI에서 새 이미지를 빌드하면, Flux가 자동으로 감지하여 Git 리포지토리의 매니페스트를 업데이트합니다.

apiVersion: image.toolkit.fluxcd.io/v1beta2
kind: ImagePolicy
metadata:
  name: my-app
spec:
  imageRepositoryRef:
    name: my-app
  policy:
    semver:
      range: ">=1.0.0"

이 기능은 "CI가 이미지를 빌드하면, Flux가 Git에 커밋하고, 다시 Flux가 그 커밋을 감지해서 배포"하는 완전 자동화 루프를 만듭니다.

3. Kustomize 네이티브 통합

Flux는 Kustomize를 1등 시민(first-class citizen)으로 지원합니다. 복잡한 오버레이 구조를 그대로 활용할 수 있습니다.

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 10m
  sourceRef:
    kind: GitRepository
    name: fleet-infra
  path: ./apps/production
  prune: true
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: my-app
      namespace: production

4. 멀티 테넌시 설계

Flux는 각 대상 클러스터에 직접 설치되는 구조입니다. 팀별로 별도의 GitRepository와 Kustomization을 정의하여 테넌트 격리가 자연스럽습니다.

Flux의 운영 고려사항

UI 부재: 네이티브 Web UI가 없습니다. 상태 확인은 flux get CLI 또는 Grafana 대시보드로 해야 합니다. Weave GitOps(현 Flux Subsystem for Argo)를 추가 설치하면 UI를 사용할 수 있지만 별도 구성이 필요합니다.
디버깅 복잡도: 여러 컨트롤러가 독립적으로 동작하므로, 문제 발생 시 어떤 컨트롤러에서 이슈가 발생했는지 파악해야 합니다.
멀티 클러스터 관리: Argo CD처럼 중앙 집중식이 아니라, 각 클러스터에 Flux를 설치해야 합니다. 관리 오버헤드가 클러스터 수에 비례합니다.

6. Argo CD vs Flux: 선택 기준

기준	Argo CD	Flux
아키텍처	모놀리식 (API Server + Controller + Repo Server)	마이크로서비스 (독립 컨트롤러 조합)
UI	내장 Web UI (토폴로지 뷰, 실시간 상태)	없음 (CLI + Grafana 또는 별도 UI 설치)
멀티 클러스터	중앙 집중식 (한 곳에서 여러 클러스터 관리)	분산형 (각 클러스터에 설치)
매니페스트 렌더링	Helm, Kustomize, Jsonnet, 커스텀 플러그인	Helm, Kustomize (Jsonnet 미지원)
이미지 자동 업데이트	별도 프로젝트(Argo CD Image Updater)	네이티브 지원 (Image Automation Controller)
대규모 배포	ApplicationSet으로 템플릿 기반 대량 생성	Kustomization 계층 구조로 관리
CNCF 상태	Graduated (2022.12)	Graduated (2022.11)
리소스 소비	상대적으로 높음 (Redis, Repo Server 등)	상대적으로 낮음 (필요한 컨트롤러만 설치)
학습 곡선	UI가 있어 초기 진입이 쉬움	CLI 기반으로 Kubernetes 개념에 익숙해야 함
커뮤니티 규모	더 큼 (GitHub Stars 18k+, 채택률 약 60%)	상대적으로 작음 (채택률 약 11%)

이런 상황이면 Argo CD

팀에 Kubernetes 경험이 적은 멤버가 있어 UI 기반 관리가 필요할 때
하나의 플랫폼 팀이 여러 클러스터를 중앙에서 관리해야 할 때
배포 상태를 비개발자(PM, QA)에게도 가시적으로 보여줘야 할 때
ApplicationSet으로 수십 개 서비스를 템플릿화해야 할 때

이런 상황이면 Flux

Kustomize 기반 매니페스트 관리를 이미 하고 있을 때
이미지 태그 변경 시 자동으로 Git 커밋 → 배포까지 완전 자동화하고 싶을 때
클러스터별 독립적인 GitOps 운영이 필요할 때 (팀 자율성 우선)
리소스 소비를 최소화하고 싶은 소규모 클러스터일 때

실무 시나리오: 스타트업 vs 엔터프라이즈

스타트업 (클러스터 2~3개, 엔지니어 5명)

Argo CD를 하나의 관리 클러스터에 설치하고, dev/staging/prod 클러스터를 등록합니다. 전체 팀이 Web UI에서 배포 상태를 확인하고, PR 머지만으로 배포가 진행됩니다.

이 규모에서 Flux를 선택하면 각 클러스터에 별도 설치해야 하므로 관리 포인트가 늘어납니다. 다만 리소스가 제한적이라면 Flux의 경량 구조가 유리할 수 있습니다.

엔터프라이즈 (클러스터 50개+, 팀 20개+)

각 팀이 자체 클러스터와 GitOps 리포지토리를 관리합니다. 플랫폼 팀은 Flux bootstrap 구성을 표준화하고, 각 팀이 자율적으로 배포합니다. 중앙 집중식 Argo CD가 수백 개 Application을 관리하면 Repo Server와 Application Controller에 상당한 부하가 발생할 수 있습니다.

다만 엔터프라이즈에서도 Argo CD를 선택하는 경우가 많습니다. 이 경우 Argo CD를 팀별로 분리(sharding) 하거나, Application Controller를 수평 확장하는 전략을 적용합니다.

7. GitOps 도입 시 고려할 점

Git 리포지토리 구조 설계

GitOps를 도입할 때 가장 먼저 결정해야 하는 것은 리포지토리 구조입니다.

패턴	구조	장점	단점
Monorepo	앱 코드 + 매니페스트를 한 리포에	변경 추적이 단순	권한 분리 어려움
Polyrepo (App + Config 분리)	앱 리포 + 배포 매니페스트 리포 분리	명확한 관심사 분리	이미지 태그 업데이트 자동화 필요
Multi-tenant	환경/팀별 디렉토리 분리	멀티 테넌시 지원	디렉토리 구조가 복잡해질 수 있음

실무에서는 App 리포와 Config 리포를 분리하는 패턴이 보편적입니다. CI는 App 리포에서 이미지를 빌드하고, Config 리포의 이미지 태그를 업데이트합니다.

Secret 관리

Git에 Secret을 평문으로 저장할 수 없으므로, 별도 전략이 필요합니다.

도구	방식	연동
Sealed Secrets	암호화된 Secret을 Git에 저장, 클러스터에서 복호화	Argo CD / Flux 모두 지원
External Secrets Operator	AWS Secrets Manager/Vault 등 외부 저장소 참조	Argo CD / Flux 모두 지원
SOPS	파일 단위 암호화, KMS/PGP 기반	Flux 네이티브 지원, Argo CD는 플러그인

Flux는 SOPS(Mozilla)를 네이티브로 지원합니다. Argo CD를 사용한다면 External Secrets Operator 또는 Sealed Secrets를 조합하는 것이 일반적입니다.

Drift 감지 정책

GitOps Agent가 Drift를 감지했을 때 어떻게 대응할지 정책을 결정해야 합니다.

Auto-sync (자동 복구): Drift 발생 시 즉시 Git 상태로 되돌림. 운영 안정성이 높지만, 긴급 대응 시 불편할 수 있음.
Manual sync (알림만): Drift 감지 시 알림만 보내고, 수동으로 Sync 실행. 유연하지만 Drift가 방치될 수 있음.

운영 환경에서는 Auto-sync를 기본으로 하되, 특정 리소스(ConfigMap, HPA 등)는 제외하는 방식이 일반적입니다.

8. 관련 글

마무리

GitOps는 "배포를 어떻게 할 것인가"보다 "클러스터의 상태를 어떻게 관리할 것인가"에 초점을 맞춘 운영 모델입니다. Git을 중심으로 변경 이력 추적, 코드 리뷰 기반 배포, 자동 Drift 감지/복구가 가능해지며, 이는 특히 Kubernetes 환경에서 운영 안정성과 보안 수준을 높입니다.

Argo CD와 Flux 모두 성숙한 도구입니다. "어떤 것이 더 좋은가"보다 팀의 워크플로우, 기존 매니페스트 관리 방식, 멀티 클러스터 전략에 맞는 도구를 선택하는 것이 중요합니다.

Kubernetes OOMKilled 원인 분석과 메모리 설계

wero90 — Mon, 8 Jun 2026 15:55:16 +0900

Deployment를 배포한 뒤 한동안 잘 동작하던 Pod가 갑자기 재시작됩니다. kubectl describe pod를 확인하면 Reason: OOMKilled, Exit Code: 137이 보입니다. 메모리 limit을 올리면 잠시 괜찮다가 며칠 뒤 또 같은 증상이 반복됩니다. OOMKilled는 단순히 limit을 올린다고 해결되는 문제가 아닙니다. 왜 메모리가 초과했는지, 어느 수준에서 kill이 발생했는지, 어떤 기준으로 requests와 limits를 설계해야 하는지를 이해해야 재발을 방지할 수 있습니다.

핵심 요약

구분	Container OOMKilled	Node 수준 Eviction
트리거	컨테이너가 memory limit 초과	Node 가용 메모리가 eviction threshold 이하
Exit Code	137 (SIGKILL)	137 (SIGKILL)
Reason	`OOMKilled`	`Evicted`
대상	해당 컨테이너만 종료	QoS 등급 낮은 Pod부터 축출
확인 방법	`kubectl describe pod` → Last State	`kubectl describe node` → Conditions
해결 방향	limit 조정 또는 앱 메모리 최적화	requests 설정, Node 용량 확보

1. OOMKilled 동작 원리

OOMKilled는 두 가지 경로로 발생합니다. 하나는 컨테이너의 cgroup memory limit 초과, 다른 하나는 Node 전체 메모리 부족으로 인한 kubelet eviction입니다. 둘 다 Exit Code 137로 표시되지만, 원인과 대응 방법이 다릅니다.

OOMKilled 발생 경로

1-1. Container OOMKilled (cgroup 기반)

Kubernetes는 컨테이너의 resources.limits.memory를 Linux cgroup의 memory.max(cgroup v2) 또는 memory.limit_in_bytes(cgroup v1)로 설정합니다. 컨테이너 내 프로세스의 메모리 사용량(RSS + page cache 일부)이 이 값을 초과하면, 커널의 OOM Killer가 해당 cgroup 내 프로세스를 SIGKILL(signal 9)로 종료합니다.

핵심 포인트:

Exit Code 137 = 128 + 9 (SIGKILL)
컨테이너 단위로 격리되어, 같은 Pod의 다른 컨테이너에는 영향 없음
limit이 설정되지 않은 컨테이너는 Node의 전체 메모리를 사용할 수 있어서, 다른 Pod에 영향을 줄 수 있음

1-2. Node 수준 Eviction

kubelet은 Node의 가용 메모리를 주기적으로 확인합니다. memory.available이 eviction threshold(기본: 100Mi) 아래로 내려가면, QoS 등급이 낮은 Pod부터 축출(evict)합니다.

QoS 등급별 축출 우선순위:

QoS Class	조건	축출 우선순위
BestEffort	requests/limits 모두 미설정	가장 먼저 축출
Burstable	requests < limits 또는 일부만 설정	두 번째
Guaranteed	requests = limits (모든 컨테이너)	가장 마지막

운영 환경에서는 모든 컨테이너에 최소 requests를 설정하여 BestEffort 등급을 피해야 합니다. BestEffort Pod는 Node에 메모리 압박이 오면 가장 먼저 종료됩니다.

2. OOMKilled 진단 절차

2-1. Pod 상태에서 OOMKilled 확인

# 1. Pod 상태 확인
kubectl describe pod <pod-name> -n <namespace>

출력에서 확인할 부분:

State:          Waiting
  Reason:       CrashLoopBackOff
Last State:     Terminated
  Reason:       OOMKilled
  Exit Code:    137
  Started:      Mon, 08 Jun 2026 09:15:00 +0900
  Finished:     Mon, 08 Jun 2026 11:42:33 +0900

Reason: OOMKilled가 명시되면 container limit 초과입니다. Reason: Evicted면 Node 수준 메모리 부족입니다.

2-2. Container OOMKilled vs Node Eviction 구분

# Container OOMKilled인 경우 — Pod는 같은 Node에서 재시작
kubectl get pod <pod-name> -n <namespace> -o wide
# RESTARTS 증가, NODE 동일

# Node Eviction인 경우 — Pod가 다른 Node로 이동
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | grep -i evict
# "The node was low on resource: memory" 메시지 확인

2-3. 현재 메모리 사용량과 limit 비교

# 실시간 메모리 사용량 (metrics-server 필요)
kubectl top pod <pod-name> -n <namespace> --containers

# 설정된 limit 확인
kubectl get pod <pod-name> -n <namespace> \
  -o jsonpath='{range .spec.containers[*]}{.name}{"\t"}{.resources.limits.memory}{"\n"}{end}'

출력 예시:

CONTAINER    MEMORY(bytes)
my-app       480Mi

my-app    512Mi    (← limit)

사용량이 limit에 근접하면 OOMKilled 위험이 높습니다. kubectl top은 특정 시점의 스냅샷이므로, 피크 시점을 포착하려면 모니터링 도구(Prometheus 등)에서 container_memory_working_set_bytes 메트릭을 확인하는 것이 정확합니다.

2-4. Node 수준 메모리 상태 확인

# Node 리소스 상태
kubectl describe node <node-name> | grep -A 5 "Conditions"
# MemoryPressure가 True이면 Node 수준 메모리 부족

# Node에서 실행 중인 Pod의 메모리 requests 합계
kubectl describe node <node-name> | grep -A 20 "Allocated resources"

출력 예시:

Conditions:
  Type               Status
  MemoryPressure     False
  DiskPressure       False
  PIDPressure        False
  Ready              True

Allocated resources:
  Resource           Requests    Limits
  memory             3200Mi (82%)  5120Mi (131%)

Limits 합계가 Node 용량을 초과(overcommit)하는 것은 허용되지만, 동시에 모든 Pod가 limit까지 사용하면 OOM이 발생합니다.

OOMKilled 진단 흐름

3. 원인별 분석

3-1. Memory Limit이 실제 사용량보다 낮게 설정된 경우

가장 단순한 원인입니다. 애플리케이션의 정상 동작에 필요한 메모리보다 limit이 낮게 설정되어 있습니다.

실무 시나리오:

Java Spring Boot 애플리케이션을 배포합니다. 개발 환경에서 kubectl top으로 확인한 메모리가 300Mi 정도여서 limit을 512Mi로 설정했습니다. 하지만 운영 환경에서는 동시 요청이 많아지면 Thread Pool, Connection Pool, HTTP 요청 버퍼 등이 추가로 메모리를 소비하여 512Mi를 초과합니다.

진단:

# Prometheus 쿼리로 메모리 피크 확인
# container_memory_working_set_bytes{pod="my-app-xxx", container="my-app"}
# 또는 kubectl top으로 부하 시점에 확인

kubectl top pod -n production --containers | grep my-app

해결:

부하 테스트를 수행한 뒤, P99 메모리 사용량을 기준으로 limit을 설정합니다.

spec:
  containers:
    - name: my-app
      resources:
        requests:
          memory: "512Mi"    # P50 사용량 기준
        limits:
          memory: "1Gi"      # P99 사용량 + 20% 여유

3-2. 메모리 누수 (Memory Leak)

시간이 지날수록 메모리 사용량이 계속 증가하여 결국 limit에 도달하는 패턴입니다. limit을 올려도 시간이 더 걸릴 뿐 결국 OOMKilled가 발생합니다.

실무 시나리오:

Node.js Express 서버에서 요청마다 캐시 객체에 데이터를 저장하는데, 만료 정책 없이 무한히 쌓입니다. 배포 직후에는 메모리가 200Mi 수준이지만, 며칠 운영 후 limit(1Gi)에 도달하여 OOMKilled가 됩니다.

메모리 누수를 의심할 수 있는 패턴:

배포 직후에는 정상이지만, 일정 시간(수 시간~수 일) 후 OOMKilled 발생
limit을 올려도 더 오래 버틸 뿐 결국 같은 증상 반복
Prometheus 그래프에서 메모리가 계속 우상향 (톱니 패턴 없이)

진단:

# 시간별 메모리 추이 확인 (Prometheus/Grafana)
# rate(container_memory_working_set_bytes{pod=~"my-app.*"}[1h])

# Pod가 시작된 지 얼마나 됐는지 확인
kubectl get pod <pod-name> -n <namespace> \
  -o jsonpath='{.status.startTime}'

해결 방향:

앱 코드에서 메모리 누수 원인을 찾아 수정 (근본 해결)
임시 방편: 정기적으로 Pod를 재시작 (롤링 리스타트 CronJob)

# 임시 방편 — 매일 새벽 3시에 롤링 리스타트
# CronJob으로 kubectl rollout restart를 수행
kubectl rollout restart deployment/my-app -n production

주의
정기 재시작은 메모리 누수의 근본 해결이 아닙니다. 누수 원인을 찾는 동안 서비스 안정성을 유지하기 위한 임시 방편입니다. 장기적으로는 프로파일링 도구(Java: JFR/VisualVM, Node.js: --inspect, Go: pprof)로 누수 지점을 식별하고 코드를 수정해야 합니다.

3-3. JVM 메모리 구조와 컨테이너 limit 불일치

Java 애플리케이션에서 가장 흔한 OOMKilled 원인입니다. JVM의 전체 메모리 사용량은 Heap만이 아닙니다.

JVM 메모리 구성:

영역	설명	크기 예시
Heap (-Xmx)	객체 저장	512Mi
Metaspace	클래스 메타데이터	100~200Mi
Thread Stack	스레드당 1Mi (기본)	200 threads × 1Mi = 200Mi
Native Memory	JNI, NIO DirectBuffer	50~200Mi
Code Cache	JIT 컴파일 코드	50~240Mi
GC 오버헤드	GC 알고리즘 내부 구조	가변

실무 시나리오:

Container limit을 1Gi로 설정하고, -Xmx512m을 지정했습니다. Heap은 512Mi지만 Metaspace(150Mi) + Thread Stack(200개 스레드 × 1Mi) + Native(100Mi)을 합치면 약 960Mi~1Gi에 달합니다. 트래픽이 몰려 스레드가 더 생성되면 limit을 초과합니다.

권장 설정:

spec:
  containers:
    - name: java-app
      resources:
        requests:
          memory: "768Mi"
        limits:
          memory: "1Gi"
      env:
        - name: JAVA_OPTS
          value: "-Xms256m -Xmx512m -XX:MaxMetaspaceSize=150m -XX:ReservedCodeCacheSize=64m"

JVM과 Container limit 관계 설계 공식:

Container limit ≥ Xmx + MaxMetaspaceSize + (Thread수 × ThreadStackSize) + Native + 여유(100~200Mi)

일반적으로 -Xmx를 container limit의 50~70%로 설정하면 Non-Heap 영역을 위한 여유가 확보됩니다.

Tip
Java 17+ 에서는 -XX:MaxRAMPercentage=70.0 옵션으로 컨테이너 메모리 limit의 70%를 자동으로 Heap에 할당할 수 있습니다. -Xmx를 직접 계산할 필요가 줄어듭니다. 다만 이 옵션은 cgroup limit을 기준으로 동작하므로, limit이 설정되어 있어야 합니다.

3-4. Node.js / Go 런타임 메모리 설정

Node.js:

V8 엔진의 기본 Heap 크기는 약 1.5~2GB(64비트 시스템)입니다. Container limit이 512Mi인데 V8이 기본 설정으로 동작하면 limit을 초과할 수 있습니다.

spec:
  containers:
    - name: node-app
      resources:
        limits:
          memory: "512Mi"
      env:
        - name: NODE_OPTIONS
          value: "--max-old-space-size=384"  # limit의 75% (MiB 단위)

Go:

Go 런타임은 기본적으로 가용 메모리의 일정 비율을 GC 트리거 기준으로 사용합니다. Go 1.19+에서는 GOMEMLIMIT 환경변수로 메모리 사용 상한을 설정할 수 있습니다.

spec:
  containers:
    - name: go-app
      resources:
        limits:
          memory: "256Mi"
      env:
        - name: GOMEMLIMIT
          value: "200MiB"   # limit의 약 80%
        - name: GOGC
          value: "100"      # 기본값 유지, 필요시 50으로 낮춰 GC 빈도 증가

3-5. 사이드카 컨테이너 메모리 미포함

Pod에 사이드카(Istio Envoy, Fluentd, CloudSQL Proxy 등)가 있을 때, 메인 컨테이너만 고려하고 사이드카의 메모리를 빠뜨리는 경우입니다.

실무 시나리오:

Istio Service Mesh를 사용하는 클러스터에서, 메인 앱 컨테이너 limit을 512Mi로 설정합니다. Istio가 자동 주입하는 Envoy 사이드카(istio-proxy)는 기본적으로 requests 128Mi, limit 미설정입니다. 트래픽이 많아지면 Envoy가 200~300Mi를 사용하면서 Node 메모리를 압박합니다. Node Eviction으로 다른 Pod가 축출되는 원인이 됩니다.

확인 방법:

# Pod의 모든 컨테이너 리소스 확인
kubectl get pod <pod-name> -n <namespace> -o json | \
  jq '.spec.containers[] | {name, resources}'

# 모든 컨테이너의 실제 사용량 확인
kubectl top pod <pod-name> -n <namespace> --containers

해결:

# Istio 사이드카 리소스 설정 (Pod annotation)
metadata:
  annotations:
    sidecar.istio.io/proxyMemoryLimit: "256Mi"
    sidecar.istio.io/proxyMemory: "128Mi"

4. requests와 limits 설계 전략

4-1. 설계 원칙

항목	requests	limits
목적	스케줄링 기준 (Node에 공간 예약)	런타임 상한 (초과 시 OOMKill)
기준값	P50~P75 메모리 사용량	P99 + 20~30% 여유
미설정 시	스케줄러가 0으로 간주 (어디든 배치)	Node 전체 메모리 사용 가능
QoS 영향	Guaranteed: requests = limits	BestEffort: 둘 다 미설정

4-2. 측정 기반 설정 절차

부하 테스트 실행: 운영과 유사한 트래픽 패턴으로 부하를 생성합니다.
메트릭 수집: container_memory_working_set_bytes를 15~30분간 관찰합니다.
백분위 계산: P50(requests 후보), P99(limits 후보)를 도출합니다.
여유분 추가: limits = P99 × 1.2~1.3 (버스트 대응)
검증: 설정 후 1~2주 운영하면서 OOMKilled 재발 여부 확인

# Prometheus 쿼리 — P99 메모리 사용량 (최근 7일)
quantile_over_time(0.99, 
  container_memory_working_set_bytes{
    namespace="production", 
    pod=~"my-app.*", 
    container="my-app"
  }[7d]
)

4-3. requests = limits로 설정할지 여부

Guaranteed QoS (requests = limits):

장점: OOM 시 가장 마지막에 축출. 성능 예측 가능.
단점: 메모리 효율이 낮음 (사용하지 않는 메모리도 예약됨).
적합한 경우: 미션 크리티컬 서비스, DB, 메시지 큐 등

Burstable QoS (requests < limits):

장점: 평상시 메모리 효율 높음. Node에 더 많은 Pod 배치 가능.
단점: 메모리 경합 시 축출 대상이 될 수 있음.
적합한 경우: 일반 웹 서비스, 배치 작업, 트래픽 변동이 큰 서비스

실무 권장:

# 미션 크리티컬 서비스 — Guaranteed
resources:
  requests:
    memory: "1Gi"
  limits:
    memory: "1Gi"

# 일반 웹 서비스 — Burstable
resources:
  requests:
    memory: "512Mi"    # P50 사용량
  limits:
    memory: "1Gi"      # P99 + 여유

메모리 설계 전략

5. Memory QoS와 cgroup v2 (Kubernetes v1.36)

Kubernetes v1.36에서는 Memory QoS 기능이 알파 단계로 제공됩니다(KEP-2570). 이 기능은 cgroup v2의 memory.min, memory.low, memory.high 컨트롤러를 활용하여, 단순한 "limit 초과 → 즉시 OOM Kill" 이외의 단계적 메모리 보호를 제공합니다.

기존 방식 (cgroup v1 또는 Memory QoS 미사용):

memory.max = limits.memory → 초과 즉시 OOM Kill
단계적 경고나 throttling 없음

Memory QoS 활성화 시 (cgroup v2 + MemoryQoS feature gate):

cgroup v2 파라미터	Kubernetes 매핑	동작
`memory.min`	requests.memory	커널이 이 크기까지는 회수하지 않음 (hard reservation)
`memory.low`	정책에 따라 자동 설정	이 이하로는 가급적 회수하지 않음 (soft protection)
`memory.high`	limits.memory 근처	초과 시 throttling (프로세스 느려짐, kill은 아님)
`memory.max`	limits.memory	초과 시 OOM Kill

의미:

requests로 설정한 메모리는 Node에 메모리 압박이 와도 커널이 보호합니다.
limits에 도달하기 전에 throttling 단계가 있어, 즉시 kill 대신 "느려짐" 상태를 먼저 경험합니다.
운영자 입장에서 OOMKilled 빈도를 줄일 수 있는 가능성이 있습니다.

주의
Memory QoS는 Kubernetes v1.36 기준 알파 기능입니다. 프로덕션에서 사용하려면 feature gate를 명시적으로 활성화해야 하며, Node OS가 cgroup v2를 지원해야 합니다. EKS(Amazon Linux 2023), AKS, GKE Autopilot은 기본적으로 cgroup v2를 사용하지만, 클러스터별로 확인이 필요합니다.

6. 실무 시나리오: Java 서비스 OOMKilled 디버깅

상황: 운영 환경의 Java Spring Boot 서비스가 배포 후 2~3시간이 지나면 OOMKilled로 재시작됩니다. Container limit은 1Gi, -Xmx는 설정하지 않은 상태입니다.

진단 과정:

# 1. OOMKilled 확인
kubectl describe pod order-service-7f8b9c-x4k2p -n production | grep -A 5 "Last State"
# Last State:     Terminated
#   Reason:       OOMKilled
#   Exit Code:    137

# 2. 현재 메모리 사용량 확인
kubectl top pod order-service-7f8b9c-x4k2p -n production --containers
# CONTAINER       CPU    MEMORY
# order-service   120m   945Mi    ← limit(1Gi)에 근접

# 3. JVM 메모리 상세 확인 (Pod 접속 가능할 때)
kubectl exec order-service-7f8b9c-x4k2p -n production -- \
  java -XX:+PrintFlagsFinal -version 2>&1 | grep -i "maxheapsize\|maxram"
# MaxHeapSize = 268435456 (256Mi) ← 기본값: container limit의 25%

# 4. Metaspace 확인 (JFR 또는 JMX로)
# Metaspace: 180Mi, Threads: 250개 × 1Mi = 250Mi
# 합계: Heap(256Mi) + Metaspace(180Mi) + Threads(250Mi) + Native(150Mi) ≈ 836Mi~1Gi+

원인 분석:

-Xmx를 지정하지 않으면 JVM은 기본적으로 container limit의 25%(또는 물리 메모리의 25%)를 Heap으로 사용합니다. 1Gi limit에서 Heap은 약 256Mi입니다. 다만 Non-Heap 영역(Metaspace, Thread Stack, Native Memory)이 예상보다 커서 전체 합이 1Gi를 초과합니다.

해결:

spec:
  containers:
    - name: order-service
      image: order-service:v2.1.0
      resources:
        requests:
          memory: "1Gi"
        limits:
          memory: "1536Mi"    # 1.5Gi로 상향
      env:
        - name: JAVA_OPTS
          value: >-
            -XX:MaxRAMPercentage=65.0
            -XX:InitialRAMPercentage=50.0
            -XX:MaxMetaspaceSize=200m
            -XX:ReservedCodeCacheSize=64m
            -Xss512k

설정 근거:

MaxRAMPercentage=65.0: 1536Mi의 65% ≈ 998Mi를 Heap으로 사용
MaxMetaspaceSize=200m: Metaspace 상한 제한
Xss512k: 기본 1MB인 Thread Stack을 512KB로 줄임 (250 threads × 512KB = 125Mi 절약)
총 예상: Heap(998Mi) + Metaspace(200Mi) + Threads(125Mi) + Native(100Mi) = 1423Mi < 1536Mi

7. limits 없이 운영하는 전략

일부 팀에서는 memory limits를 설정하지 않고 requests만 설정하는 전략을 사용합니다. 이 접근의 trade-off를 이해해야 합니다.

limits 미설정 시:

장점: OOMKilled가 발생하지 않음 (container 수준). 앱이 일시적으로 많은 메모리를 사용해도 kill되지 않음.
단점: Node 전체 메모리를 소진할 수 있음. 다른 Pod에 영향. Node Eviction 발생 가능.

이 전략이 적합한 경우:

Node당 하나의 서비스만 운영하는 경우
모니터링이 잘 되어 있고, 메모리 이상을 빠르게 감지할 수 있는 경우
서비스의 메모리 사용 패턴이 예측 가능한 경우

이 전략이 위험한 경우:

멀티 테넌트 클러스터 (여러 팀이 같은 Node를 공유)
메모리 누수 가능성이 있는 서비스
BestEffort Pod가 혼재하는 환경

운영 환경에서는 일반적으로 limits를 설정하는 것이 안전합니다. 하나의 Pod가 Node 전체를 다운시키는 상황을 방지할 수 있기 때문입니다.

8. 재발 방지 체크리스트

항목	확인 내용	권장 방법
메모리 측정	부하 테스트로 P99 사용량 확인했는가?	최소 30분 부하 테스트 수행
requests 설정	P50~P75 기준으로 설정했는가?	BestEffort 등급 방지
limits 설정	P99 + 20~30% 여유가 있는가?	버스트 대응
런타임 설정	JVM/Node.js/Go의 메모리 옵션이 limit과 정합하는가?	Heap ≤ limit의 70%
사이드카	Envoy, 로그 수집기 등의 메모리를 포함했는가?	모든 컨테이너 합계 확인
모니터링	`container_memory_working_set_bytes` 알림 설정했는가?	limit의 80% 도달 시 경고
메모리 누수	시간 경과에 따른 메모리 증가 패턴이 있는가?	프로파일링 도구 사용
Node 용량	requests 합계가 Node allocatable의 80% 이하인가?	시스템 예약분 확보

9. 모니터링 알림 설정 예시

OOMKilled가 발생하기 전에 경고를 받으려면, 메모리 사용률이 limit의 80%에 도달했을 때 알림을 보내는 것이 효과적입니다.

Prometheus Alerting Rule:

groups:
  - name: memory-alerts
    rules:
      - alert: ContainerMemoryNearLimit
        expr: |
          container_memory_working_set_bytes{container!=""}
          /
          container_spec_memory_limit_bytes{container!=""}
          > 0.8
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Container {{ $labels.container }} in pod {{ $labels.pod }} is using >80% of memory limit"
          description: "Current usage: {{ $value | humanizePercentage }} of limit. OOMKilled risk is high."

      - alert: ContainerOOMKilled
        expr: |
          kube_pod_container_status_last_terminated_reason{reason="OOMKilled"} == 1
        for: 0m
        labels:
          severity: critical
        annotations:
          summary: "Container {{ $labels.container }} in pod {{ $labels.pod }} was OOMKilled"

10. 정리

OOMKilled는 container limit 초과(cgroup OOM)와 Node 메모리 부족(kubelet eviction) 두 경로로 발생합니다. kubectl describe pod에서 Reason을 확인하여 구분합니다.
limit을 올리는 것은 임시 방편입니다. 메모리 누수가 원인이면 결국 재발합니다. 시간에 따른 메모리 추이를 먼저 확인하세요.
JVM 애플리케이션은 Heap 외에 Metaspace, Thread Stack, Native Memory를 합산해야 합니다. -Xmx를 container limit의 50~70%로 설정하는 것이 안전합니다.
requests는 스케줄링과 QoS 등급에 영향합니다. BestEffort 등급을 피하려면 최소한 requests를 설정해야 합니다.
부하 테스트 → P99 측정 → limits 설계 순서로 접근하면, 추측이 아닌 데이터 기반으로 안정적인 메모리 설정이 가능합니다.

참고 문서

OpenTelemetry란 무엇인가: 분산 트레이싱 기본 개념

wero90 — Mon, 8 Jun 2026 12:57:58 +0900

마이크로서비스 환경에서 "이 요청이 어디서 느려지는가"를 확인하려면 서비스 간 요청 경로를 추적할 수 있어야 합니다. OpenTelemetry는 이 추적 데이터를 벤더 종속 없이 수집하는 오픈소스 표준입니다. Trace, Span, Context Propagation의 동작 원리를 이해하면 분산 시스템의 병목을 체계적으로 진단할 수 있습니다.

핵심 요약

OpenTelemetry(OTel)는 Metrics, Logs, Traces를 수집하는 CNCF Graduated 오픈소스 표준입니다. 2026년 5월 CNCF 졸업(Graduated) 단계에 도달했습니다.
분산 트레이싱은 하나의 요청이 여러 서비스를 거치는 경로를 Trace ID로 연결하여 추적하는 기술입니다.
OpenTelemetry는 계측(Instrumentation)과 백엔드(Storage/Analysis)를 분리합니다. SDK로 데이터를 생성하고, Collector로 처리한 뒤, 원하는 백엔드(Jaeger, Datadog, Tempo 등)로 전송합니다.
W3C Trace Context 표준(traceparent 헤더)을 통해 서비스 간 Context를 전파합니다.
Collector는 Receiver → Processor → Exporter 파이프라인으로 구성되며, 배포 패턴(Agent, Gateway)에 따라 확장성과 운영 복잡도가 달라집니다.

1. 왜 필요한가

5개 마이크로서비스로 구성된 이커머스 시스템을 운영하고 있다고 가정합니다. 사용자가 "결제 완료까지 8초 이상 걸린다"고 신고합니다.

각 서비스의 로그를 확인하면:

API Gateway: 요청 수신 → 정상 (50ms)
Order Service: 주문 생성 → 정상 (100ms)
Inventory Service: 재고 확인 → 정상 (80ms)
Payment Service: 결제 요청 → ??? (로그에 에러 없음)
Notification Service: 알림 발송 → 정상 (200ms)

개별 서비스는 에러를 남기지 않지만, 전체 응답 시간은 8초입니다. "어디에서 시간이 소요되는가?"를 파악하려면 하나의 요청이 서비스를 거치는 전체 경로를 한 화면에서 볼 수 있어야 합니다.

이것이 분산 트레이싱이 해결하는 문제입니다.

그런데 트레이싱을 도입하려면 또 다른 문제가 생깁니다:

문제	설명
벤더 종속	Datadog SDK로 계측하면 나중에 Jaeger로 바꿀 때 전체 코드 수정 필요
팀별 도구 파편화	A팀은 Zipkin, B팀은 Jaeger를 사용하면 Trace가 연결되지 않음
일관성 부재	서비스마다 다른 형식으로 데이터를 내보내면 중앙에서 분석 불가

OpenTelemetry는 이 문제들을 해결합니다. 계측은 OTel SDK 하나로 통일하고, 백엔드는 자유롭게 선택하거나 교체할 수 있습니다.

2. OpenTelemetry란 무엇인가

OpenTelemetry(OTel)는 Observability 데이터(Metrics, Logs, Traces)를 생성, 수집, 전송하기 위한 오픈소스 표준 프레임워크입니다.

배경

OpenTelemetry는 두 개의 CNCF 프로젝트가 합쳐져 탄생했습니다:

OpenTracing (2016): 분산 트레이싱 API 표준
OpenCensus (2018): Google이 주도한 메트릭 + 트레이싱 라이브러리

두 프로젝트가 겹치는 영역이 많아 2019년에 합쳐져 OpenTelemetry가 되었습니다. 2026년 5월 21일 CNCF Graduated 프로젝트로 승격되어 프로덕션 사용 준비가 완료된 성숙 단계에 도달했습니다.

OpenTelemetry가 하는 것과 하지 않는 것

OTel이 하는 것	OTel이 하지 않는 것
텔레메트리 데이터 생성 (SDK)	데이터 저장
데이터 수집 및 처리 (Collector)	데이터 분석/시각화
표준 프로토콜 정의 (OTLP)	알림 발생
자동 계측 (Auto-instrumentation)	대시보드 제공
다양한 백엔드로 내보내기 (Exporter)	장애 대응 자동화

핵심 설계 원칙은 "계측과 백엔드의 분리"입니다. 애플리케이션 코드에서 데이터를 생성하는 부분(SDK)과, 그 데이터를 저장하고 분석하는 부분(Backend)을 독립적으로 선택할 수 있습니다.

지원 언어

OpenTelemetry SDK는 주요 언어를 지원합니다:

언어	Traces 상태	Metrics 상태	Logs 상태
Java	Stable	Stable	Stable
Python	Stable	Stable	Stable
Go	Stable	Stable	Stable
JavaScript/Node.js	Stable	Stable	Stable
.NET (C#)	Stable	Stable	Stable
C++	Stable	Stable	Stable
Rust	Stable	Stable	Stable
PHP	Stable	Stable	Stable
Ruby	Stable	Stable	Stable
Swift	Stable	Stable	Experimental
Erlang/Elixir	Stable	Stable	Experimental

Java, Python, .NET, PHP, JavaScript는 코드 수정 없이 자동 계측(Zero-code instrumentation)도 지원합니다.

3. 전체 아키텍처

OpenTelemetry 전체 아키텍처

OpenTelemetry의 전체 구조는 세 계층으로 나뉩니다:

계층별 역할

계층	구성 요소	역할
생성 (Instrumentation)	SDK, Auto-instrumentation	애플리케이션에서 텔레메트리 데이터 생성
수집/처리 (Collection)	Collector (Receiver → Processor → Exporter)	데이터를 받아서 가공하고 내보냄
저장/분석 (Backend)	Jaeger, Prometheus, Grafana, Datadog 등	데이터를 저장하고 시각화/분석

이 구조의 장점:

백엔드 교체가 자유로움: Jaeger에서 Grafana Tempo로 바꿔도 애플리케이션 코드를 수정하지 않음
데이터 처리를 중앙화: Collector에서 샘플링, 필터링, 메타데이터 추가를 한 곳에서 관리
언어에 구애받지 않음: Java, Python, Go 등 각 서비스 언어에 맞는 SDK를 사용하되, 출력 형식은 OTLP로 통일

4. 분산 트레이싱 핵심 개념

분산 트레이싱은 OpenTelemetry의 세 Signal(Traces, Metrics, Logs) 중 가장 먼저 안정화된 영역이며, 분산 시스템 디버깅의 핵심입니다.

Trace와 Span

용어	설명	비유
Trace	하나의 요청에 대한 전체 처리 경로	택배 배송의 전체 경로 (출발지 → 도착지)
Span	하나의 작업 단위	각 중간 경유지에서의 처리 (집하 → 허브 → 배달)
Root Span	Trace의 첫 번째 Span (부모 없음)	최초 출발지
Child Span	다른 Span에 의해 생성된 Span	경유지에서 다음 경유지로 넘기는 과정

하나의 Trace는 여러 Span의 트리 구조입니다:

Trace (trace_id: abc-123)
├─ Span A: API Gateway (root span)
│   ├─ Span B: Order Service
│   │   ├─ Span D: DB Query (SELECT orders)
│   │   └─ Span E: Payment Service 호출
│   │       └─ Span F: 외부 PG API 호출
│   └─ Span C: Notification Service

Span의 구조

각 Span은 다음 정보를 포함합니다:

{
  "name": "POST /api/orders",
  "context": {
    "trace_id": "5b8aa5a2d2c872e8321cf37308d69df2",
    "span_id": "051581bf3cb55c13"
  },
  "parent_span_id": "e457b5a2e4d86bd1",
  "start_time": "2026-06-08T10:15:30.123Z",
  "end_time": "2026-06-08T10:15:30.456Z",
  "duration_ms": 333,
  "status": "OK",
  "kind": "SERVER",
  "attributes": {
    "http.method": "POST",
    "http.url": "/api/orders",
    "http.status_code": 201,
    "service.name": "order-service",
    "db.system": "postgresql"
  },
  "events": [
    {
      "name": "order.validated",
      "timestamp": "2026-06-08T10:15:30.200Z"
    }
  ]
}

주요 필드:

필드	설명
trace_id	요청 전체를 식별하는 128bit ID (모든 서비스가 공유)
span_id	개별 작업을 식별하는 64bit ID
parent_span_id	이 Span을 호출한 부모 Span의 ID
kind	SERVER, CLIENT, PRODUCER, CONSUMER, INTERNAL 중 하나
attributes	키-값 쌍으로 된 메타데이터 (Semantic Conventions 기반)
events	Span 실행 중 발생한 시점별 이벤트
status	OK, ERROR, UNSET

Span Kind의 의미

Kind	설명	예시
SERVER	서버로서 요청을 수신	HTTP 서버가 요청을 처리
CLIENT	클라이언트로서 요청을 발신	HTTP 클라이언트가 다른 서비스 호출
PRODUCER	비동기 메시지를 생성	Kafka Producer가 메시지 발행
CONSUMER	비동기 메시지를 소비	Kafka Consumer가 메시지 처리
INTERNAL	내부 작업 (네트워크 호출 없음)	함수 내부 로직

5. Context Propagation: 서비스 간 추적 연결

Context Propagation 동작 원리

분산 트레이싱에서 가장 중요한 메커니즘은 Context Propagation입니다. 서비스 A가 서비스 B를 호출할 때 "이 요청은 같은 Trace의 일부"라는 정보를 전달해야 합니다.

W3C Trace Context 표준

OpenTelemetry는 W3C Trace Context 표준을 기본 전파 형식으로 사용합니다. HTTP 요청 시 traceparent 헤더에 Context를 담아 전달합니다.

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
             ^^-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^-^^^^^^^^^^^^^^^^-^^
             |  |                                |                |
             |  trace-id (128bit)               span-id (64bit)  flags
             version                                              (sampled)

필드	설명
version	항상 `00` (현재 버전)
trace-id	요청 전체를 식별하는 ID (32 hex chars)
span-id	현재 Span ID (16 hex chars) — 수신 서비스가 parent로 사용
flags	`01` = sampled (수집 대상), `00` = not sampled

전파 과정 예시

API Gateway: 요청 수신 → Trace ID가 없으면 새로 생성 → traceparent 헤더에 포함하여 다음 서비스 호출
Order Service: traceparent 헤더에서 trace-id와 parent span-id를 추출 → 새 Span 생성 (parent = 수신한 span-id) → 다음 호출 시 자신의 span-id를 traceparent에 담아 전달
Payment Service: 동일한 과정 반복

이렇게 모든 서비스가 같은 trace-id를 공유하면서 각자의 Span을 기록하면, 나중에 수집기에서 trace-id로 모든 Span을 조합하여 전체 경로를 재구성할 수 있습니다.

전파가 실패하는 경우

원인	증상	해결
미들웨어가 traceparent 헤더를 제거	Trace가 서비스 경계에서 끊어짐	프록시/게이트웨이에서 헤더 보존 설정
비동기 메시징(Kafka)에서 전파 누락	Consumer Span이 별도 Trace로 분리	Message 헤더에 traceparent 포함
서비스가 OTel SDK를 사용하지 않음	해당 서비스의 Span이 누락	SDK 적용 또는 프록시 레벨에서 Span 생성
레거시 시스템이 커스텀 헤더 사용	X-B3-TraceId와 traceparent 혼재	Bridge Propagator 설정

Tip
서비스 메시(Istio, Linkerd)를 사용하면 애플리케이션 코드 수정 없이 사이드카 프록시가 자동으로 traceparent 헤더를 전파합니다. 다만 애플리케이션 내부의 상세 Span(DB 쿼리, 비즈니스 로직)은 여전히 SDK로 계측해야 합니다.

6. OpenTelemetry Collector

Collector는 OpenTelemetry의 핵심 구성 요소입니다. 애플리케이션에서 생성한 텔레메트리 데이터를 수신하고, 가공하고, 원하는 백엔드로 내보내는 중간 에이전트 역할을 합니다.

왜 Collector를 사용하는가

SDK에서 직접 백엔드로 보내지 않고 Collector를 중간에 두는 이유:

이점	설명
백엔드 변경 시 코드 수정 불필요	Collector 설정만 바꾸면 됨
중앙 집중 처리	샘플링, 필터링, 메타데이터 추가를 한 곳에서 관리
버퍼링/재시도	백엔드 장애 시 데이터 유실 방지
다중 백엔드 전송	하나의 데이터를 여러 백엔드로 동시에 전송 가능
리소스 절약	배치 처리로 네트워크 호출 횟수 감소

Collector 파이프라인 구조

Collector는 세 가지 핵심 컴포넌트로 구성됩니다:

Receiver: 데이터를 수신하는 입구

Receiver	프로토콜	용도
otlp	gRPC, HTTP	OTel SDK에서 보내는 데이터 수신 (기본)
jaeger	Thrift, gRPC	기존 Jaeger 에이전트에서 전환 시
prometheus	Scrape	Prometheus 메트릭 수집
filelog	파일 읽기	로그 파일 수집

Processor: 데이터를 가공하는 중간 처리

Processor	역할
batch	데이터를 묶어서 일괄 전송 (네트워크 효율화)
filter	조건에 맞지 않는 데이터 제거 (헬스체크 등)
tail_sampling	조건부 수집 (에러 100%, 정상 10%)
attributes	속성 추가/수정/삭제 (환경 정보, 팀 태그 등)
resource	리소스 정보 추가 (service.name, k8s.namespace 등)
memory_limiter	메모리 사용량 제한 (OOM 방지)

Exporter: 데이터를 내보내는 출구

Exporter	대상
otlp	OTLP 호환 백엔드 (Tempo, SigNoz, Datadog 등)
prometheus	Prometheus Remote Write
jaeger	Jaeger 백엔드
loki	Grafana Loki
debug	콘솔 출력 (디버깅용)

설정 예시

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    send_batch_size: 1024
    timeout: 5s
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
  filter:
    traces:
      span:
        - 'attributes["http.route"] == "/health"'
  tail_sampling:
    decision_wait: 10s
    policies:
      - name: errors
        type: status_code
        status_code: {status_codes: [ERROR]}
      - name: slow-traces
        type: latency
        latency: {threshold_ms: 3000}
      - name: default
        type: probabilistic
        probabilistic: {sampling_percentage: 10}

exporters:
  otlp/tempo:
    endpoint: tempo:4317
    tls:
      insecure: true
  prometheus:
    endpoint: 0.0.0.0:8889

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, filter, tail_sampling, batch]
      exporters: [otlp/tempo]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [prometheus]

이 설정의 의미:

OTLP gRPC(4317)와 HTTP(4318)로 데이터 수신
헬스체크 요청(/health)은 필터링으로 제거
에러와 3초 이상 지연 Trace는 100% 수집, 나머지는 10% 샘플링
Traces는 Grafana Tempo로, Metrics는 Prometheus로 전송

7. 배포 패턴

배포 패턴: Agent + Gateway

Collector를 어떻게 배포하느냐에 따라 운영 복잡도와 확장성이 달라집니다.

Agent 패턴

각 노드(또는 Pod)에 Collector를 배치하는 방식입니다. Kubernetes에서는 DaemonSet으로 배포합니다.

# DaemonSet으로 Agent 배포
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: otel-agent
spec:
  selector:
    matchLabels:
      app: otel-agent
  template:
    spec:
      containers:
        - name: otel-collector
          image: otel/opentelemetry-collector-contrib:0.115.0
          ports:
            - containerPort: 4317  # OTLP gRPC
            - containerPort: 4318  # OTLP HTTP

장점:

로컬 네트워크로 데이터 전송 (지연 낮음)
노드별 리소스 메타데이터 자동 수집 가능

단점:

노드 수에 비례하여 Collector 인스턴스 증가
Tail-based Sampling 불가 (전체 Trace를 한 Agent가 볼 수 없음)

Gateway 패턴

중앙에 Collector 클러스터를 배치하고, 모든 서비스가 이곳으로 데이터를 전송합니다.

장점:

Tail-based Sampling 가능 (전체 Trace를 모아서 판단)
중앙 집중 관리 (설정 변경을 한 곳에서)
다중 백엔드 라우팅

단점:

단일 장애점(SPOF) 위험 → 고가용성 구성 필요
네트워크 홉 추가

Agent + Gateway 조합 (권장)

실무에서는 두 패턴을 조합합니다:

Agent (DaemonSet): 각 노드에서 데이터 수집, 기본 배치 처리 후 Gateway로 전송
Gateway (Deployment): 중앙에서 Tail-based Sampling, 메타데이터 보강, 다중 백엔드 라우팅

이 조합이 권장되는 이유:

Agent가 로컬에서 빠르게 수집하여 애플리케이션 성능에 미치는 영향을 최소화
Gateway에서 전체 Trace를 모아 지능적인 샘플링 결정
Gateway를 수평 확장하여 트래픽 증가에 대응

8. 실무 적용 시나리오: Kubernetes에서 OTel 도입

스타트업의 Kubernetes 환경(EKS)에서 5개 마이크로서비스를 운영한다고 가정합니다. 현재 로그만 CloudWatch로 수집하고 있고, 서비스 간 지연 문제가 자주 발생합니다.

단계별 도입 전략

1단계 — Auto-instrumentation으로 시작 (코드 수정 최소)

Java/Python/Node.js 서비스라면 OTel Auto-instrumentation Agent를 사용하여 코드 수정 없이 기본 Span을 생성할 수 있습니다.

# Kubernetes에서 Java 서비스에 Auto-instrumentation 적용
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
spec:
  template:
    metadata:
      annotations:
        instrumentation.opentelemetry.io/inject-java: "true"
    spec:
      containers:
        - name: order-service
          image: order-service:v1.2
          env:
            - name: OTEL_SERVICE_NAME
              value: "order-service"
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "http://otel-agent:4317"

이것만으로 HTTP 요청/응답, DB 쿼리, gRPC 호출에 대한 Span이 자동 생성됩니다.

2단계 — 핵심 비즈니스 로직에 Manual Span 추가

Auto-instrumentation은 프레임워크 수준의 Span만 생성합니다. "결제 검증 → 포인트 차감 → PG 호출"처럼 비즈니스 로직 내부를 추적하려면 수동으로 Span을 추가합니다.

# Python 예시: 결제 처리 내부 추적
from opentelemetry import trace

tracer = trace.get_tracer("payment-service")

def process_payment(order_id, amount):
    with tracer.start_as_current_span("validate_payment") as span:
        span.set_attribute("order.id", order_id)
        span.set_attribute("payment.amount", amount)
        validate_card()

    with tracer.start_as_current_span("call_pg_api") as span:
        span.set_attribute("pg.provider", "nice-pay")
        result = call_external_pg(amount)
        span.set_attribute("pg.response_code", result.code)
        return result

3단계 — 샘플링과 비용 최적화

트래픽이 많아지면 모든 Trace를 수집하는 것은 비용적으로 비현실적입니다. Gateway에서 Tail-based Sampling을 적용합니다:

에러가 발생한 Trace: 100% 수집
3초 이상 지연된 Trace: 100% 수집
정상 Trace: 10% 샘플링

4단계 — 대시보드와 알림 연동

수집된 Trace 데이터를 기반으로:

Grafana에서 서비스 의존성 맵 시각화
p99 응답시간 알림 설정
에러율 급증 시 관련 Trace로 바로 점프

9. Semantic Conventions: 표준화된 속성 이름

OpenTelemetry는 Span 속성(Attributes)의 이름을 표준화하여 서로 다른 언어, 서로 다른 팀이 만든 서비스의 데이터를 일관되게 분석할 수 있도록 합니다. 이를 Semantic Conventions라고 합니다.

주요 Semantic Conventions

HTTP 관련:

속성	설명	예시
http.request.method	HTTP 메서드	GET, POST
url.full	전체 URL	https://api.example.com/orders
http.response.status_code	응답 코드	200, 500
server.address	서버 호스트	api.example.com

데이터베이스 관련:

속성	설명	예시
db.system	DB 종류	postgresql, mysql, redis
db.operation.name	작업 유형	SELECT, INSERT
db.collection.name	테이블/컬렉션	orders, users

Kubernetes 관련:

속성	설명	예시
k8s.namespace.name	네임스페이스	production
k8s.pod.name	Pod 이름	order-service-7b4d5c-xkf2
k8s.deployment.name	Deployment 이름	order-service
k8s.node.name	노드 이름	ip-10-0-1-42

Semantic Conventions를 따르면 서로 다른 서비스에서 온 데이터를 db.system = "postgresql"로 일관되게 필터링할 수 있습니다. 팀마다 database_type, db_kind, dbSystem 등 제각각 이름을 붙이면 분석이 어렵습니다.

10. OTLP: OpenTelemetry Protocol

OTLP(OpenTelemetry Protocol)는 텔레메트리 데이터를 전송하는 표준 프로토콜입니다. SDK → Collector, Collector → Backend 간 통신에 사용됩니다.

OTLP vs 다른 프로토콜

프로토콜	데이터 유형	특징
OTLP gRPC	Traces, Metrics, Logs	바이너리 인코딩, 양방향 스트리밍, 성능 최적
OTLP HTTP	Traces, Metrics, Logs	HTTP/1.1 호환, 프록시 통과 용이
Jaeger Thrift	Traces만	레거시, 점차 OTLP로 전환
Zipkin JSON	Traces만	레거시, 경량
Prometheus Remote Write	Metrics만	Prometheus 생태계 호환

OTLP의 장점:

Traces, Metrics, Logs를 하나의 프로토콜로 통합
Protobuf 기반 바이너리 인코딩으로 네트워크 효율성 높음
gRPC 사용 시 양방향 스트리밍과 헤더 압축 지원

Tip
새로 구성하는 환경이라면 OTLP gRPC를 기본으로 사용합니다. 로드밸런서나 프록시가 gRPC를 지원하지 않는 환경에서만 OTLP HTTP를 선택합니다. Jaeger, Zipkin 형식은 기존 시스템과의 호환이 필요한 경우에만 사용합니다.

11. 보안 고려사항

Security Note
Trace 데이터에는 요청 URL, 쿼리 파라미터, 헤더 값이 포함될 수 있습니다. 민감 정보가 Span 속성에 기록되지 않도록 설계 단계에서 정책을 수립해야 합니다.

민감 정보 노출 위험

위험	예시	대응
URL에 토큰 포함	`/api/users?token=abc123`이 url.full 속성에 기록됨	URL 파라미터 마스킹 또는 경로만 기록
요청 헤더에 인증 정보	Authorization 헤더가 Span 속성에 기록됨	민감 헤더 수집 제외 설정
DB 쿼리에 사용자 데이터	`SELECT * FROM users WHERE email='user@email.com'`이 db.statement에 기록됨	쿼리 난독화(Obfuscation) 적용
Span 속성에 PII 포함	user.email, user.phone을 커스텀 속성으로 기록	PII 속성 사용 금지 정책

Collector에서의 보안 처리

processors:
  attributes:
    actions:
      # 민감 속성 삭제
      - key: http.request.header.authorization
        action: delete
      - key: user.email
        action: delete
      # URL 쿼리 파라미터 제거
      - key: url.full
        action: hash  # 해시 처리

통신 보안

SDK → Collector: 클러스터 내부 통신이면 mTLS 또는 서비스 메시로 암호화
Collector → Backend: TLS 필수 (외부 SaaS 백엔드로 전송 시)
Collector 엔드포인트 접근 제어: NetworkPolicy로 허용된 Pod만 접근 가능하도록 제한

12. 비용/운영 고려사항

주의
분산 트레이싱의 데이터 볼륨은 트래픽에 비례하여 급증합니다. 초당 10,000 요청 × 5 서비스 × 평균 3개 Span = 초당 150,000 Span입니다. 샘플링 없이 100% 수집하면 저장 비용이 빠르게 증가합니다.

비용 구조

항목	비용 발생 요인	최적화 방향
Collector 리소스	CPU/메모리 사용량	배치 크기 조정, 불필요 데이터 필터링
네트워크 전송	Span 수 × Span 크기	샘플링, 속성 수 제한
백엔드 저장	수집된 Span 총량 × 보존 기간	샘플링 비율 조정, 보존 정책
쿼리 비용	조회 빈도와 쿼리 복잡도	인덱싱 최적화

샘플링 전략 비교

전략	장점	단점	적합 환경
Head-based (10%)	구현 간단, 예측 가능한 비용	에러 Trace를 놓칠 수 있음	트래픽이 많고 비용 민감
Tail-based (조건부)	중요한 Trace를 놓치지 않음	메모리 사용량 높음, Gateway 필요	에러/지연 분석이 중요
Head + Tail 조합	균형 잡힌 수집	구성 복잡도 증가	대부분의 운영 환경

운영 체크리스트

[ ] Collector에 memory_limiter 설정 (OOM 방지)
[ ] 백엔드 장애 시 Collector의 재시도 정책 확인
[ ] 샘플링 비율을 트래픽 변화에 맞게 조정
[ ] Span 속성 수와 크기 제한 (불필요하게 큰 데이터 방지)
[ ] Collector 자체의 모니터링 (자신의 메트릭을 Prometheus로 노출)
[ ] 보존 기간 정의: Trace 7~14일, 중요 Trace 30일

13. 기존 도구와의 관계

OpenTelemetry와 Jaeger/Zipkin

Jaeger와 Zipkin은 트레이싱 백엔드(저장/시각화)입니다. OpenTelemetry는 데이터 생성/수집 표준입니다. 경쟁이 아니라 보완 관계입니다.

[AS-IS] 서비스 → Jaeger SDK → Jaeger Backend
[TO-BE] 서비스 → OTel SDK → OTel Collector → Jaeger Backend (또는 Tempo, Datadog)

전환 시 장점:

Jaeger SDK를 OTel SDK로 교체하면 나중에 Tempo나 Datadog으로 백엔드를 바꿀 수 있음
Jaeger 자체도 OTLP 수신을 지원하므로 호환됨

OpenTelemetry와 Prometheus

Prometheus는 메트릭 수집/저장 도구입니다. OpenTelemetry는 Prometheus 형식의 메트릭도 수집할 수 있고(prometheus receiver), Prometheus로 내보낼 수도 있습니다(prometheus exporter).

기존 Prometheus 환경에 트레이싱을 추가하고 싶다면: OTel SDK + Collector로 Trace를 수집하고, 메트릭은 기존 Prometheus 유지
새 환경을 구축한다면: OTel SDK로 Metrics와 Traces를 모두 수집 → Collector에서 각각 Prometheus와 Tempo로 라우팅

OpenTelemetry와 Datadog/New Relic

상용 APM 도구들은 이미 OTLP 수신을 지원합니다. OTel SDK로 계측하고 Collector에서 Datadog Exporter로 전송하면 됩니다.

장점:

나중에 비용 문제로 오픈소스 백엔드로 전환할 때 코드 수정 없음
멀티 벤더 전략 가능 (Traces는 Datadog, Metrics는 Prometheus)

14. 자주 하는 실수

1. Collector 없이 SDK에서 직접 백엔드로 전송

초기에는 간단해 보이지만, 백엔드 변경 시 모든 서비스의 환경 변수를 수정해야 합니다. Collector를 중간에 두면 설정 한 곳만 바꾸면 됩니다.

2. 모든 속성을 무분별하게 추가

Span에 속성을 많이 추가할수록 데이터 크기가 커집니다. 분석에 실제로 필요한 속성만 추가하고, Semantic Conventions를 따릅니다.

3. 샘플링을 고려하지 않고 시작

개발 환경에서 100% 수집으로 시작했다가 프로덕션에서 트래픽이 늘어나면 비용이 폭발합니다. 처음부터 샘플링 정책을 설계합니다.

4. traceparent 전파를 확인하지 않음

SDK를 설치했지만 서비스 간 Trace가 연결되지 않는 경우가 많습니다. 프록시나 메시지 큐에서 traceparent 헤더가 전달되는지 확인해야 합니다.

5. Collector의 리소스 제한을 설정하지 않음

Collector에 memory_limiter를 설정하지 않으면, 백엔드 장애 시 데이터가 Collector에 쌓여 OOM이 발생합니다. 반드시 리소스 제한을 설정합니다.

6. Auto-instrumentation만으로 충분하다고 생각

Auto-instrumentation은 HTTP, DB, gRPC 같은 프레임워크 수준의 Span만 생성합니다. "결제 검증에 3초 걸렸다"를 확인하려면 비즈니스 로직에 Manual Span을 추가해야 합니다.

15. 정리

OpenTelemetry는 Observability 데이터를 벤더 중립적으로 수집하는 CNCF Graduated 표준입니다. 계측(SDK)과 백엔드(Storage)를 분리하여 도구 교체를 자유롭게 합니다.
분산 트레이싱의 핵심은 Trace ID를 서비스 간 전파하여 하나의 요청 경로를 재구성하는 것입니다. W3C Trace Context(traceparent 헤더)가 표준 전파 형식입니다.
Collector는 Receiver → Processor → Exporter 파이프라인으로 구성됩니다. 샘플링, 필터링, 메타데이터 보강을 중앙에서 관리합니다.
배포 패턴은 Agent(DaemonSet) + Gateway(Deployment) 조합이 운영 환경에서 적합합니다.
비용 관리가 중요합니다. Tail-based Sampling(에러/지연 100% + 정상 10%)으로 중요한 데이터를 놓치지 않으면서 비용을 제어합니다.
신규 서비스는 처음부터 OTel SDK로 계측하는 것이 유리합니다. 기존 서비스는 Auto-instrumentation으로 시작하고 점진적으로 Manual Span을 추가합니다.

참고 문서

EKS vs AKS vs GKE: 매니지드 Kubernetes 비교

wero90 — Mon, 8 Jun 2026 11:03:42 +0900

"Kubernetes로 컨테이너를 운영하기로 했습니다. AWS, Azure, GCP 모두 매니지드 Kubernetes를 제공하는데, 어떤 걸 써야 하죠?" 팀에서 이미 주로 사용하는 클라우드가 있다면 해당 벤더의 매니지드 서비스를 선택하는 것이 자연스럽습니다. 다만 각 서비스의 Control Plane 관리 방식, 비용 구조, 네트워킹 모델, 운영 편의성에는 분명한 차이가 있습니다. 이 차이를 이해해야 클러스터 설계 단계에서 운영 비용과 복잡도를 예측할 수 있습니다.

Kubernetes Comparison Level 2 20분

요약

기준	EKS (AWS)	AKS (Azure)	GKE (GCP)
Control Plane 비용	$0.10/시간 (~$73/월)	무료 (Standard), $0.10/시간 (Uptime SLA 옵션)	무료 (1 클러스터), $0.10/시간 (Standard)
기본 K8s 버전 관리	수동 업그레이드 (13개월 지원)	수동 또는 자동 업그레이드 선택	자동 업그레이드 (Release Channel)
서버리스 노드 옵션	Fargate Profile	Virtual Nodes (ACI 기반)	Autopilot 모드
네트워킹 모델	VPC CNI (Pod에 VPC IP 할당)	Azure CNI 또는 kubenet	VPC-native (Alias IP)
IAM 통합	IRSA / Pod Identity	Workload Identity (Managed Identity)	Workload Identity (GCP SA 바인딩)
노드 자동 스케일링	Karpenter 또는 Cluster Autoscaler	Cluster Autoscaler (AKS 내장)	Node Auto-provisioning 또는 Autopilot
운영 복잡도	높음 (Add-on 수동 관리 많음)	중간 (Azure Portal 통합)	낮음 (Autopilot 시 대부분 자동)
멀티 클러스터 관리	별도 구성 필요	Azure Arc / Fleet Manager	GKE Fleet

1. 아키텍처 비교: Control Plane 관리 방식

세 서비스 모두 Control Plane(API Server, etcd, Controller Manager, Scheduler)을 벤더가 관리합니다. 사용자는 Worker Node만 관리하면 됩니다. 다만 관리의 깊이와 자동화 수준이 다릅니다.

EKS vs AKS vs GKE 아키텍처 비교

EKS — Control Plane을 사용자 VPC에 연결

EKS는 Control Plane을 AWS 관리 계정에서 실행하고, 사용자 VPC에 ENI(Elastic Network Interface)를 생성하여 연결합니다.

API Server Endpoint: Public, Private, 또는 Public+Private 선택 가능
etcd: AWS가 관리하는 별도 계정에서 실행, 암호화 적용
Worker Node와 Control Plane 통신: 사용자 VPC 내 ENI를 통해 프라이빗 통신 가능

특징적인 점: EKS는 Control Plane의 네트워크 노출 범위를 사용자가 직접 제어할 수 있습니다. Private Endpoint만 활성화하면 VPC 외부에서 API Server에 접근할 수 없어, 보안 요구사항이 높은 환경에서 유리합니다.

AKS — 관리형 리소스 그룹 분리

AKS는 클러스터 생성 시 두 개의 리소스 그룹을 사용합니다.

사용자 리소스 그룹: 사용자가 직접 관리하는 AKS 리소스
노드 리소스 그룹 (MC_*): AKS가 자동 생성하는 인프라 리소스 (VM, Disk, NIC, NSG)

Control Plane은 Azure가 완전히 관리하며 사용자에게 노출되지 않습니다. API Server는 기본적으로 Public Endpoint이며, Private Cluster 옵션으로 Private Endpoint를 활성화할 수 있습니다.

특징적인 점: AKS는 무료 티어에서도 Control Plane SLA 없이 운영이 가능합니다. 프로덕션 환경에서 99.95% SLA가 필요하면 Standard 또는 Premium 티어를 선택해야 합니다.

GKE — 가장 성숙한 자동화

GKE는 Google이 Kubernetes를 직접 개발한 만큼, 가장 긴밀하게 통합된 관리 환경을 제공합니다.

Standard 모드: 사용자가 Node Pool을 관리 (EKS, AKS와 유사)
Autopilot 모드: Node 관리까지 GKE가 자동 처리 (Pod 수준에서만 관리)

Autopilot은 노드 프로비저닝, OS 패치, 보안 설정을 모두 GKE가 처리합니다. 사용자는 Pod manifest만 배포하면 됩니다. 다만 Autopilot에서는 특권 컨테이너가 기본적으로 차단되며, DaemonSet도 allowlist를 통해 선택적으로만 허용됩니다. 보안 강화를 위해 privileged: true나 NET_RAW, SYS_ADMIN 같은 Linux capability가 제한됩니다.

특징적인 점: GKE는 Release Channel(Rapid, Regular, Stable)을 통해 Kubernetes 버전 자동 업그레이드를 기본으로 제공합니다. 버전 관리에 대한 운영 부담이 세 서비스 중 가장 적습니다.

2. 비용 구조 비교

매니지드 Kubernetes의 비용은 크게 Control Plane 비용과 Worker Node(컴퓨팅) 비용으로 나뉩니다. 동일한 워크로드를 운영해도 비용 구조의 차이로 인해 총 비용이 달라질 수 있습니다.

EKS vs AKS vs GKE 비용 구조 비교

Control Plane 비용

서비스	무료 티어	유료 티어
EKS	없음	$0.10/시간 (~$73/월) 고정
AKS	Free 티어 (SLA 없음)	Standard $0.10/시간, Premium $0.10/시간 + 추가 기능
GKE	Autopilot/Standard 1개 클러스터 존별 무료	Standard: $0.10/시간 (~$73/월)

실무 시나리오: 개발/테스트용 클러스터 3개 + 프로덕션 클러스터 2개를 운영한다면?

EKS: 5 × $73 = $365/월 (Control Plane만)
AKS: Free 티어 3개(dev) + Standard 2개(prod) = 2 × $73 = $146/월
GKE: 무료 1개 + 4 × $73 = $292/월

AKS의 Free 티어는 SLA를 제공하지 않으므로 프로덕션에는 부적합하지만, 개발/테스트 클러스터에 활용하면 비용을 절감할 수 있습니다.

Worker Node 비용

Worker Node 비용은 클라우드별 VM 가격에 따르며, 이것이 전체 Kubernetes 비용의 대부분(80~90%)을 차지합니다. 동일 스펙 VM의 가격은 리전과 프로모션에 따라 달라지므로 단순 비교가 어렵지만, 할인 프로그램에 차이가 있습니다.

서비스	Spot/Preemptible	예약 할인	자동 할인
EKS	Spot Instance (최대 ~90% 할인)	Reserved Instance, Savings Plan	없음
AKS	Spot VM (최대 ~90% 할인)	Reserved VM Instance	없음
GKE	Spot VM (최대 ~91% 할인)	Committed Use Discount (1년/3년)	Sustained Use Discount (자동 적용)

GKE의 Sustained Use Discount는 월 사용량에 따라 자동으로 할인이 적용됩니다. 별도 약정 없이도 장기 실행 워크로드의 비용이 줄어드는 점이 차별화됩니다.

서버리스 노드 옵션 비용

노드 관리 없이 Pod 단위로 비용을 지불하는 옵션도 비교해야 합니다.

서비스	옵션	과금 방식	적합한 상황
EKS	Fargate	vCPU/메모리 × 초 단위	배치 작업, 간헐적 워크로드
AKS	Virtual Nodes (ACI)	vCPU/메모리 × 초 단위	버스트 트래픽 처리
GKE	Autopilot	Pod 요청 리소스 × 초 단위	노드 관리 부담을 완전히 제거하고 싶은 팀

비용 최적화 관점
Control Plane 비용보다 Worker Node 비용이 훨씬 큽니다. 서비스 선택 시 Control Plane 비용 차이($73/월)보다 해당 클라우드의 VM 가격, 할인 프로그램, 팀의 기존 예약 계약을 더 중요하게 고려해야 합니다.

3. 네트워킹 모델 비교

Kubernetes 네트워킹은 "모든 Pod가 다른 모든 Pod와 NAT 없이 통신할 수 있어야 한다"는 요구사항을 충족해야 합니다. 세 서비스는 이를 구현하는 방식이 다르며, 이 차이가 IP 주소 관리, 네트워크 정책, VPC 통합에 영향을 미칩니다.

EKS vs AKS vs GKE 네트워킹 모델 비교

EKS — VPC CNI

EKS의 기본 CNI(Container Network Interface)인 VPC CNI는 각 Pod에 VPC 서브넷의 실제 IP를 할당합니다.

Pod IP = VPC 내 실제 ENI의 Secondary IP
VPC 내 다른 리소스(EC2, RDS, Lambda)와 직접 통신 가능 (별도 라우팅 불필요)
Security Group을 Pod 단위로 적용 가능 (Security Group for Pods)

trade-off:

장점: Pod가 VPC 네이티브 IP를 사용하므로, VPC Flow Logs, Security Group, Route Table 등 기존 AWS 네트워크 도구를 그대로 활용할 수 있습니다.
단점: 서브넷의 IP 주소를 Pod가 소비합니다. Pod 수가 많으면 IP 고갈 문제가 발생할 수 있습니다. 대규모 클러스터에서는 서브넷 CIDR 설계가 중요합니다.

# IP 고갈 방지: 별도 CIDR을 Pod 전용으로 할당
aws ec2 associate-vpc-cidr-block --vpc-id vpc-xxx --cidr-block 100.64.0.0/16

AKS — Azure CNI vs kubenet

AKS는 두 가지 네트워킹 모델을 제공합니다.

Azure CNI (기본 권장):

Pod에 VNet 서브넷의 실제 IP를 할당 (EKS VPC CNI와 유사)
Azure 네트워크 도구(NSG, UDR, Private Endpoint)와 직접 통합
IP 소비량이 크므로 서브넷 CIDR 계획이 필수

kubenet:

Node에만 VNet IP를 할당하고, Pod는 Node 내부의 Overlay 네트워크 IP를 사용
UDR(User Defined Route)로 노드 간 통신을 라우팅
IP 소비가 적지만, Azure 네트워크 기능과의 통합이 제한적

Azure CNI Overlay (GA, 현재 AKS 기본 IPAM 모드):

Pod에 Overlay 네트워크 IP를 사용하되, Azure CNI의 네트워크 기능은 유지
VNet IP 소비 없이 대규모 클러스터 운영 가능
기본 Pod CIDR: 10.244.0.0/16 (65,536 IP), 노드당 /24 할당으로 최대 256개 노드 스케일링
기존 kubenet 클러스터에서 Azure CNI Overlay로의 마이그레이션 경로 지원

GKE — VPC-native (Alias IP)

GKE의 VPC-native 모드는 각 Node에 Secondary IP Range(Alias IP)를 할당하고, 해당 범위에서 Pod IP를 배분합니다.

Pod IP는 VPC의 Secondary Range에서 할당
GCP의 네트워크 도구(Firewall Rule, Cloud NAT, VPC Flow Logs)와 통합
IP 범위를 Node Pool별로 분리할 수 있어 관리가 용이

trade-off:

장점: Pod CIDR을 VPC와 분리하여 설계할 수 있어, IP 고갈 문제가 EKS보다 적습니다.
단점: Alias IP의 최대 Pod 수 제한 (노드당 기본 110개)이 있습니다.

네트워킹 모델 비교 요약

항목	EKS (VPC CNI)	AKS (Azure CNI)	GKE (VPC-native)
Pod IP 유형	VPC 실제 IP	VNet 실제 IP	VPC Secondary Range IP
IP 소비	높음 (Pod당 VPC IP 1개)	높음 (CNI) / 낮음 (kubenet, CNI Overlay)	중간 (Secondary Range 분리)
VPC/VNet 통합	높음	높음 (CNI) / 제한적 (kubenet)	높음
Network Policy 엔진	Calico (Add-on)	Calico 또는 Azure NPM	Calico 또는 Dataplane V2 (Cilium 기반)
노드당 최대 Pod 수	인스턴스 타입에 따라 다름 (ENI × IP 수)	250개 (CNI) / 110개 (kubenet)	110개 (기본)

4. IAM 통합과 보안

Kubernetes 워크로드에서 클라우드 리소스(S3, Blob Storage, GCS 등)에 접근해야 할 때, 각 서비스의 IAM 통합 방식이 달라집니다.

EKS — IRSA와 Pod Identity

EKS는 Kubernetes ServiceAccount에 IAM Role을 연결하는 두 가지 방식을 제공합니다.

IRSA (IAM Roles for Service Accounts):

OIDC Provider를 설정하여 K8s ServiceAccount와 IAM Role을 연결
Pod가 AWS STS를 통해 임시 자격 증명을 획득
설정이 다소 복잡하지만 세밀한 권한 제어 가능

EKS Pod Identity (GA, 신규 클러스터 권장):

IRSA보다 설정이 간단한 방식으로, 2023년 말 출시 후 GA 상태
EKS Add-on으로 설치하고 Association을 생성하면 완료 (OIDC Provider 설정 불필요)
Trust Policy가 범용적이어 계정/클러스터마다 재작성할 필요 없음
세션 태그가 자동 부여되어 ABAC(Attribute-Based Access Control) 활용 가능
IRSA도 계속 지원되지만, 신규 설정에는 Pod Identity가 권장됨

AKS — Workload Identity

AKS는 Azure AD(Entra ID)의 Workload Identity를 사용합니다.

Kubernetes ServiceAccount에 Azure Managed Identity를 연결
Federated Credential을 통해 토큰 교환
Azure 리소스(Key Vault, Storage, Cosmos DB 등)에 비밀번호 없이 접근 가능

설정이 비교적 직관적이며, Azure Portal에서 시각적으로 관리할 수 있습니다.

GKE — Workload Identity Federation

GKE의 Workload Identity는 Kubernetes ServiceAccount를 GCP IAM Service Account에 매핑합니다.

Node의 기본 Service Account 대신 Pod별 권한 분리 가능
iam.gke.io/gcp-service-account annotation으로 매핑
GCP 리소스에 최소 권한으로 접근

GKE는 Workload Identity가 가장 일찍 도입되어 성숙도가 높고, 설정 과정이 비교적 단순합니다.

보안 기능 비교

기능	EKS	AKS	GKE
Pod 수준 IAM	IRSA / Pod Identity	Workload Identity	Workload Identity
Node 격리	Managed Node Group + Launch Template	Node Pool + VMSS	Node Pool + Shielded GKE Nodes
이미지 검증	ECR 스캔 + 서명 (별도 구성)	ACR + Defender for Containers	Binary Authorization (네이티브)
네트워크 정책	Calico (Add-on 설치 필요)	Calico 또는 Azure NPM (생성 시 활성화)	Dataplane V2 (기본 활성화 가능)
Secret 암호화	KMS envelope encryption (수동 설정)	Azure Key Vault 통합	Cloud KMS 통합 + Application-layer encryption

보안 관점
세 서비스 모두 Pod 수준의 IAM 분리를 지원합니다. 다만 Node의 기본 Service Account/Instance Profile에 과도한 권한이 있으면, Pod가 metadata endpoint를 통해 Node 권한을 획득할 수 있습니다. Workload Identity를 활성화하고, Node의 기본 권한은 최소화해야 합니다.

5. 운영 편의성과 업그레이드

Kubernetes 버전 관리

항목	EKS	AKS	GKE
지원 버전 수	4개 (일반적으로 최근 4개 minor 버전)	3~4개	3개 (Release Channel 기준)
자동 업그레이드	없음 (수동)	선택 가능 (Planned Maintenance)	기본 활성화 (Release Channel)
지원 종료 후	Extended Support ($0.60/시간 추가)	자동 업그레이드 강제	Release Channel에서 자동 진행
업그레이드 방식	In-place (Control Plane → Node Group 순차)	In-place (Surge 업그레이드)	In-place (Surge 또는 Blue-Green)

실무 시나리오: Kubernetes 1.28에서 1.29로 업그레이드해야 합니다.

EKS: Control Plane 업그레이드(CLI/콘솔, ~20분) → 각 Node Group을 순차적으로 업그레이드. Add-on(CoreDNS, kube-proxy, VPC CNI)도 별도로 업데이트해야 합니다. 가장 수동 작업이 많습니다.
AKS: 클러스터 업그레이드 명령 한 번으로 Control Plane + Node Pool 순차 업그레이드 가능. az aks upgrade 또는 자동 업그레이드 정책으로 처리합니다.
GKE: Release Channel에 따라 자동으로 진행됩니다. Maintenance Window 내에서 Control Plane → Node Pool 순서로 업그레이드됩니다. 사용자가 개입할 일이 가장 적습니다.

Add-on 관리

Add-on 유형	EKS	AKS	GKE
CNI	VPC CNI (EKS Add-on)	Azure CNI (기본 내장)	VPC-native (기본 내장)
DNS	CoreDNS (EKS Add-on)	CoreDNS (내장)	kube-dns (내장)
Ingress Controller	AWS LB Controller (별도 설치)	AGIC 또는 Nginx (Add-on)	GKE Ingress Controller (내장)
Monitoring	CloudWatch Agent (별도)	Container Insights (활성화)	Cloud Operations (기본 활성화)
Service Mesh	App Mesh 또는 Istio (별도)	Istio-based (Add-on 프리뷰)	Anthos Service Mesh (Add-on)

EKS의 운영 부담이 큰 이유: EKS는 "필요한 것을 직접 설치"하는 철학입니다. Ingress Controller, External DNS, Cert Manager, Metrics Server, CSI Driver 등을 모두 사용자가 설치하고 버전을 관리해야 합니다. 유연하지만 운영 부담이 큽니다.

GKE의 운영이 편한 이유: GKE는 대부분의 기능이 내장되어 있거나 체크박스 하나로 활성화됩니다. Kubernetes를 처음 운영하는 팀에게는 GKE의 자동화 수준이 진입 장벽을 크게 낮춥니다.

6. 노드 스케일링 전략

기본 스케일링 옵션

서비스	기본 도구	고급 옵션	서버리스
EKS	Cluster Autoscaler	Karpenter	Fargate
AKS	Cluster Autoscaler (내장)	KEDA (이벤트 기반)	Virtual Nodes (ACI)
GKE	Cluster Autoscaler (내장)	Node Auto-provisioning (NAP)	Autopilot 모드

EKS + Karpenter

Karpenter는 AWS에서 개발한 노드 스케일러로, Cluster Autoscaler보다 빠르고 유연합니다.

Pod 요구사항에 맞는 최적의 인스턴스 타입을 자동 선택
Node Group 없이 직접 EC2를 프로비저닝
30초~1분 내에 노드 추가 가능 (Cluster Autoscaler는 2~5분)
Spot Instance와의 통합이 용이

GKE Autopilot

Autopilot은 노드 관리를 완전히 제거합니다.

사용자는 Node Pool, 인스턴스 타입, OS 업데이트를 관리하지 않음
Pod의 resources.requests 기반으로 과금
보안 설정(Shielded Nodes, Workload Identity)이 기본 적용
다만 DaemonSet, 특권 컨테이너 등 일부 기능에 제약 존재

스케일링 속도 비교

시나리오	EKS (Karpenter)	AKS (CA)	GKE (NAP)
신규 노드 추가	~30초~1분	~2~5분	~1~2분
스케일 다운	빈 노드 즉시 제거	10분 대기 후 제거	빈 노드 즉시 제거
인스턴스 타입 선택	자동 (다양한 타입 혼합)	Node Pool에 고정	자동 (NAP)

7. 선택 기준: 어떤 상황에서 어떤 서비스를 고르는가

EKS vs AKS vs GKE 선택 의사결정

팀 상황별 권장

EKS를 선택하는 경우:

팀이 이미 AWS 서비스(RDS, S3, SQS 등)를 중심으로 아키텍처를 구성하고 있음
Kubernetes 운영 경험이 있고, 세밀한 커스터마이징이 필요함
Karpenter를 활용한 고급 노드 스케일링이 필요함
IAM, VPC, Security Group 등 AWS 네트워크/보안 도구와 깊은 통합이 필요함

AKS를 선택하는 경우:

팀이 Azure 환경(Active Directory, Azure DevOps, Key Vault 등)을 사용 중임
.NET 기반 워크로드가 있거나, Windows 컨테이너를 운영해야 함
Control Plane 비용을 절감하고 싶음 (Free 티어 활용)
Azure Portal에서 시각적으로 클러스터를 관리하고 싶음

GKE를 선택하는 경우:

Kubernetes 운영 경험이 적고, 관리 부담을 최소화하고 싶음
Autopilot 모드로 노드 관리를 완전히 위임하고 싶음
데이터 분석/ML 워크로드와 연계해야 함 (BigQuery, Vertex AI)
버전 업그레이드, 보안 패치를 자동으로 처리하고 싶음

멀티 클라우드 고려사항

"멀티 클라우드를 위해 Kubernetes를 선택했으니 어떤 벤더든 상관없다"는 이론과 현실은 다릅니다.

실제로는 각 서비스가 클라우드 네이티브 기능(IAM, 네트워킹, 스토리지, LB)과 깊게 결합되어 있어, 클러스터를 다른 벤더로 옮기는 것은 상당한 작업을 필요로 합니다. Kubernetes manifest(Deployment, Service 등)는 이식 가능하지만, 인프라 통합 부분(Ingress annotation, StorageClass, IAM binding)은 벤더별로 다시 작성해야 합니다.

멀티 클라우드가 실제로 필요한 경우라면, 벤더 종속 부분을 추상화하는 계층(예: Crossplane, Terraform, 표준화된 Helm chart)을 도입하는 것이 현실적인 접근입니다.

8. 실무 사용 사례

사례: 50인 규모 스타트업, MSA 15개 서비스 운영

상황:

팀: DevOps 2명, 백엔드 개발자 10명
워크로드: 웹 서비스 15개 (Python, Node.js), 일일 트래픽 변동 큼
이미 AWS를 주력으로 사용, RDS, S3, SQS 의존
Kubernetes 운영 경험: DevOps 팀 2명만 있음

선택: EKS + Karpenter

결정 요소	이유
AWS 종속	RDS, S3, SQS와의 통합이 이미 깊고, 다른 클라우드로 이전 계획 없음
Karpenter	트래픽 변동이 커서 빠른 스케일링 필요. Spot Instance 활용으로 비용 40% 절감
IRSA	서비스별 S3 버킷, SQS 큐 접근 권한을 Pod 단위로 분리

고려한 대안: GKE Autopilot도 검토했지만, AWS 서비스와의 통합 비용(VPN, 지연)이 더 컸습니다.

사례: 대기업 Azure 환경, Windows + Linux 혼합 워크로드

상황:

조직: Azure AD로 전사 인증 관리, Azure DevOps 파이프라인 사용 중
워크로드: .NET 레거시(Windows 컨테이너) + 신규 서비스(Linux)
보안: 금융 규제로 Private Cluster 필수, Key Vault 중앙 관리

선택: AKS

결정 요소	이유
Windows 노드 지원	AKS는 Windows Node Pool을 네이티브로 지원, 혼합 워크로드 운영 가능
Azure AD 통합	RBAC를 Azure AD 그룹과 연동하여 전사 인증 체계 유지
Private Cluster	Azure Private Link/Endpoint와의 네이티브 통합으로 네트워크 격리 용이
비용	Free 티어로 dev/staging 클러스터 비용 절감

사례: ML 팀, GPU 워크로드 + 최소 운영 부담

상황:

팀: ML 엔지니어 5명 (K8s 운영 경험 없음)
워크로드: 모델 학습(GPU), 추론 서비스(CPU), 데이터 전처리(BigQuery)
요구사항: K8s 운영에 시간을 쓰고 싶지 않음, 모델 개발에 집중하고 싶음

선택: GKE Autopilot

결정 요소	이유
Autopilot	노드 관리, OS 패치, 보안 설정을 GKE가 자동 처리
GPU 지원	Autopilot에서 GPU Pod 요청 시 자동으로 GPU 노드 프로비저닝
BigQuery/Vertex AI 통합	같은 GCP 내에서 데이터 파이프라인과 자연스럽게 연결
Workload Identity	GCS, BigQuery 접근 시 키 파일 없이 안전하게 인증

9. 주의할 점과 일반적인 실수

1. "Kubernetes니까 어디서든 동일하게 동작한다"는 가정

Kubernetes API는 표준이지만, 아래 영역은 벤더마다 다릅니다:

Ingress Controller 동작 방식과 annotation
StorageClass와 Persistent Volume 프로비저너
IAM/RBAC 통합 방식
Load Balancer 타입과 설정
Node 스케일링 동작

2. Control Plane 비용만 보고 결정

Control Plane 비용 차이는 월 $73 수준입니다. 실제 총 비용의 80~90%는 Worker Node입니다. 비용 비교는 VM 가격, 할인 프로그램, 네트워크 전송 비용을 포함하여 전체적으로 해야 합니다.

3. 버전 업그레이드 전략 없이 클러스터 운영

EKS는 버전 지원이 종료되면 자동 업그레이드가 아닌 Extended Support(추가 비용)로 전환됩니다. 업그레이드를 미루면 비용이 증가하고, 여러 버전을 한 번에 건너뛰기 어려워집니다. 클러스터 생성 시점부터 업그레이드 주기를 계획해야 합니다.

4. 서버리스 노드 옵션의 제약을 모르고 선택

Fargate, Virtual Nodes, Autopilot 모두 일반 VM 노드 대비 제약이 있습니다:

DaemonSet 불가 또는 제한
hostNetwork/hostPort 사용 불가
특권 컨테이너 제한
GPU 지원 범위 차이
노드 레벨 커스터마이징 불가

운영하려는 워크로드가 이 제약에 영향을 받는지 사전에 확인해야 합니다.

10. 정리

선택 기준	EKS	AKS	GKE
이미 사용 중인 클라우드	AWS 중심	Azure 중심	GCP 중심
팀 K8s 경험	중~상	초~중	초~중
운영 자동화 수준	직접 구성	중간	높음 (Autopilot)
노드 스케일링	Karpenter (가장 유연)	기본 CA	NAP / Autopilot
비용 효율	Spot + Karpenter 조합	Free 티어 + Reserved VM	Sustained Use + Autopilot
Windows 컨테이너	지원 (제한적)	네이티브 지원 (강점)	지원 (제한적)
보안 자동화	수동 설정 많음	중간	높음 (Shielded Nodes 기본)

결론적으로: 대부분의 경우, 팀이 이미 사용하고 있는 클라우드의 매니지드 Kubernetes를 선택하는 것이 가장 합리적입니다. 클라우드 간 서비스 간 통합(IAM, 네트워킹, 스토리지)이 매니지드 K8s의 핵심 가치이기 때문입니다. 다만 Kubernetes 운영 경험이 없는 팀이라면 GKE Autopilot이, 세밀한 커스터마이징이 필요한 팀이라면 EKS가, Azure 생태계에 깊이 투자한 조직이라면 AKS가 각각 강점을 보입니다.

참고 문서

IAM과 RBAC 차이: AWS, Azure, GCP 기준으로 이해하기

wero90 — Mon, 8 Jun 2026 10:45:05 +0900

"개발자에게 S3 읽기 권한을 주려면 IAM으로 해야 하나요, RBAC로 해야 하나요?" — 이 질문 자체가 두 개념의 관계를 혼동하고 있다는 신호입니다. IAM은 접근 제어 시스템 전체를 가리키고, RBAC는 그 안에서 권한을 부여하는 방식 중 하나입니다.

핵심 요약

IAM(Identity and Access Management)은 "누가, 무엇에, 어떤 작업을 할 수 있는가"를 관리하는 시스템 전체를 의미합니다.
RBAC(Role-Based Access Control)는 역할(Role)을 기준으로 권한을 묶어서 부여하는 접근 제어 모델입니다.
AWS는 IAM 안에서 Policy 기반(ABAC/PBAC)과 Role 기반(RBAC)을 혼합하여 사용합니다.
Azure는 IAM 계층 안에서 RBAC를 명시적으로 분리한 구조(Azure RBAC)를 제공합니다.
GCP는 IAM 안에서 Role을 중심으로 권한을 부여하되, Predefined Role과 Custom Role로 유연성을 확보합니다.
실무에서는 "RBAC만 쓴다" 또는 "IAM만 쓴다"가 아니라, 각 클라우드의 IAM 시스템 안에서 RBAC 원칙을 어떻게 적용할지 설계하는 것이 핵심입니다.

1. IAM과 RBAC는 어떤 관계인가

1.1 시나리오: 신입 개발자 온보딩

팀에 신입 개발자가 합류했습니다. 이 개발자에게 다음 권한이 필요합니다:

개발 환경 S3 버킷 읽기/쓰기
CloudWatch 로그 조회
개발 환경 EC2 인스턴스 재시작

이 권한을 부여하는 방법은 크게 두 가지입니다:

방법 A (개별 부여): 개발자 계정에 S3, CloudWatch, EC2 권한을 각각 직접 연결합니다. 개발자가 5명이면 5번, 50명이면 50번 반복합니다.

방법 B (역할 기반): "Backend Developer"라는 역할을 만들고, 필요한 권한을 이 역할에 묶습니다. 신입 개발자에게는 역할만 부여합니다. 권한 변경이 필요하면 역할 하나만 수정합니다.

방법 B가 RBAC입니다. 그리고 IAM은 방법 A와 B 모두를 포함하는 시스템 전체를 말합니다.

IAM과 RBAC 관계 구조

1.2 개념 정리

구분	IAM	RBAC
정의	접근 제어 시스템 전체	역할 기반 권한 부여 모델
범위	인증 + 인가 + 감사	인가(Authorization) 방식 중 하나
포함 관계	RBAC를 포함하는 상위 개념	IAM 안에서 동작하는 하위 모델
대안	—	ABAC, PBAC, ACL 등

IAM은 다음 세 가지를 모두 다룹니다:

인증(Authentication): 이 사용자가 누구인가? (로그인, MFA, SSO)
인가(Authorization): 이 사용자가 무엇을 할 수 있는가? (RBAC, ABAC, Policy)
감사(Audit): 이 사용자가 무엇을 했는가? (로그, 추적)

RBAC는 이 중 인가 단계에서 "역할"이라는 중간 계층을 통해 권한을 부여하는 방식입니다.

1.3 RBAC 외의 접근 제어 모델

모델	설명	예시
RBAC	역할에 권한을 묶어 부여	"개발자 역할"에 S3 읽기 권한 포함
ABAC	속성(태그, 부서, 환경)에 따라 동적으로 권한 결정	`env=dev` 태그가 붙은 리소스만 접근 허용
PBAC	정책 문서로 세밀하게 조건 정의	JSON Policy에 조건절(Condition) 포함
ACL	리소스별로 접근 가능한 주체 목록 관리	S3 버킷 ACL, 파일시스템 ACL

실무에서는 하나만 쓰는 경우가 드뭅니다. 대부분 RBAC를 기본으로 하되, 세밀한 조건이 필요하면 ABAC이나 PBAC를 결합합니다.

2. 클라우드별 IAM과 RBAC 구현 비교

클라우드별 IAM/RBAC 구조 비교

2.1 AWS: IAM + Policy 기반 혼합 모델

AWS IAM은 RBAC라는 용어를 명시적으로 분리하지 않습니다. 대신 Policy와 Role이라는 두 축으로 접근 제어를 설계합니다.

구성 요소:

IAM User/Group: 사람 또는 사람의 집합
IAM Role: 서비스나 사용자가 임시로 맡는(assume) 자격
IAM Policy: 허용/거부할 작업을 JSON으로 정의한 규칙

AWS에서 RBAC를 구현하는 방식:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::dev-bucket",
        "arn:aws:s3:::dev-bucket/*"
      ]
    }
  ]
}

이 Policy를 "BackendDeveloper"라는 IAM Role에 연결하고, 개발자에게 이 Role을 부여하면 RBAC 패턴이 됩니다.

AWS의 특징:

RBAC와 ABAC를 동시에 지원합니다. Policy의 Condition 블록에서 태그 기반 접근 제어(ABAC)를 설정할 수 있습니다.
IAM Role은 사람뿐 아니라 EC2, Lambda 등 서비스에도 권한을 부여하는 데 사용됩니다.
권한 경계(Permission Boundary)로 Role이 가질 수 있는 권한의 상한선을 설정할 수 있습니다.

2.2 Azure: 명시적 RBAC 분리 모델

Azure는 IAM 내에서 RBAC를 별도 시스템으로 명확히 분리했습니다. "Azure RBAC"라는 이름으로 독립적인 접근 제어 계층을 제공합니다.

구성 요소:

Security Principal: 권한을 받을 주체 (User, Group, Service Principal, Managed Identity)
Role Definition: 허용할 작업의 집합 (Reader, Contributor, Owner 등)
Scope: 권한이 적용되는 범위 (Management Group → Subscription → Resource Group → Resource)
Role Assignment: Principal + Role + Scope를 연결하는 바인딩

Azure에서 RBAC를 구현하는 방식:

# 개발자 그룹에 개발 리소스 그룹의 Contributor 역할 부여
az role assignment create \
  --assignee "dev-team-group-id" \
  --role "Contributor" \
  --scope "/subscriptions/{sub-id}/resourceGroups/dev-rg"

Azure의 특징:

Scope 계층 구조가 명확합니다. 상위 Scope에서 부여한 권한이 하위로 상속됩니다.
Built-in Role이 수백 개 제공되어 대부분의 시나리오를 커버합니다.
Deny Assignment로 특정 권한을 명시적으로 차단할 수 있습니다(제한적 사용).
Entra ID(구 Azure AD)의 디렉토리 역할과 Azure RBAC는 별개 시스템입니다.

2.3 GCP: IAM + Predefined Role 모델

GCP IAM은 Role을 중심으로 권한을 부여하는 구조이며, Azure처럼 명시적으로 "RBAC"를 별도 제품으로 분리하지는 않습니다.

구성 요소:

Principal(Member): 권한을 받을 주체 (Google 계정, Service Account, Group)
Role: 권한(Permission)의 집합 (Basic, Predefined, Custom)
Resource: 권한이 적용되는 대상 (Organization → Folder → Project → Resource)
Allow Policy(IAM Binding): Principal + Role + Resource를 연결

GCP에서 RBAC를 구현하는 방식:

# 개발자 그룹에 프로젝트 수준 Storage Object Viewer 역할 부여
gcloud projects add-iam-policy-binding dev-project \
  --member="group:dev-team@company.com" \
  --role="roles/storage.objectViewer"

GCP의 특징:

Predefined Role이 서비스별로 세분화되어 있습니다 (예: roles/storage.objectViewer, roles/storage.objectAdmin).
Basic Role(Owner, Editor, Viewer)은 권한이 넓어서 운영 환경에서는 사용을 피합니다.
IAM Conditions로 시간, IP, 리소스 속성 기반 조건부 접근 제어(ABAC)를 추가할 수 있습니다.
Resource 계층 상속이 동작하며, Organization → Folder → Project 순으로 권한이 내려갑니다.

3. 클라우드별 상세 비교

클라우드별 권한 부여 흐름

3.1 핵심 비교표

비교 항목	AWS	Azure	GCP
RBAC 명시적 분리	아니오 (Policy+Role 혼합)	예 (Azure RBAC)	아니오 (IAM 내 Role 중심)
권한 정의 단위	IAM Policy (JSON)	Role Definition (Actions)	Role (Permissions 집합)
역할 연결 방식	Role에 Policy Attach	Role Assignment (Principal+Role+Scope)	IAM Binding (Member+Role+Resource)
Scope 계층	Account (Organization → OU)	Management Group → Subscription → RG → Resource	Organization → Folder → Project → Resource
서비스 자격 증명	IAM Role (AssumeRole)	Service Principal / Managed Identity	Service Account
속성 기반 제어 (ABAC)	Policy Condition + Tags	ABAC (Preview / 제한적)	IAM Conditions
기본 제공 역할 수	AWS Managed Policy ~1,000+	Built-in Role ~500+	Predefined Role ~1,000+
권한 상한 설정	Permission Boundary	상위 Scope 제한	Organization Policy
Deny 메커니즘	Explicit Deny in Policy	Deny Assignment (제한적)	IAM Deny Policy
감사	CloudTrail	Activity Log	Cloud Audit Logs

3.2 설계 철학의 차이

AWS — 유연성 우선

Policy라는 범용 도구로 RBAC, ABAC, 조건부 접근을 모두 표현합니다.
유연하지만, 그만큼 정책이 복잡해질 수 있습니다.
Role과 Policy를 조합하는 방식은 자유도가 높지만 설계 패턴이 여러 개 존재하여 팀마다 다른 방식을 쓸 수 있습니다.

Azure — 구조화 우선

RBAC를 별도 시스템으로 명확히 분리하여 "누구에게, 어떤 역할을, 어떤 범위에서"를 한 문장으로 표현합니다.
Scope 계층이 깔끔하여 권한 상속과 재활용이 직관적입니다.
다만 Custom Role을 만들려면 Actions/DataActions 목록을 직접 정의해야 합니다.

GCP — 서비스 세분화 우선

서비스별로 Predefined Role이 세밀하게 나뉘어 있어 "딱 필요한 만큼"을 부여하기 쉽습니다.
Basic Role의 유혹(Editor/Owner)이 있지만, 운영 환경에서는 Predefined 또는 Custom Role을 권장합니다.
Resource 계층이 Organization → Folder → Project로 논리적 구분이 명확합니다.

4. 실무 설계 패턴

4.1 시나리오: 멀티 클라우드 환경의 개발팀 권한 설계

5명의 백엔드 개발 팀에게 다음 권한을 부여해야 합니다:

개발 환경: 리소스 생성/수정/삭제 가능
스테이징 환경: 읽기 + 배포만 가능
프로덕션 환경: 읽기만 가능

각 클라우드에서 이 요구사항을 구현하는 패턴입니다:

AWS 구현:

IAM Group: backend-dev-team
├── Role: DevEnvFullAccess (dev 리소스 CRUD)
├── Role: StagingDeployAccess (staging 읽기 + 특정 배포 Action)
└── Role: ProdReadOnly (prod 리소스 읽기만)

각 Role에 환경별 리소스 ARN을 Condition으로 제한합니다.
또는 Tag 기반 ABAC로 env=dev 태그가 붙은 리소스에만 접근을 허용합니다.

Azure 구현:

Azure AD Group: backend-dev-team
├── Role Assignment: Contributor @ dev-rg (개발 리소스 그룹)
├── Role Assignment: Reader + Custom Deploy Role @ staging-rg
└── Role Assignment: Reader @ prod-rg

Scope를 Resource Group 단위로 분리하여 환경별 접근을 제한합니다.
Custom Role에 배포 관련 Actions만 포함시킵니다.

GCP 구현:

Google Group: backend-dev-team@company.com
├── IAM Binding: roles/editor @ dev-project
├── IAM Binding: roles/viewer + custom.deployer @ staging-project
└── IAM Binding: roles/viewer @ prod-project

Project 단위로 환경을 분리하여 권한 경계를 명확히 합니다.
Custom Role에 배포에 필요한 Permission만 포함시킵니다.

4.2 RBAC 설계 시 공통 원칙

어떤 클라우드를 사용하든 다음 원칙은 동일하게 적용됩니다:

최소 권한 원칙(Least Privilege): 필요한 권한만 부여합니다. "일단 넓게 주고 나중에 줄이자"는 운영 환경에서는 위험합니다.
그룹/역할 기반 부여: 개인에게 직접 권한을 부여하지 않습니다. 역할이나 그룹을 중간에 둡니다.
환경별 분리: 개발/스테이징/프로덕션 환경은 별도 계정, 구독, 프로젝트로 분리합니다.
정기 감사: 사용하지 않는 권한은 주기적으로 제거합니다(90일 미사용 기준).
임시 권한(JIT): 프로덕션 접근은 상시 부여보다 필요 시 임시 승격 방식을 선택합니다.

4.3 흔한 실수와 대응

실수	문제점	대응
Admin/Owner 권한 상시 부여	피해 범위가 전체로 확대됨	JIT 접근 + 별도 Break Glass 계정 운용
개인에게 직접 권한 연결	퇴사/이동 시 정리 누락	Group/Role 기반 부여 후 멤버십만 관리
환경 미분리	개발 실수가 프로덕션에 영향	Account/Subscription/Project 수준 분리
권한 감사 미실시	불필요 권한 누적 (권한 팽창)	90일 미사용 권한 자동 알림 설정
Service Account 키 직접 사용	키 유출 시 영구 접근 가능	Workload Identity/IRSA/Managed Identity 사용

5. Kubernetes RBAC와의 관계

클라우드 IAM과 Kubernetes RBAC는 별도의 인가 시스템입니다. 두 계층이 함께 동작하며, 둘 다 통과해야 실제 작업이 가능합니다.

클라우드 IAM과 Kubernetes RBAC 이중 인가 흐름

5.1 이중 인가 구조

사용자 → 클라우드 IAM 인증 → Kubernetes API Server → K8s RBAC 인가 → 리소스 접근

클라우드 IAM: 클러스터에 접근할 수 있는가? (kubectl 명령을 실행할 자격이 있는가)
Kubernetes RBAC: 클러스터 안에서 어떤 네임스페이스의 어떤 리소스에 어떤 작업을 할 수 있는가?

5.2 클라우드별 Kubernetes 인증 연동

클라우드	인증 방식	RBAC 연동
AWS EKS	IAM Role → aws-auth ConfigMap 또는 EKS Access Entry	IAM Role을 K8s Group에 매핑
Azure AKS	Entra ID 인증	Entra ID Group을 K8s RoleBinding에 연결
GCP GKE	Google Account / Service Account	IAM Role에 K8s RBAC 권한 포함 가능

5.3 실무 예시: EKS에서 개발자 권한 분리

# 1. K8s RBAC: dev 네임스페이스에서 Pod 읽기/실행만 허용
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: dev
  name: pod-reader
rules:
- apiGroups: [""]
  resources: ["pods", "pods/log"]
  verbs: ["get", "list", "watch"]
- apiGroups: [""]
  resources: ["pods/exec"]
  verbs: ["create"]
---
# 2. RoleBinding: 개발자 그룹에 연결
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  namespace: dev
  name: dev-pod-reader
subjects:
- kind: Group
  name: backend-developers
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

이 구성에서 개발자가 실제로 kubectl exec를 실행하려면:

AWS IAM Role로 EKS 클러스터에 인증되어야 하고 (클라우드 IAM)
backend-developers 그룹에 매핑되어 있어야 하며 (aws-auth 또는 Access Entry)
dev 네임스페이스의 pod-reader Role이 허용하는 범위 안에서만 동작합니다 (K8s RBAC)

6. 의사결정 가이드

6.1 언제 무엇을 선택하는가

상황	권장 접근 방식
팀 단위로 동일 권한 부여	RBAC (역할 기반)
리소스 태그/속성에 따라 동적 권한	ABAC (속성 기반)
세밀한 조건 분기 필요	Policy 기반 (PBAC)
환경별 접근 분리	계정/구독/프로젝트 분리 + RBAC
서비스 간 권한	Service Account/Role + 최소 권한
임시 접근 필요	JIT 접근 (Privileged Identity Management)

6.2 멀티 클라우드 환경에서의 고려사항

중앙 ID 제공자(IdP)를 통한 SSO 통합이 선행되어야 합니다.
각 클라우드의 RBAC 모델이 다르므로, 역할 이름은 통일하되 구현은 클라우드별로 맞춥니다.
"Contributor"(Azure)와 "Editor"(GCP), IAM Policy(AWS)의 실제 권한 범위가 다릅니다. 이름만으로 동일한 수준이라고 가정하면 안 됩니다.
Terraform 같은 IaC 도구로 멀티 클라우드 IAM을 코드화하면 일관성을 유지하기 쉬워집니다.

7. 보안과 비용 관점

7.1 보안 Trade-off

결정	보안 이점	운영 부담
세밀한 Custom Role	최소 권한 달성	역할 관리 복잡도 증가
Predefined/Managed Role 사용	관리 단순	불필요 권한 포함 가능성
JIT 접근	상시 노출 최소화	승인 프로세스 필요
Service Account 키 제거	키 유출 위험 제거	Workload Identity 설정 필요

7.2 비용 관점

IAM 자체는 AWS, Azure, GCP 모두 무료입니다 (추가 비용 없음).
다만 AWS Organizations, Azure PIM(Privileged Identity Management), GCP BeyondCorp Enterprise 등 고급 거버넌스 기능은 별도 과금이 있을 수 있습니다.
권한 관리의 비용은 금전보다 운영 인력과 시간에서 발생합니다. 복잡한 Custom Role 구조는 유지보수 부담을 높입니다.

8. 정리: 면접에서 이렇게 설명합니다

"IAM과 RBAC의 차이를 설명해주세요"라는 질문에 대한 답변 구조:

관계 설명: IAM은 접근 제어 시스템 전체이고, RBAC는 그 안에서 권한을 역할 단위로 부여하는 모델입니다.
클라우드별 차이: AWS는 Policy+Role 혼합, Azure는 RBAC를 명시적으로 분리, GCP는 Predefined Role 중심으로 구현합니다.
설계 원칙: 어떤 클라우드든 최소 권한, 그룹 기반 부여, 환경 분리, 정기 감사가 핵심입니다.
Kubernetes 연동: 클라우드 IAM과 K8s RBAC는 별도 계층이며, 둘 다 통과해야 실제 작업이 가능합니다.

OIDC 기반 인증 설계: GitHub Actions, EKS, Cloud Provider 연동

wero90 — Mon, 8 Jun 2026 10:38:40 +0900

GitHub Actions에서 AWS에 배포할 때 Access Key를 Repository Secret에 저장하고 있다면, 그 Key는 누가 마지막으로 교체했는지, 어떤 권한이 붙어 있는지 확인해볼 필요가 있습니다. 팀원이 퇴사해도 Key는 남아 있고, 유출되면 교체할 때까지 무제한으로 사용됩니다. OIDC(OpenID Connect)는 이 문제를 구조적으로 해결합니다. 장기 자격 증명을 저장하지 않고, 실행 시점에 단기 토큰을 발급받아 사용하는 방식입니다.

핵심 요약

OIDC 기반 인증은 장기 자격 증명(Access Key, Service Account Key) 자체를 제거하여 유출 위험을 구조적으로 줄입니다.
GitHub Actions, EKS Pod, GKE Pod 모두 동일한 원리로 동작합니다: 워크로드가 OIDC 토큰을 발급받고, Cloud Provider가 검증 후 임시 자격 증명을 교환합니다.
AWS는 IRSA(기존)와 Pod Identity(신규) 두 가지 방식을 제공하며, 신규 클러스터에는 Pod Identity가 권장됩니다.
Azure는 Workload Identity Federation으로 GitHub Actions와 AKS Pod 모두 동일한 패턴을 사용합니다.
GCP는 Workload Identity Federation으로 GitHub Actions를, Workload Identity for GKE로 Pod를 연결합니다.
설계 시 핵심 판단 기준: 토큰 범위 제한(audience, subject), 최소 권한 IAM Role, 멀티 계정 구조에서의 Role Chaining입니다.

1. 왜 OIDC인가: 장기 자격 증명의 구조적 문제

5명으로 구성된 DevOps 팀이 GitHub Actions로 AWS, Azure 리소스에 배포하고, EKS 클러스터에서 S3와 DynamoDB에 접근하는 상황을 생각해봅니다.

장기 자격 증명(Access Key, Client Secret) 방식으로 운영하면 시간이 지날수록 다음 문제가 누적됩니다.

교체 부담: Key를 90일마다 교체하려면 모든 워크플로우와 Kubernetes Secret을 동시에 업데이트해야 합니다. 하나라도 누락하면 배포가 실패합니다.
유출 시 피해 범위: Key가 유출되면 교체 완료까지 무제한 사용됩니다. CloudTrail 로그로 발견하더라도 이미 피해가 발생한 후입니다.
범위 제어 한계: 같은 Key를 여러 워크플로우에서 공유하면, 한 워크플로우가 침해되었을 때 다른 워크플로우의 리소스까지 영향받습니다.
감사 추적 어려움: 누가 언제 Key를 생성했고 어디에 배포했는지 추적이 어렵습니다.

OIDC는 이 문제를 "자격 증명을 저장하지 않는다"는 설계로 해결합니다.

OIDC 인증 개요

2. OIDC 동작 원리: 토큰 교환의 구조

OIDC 기반 인증의 핵심은 토큰 교환(Token Exchange) 패턴입니다. 모든 Cloud Provider에서 동일한 3단계로 동작합니다.

토큰 교환 흐름

1. 워크로드(GitHub Actions Runner, EKS Pod)가 자체 OIDC Provider로부터 JWT를 발급받음
2. JWT를 Cloud Provider의 STS(Security Token Service)에 제출
3. Cloud Provider가 JWT를 검증하고, 조건이 맞으면 임시 자격 증명(1시간)을 발급

JWT 내부 구조

GitHub Actions가 발급하는 OIDC 토큰의 주요 클레임:

{
  "iss": "https://token.actions.githubusercontent.com",
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "aud": "sts.amazonaws.com",
  "ref": "refs/heads/main",
  "repository": "my-org/my-repo",
  "repository_owner": "my-org",
  "job_workflow_ref": "my-org/my-repo/.github/workflows/deploy.yml@refs/heads/main",
  "exp": 1718000000,
  "iat": 1717999400
}

클레임	역할
`iss` (Issuer)	토큰 발급자. Cloud Provider가 이 URL에서 공개 키를 가져와 서명 검증
`sub` (Subject)	워크로드의 신원. Trust Policy에서 조건 매칭에 사용
`aud` (Audience)	토큰의 대상. 의도하지 않은 서비스에서 토큰 재사용을 방지
`exp` / `iat`	토큰 유효 기간. 일반적으로 5~15분

Cloud Provider는 iss로 공개 키를 조회하고, 서명을 검증한 뒤, sub와 aud 조건이 Trust Policy와 일치하는지 확인합니다. 모든 조건이 통과하면 임시 자격 증명을 발급합니다.

OIDC 토큰 교환 흐름

보안 설계 포인트

토큰 수명 최소화: JWT 자체는 5~15분, 발급받는 임시 자격 증명은 기본 1시간입니다. 유출되어도 피해 시간이 제한됩니다.
Subject 범위 제한: sub 클레임으로 특정 저장소, 브랜치, 환경만 허용할 수 있습니다. repo:my-org/*처럼 와일드카드를 넓게 잡으면 OIDC의 보안 이점이 줄어듭니다.
Audience 검증: aud를 명시적으로 지정해야 다른 서비스에서 토큰을 재사용하는 confused deputy 공격을 방지합니다.

3. GitHub Actions + AWS OIDC 연동

설정 구조

GitHub Actions에서 AWS 리소스에 접근하려면 3가지를 설정합니다.

AWS에 OIDC Provider 등록: GitHub의 토큰 발급 서버를 AWS가 신뢰하도록 등록
IAM Role 생성: Trust Policy로 어떤 저장소/브랜치에서 Assume 가능한지 제한
워크플로우에서 토큰 요청: permissions: id-token: write를 선언하고 Action 사용

Terraform으로 OIDC Provider + IAM Role 생성

# OIDC Provider 등록
resource "aws_iam_openid_connect_provider" "github" {
  url             = "https://token.actions.githubusercontent.com"
  client_id_list  = ["sts.amazonaws.com"]
  thumbprint_list = ["1b511abead59c6ce207077c0bf0e0043b1382612"]
}

# IAM Role - Trust Policy에서 저장소와 브랜치 제한
resource "aws_iam_role" "github_actions" {
  name = "github-actions-deploy"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          Federated = aws_iam_openid_connect_provider.github.arn
        }
        Action = "sts:AssumeRoleWithWebIdentity"
        Condition = {
          StringEquals = {
            "token.actions.githubusercontent.com:aud" = "sts.amazonaws.com"
          }
          StringLike = {
            "token.actions.githubusercontent.com:sub" = "repo:my-org/my-app:ref:refs/heads/main"
          }
        }
      }
    ]
  })
}

# 필요한 권한만 부여 (예: ECR Push + ECS Deploy)
resource "aws_iam_role_policy_attachment" "ecr_push" {
  role       = aws_iam_role.github_actions.name
  policy_arn = "arn:aws:iam::123456789012:policy/ECRPushPolicy"
}

워크플로우 설정

name: Deploy to AWS
on:
  push:
    branches: [main]

permissions:
  id-token: write   # OIDC 토큰 요청 권한
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
          aws-region: ap-northeast-2

      - run: aws sts get-caller-identity  # 임시 자격 증명 확인

aws-actions/configure-aws-credentials의 현재 최신 버전은 v6.2.0입니다. v6부터 Node 24 런타임을 사용하며, role-chaining과 custom session tag를 지원합니다.

멀티 계정 구조: Role Chaining

대부분의 운영 환경에서는 AWS 계정이 여러 개입니다. 하나의 Hub 계정에 OIDC Trust를 설정하고, 실제 워크로드 계정으로 Role Chaining하는 패턴이 일반적입니다.

steps:
  # 1단계: Hub 계정의 Role을 OIDC로 Assume
  - uses: aws-actions/configure-aws-credentials@v6
    with:
      role-to-assume: arn:aws:iam::111111111111:role/github-oidc-hub
      aws-region: ap-northeast-2

  # 2단계: Hub Role에서 워크로드 계정의 Role로 Chaining
  - uses: aws-actions/configure-aws-credentials@v6
    with:
      role-to-assume: arn:aws:iam::222222222222:role/workload-deploy
      role-chaining: true
      aws-region: ap-northeast-2

이 구조의 장점은 OIDC Provider를 1개 계정에만 등록하면 되므로 관리 포인트가 줄어든다는 점입니다. 다만 Hub Role의 Trust Policy가 과도하게 넓으면 어떤 저장소든 모든 워크로드 계정에 접근할 수 있으므로, Hub Role에서도 sub 조건을 저장소 단위로 제한해야 합니다.

4. EKS 워크로드 인증: IRSA vs Pod Identity

EKS에서 Pod가 AWS 리소스에 접근할 때도 OIDC 기반 인증을 사용합니다. 현재 두 가지 방식이 있습니다.

IRSA (IAM Roles for Service Accounts)

2019년에 출시된 방식으로, EKS 클러스터의 OIDC Provider를 IAM에 등록하고 ServiceAccount와 IAM Role을 연결합니다.

# ServiceAccount에 IAM Role ARN을 annotation으로 연결
apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-app
  namespace: production
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/my-app-role

# IAM Role Trust Policy - 특정 클러스터의 특정 ServiceAccount만 허용
resource "aws_iam_role" "my_app" {
  name = "my-app-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          Federated = "arn:aws:iam::123456789012:oidc-provider/oidc.eks.ap-northeast-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE"
        }
        Action = "sts:AssumeRoleWithWebIdentity"
        Condition = {
          StringEquals = {
            "oidc.eks.ap-northeast-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub" = "system:serviceaccount:production:my-app"
            "oidc.eks.ap-northeast-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud" = "sts.amazonaws.com"
          }
        }
      }
    ]
  })
}

Pod Identity (2023년 출시)

Pod Identity는 OIDC Provider를 직접 관리하지 않고, AWS가 제공하는 Pod Identity Agent가 노드에서 자격 증명을 중개합니다.

# Pod Identity Association 생성
aws eks create-pod-identity-association \
  --cluster-name my-cluster \
  --namespace production \
  --service-account my-app \
  --role-arn arn:aws:iam::123456789012:role/my-app-role

# Terraform으로 Pod Identity Association 설정
resource "aws_eks_pod_identity_association" "my_app" {
  cluster_name    = aws_eks_cluster.main.name
  namespace       = "production"
  service_account = "my-app"
  role_arn        = aws_iam_role.my_app.arn
}

Pod Identity의 IAM Role Trust Policy는 클러스터별 OIDC URL이 아닌 범용 Principal을 사용합니다:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "pods.eks.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ]
    }
  ]
}

EKS IRSA vs Pod Identity 비교

IRSA vs Pod Identity 선택 기준

기준	IRSA	Pod Identity
OIDC Provider 관리	클러스터마다 등록 필요	불필요 (AWS 관리)
Trust Policy	클러스터별 OIDC URL 포함 → 복잡	범용 Service Principal → 단순
멀티 클러스터	클러스터마다 Trust Policy 수정 필요	1개 Role을 여러 클러스터에서 재사용 가능
Session Tag	수동 설정 필요	자동 태깅 (클러스터명, namespace, SA)
ABAC 지원	제한적	Session Tag 기반 ABAC 지원
최소 EKS 버전	1.14+	1.24+
추가 Agent	불필요	Pod Identity Agent DaemonSet 필요

설계 판단: 신규 EKS 클러스터(1.24+)에서는 Pod Identity가 운영 복잡도를 줄여줍니다. 특히 멀티 클러스터 환경에서는 Trust Policy 관리 부담이 크게 줄어듭니다. 기존 클러스터에서 IRSA가 이미 동작 중이라면 당장 마이그레이션할 필요는 없으며, 신규 워크로드부터 Pod Identity를 적용하는 점진적 전환이 적합합니다.

5. Azure Workload Identity Federation

Azure에서도 동일한 패턴으로 GitHub Actions와 AKS Pod에서 OIDC 인증을 사용합니다. Azure는 이를 Workload Identity Federation이라 부릅니다.

GitHub Actions + Azure 연동

# 1. App Registration 생성
az ad app create --display-name "github-actions-deploy"

# 2. Federated Credential 추가 (GitHub OIDC 신뢰)
az ad app federated-credential create \
  --id <app-object-id> \
  --parameters '{
    "name": "github-main-branch",
    "issuer": "https://token.actions.githubusercontent.com",
    "subject": "repo:my-org/my-app:ref:refs/heads/main",
    "audiences": ["api://AzureADTokenExchange"]
  }'

# 3. Service Principal에 역할 할당
az role assignment create \
  --assignee <app-client-id> \
  --role "Contributor" \
  --scope "/subscriptions/<sub-id>/resourceGroups/my-rg"

워크플로우:

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - run: az resource list --resource-group my-rg

Azure의 경우 client-id, tenant-id, subscription-id는 Secret에 저장하지만, 이들은 식별자일 뿐 자격 증명이 아닙니다. Client Secret이나 Certificate 없이 OIDC 토큰만으로 인증이 완료됩니다.

AKS Workload Identity

AKS에서는 azure-workload-identity 프로젝트를 통해 Pod가 Azure 리소스에 접근합니다.

# ServiceAccount에 Workload Identity annotation
apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-app
  namespace: production
  annotations:
    azure.workload.identity/client-id: "<managed-identity-client-id>"

# Pod에 Workload Identity 라벨 추가
apiVersion: v1
kind: Pod
metadata:
  labels:
    azure.workload.identity/use: "true"
spec:
  serviceAccountName: my-app
  containers:
    - name: app
      image: my-app:latest

6. GCP Workload Identity Federation

GitHub Actions + GCP 연동

# 1. Workload Identity Pool 생성
gcloud iam workload-identity-pools create "github-pool" \
  --location="global" \
  --display-name="GitHub Actions Pool"

# 2. OIDC Provider 추가
gcloud iam workload-identity-pools providers create-oidc "github-provider" \
  --location="global" \
  --workload-identity-pool="github-pool" \
  --display-name="GitHub OIDC" \
  --issuer-uri="https://token.actions.githubusercontent.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
  --attribute-condition="assertion.repository_owner == 'my-org'"

# 3. Service Account에 workloadIdentityUser 역할 바인딩
gcloud iam service-accounts add-iam-policy-binding "deploy@my-project.iam.gserviceaccount.com" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/123456/locations/global/workloadIdentityPools/github-pool/attribute.repository/my-org/my-app"

워크플로우:

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: "projects/123456/locations/global/workloadIdentityPools/github-pool/providers/github-provider"
          service_account: "deploy@my-project.iam.gserviceaccount.com"
      - uses: google-github-actions/setup-gcloud@v2
      - run: gcloud run deploy my-service --image gcr.io/my-project/my-app

GKE Workload Identity

GKE에서는 Workload Identity Federation for GKE가 기본으로 활성화됩니다. Pod의 Kubernetes ServiceAccount를 GCP IAM Service Account에 연결합니다.

# Kubernetes ServiceAccount와 GCP Service Account 바인딩
gcloud iam service-accounts add-iam-policy-binding \
  "my-app@my-project.iam.gserviceaccount.com" \
  --role="roles/iam.workloadIdentityUser" \
  --member="serviceAccount:my-project.svc.id.goog[production/my-app]"

apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-app
  namespace: production
  annotations:
    iam.gke.io/gcp-service-account: my-app@my-project.iam.gserviceaccount.com

GKE Workload Identity는 OIDC Provider를 별도로 등록할 필요 없이, 클러스터 생성 시 --workload-pool 옵션만 활성화하면 됩니다.

7. 멀티 클라우드 OIDC 설계 비교

멀티 클라우드 OIDC 비교

구분	AWS	Azure	GCP
GitHub OIDC Trust 등록	IAM OIDC Provider	App Registration + Federated Credential	Workload Identity Pool + Provider
토큰 교환 엔드포인트	STS (AssumeRoleWithWebIdentity)	Microsoft Entra ID	STS (ExchangeToken)
Kubernetes Pod 인증	IRSA 또는 Pod Identity	AKS Workload Identity	GKE Workload Identity
Trust 범위 제한	Condition (sub, aud)	subject + audiences	attribute-condition
임시 자격 증명 수명	기본 1시간 (최대 12시간)	기본 1시간	기본 1시간
멀티 계정/구독/프로젝트	Role Chaining	구독별 Role Assignment	Cross-project IAM binding

설계 시 공통 원칙

Subject 범위를 최소화: 저장소 + 브랜치 + 환경 단위로 제한. repo:my-org/*처럼 와일드카드를 조직 전체로 열면 안 됩니다.
환경별 Role 분리: 개발/스테이징/프로덕션 환경마다 별도 Role을 생성하고, GitHub Environment Protection Rules와 연동합니다.
감사 로그 활성화: 임시 자격 증명으로 수행한 작업도 CloudTrail, Azure Activity Log, GCP Cloud Audit Logs에 기록됩니다. Session Name에 워크플로우 정보를 포함하면 추적이 쉽습니다.
임시 자격 증명 수명 최소화: 기본 1시간이지만, 빌드/배포 작업이 30분 내에 끝난다면 role-duration-seconds를 줄여 피해 시간을 제한할 수 있습니다.

8. 실무 시나리오: 스타트업 CI/CD + EKS 배포 파이프라인

3명의 DevOps 팀이 운영하는 환경을 가정합니다.

GitHub 조직: startup-corp
AWS 계정: Shared (Hub), Dev, Production 3개
EKS 클러스터: Dev 1개, Production 1개
배포 대상: 3개 마이크로서비스 (user-api, order-api, payment-api)

설계 구조

GitHub Actions (OIDC)
  └─ Hub 계정 Role (github-oidc-hub)
       ├─ Dev 계정 Role (dev-deploy) ← Role Chaining
       └─ Prod 계정 Role (prod-deploy) ← Role Chaining + Environment 보호 규칙

EKS Pod (Pod Identity)
  ├─ user-api ServiceAccount → user-api-role (DynamoDB 읽기)
  ├─ order-api ServiceAccount → order-api-role (SQS 송수신)
  └─ payment-api ServiceAccount → payment-api-role (KMS 복호화 + S3 쓰기)

왜 이렇게 설계하는가

Hub 계정 분리: OIDC Provider를 1곳에만 등록하면 GitHub 인증서 thumbprint 변경 시 1곳만 업데이트합니다.
환경별 Role 분리: Dev Role에는 terraform plan 수준의 읽기 권한만, Prod Role에는 terraform apply 권한을 부여합니다.
Pod 단위 최소 권한: payment-api가 침해되어도 DynamoDB에는 접근할 수 없습니다. 각 Pod는 자신의 서비스에 필요한 권한만 가집니다.
Pod Identity 선택 이유: 2개 클러스터에서 같은 Role을 재사용할 수 있어 Trust Policy 관리가 단순합니다. Session Tag로 어떤 클러스터, 어떤 namespace에서 호출했는지 CloudTrail에 자동 기록됩니다.

9. 주의사항과 트러블슈팅

GitHub Actions OIDC 관련

증상	원인	해결
`Not authorized to perform: sts:AssumeRoleWithWebIdentity`	Trust Policy의 sub 조건 불일치	`github.event_name`, `github.ref`를 확인. PR 이벤트는 `ref:refs/pull/*/merge` 형태
`permissions: id-token: write` 추가했는데 토큰이 안 나옴	Fork된 저장소에서는 OIDC 토큰 미발급	Fork PR 워크플로우에서는 OIDC 사용 불가
토큰 만료 에러	워크플로우 실행 시간이 토큰 유효 기간 초과	`role-duration-seconds`를 늘리거나, 장시간 작업은 Step을 분리

EKS IRSA/Pod Identity 관련

증상	원인	해결
Pod에서 `An error occurred (AccessDenied)`	ServiceAccount annotation 누락 또는 Trust Policy 불일치	`kubectl describe sa` + IAM Role Trust Policy 확인
Pod Identity Agent가 CrashLoop	EKS 클러스터 버전이 1.24 미만	클러스터 업그레이드 필요
`No OpenIDConnect provider found`	OIDC Provider가 IAM에 미등록 (IRSA)	`aws eks describe-cluster`로 OIDC URL 확인 후 등록

Subject 클레임 참고

GitHub Actions의 sub 클레임은 트리거 이벤트에 따라 달라집니다:

이벤트	sub 형태
`push` (main)	`repo:org/repo:ref:refs/heads/main`
`push` (tag)	`repo:org/repo:ref:refs/tags/v1.0.0`
`pull_request`	`repo:org/repo:pull_request`
`environment`	`repo:org/repo:environment:production`
`workflow_dispatch`	`repo:org/repo:ref:refs/heads/main`

프로덕션 배포에는 environment 기반 sub를 사용하고, GitHub Environment Protection Rules(Required Reviewers)와 결합하면 승인 없이 프로덕션에 배포되는 것을 방지할 수 있습니다.

10. OIDC vs 기존 방식: 언제 OIDC를 선택할 수 없는가

OIDC가 일반적으로 더 안전한 방식이지만, 모든 상황에 적합하지는 않습니다.

상황	OIDC 사용 가능	대안
GitHub Actions → AWS/Azure/GCP	✅	—
EKS/AKS/GKE Pod → 동일 Cloud	✅	—
Jenkins → AWS	✅ (Jenkins OIDC Plugin 사용)	—
GitHub Actions → 외부 SaaS API (Slack, Datadog 등)	❌	Repository/Environment Secret
On-premise 서버 → Cloud	조건부 (IdP 필요)	IAM User + IP 제한 + MFA
Lambda → 다른 AWS 서비스	불필요 (Execution Role 사용)	—

OIDC를 지원하지 않는 외부 서비스에 대해서는 여전히 Secret 기반 인증이 필요합니다. 이 경우에도 Environment Secret + Rotation Policy를 적용하여 위험을 줄입니다.

GitHub Actions에서 Secret을 안전하게 관리하는 방법 — OIDC를 포함한 전체 Secret 관리 전략
GitHub Actions로 Docker 이미지를 빌드하고 배포하기 — OIDC를 적용한 실제 배포 파이프라인
IAM과 RBAC 차이: AWS, Azure, GCP 기준으로 이해하기 — OIDC Role에 붙이는 IAM 권한 설계의 기본

참고 문서

RAG 검색 품질 개선: Hybrid Search, Reranking, Query Transformation

wero90 — Mon, 8 Jun 2026 10:10:20 +0900

RAG의 응답 품질은 검색 품질에 의해 결정됩니다. 아무리 좋은 LLM을 사용해도, 검색 단계에서 관련 문서를 가져오지 못하면 정확한 답변을 생성할 수 없습니다. 이 글에서는 검색 품질을 개선하는 세 가지 핵심 전략을 다룹니다.

핵심 요약

순수 벡터 검색(Dense Retrieval)만으로는 키워드 매칭이 필요한 질문에 취약합니다. BM25와 결합한 Hybrid Search로 커버리지를 높일 수 있습니다.
검색 결과의 순위를 Cross-encoder로 재정렬하는 Reranking은 적은 비용으로 정밀도를 높이는 효과적인 방법입니다.
사용자 질문을 그대로 검색하지 않고, LLM으로 변환하는 Query Transformation은 질문-문서 간 의미 격차를 줄입니다.
세 전략은 독립적이지 않으며, Hybrid Search → Reranking → Query Transformation 순으로 조합하면 누적 효과가 큽니다.
전략 도입 전에 현재 검색 품질의 baseline을 측정하고, 각 전략 추가 후 개선폭을 확인하는 방식이 실무적입니다.

1. 문제 상황: 왜 벡터 검색만으로는 부족한가

RAG 시스템을 구축하고 사내 문서를 임베딩해서 질문에 답하게 만들었습니다. 그런데 운영을 시작하면 이런 문제가 반복됩니다.

사례 1: 키워드 매칭 실패

질문: "ERROR-4032 에러 코드 해결 방법은?"
기대: ERROR-4032를 설명하는 문서
실제: "에러 처리 일반 가이드"가 반환됨

벡터 검색은 의미적 유사도 기반입니다. "ERROR-4032"라는 구체적인 코드와 의미적으로 유사한 벡터를 찾지만, 해당 코드가 정확히 포함된 문서를 우선하지는 않습니다.

사례 2: 검색 결과 순위 문제

Top-5 검색 결과 중 정답이 4번째에 있음
LLM은 1~2번째 결과에 더 가중치를 두어 부정확한 답변 생성

벡터 유사도 점수 차이가 미세한 경우, 실제 관련성이 높은 문서가 순위에서 밀릴 수 있습니다.

사례 3: 질문과 문서의 표현 격차

질문: "서버가 느려졌을 때 어떻게 해야 해?"
문서: "Latency 증가 시 수평 확장 전략과 캐시 레이어 도입을 검토합니다"
의미는 같지만 표현이 달라 유사도가 낮게 측정됨

이 세 가지 문제를 각각 해결하는 전략이 Hybrid Search, Reranking, Query Transformation입니다.

RAG 검색 품질 개선 전략 개요

2. Hybrid Search: BM25와 Dense Retrieval의 결합

2.1 왜 두 가지를 결합하는가

Dense Retrieval(벡터 검색)과 Sparse Retrieval(BM25)은 서로 다른 강점을 가집니다.

특성	Dense Retrieval (벡터 검색)	Sparse Retrieval (BM25)
강점	의미적 유사성, 동의어/패러프레이즈 처리	정확한 키워드 매칭, 희귀 용어 검색
약점	희귀 키워드나 코드에 취약	의미적 연관성을 이해하지 못함
적합한 질문	"환불 정책 알려줘" (문서에는 "반품 절차")	"ERROR-4032 해결 방법" (정확한 코드 매칭)
인덱스	벡터 인덱스 (HNSW, IVF 등)	역인덱스 (Inverted Index)

운영 환경에서 들어오는 질문은 한 가지 유형으로 통일되지 않습니다. 의미 기반 질문과 키워드 기반 질문이 섞여 있으므로, 두 방식을 결합해야 전체 커버리지가 높아집니다.

2.2 Hybrid Search 아키텍처

Hybrid Search 아키텍처

Hybrid Search의 기본 흐름은 다음과 같습니다.

병렬 검색: 동일한 쿼리를 BM25 인덱스와 벡터 인덱스에 각각 전달합니다.
개별 결과 수집: BM25에서 Top-N, 벡터 검색에서 Top-N 결과를 가져옵니다.
결과 융합(Fusion): 두 결과 리스트를 하나로 합칩니다.
최종 Top-K 선택: 융합된 순위에서 상위 K개를 LLM에 전달합니다.

2.3 결과 융합: Reciprocal Rank Fusion (RRF)

두 검색 결과의 점수 스케일이 다르므로(BM25는 0~수십, 코사인 유사도는 0~1), 단순 점수 합산은 효과적이지 않습니다. Reciprocal Rank Fusion(RRF)은 점수 대신 순위만 사용하여 이 문제를 해결합니다.

RRF_score(d) = Σ  1 / (k + rank(r, d))
               r∈R

d: 문서
R: 결과 리스트 집합 (BM25 결과, 벡터 검색 결과)
rank(r, d): 결과 리스트 r에서 문서 d의 순위
k: 스무딩 상수 (일반적으로 60)

예시: 문서 A가 BM25에서 3위, 벡터에서 7위인 경우

RRF_score(A) = 1/(60+3) + 1/(60+7) = 0.0159 + 0.0149 = 0.0308

RRF의 장점은 점수 보정(calibration)이 불필요하다는 것입니다. BM25 점수와 코사인 유사도의 스케일이 달라도, 순위 기반으로 동작하므로 안정적으로 융합됩니다.

2.4 구현 예시: LangChain + Elasticsearch

from langchain.retrievers import EnsembleRetriever
from langchain_community.retrievers import BM25Retriever
from langchain_community.vectorstores import OpenSearchVectorSearch

# BM25 Retriever 설정
bm25_retriever = BM25Retriever.from_documents(documents)
bm25_retriever.k = 20  # 상위 20개 후보

# Vector Retriever 설정
vector_store = OpenSearchVectorSearch(
    index_name="documents",
    embedding_function=embeddings,
    opensearch_url="https://opensearch-endpoint:443"
)
vector_retriever = vector_store.as_retriever(search_kwargs={"k": 20})

# Hybrid: EnsembleRetriever (RRF 기반 융합)
hybrid_retriever = EnsembleRetriever(
    retrievers=[bm25_retriever, vector_retriever],
    weights=[0.4, 0.6]  # BM25 40%, Vector 60% 가중치
)

results = hybrid_retriever.invoke("ERROR-4032 에러 해결 방법")

2.5 가중치 설정 기준

BM25와 Dense Retrieval 간 가중치는 질문 유형 분포에 따라 조정합니다.

질문 유형 분포	권장 가중치 (BM25 : Vector)	이유
키워드/코드 질문이 많음	0.5 : 0.5 또는 0.6 : 0.4	BM25가 정확 매칭에 강함
의미 기반 질문이 많음	0.3 : 0.7	벡터 검색이 패러프레이즈에 강함
혼합	0.4 : 0.6	일반적인 시작점

운영 중에는 실제 질문 로그를 분석하여 키워드형과 의미형 비율을 측정하고, 가중치를 조정합니다.

2.6 Hybrid Search를 지원하는 벡터 DB

벡터 DB	Hybrid Search 지원 방식	비고
OpenSearch	네이티브 BM25 + kNN 통합	RRF 내장 지원
Elasticsearch	BM25 + dense_vector kNN	RRF 내장 지원 (8.x+)
Weaviate	BM25 + Vector 하이브리드 모드	alpha 파라미터로 가중치 조정
Pinecone	Sparse-Dense 벡터 결합	단일 인덱스에서 하이브리드 지원
pgvector	벡터 검색만 네이티브, BM25는 별도 구현 필요	pg_search 또는 별도 BM25 레이어 필요

3. Reranking: 검색 결과 재정렬

3.1 왜 Reranking이 필요한가

Hybrid Search로 후보를 가져온 후에도, Top-K 내 순위가 최적이 아닐 수 있습니다. 이유는 다음과 같습니다.

Bi-encoder의 한계: 벡터 검색에 사용되는 Bi-encoder는 질문과 문서를 각각 독립적으로 인코딩합니다. 두 벡터 간 유사도를 계산하므로 속도는 빠르지만, 질문과 문서의 세밀한 상호작용을 포착하지 못합니다.
Cross-encoder의 강점: 질문과 문서를 하나의 입력으로 결합하여 동시에 처리합니다. 질문의 각 토큰이 문서의 모든 토큰과 상호작용(attention)하므로, 관련성 판단이 훨씬 정밀합니다.

Bi-encoder:   query → [Encoder] → q_vec   }→ cosine(q_vec, d_vec)
              doc   → [Encoder] → d_vec   }

Cross-encoder: [query + doc] → [Encoder] → relevance_score

Cross-encoder는 정확도가 높지만, 모든 문서에 적용하면 속도가 느립니다. 따라서 1단계에서 후보를 좁히고(Retrieval), 2단계에서 소수의 후보만 재정렬하는(Reranking) 2단계 구조가 표준입니다.

Reranking 파이프라인

3.2 2단계 Retrieval-Reranking 파이프라인

[전체 문서 인덱스]
    ↓ 1단계: Retrieval (Hybrid Search)
[Top-50 후보] ← 빠른 검색 (ms 단위)
    ↓ 2단계: Reranking (Cross-encoder)
[Top-5 재정렬] ← 정밀 평가 (수백 ms)
    ↓
[LLM에 전달]

1단계 (Retrieval): Hybrid Search로 Top-50 후보를 빠르게 가져옵니다. 여기서는 Recall(관련 문서를 빠뜨리지 않는 것)이 중요합니다.
2단계 (Reranking): 50개 후보를 Cross-encoder로 정밀 평가하여 Top-5를 선별합니다. 여기서는 Precision(상위 결과의 정확도)이 중요합니다.

3.3 Reranking 모델 선택지

모델/서비스	컨텍스트 윈도우	특징	비고
Cohere Rerank 4	32,000 토큰	100+ 언어 지원, JSON 구조 데이터 처리 가능	rerank-v4.0 (품질 우선) / rerank-v4.0-fast (속도 우선)
Cohere Rerank 3.5	4,096 토큰	다국어 SOTA, 추론 능력 포함	비용 대비 효율 높음
Cross-encoder/ms-marco-MiniLM	512 토큰	오픈소스, 로컬 실행 가능	영어 중심, 짧은 문서에 적합
BGE-reranker-v2-m3	8,192 토큰	오픈소스, 다국어 지원	로컬 GPU 필요
Jina Reranker v2	8,192 토큰	코드, 다국어 지원	API 또는 로컬 실행

3.4 구현 예시: Cohere Rerank

import cohere

co = cohere.ClientV2()

# 1단계: Hybrid Search로 후보 검색 (위 예시에서 가져온 결과)
candidates = hybrid_retriever.invoke(query)

# 2단계: Reranking
rerank_response = co.rerank(
    model="rerank-v4.0",
    query="ERROR-4032 에러 해결 방법",
    documents=[doc.page_content for doc in candidates],
    top_n=5,  # 상위 5개만 반환
    return_documents=True
)

# 재정렬된 결과
for result in rerank_response.results:
    print(f"Score: {result.relevance_score:.4f}")
    print(f"Content: {result.document.text[:100]}...")

3.5 Reranking 비용-성능 trade-off

Reranking은 후보 수에 비례하여 비용과 지연 시간이 증가합니다.

후보 수	지연 시간 (일반적)	정밀도 향상	비용 영향
10개	50~100ms	소폭 향상	낮음
20~30개	100~200ms	중간 향상	중간
50개	200~400ms	높은 향상	높음
100개 이상	400ms+	추가 향상 미미	높음

운영 환경에서는 후보 수를 20~50개로 설정하는 것이 일반적입니다. 그 이상에서는 비용 대비 품질 향상이 감소합니다.

3.6 Reranking 없이 대안: Lost in the Middle 문제

Reranking을 적용하지 않으면, LLM이 긴 컨텍스트의 중간에 있는 정보를 놓치는 "Lost in the Middle" 현상이 발생할 수 있습니다. 연구에 따르면, LLM은 컨텍스트의 처음과 끝에 있는 정보는 잘 활용하지만, 중간에 있는 정보는 간과하는 경향이 있습니다.

Reranking으로 가장 관련성 높은 문서를 상위에 배치하면, LLM이 핵심 정보를 먼저 읽게 되어 이 문제를 완화할 수 있습니다.

4. Query Transformation: 질문을 검색에 최적화하기

4.1 왜 질문을 변환하는가

사용자 질문은 검색에 최적화된 형태가 아닌 경우가 많습니다.

모호한 질문: "이거 어떻게 해?" → 무엇을 어떻게 하는 건지 불명확
대화체 질문: "서버가 느려졌는데 왜 그런 거야?" → 문서에는 "Latency 증가 원인"으로 기술
복합 질문: "VPC 설계하려는데 서브넷 분리 기준이랑 보안 그룹 설정 방법 알려줘" → 두 가지 주제가 혼합

Query Transformation은 이런 질문을 검색에 더 적합한 형태로 바꾸는 전처리 단계입니다.

Query Transformation 전략 비교

4.2 Multi-Query: 질문을 여러 관점으로 확장

하나의 질문을 여러 버전으로 변환하여 각각 검색한 후 결과를 합칩니다. 하나의 표현으로 검색하면 놓칠 수 있는 관련 문서를 다양한 표현으로 커버합니다.

from langchain.retrievers.multi_query import MultiQueryRetriever
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.3)

multi_query_retriever = MultiQueryRetriever.from_llm(
    retriever=vector_retriever,
    llm=llm
)

# 원본: "EKS에서 Pod가 외부 통신이 안 되는 이유는?"
# 생성되는 변형:
# 1. "EKS Pod outbound traffic 실패 원인"
# 2. "Kubernetes Pod 인터넷 접근 불가 해결 방법"
# 3. "EKS NAT Gateway VPC 설정 문제"
results = multi_query_retriever.invoke(
    "EKS에서 Pod가 외부 통신이 안 되는 이유는?"
)

장점: 원래 질문으로는 검색되지 않던 관련 문서를 추가로 찾을 수 있습니다. 단점: LLM 호출이 추가되므로 지연 시간과 비용이 증가합니다.

4.3 HyDE: Hypothetical Document Embeddings

질문을 그대로 임베딩하지 않고, LLM이 가상의 답변 문서를 먼저 생성한 뒤 그 문서를 임베딩하여 검색합니다.

일반 RAG:     질문 → 임베딩 → 벡터 검색 → 결과
HyDE:         질문 → LLM(가상 답변 생성) → 가상 답변 임베딩 → 벡터 검색 → 결과

핵심 아이디어는 "질문과 문서의 표현 격차(gap)를 줄이는 것"입니다. 질문 벡터보다 문서와 비슷한 형태의 벡터로 검색하면, 문서 인덱스에서 더 정확한 매칭이 가능합니다.

from langchain.chains import HypotheticalDocumentEmbedder
from langchain_openai import ChatOpenAI, OpenAIEmbeddings

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
base_embeddings = OpenAIEmbeddings(model="text-embedding-3-small")

# HyDE Embedder: LLM으로 가상 문서 생성 후 임베딩
hyde_embeddings = HypotheticalDocumentEmbedder.from_llm(
    llm=llm,
    base_embeddings=base_embeddings,
    prompt_key="web_search"  # 프롬프트 템플릿 유형
)

# "서버가 느려졌을 때 대응 방법" 질문에 대해
# LLM이 먼저 가상의 답변 문서를 생성:
# "서버 응답 시간 증가 시 수평 확장, 캐시 레이어 도입,
#  DB 쿼리 최적화, CDN 적용을 검토합니다..."
# → 이 가상 문서의 임베딩으로 검색

장점: 질문-문서 간 어휘 불일치(vocabulary mismatch) 문제를 효과적으로 해결합니다. 단점: LLM이 생성한 가상 답변이 부정확하면 오히려 검색 품질이 떨어질 수 있습니다. 사실 기반 질문(수치, 코드명 등)에서는 효과가 제한적입니다.

4.4 Query Decomposition: 복합 질문 분해

하나의 복합 질문을 여러 단순 질문으로 분해하여 각각 검색합니다.

from langchain.output_parsers import NumberedListOutputParser
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

decomposition_prompt = """
다음 질문을 2~4개의 단순한 하위 질문으로 분해하세요.
각 하위 질문은 독립적으로 검색할 수 있어야 합니다.

질문: {question}
"""

# 원본: "VPC 설계 시 서브넷 분리 기준과 보안 그룹 설정 방법은?"
# 분해 결과:
# 1. "VPC 서브넷 분리 기준은?"
# 2. "Public/Private 서브넷 설계 패턴은?"
# 3. "보안 그룹 설정 방법과 규칙 설계 기준은?"

적합한 경우: 사용자가 여러 주제를 한 번에 질문하는 패턴이 많은 시스템. FAQ 챗봇보다는 기술 문서 검색, 리서치 보조 도구에 적합합니다.

4.5 Step-back Prompting: 추상화된 질문으로 검색

구체적인 질문을 한 단계 추상화하여 더 넓은 범위의 관련 문서를 찾습니다.

원본 질문:    "EKS 1.28에서 CoreDNS가 CrashLoopBackOff 되는 이유?"
Step-back:   "Kubernetes CoreDNS 장애 원인과 해결 방법"

구체적인 질문으로만 검색하면 해당 버전에 국한된 문서만 찾을 수 있습니다. Step-back으로 범용적인 문서를 함께 검색하면, 배경 지식과 구체적 해결책을 모두 LLM에 제공할 수 있습니다.

4.6 전략별 비교

전략	추가 LLM 호출	지연 시간 증가	효과적인 상황	주의할 점
Multi-Query	1회 (변형 생성)	+200~500ms	다양한 표현의 문서가 있을 때	결과 중복 제거 필요
HyDE	1회 (가상 답변 생성)	+300~800ms	질문-문서 표현 격차가 클 때	사실 기반 질문에는 비효과적
Query Decomposition	1회 (분해)	+200~500ms	복합 질문이 많을 때	단순 질문에는 오버헤드만 증가
Step-back Prompting	1회 (추상화)	+200~500ms	구체적 문제에 배경 지식이 필요할 때	추상화가 너무 넓으면 노이즈 증가

5. 전략 조합: 실무 파이프라인 설계

5.1 권장 파이프라인 구성

세 전략을 조합한 실무 파이프라인의 일반적인 구성입니다.

[사용자 질문]
    ↓ (선택) Query Transformation
[변환된 질문(들)]
    ↓ Hybrid Search (BM25 + Dense)
[Top-50 후보]
    ↓ Reranking (Cross-encoder)
[Top-5 재정렬]
    ↓
[LLM 응답 생성]

5.2 시나리오별 권장 조합

전략 조합 의사결정 흐름

시나리오 1: 사내 기술 문서 검색 (에러 코드 + 개념 질문 혼합)

구성 요소	선택	이유
검색	Hybrid Search (BM25 0.4 : Vector 0.6)	에러 코드는 BM25, 개념 질문은 벡터
Reranking	Cohere Rerank 4	다국어(한국어 문서) 지원, 긴 문서 처리
Query Transformation	Multi-Query	동일 개념의 다양한 표현을 커버

시나리오 2: 고객 지원 FAQ 챗봇 (짧은 질문, 빠른 응답 필요)

구성 요소	선택	이유
검색	Hybrid Search (BM25 0.3 : Vector 0.7)	고객 질문은 대부분 의미 기반
Reranking	Cohere Rerank v4.0-fast 또는 경량 Cross-encoder	지연 시간 최소화
Query Transformation	미적용	FAQ 질문은 보통 단순하고 직접적

시나리오 3: 법률/계약서 분석 시스템 (정확도 최우선)

구성 요소	선택	이유
검색	Hybrid Search (BM25 0.5 : Vector 0.5)	조항 번호 매칭 + 의미 검색 균형
Reranking	Cohere Rerank 4 (Top-50 → Top-5)	정밀도 최우선, 지연 시간 허용
Query Transformation	Query Decomposition + Step-back	복합 법률 질문 분해 + 배경 조항 검색

5.3 점진적 도입 전략

모든 전략을 한 번에 도입하기보다, 단계적으로 추가하며 각 단계의 효과를 측정하는 방식을 권장합니다.

1단계: Dense Retrieval만 (baseline 측정)
   → Recall@10: 65%, Precision@5: 40%

2단계: + BM25 Hybrid Search 추가
   → Recall@10: 80% (+15%), Precision@5: 48% (+8%)

3단계: + Reranking 추가
   → Recall@10: 80% (유지), Precision@5: 68% (+20%)

4단계: + Query Transformation 추가
   → Recall@10: 88% (+8%), Precision@5: 72% (+4%)

각 단계에서 개선이 확인되면 다음 단계로 진행합니다. 특정 전략이 효과가 없으면 해당 단계를 건너뛰거나 다른 방식으로 대체합니다.

6. 비용/운영 고려사항

6.1 전략별 비용 영향

전략	추가 API 호출	지연 시간 영향	인프라 요구사항
Hybrid Search	없음 (인덱스 추가만)	+10~50ms	BM25 인덱스 추가 (Elasticsearch 등)
Reranking	Rerank API 1회/쿼리	+100~400ms	외부 API 또는 GPU 서버
Multi-Query	LLM 1회/쿼리	+200~500ms	LLM API 비용
HyDE	LLM 1회/쿼리	+300~800ms	LLM API 비용

6.2 비용 최적화 방법

Reranking 후보 수 제한: 50개 이상은 비용 대비 효과가 감소합니다. 20~30개로 시작합니다.
Query Transformation 조건부 적용: 모든 질문에 HyDE를 적용하면 비용이 2배 증가합니다. 질문 유형을 분류하여 필요한 경우에만 적용합니다.
캐시 활용: 동일하거나 유사한 질문에 대한 검색 결과를 캐시하면 반복 비용을 줄일 수 있습니다.
경량 Reranker 사용: 실시간 응답이 중요한 경우 Cohere Rerank v4.0-fast나 오픈소스 경량 모델을 선택합니다.

6.3 모니터링 지표

운영 중 검색 품질을 지속적으로 관찰하기 위한 지표입니다.

지표	설명	목표
Retrieval Latency	검색 완료까지 소요 시간 (Reranking 포함)	< 500ms (일반), < 200ms (실시간)
Reranker Score Distribution	Top-K 결과의 relevance score 분포	상위 결과가 0.8+ 유지
Empty Result Rate	검색 결과가 비어 있는 비율	< 5%
User Feedback	사용자가 응답에 만족했는지 (thumbs up/down)	만족도 80%+
Fallback Rate	Query Transformation 후에도 검색 실패하는 비율	< 10%

7. 자주 하는 실수

Reranking 없이 Top-K를 바로 LLM에 전달: 벡터 유사도 순위가 실제 관련성 순위와 다를 수 있습니다. 특히 Top-5 내 순서가 중요한 경우 Reranking 없이는 "Lost in the Middle" 문제가 발생합니다.
모든 질문에 HyDE 적용: 사실 기반 질문(코드, 수치, 이름 검색)에 HyDE를 적용하면 LLM이 잘못된 가상 답변을 생성하여 오히려 검색 품질이 떨어집니다.
BM25 인덱스를 관리하지 않음: 벡터 인덱스만 업데이트하고 BM25 인덱스 동기화를 놓치면, Hybrid Search에서 오래된 BM25 결과가 반환됩니다.
Reranking 후보를 너무 적게 설정: Top-5만 가져와서 Reranking하면, 원래 6위에 있던 정답 문서를 놓칩니다. Recall을 확보하려면 1단계에서 충분한 후보(20~50개)를 가져와야 합니다.
전략 효과를 측정하지 않음: 각 전략이 실제로 검색 품질을 개선하는지 A/B 테스트 없이 도입하면, 비용만 증가하고 품질은 개선되지 않을 수 있습니다.
RRF의 k값을 조정하지 않음: RRF의 스무딩 상수 k(기본 60)는 순위 상위 문서에 얼마나 가중치를 줄지를 결정합니다. 도메인에 따라 k값을 실험해볼 필요가 있습니다.

8. 정리

Hybrid Search는 키워드 매칭과 의미 검색을 결합하여 단일 방식의 맹점을 보완합니다. RRF로 점수 보정 없이 안정적으로 융합할 수 있습니다.
Reranking은 Cross-encoder로 검색 결과의 순위를 정밀하게 재조정합니다. 비용 대비 정밀도 향상 효과가 가장 큰 전략입니다.
Query Transformation은 사용자 질문과 문서 간 표현 격차를 줄여 Recall을 높입니다. 다만 모든 질문에 적용할 필요는 없으며, 질문 유형에 따라 선택적으로 적용합니다.
세 전략의 도입 순서는 일반적으로 Hybrid Search → Reranking → Query Transformation입니다. 각 단계에서 효과를 측정하고, 비용 대비 개선이 확인되면 다음 단계로 진행합니다.
측정 없는 최적화는 불가능합니다. Baseline을 먼저 측정하고, 각 전략 추가 후 Retrieval Precision/Recall 변화를 추적하는 체계가 가장 먼저 필요합니다.

참고 문서

Kubernetes Secret을 안전하게 관리하는 방법: etcd 암호화부터 외부 Secret 관리 도구까지

wero90 — Mon, 8 Jun 2026 09:58:14 +0900

Kubernetes Secret은 민감 데이터를 저장하는 기본 메커니즘이지만, 기본 설정만으로는 안전하지 않습니다. Base64 인코딩은 암호화가 아니며, etcd에 평문으로 저장될 수 있습니다. 운영 환경에서는 암호화, 접근 제어, 외부 Secret 관리 도구를 조합하여 보안을 강화해야 합니다.

핵심 요약

Kubernetes Secret은 Base64 인코딩만 적용됩니다. 이는 난독화일 뿐 암호화가 아닙니다.
기본 설정에서 Secret은 etcd에 평문으로 저장됩니다. EncryptionConfiguration을 통해 저장 시 암호화(Encryption at Rest)를 활성화해야 합니다.
RBAC로 Secret 접근을 최소화하고, 감사 로그로 접근 이력을 추적합니다.
운영 환경에서는 외부 Secret 관리 도구(External Secrets Operator, Sealed Secrets, HashiCorp Vault)를 사용하여 Git 저장소에 Secret이 노출되지 않도록 합니다.
매니지드 Kubernetes(EKS, AKS, GKE)는 기본적으로 etcd 암호화를 제공하지만, 클러스터 내부 접근 제어는 별도로 설계해야 합니다.

1. Kubernetes Secret의 보안 한계

팀에서 데이터베이스 비밀번호를 Kubernetes Secret으로 관리합니다. YAML 파일을 Git에 커밋하고, 새 팀원이 합류할 때마다 kubectl로 Secret을 확인합니다. 어느 날 보안 감사에서 이런 질문을 받습니다: "이 Secret은 누가 언제 조회했는지 추적할 수 있나요? etcd에 암호화되어 저장되나요?"

대부분의 경우 대답은 "아니오"입니다. Kubernetes Secret의 기본 보안 수준이 낮은 이유를 먼저 이해해야 합니다.

1.1 Base64 ≠ 암호화

apiVersion: v1
kind: Secret
metadata:
  name: db-credentials
  namespace: production
type: Opaque
data:
  username: YWRtaW4=        # echo -n "admin" | base64
  password: cEBzc3cwcmQ=    # echo -n "p@ssw0rd" | base64

base64 --decode로 누구나 원본 값을 복원할 수 있습니다. Git에 이 YAML이 커밋되면 사실상 평문과 동일합니다.

1.2 etcd 평문 저장

기본 설정에서 Kubernetes API Server는 Secret을 etcd에 그대로 저장합니다. etcd 백업 파일에 접근하거나, etcd를 직접 조회할 수 있는 사람은 모든 Secret을 평문으로 읽을 수 있습니다.

1.3 과도한 접근 권한

view ClusterRole을 가진 사용자는 Secret을 읽을 수 없지만, edit이나 admin ClusterRole은 Secret 읽기/쓰기가 가능합니다. 네임스페이스에 edit 권한을 부여하면 의도치 않게 Secret 접근이 허용됩니다.

위험	원인	영향
Git에 Secret YAML 노출	Base64가 암호화라고 착각	리포지토리 접근자 전원이 Secret 열람 가능
etcd 평문 저장	EncryptionConfiguration 미설정	etcd 백업/접근으로 전체 Secret 유출
과도한 RBAC 권한	네임스페이스 단위 edit/admin 부여	불필요한 서비스까지 Secret 조회 가능
감사 추적 불가	Audit Log 미설정	누가 언제 Secret을 읽었는지 확인 불가
Pod에서 환경 변수 노출	env로 Secret 주입	`kubectl describe pod`로 값 노출

2. 보안 강화 전략 개요

Kubernetes Secret 보안 계층 구조

Secret 보안은 단일 도구로 해결되지 않습니다. 여러 계층을 조합하여 방어 깊이(Defense in Depth)를 확보해야 합니다.

계층	목적	도구/설정
저장 시 암호화	etcd에 암호화된 상태로 저장	EncryptionConfiguration, 클라우드 KMS
접근 제어	Secret 읽기/쓰기 권한 최소화	RBAC, 전용 ServiceAccount
전송 시 암호화	API Server ↔ etcd 통신 암호화	TLS (기본 활성화)
외부 Secret 관리	Git에 Secret을 저장하지 않음	External Secrets Operator, Sealed Secrets, Vault
감사	접근 이력 추적	Kubernetes Audit Log
런타임 보호	Pod 내부에서 Secret 노출 최소화	Volume mount 방식, `automountServiceAccountToken: false`

3. etcd 저장 시 암호화 (Encryption at Rest)

etcd 암호화 동작 흐름

3.1 EncryptionConfiguration 설정

자체 관리 클러스터(kubeadm 등)에서는 API Server에 --encryption-provider-config 플래그로 암호화를 활성화합니다.

# /etc/kubernetes/encryption-config.yaml
apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
  - resources:
      - secrets
    providers:
      - aescbc:
          keys:
            - name: key1
              secret: <BASE64_ENCODED_32_BYTE_KEY>
      - identity: {}   # 암호화되지 않은 기존 Secret 읽기용 fallback

# 32바이트 키 생성
head -c 32 /dev/urandom | base64

# API Server 설정에 추가
# /etc/kubernetes/manifests/kube-apiserver.yaml
# --encryption-provider-config=/etc/kubernetes/encryption-config.yaml

암호화 Provider 선택:

Provider	특징	권장 용도
`aescbc`	AES-CBC 256비트 암호화. 키를 로컬에 저장	소규모 클러스터, 테스트 환경
`aesgcm`	AES-GCM 인증 암호화. 키 로테이션 시 주의 필요	성능이 중요한 경우
`kms` v2	외부 KMS와 연동 (봉투 암호화)	운영 환경 권장
`secretbox`	NaCl SecretBox 사용. 인증+암호화 동시 제공	단순한 환경에서 안전한 선택

주의
identity provider는 암호화를 적용하지 않습니다. providers 목록에서 첫 번째 항목이 쓰기에 사용됩니다. identity가 첫 번째이면 암호화가 적용되지 않으므로, 반드시 암호화 provider를 먼저 배치해야 합니다.

3.2 기존 Secret 재암호화

EncryptionConfiguration을 적용해도 기존 Secret은 자동으로 재암호화되지 않습니다. 명시적으로 업데이트해야 합니다.

# 모든 네임스페이스의 Secret을 재암호화
kubectl get secrets --all-namespaces -o json | \
  kubectl replace -f -

3.3 매니지드 Kubernetes에서의 etcd 암호화

플랫폼	기본 암호화	추가 옵션
EKS	기본 비활성화, 콘솔에서 활성화 가능	AWS KMS 키를 지정하여 봉투 암호화
AKS	기본 활성화 (Azure 관리 키)	Customer-Managed Key (CMK) 지정 가능
GKE	기본 활성화 (Google 관리 키)	CMEK(Customer-Managed Encryption Key) 지정 가능

EKS에서 Secret 암호화를 활성화하는 경우:

# EKS 클러스터에 KMS 기반 Secret 암호화 활성화
aws eks associate-encryption-config \
  --cluster-name my-cluster \
  --encryption-config '[{"resources":["secrets"],"provider":{"keyArn":"arn:aws:kms:ap-northeast-2:123456789012:key/key-id"}}]'

4. RBAC로 Secret 접근 제한

4.1 Secret 전용 Role 설계

네임스페이스 내에서도 Secret 접근은 별도 Role로 분리해야 합니다. 개발자에게 edit ClusterRole 대신 Secret을 제외한 커스텀 Role을 부여하는 패턴이 안전합니다.

# Secret 읽기를 제외한 개발자 Role
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: production
  name: developer-no-secrets
rules:
- apiGroups: [""]
  resources: ["pods", "services", "configmaps"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: ["apps"]
  resources: ["deployments", "replicasets"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
# Secret에 대한 규칙이 없으므로 접근 불가

# Secret 읽기만 허용하는 별도 Role (필요한 사람에게만 부여)
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: production
  name: secret-reader
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get", "list"]
  resourceNames: ["db-credentials", "api-key"]  # 특정 Secret만 허용

4.2 감사 로그 설정

Secret 접근 이력을 추적하려면 Kubernetes Audit Policy에서 Secret 관련 이벤트를 기록해야 합니다.

# audit-policy.yaml
apiVersion: audit.k8s.io/v1
kind: Policy
rules:
  # Secret 읽기/쓰기 모든 동작을 RequestResponse 수준으로 기록
  - level: Metadata
    resources:
      - group: ""
        resources: ["secrets"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

Tip
Secret 감사 로그에서 level: RequestResponse를 사용하면 Secret 값 자체가 로그에 기록될 수 있습니다. level: Metadata는 "누가, 언제, 어떤 Secret에 접근했는가"만 기록하므로 보안과 감사 모두를 만족합니다.

5. 외부 Secret 관리 도구 비교

외부 Secret 관리 도구 동작 비교

Git 저장소에 Secret YAML을 직접 저장하지 않으려면 외부 Secret 관리 도구를 사용해야 합니다. 각 도구의 동작 방식과 trade-off가 다릅니다.

도구	방식	Git에 저장하는 것	Secret 원본 위치	복잡도
Sealed Secrets	비대칭 암호화로 암호화된 Secret을 Git에 저장	암호화된 SealedSecret YAML	클러스터 내부 (컨트롤러가 복호화)	낮음
External Secrets Operator	외부 저장소에서 Secret을 동기화	ExternalSecret 참조 YAML (값 미포함)	AWS Secrets Manager, Vault, Azure Key Vault 등	중간
HashiCorp Vault + VSO	Vault에서 직접 Secret을 주입	VaultStaticSecret/VaultDynamicSecret CRD	HashiCorp Vault	높음
Secrets Store CSI Driver	CSI 볼륨으로 Secret을 Pod에 마운트	SecretProviderClass YAML (값 미포함)	클라우드 KMS, Vault	중간

의사결정 기준

Q1. Secret 원본을 어디에 저장할 것인가?
├── 클라우드 Secret 서비스 (Secrets Manager, Key Vault 등) → External Secrets Operator
├── 자체 관리 Vault → HashiCorp Vault + VSO
└── 별도 인프라 없이 Git 기반으로 → Sealed Secrets

Q2. 동적 Secret(TTL 기반 자동 갱신)이 필요한가?
├── 예 → HashiCorp Vault (Dynamic Secrets)
└── 아니오 → External Secrets Operator 또는 Sealed Secrets

Q3. 팀 규모와 운영 복잡도를 감당할 수 있는가?
├── 소규모 팀, 단일 클러스터 → Sealed Secrets
├── 중규모, 멀티 클라우드 → External Secrets Operator
└── 대규모, 엄격한 보안 요구사항 → HashiCorp Vault

6. Sealed Secrets: Git 친화적 암호화

Sealed Secrets 동작 흐름

Sealed Secrets는 Bitnami에서 개발한 오픈소스 도구입니다. 비대칭 암호화를 사용하여 클러스터의 컨트롤러만 복호화할 수 있는 SealedSecret을 생성합니다. 암호화된 YAML은 Git에 안전하게 커밋할 수 있습니다.

6.1 동작 원리

클러스터에 Sealed Secrets 컨트롤러를 설치합니다. 컨트롤러가 RSA 키 쌍을 생성합니다.
개발자가 kubeseal CLI로 일반 Secret을 SealedSecret으로 암호화합니다.
암호화된 SealedSecret YAML을 Git에 커밋합니다.
클러스터에 SealedSecret이 적용되면, 컨트롤러가 복호화하여 일반 Kubernetes Secret을 생성합니다.

6.2 설치 및 사용

# 컨트롤러 설치 (Helm)
helm repo add sealed-secrets https://bitnami-labs.github.io/sealed-secrets
helm install sealed-secrets sealed-secrets/sealed-secrets \
  --namespace kube-system

# kubeseal CLI 설치 (v0.27.x 기준)
# macOS
brew install kubeseal

# Linux
wget https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.27.3/kubeseal-0.27.3-linux-amd64.tar.gz
tar -xvzf kubeseal-0.27.3-linux-amd64.tar.gz
sudo install -m 755 kubeseal /usr/local/bin/kubeseal

# 일반 Secret을 SealedSecret으로 암호화
kubectl create secret generic db-credentials \
  --namespace production \
  --from-literal=username=admin \
  --from-literal=password='p@ssw0rd' \
  --dry-run=client -o yaml | \
  kubeseal --format yaml > sealed-db-credentials.yaml

# sealed-db-credentials.yaml (Git에 안전하게 커밋 가능)
apiVersion: bitnami.com/v1alpha1
kind: SealedSecret
metadata:
  name: db-credentials
  namespace: production
spec:
  encryptedData:
    username: AgBy3i4OJSWK+P... (암호화된 값)
    password: AgCtr8sMGh2DJKL... (암호화된 값)
  template:
    metadata:
      name: db-credentials
      namespace: production
    type: Opaque

6.3 키 로테이션

Sealed Secrets 컨트롤러는 기본적으로 30일마다 새 키를 생성합니다. 이전 키는 삭제되지 않으므로 기존 SealedSecret은 계속 복호화됩니다.

# 현재 사용 중인 키 확인
kubectl get secrets -n kube-system -l sealedsecrets.bitnami.com/sealed-secrets-key

# 키를 수동으로 로테이션한 후 기존 SealedSecret 재암호화
kubeseal --re-encrypt < sealed-db-credentials.yaml > sealed-db-credentials-new.yaml

6.4 trade-off

장점	단점
설치/운영이 단순	클러스터 간 키가 다르므로 멀티 클러스터에서 관리 복잡
Git에 안전하게 저장 가능	Secret 값 변경 시 re-seal 필요
외부 인프라 불필요	동적 Secret(자동 갱신) 미지원
GitOps와 자연스럽게 통합	컨트롤러 키 분실 시 모든 Secret 복구 불가

Security Note
Sealed Secrets 컨트롤러의 개인 키를 안전하게 백업해야 합니다. 이 키를 잃으면 기존 SealedSecret을 복호화할 수 없습니다. 키는 kube-system 네임스페이스의 Secret으로 저장되므로, 클러스터 재생성 시 이 키를 먼저 복원해야 합니다.

7. External Secrets Operator: 외부 저장소 연동

External Secrets Operator 동작 흐름

External Secrets Operator(ESO)는 AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, HashiCorp Vault 등 외부 Secret 저장소에서 값을 읽어와 Kubernetes Secret으로 동기화합니다.

7.1 동작 원리

외부 저장소(예: AWS Secrets Manager)에 Secret을 생성합니다.
클러스터에 SecretStore(또는 ClusterSecretStore)를 정의하여 외부 저장소 연결 정보를 설정합니다.
ExternalSecret 리소스를 생성하여 "어떤 외부 Secret을 어떤 Kubernetes Secret으로 동기화할지" 정의합니다.
ESO 컨트롤러가 주기적으로 외부 저장소에서 값을 가져와 Kubernetes Secret을 생성/갱신합니다.

7.2 설치 및 설정

# External Secrets Operator 설치 (Helm)
helm repo add external-secrets https://charts.external-secrets.io
helm install external-secrets external-secrets/external-secrets \
  --namespace external-secrets \
  --create-namespace

7.3 AWS Secrets Manager 연동 예시

# SecretStore 정의 — AWS Secrets Manager 연결
apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: aws-secrets-manager
  namespace: production
spec:
  provider:
    aws:
      service: SecretsManager
      region: ap-northeast-2
      auth:
        jwt:
          serviceAccountRef:
            name: external-secrets-sa  # IRSA로 인증

# ExternalSecret 정의 — 외부 Secret을 K8s Secret으로 동기화
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: db-credentials
  namespace: production
spec:
  refreshInterval: 1h              # 동기화 주기
  secretStoreRef:
    name: aws-secrets-manager
    kind: SecretStore
  target:
    name: db-credentials           # 생성될 K8s Secret 이름
    creationPolicy: Owner
  data:
    - secretKey: username          # K8s Secret의 key
      remoteRef:
        key: production/db-creds   # AWS Secrets Manager의 Secret 이름
        property: username         # JSON 내 특정 필드
    - secretKey: password
      remoteRef:
        key: production/db-creds
        property: password

7.4 Azure Key Vault 연동 예시

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: azure-key-vault
  namespace: production
spec:
  provider:
    azurekv:
      vaultUrl: "https://my-vault.vault.azure.net"
      authType: WorkloadIdentity
      serviceAccountRef:
        name: external-secrets-sa

7.5 trade-off

장점	단점
Secret 원본이 클러스터 외부에 있어 분리됨	외부 저장소 장애 시 Secret 갱신 불가
다양한 Provider 지원 (15+ 종류)	초기 설정(IRSA, Workload Identity) 필요
자동 동기화로 Secret 갱신 자동화	동기화 지연(refreshInterval)으로 즉시 반영 안 될 수 있음
Git에는 참조만 저장 (값 미포함)	외부 저장소 비용 발생

8. HashiCorp Vault 연동

HashiCorp Vault Kubernetes 연동 구조

HashiCorp Vault는 동적 Secret 생성, 자동 갱신, 세밀한 접근 정책을 제공하는 Secret 관리 플랫폼입니다. Kubernetes와의 연동 방식은 세 가지가 있습니다.

연동 방식	설명	특징
Vault Secrets Operator (VSO)	CRD 기반으로 Vault Secret을 K8s Secret으로 동기화	권장 방식, Operator 패턴
Vault Agent Injector	Init/Sidecar 컨테이너로 Secret을 Pod에 주입	애플리케이션 코드 변경 불필요
Secrets Store CSI Driver	CSI 볼륨으로 Secret을 파일 시스템에 마운트	표준 CSI 인터페이스 사용

8.1 Vault Secrets Operator (VSO) 방식

# VaultAuth — Vault 인증 설정
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultAuth
metadata:
  name: vault-auth
  namespace: production
spec:
  method: kubernetes
  mount: kubernetes
  kubernetes:
    role: production-app
    serviceAccount: app-sa

# VaultStaticSecret — 정적 Secret 동기화
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
  name: db-credentials
  namespace: production
spec:
  type: kv-v2
  mount: secret
  path: production/db-creds
  destination:
    name: db-credentials       # 생성될 K8s Secret 이름
    create: true
  refreshAfter: 30s            # 갱신 주기
  vaultAuthRef: vault-auth

# VaultDynamicSecret — 동적 Secret (TTL 기반 자동 갱신)
apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultDynamicSecret
metadata:
  name: db-dynamic-creds
  namespace: production
spec:
  mount: database
  path: creds/production-readonly
  destination:
    name: db-dynamic-credentials
    create: true
  renewalPercent: 67           # TTL의 67% 지점에서 갱신
  vaultAuthRef: vault-auth

8.2 Vault Agent Injector 방식

Pod에 annotation을 추가하면 Vault Agent가 sidecar로 주입되어 Secret을 파일로 제공합니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: production
spec:
  template:
    metadata:
      annotations:
        vault.hashicorp.com/agent-inject: "true"
        vault.hashicorp.com/role: "production-app"
        vault.hashicorp.com/agent-inject-secret-db-creds: "secret/data/production/db-creds"
        vault.hashicorp.com/agent-inject-template-db-creds: |
          {{- with secret "secret/data/production/db-creds" -}}
          export DB_USER="{{ .Data.data.username }}"
          export DB_PASS="{{ .Data.data.password }}"
          {{- end }}
    spec:
      serviceAccountName: app-sa
      containers:
        - name: app
          image: my-app:1.0
          # Secret은 /vault/secrets/db-creds 파일로 마운트됨

8.3 trade-off

장점	단점
동적 Secret으로 자동 로테이션 가능	Vault 자체의 운영 부담 (HA, unseal, 백업)
세밀한 접근 정책 (Policy, AppRole)	러닝 커브가 높음
감사 로그 내장	추가 인프라 비용 (Vault 클러스터)
다양한 Secret Engine (DB, PKI, AWS 등)	단일 장애점(SPOF) 위험 (HA 필수)

Tip
Vault를 자체 운영하기 어려운 경우, HCP Vault(HashiCorp Cloud Platform)나 클라우드 네이티브 Secret 관리 서비스(AWS Secrets Manager, Azure Key Vault)를 External Secrets Operator로 연동하는 방식이 운영 부담을 줄일 수 있습니다.

9. 실무 시나리오: 스타트업 프로덕션 환경 설계

시나리오

팀원 10명의 스타트업에서 EKS 클러스터를 운영합니다. 데이터베이스 비밀번호, 외부 API 키, TLS 인증서를 관리해야 합니다. GitOps(Argo CD)를 사용 중이며, Secret을 Git에 저장하면 안 됩니다.

요구사항

Secret이 Git 리포지토리에 노출되면 안 됨
Secret 변경 시 Pod 재시작 없이 반영되면 좋음
운영 부담이 적어야 함 (Vault 자체 운영은 부담)
AWS 서비스를 이미 사용 중

설계 결정

결정	이유	대안
External Secrets Operator 채택	AWS Secrets Manager와 직접 연동, Vault 운영 불필요	Sealed Secrets (동기화/갱신 미지원)
IRSA로 인증	IAM Role을 ServiceAccount에 직접 연결, 키 관리 불필요	Access Key 사용 (보안 위험)
refreshInterval: 1h 설정	Secret 변경 시 1시간 내 자동 반영	수동 `kubectl rollout restart`
EKS Secret 암호화 활성화	KMS로 etcd 암호화, 추가 비용 최소	기본 설정 유지 (보안 위험)

구현

# 1. IRSA용 ServiceAccount
apiVersion: v1
kind: ServiceAccount
metadata:
  name: external-secrets-sa
  namespace: production
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/ExternalSecretsRole

# 2. ClusterSecretStore (모든 네임스페이스에서 재사용)
apiVersion: external-secrets.io/v1beta1
kind: ClusterSecretStore
metadata:
  name: aws-secrets-manager
spec:
  provider:
    aws:
      service: SecretsManager
      region: ap-northeast-2
      auth:
        jwt:
          serviceAccountRef:
            name: external-secrets-sa
            namespace: production

# 3. ExternalSecret (Git에 이것만 커밋)
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: app-secrets
  namespace: production
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: aws-secrets-manager
    kind: ClusterSecretStore
  target:
    name: app-secrets
  data:
    - secretKey: DB_PASSWORD
      remoteRef:
        key: production/app/db
        property: password
    - secretKey: API_KEY
      remoteRef:
        key: production/app/external-api
        property: key

이 구성에서 Git에 저장되는 것은 ExternalSecret YAML뿐입니다. 실제 Secret 값은 AWS Secrets Manager에만 존재하고, ESO가 클러스터에 동기화합니다.

10. Pod에서 Secret을 안전하게 사용하기

Secret을 Pod에 주입하는 방법은 두 가지입니다: 환경 변수(env)와 볼륨 마운트(volume). 보안 관점에서 볼륨 마운트가 권장됩니다.

10.1 환경 변수 vs 볼륨 마운트

방식	장점	단점
환경 변수 (env)	코드에서 바로 접근 가능	`kubectl describe pod`로 노출, 프로세스 목록에서 보일 수 있음, Secret 변경 시 Pod 재시작 필요
볼륨 마운트 (volume)	파일 시스템 권한으로 보호, 자동 갱신 가능	파일 읽기 로직 필요

# 권장: 볼륨 마운트 방식
apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
    - name: app
      image: my-app:1.0
      volumeMounts:
        - name: secrets
          mountPath: /etc/secrets
          readOnly: true
  volumes:
    - name: secrets
      secret:
        secretName: db-credentials
        defaultMode: 0400    # 소유자만 읽기 가능

10.2 불필요한 Secret 마운트 방지

# API 접근이 불필요한 Pod에서 ServiceAccount 토큰 마운트 비활성화
apiVersion: v1
kind: Pod
metadata:
  name: simple-worker
spec:
  automountServiceAccountToken: false
  containers:
    - name: worker
      image: worker:1.0

11. 보안 체크리스트

운영 환경에서 Kubernetes Secret을 관리할 때 확인해야 하는 항목입니다.

#	항목	확인 방법
1	etcd 암호화가 활성화되어 있는가	`kubectl get secrets -o json`의 annotation 확인, 매니지드의 경우 콘솔 확인
2	Secret YAML이 Git에 커밋되어 있지 않은가	`git log --all -p -- '*.yaml' \| grep 'kind: Secret'`
3	Secret 접근 RBAC가 최소 권한인가	`kubectl auth can-i get secrets --as=<user> -n <ns>`
4	감사 로그가 Secret 접근을 기록하는가	Audit Policy에 secrets 리소스 포함 여부 확인
5	환경 변수 대신 볼륨 마운트를 사용하는가	Deployment YAML의 `envFrom` vs `volumeMounts` 확인
6	불필요한 ServiceAccount 토큰이 마운트되지 않는가	`automountServiceAccountToken: false` 확인
7	Secret 로테이션 전략이 있는가	외부 Secret 관리 도구의 refreshInterval 또는 수동 절차 확인
8	컨트롤러 키(Sealed Secrets) 또는 Vault unseal 키를 백업했는가	백업 절차 및 복구 테스트 여부 확인

12. 비용/운영 고려사항

항목	비용	운영 부담
EKS Secret 암호화 (KMS)	KMS API 호출당 $0.03/10,000건	거의 없음 (한 번 설정)
AWS Secrets Manager	Secret당 $0.40/월 + API 호출 비용	Secret 생성/갱신 관리
Azure Key Vault	표준 티어 기준 $0.03/10,000 작업	Secret 생성/갱신 관리
HashiCorp Vault (자체 운영)	인프라 비용 (EC2/EKS)	HA 구성, unseal, 백업, 업그레이드 관리
HCP Vault	월 $0.03/시간~ (인스턴스 기준)	관리형으로 운영 부담 낮음
Sealed Secrets	무료 (오픈소스)	키 백업, re-seal 관리
External Secrets Operator	무료 (오픈소스) + 외부 저장소 비용	Provider 인증 설정, 동기화 모니터링

Tip
소규모 팀에서 시작한다면 Sealed Secrets로 충분할 수 있습니다. Secret 수가 늘어나고 자동 갱신이 필요해지면 External Secrets Operator로 전환하는 단계적 접근이 실용적입니다. Vault는 동적 Secret, PKI 인증서, 데이터베이스 자격증명 자동 로테이션 등 고급 기능이 필요한 경우에 도입을 검토합니다.

13. 정리

Kubernetes Secret은 Base64 인코딩만 적용되며, 기본 설정에서는 etcd에 평문으로 저장됩니다. 단독으로는 보안 수준이 낮습니다.
저장 시 암호화(EncryptionConfiguration 또는 클라우드 KMS)를 반드시 활성화하여 etcd 수준에서 보호해야 합니다.
RBAC로 Secret 접근을 최소화하고, 감사 로그로 접근 이력을 추적합니다.
Git에 Secret을 저장하지 않기 위해 외부 Secret 관리 도구를 사용합니다. 팀 규모와 요구사항에 따라 Sealed Secrets, External Secrets Operator, HashiCorp Vault 중 선택합니다.
Pod에서는 환경 변수보다 볼륨 마운트 방식이 보안상 안전합니다. 불필요한 토큰 마운트는 비활성화합니다.
Secret 보안은 단일 도구가 아닌 여러 계층(암호화, 접근 제어, 외부 관리, 감사)의 조합으로 달성됩니다.

참고 문서

GitHub Actions와 Jenkins 차이: CI/CD 도구 선택 기준

wero90 — Mon, 8 Jun 2026 09:50:15 +0900

CI/CD 도구를 선택할 때 "Jenkins가 레거시니까 GitHub Actions로 가자"라는 판단은 위험합니다. 팀 규모, 빌드 볼륨, 보안 요구사항, 운영 역량에 따라 적합한 도구가 다릅니다. 이 글에서는 두 도구의 구조적 차이를 분석하고, 상황별 선택 기준을 정리합니다.

핵심 요약

GitHub Actions는 GitHub과 통합된 SaaS CI/CD 서비스로, 별도 인프라 운영 없이 시작할 수 있습니다.
Jenkins는 자체 호스팅 오픈소스 CI/CD 서버로, 높은 유연성과 커스터마이징이 가능하지만 운영 부담이 있습니다.
소규모 팀이 GitHub을 사용하고 있다면 GitHub Actions가 대부분 적합합니다.
빌드 볼륨이 크거나 네트워크 격리 요구사항이 있다면 Jenkins가 비용/보안 측면에서 유리할 수 있습니다.
두 도구를 조합해서 사용하는 패턴(GitHub Actions → Jenkins 배포)도 실무에서 흔합니다.

1. 왜 이 비교가 필요한가

스타트업에서 3명이 개발하다가 팀이 15명으로 성장했습니다. 기존에 GitHub Actions로 잘 돌아가던 파이프라인이 이제 문제를 보입니다.

월 CI/CD 비용이 $300을 넘어가기 시작합니다.
iOS + Android + Backend 빌드를 동시에 돌리면 무료 병렬 제한에 걸립니다.
보안 팀이 "빌드 환경에서 소스코드가 외부로 나가면 안 된다"고 요구합니다.

이때 Jenkins로의 마이그레이션을 검토하게 됩니다. 반대로, Jenkins를 5년간 운영하던 팀이 "운영 부담이 너무 크다"며 GitHub Actions로 전환을 검토하기도 합니다.

어느 쪽이 더 좋은 도구가 아니라, 어떤 상황에서 어떤 도구가 적합한지를 이해하는 것이 핵심입니다.

2. 아키텍처 비교

GitHub Actions와 Jenkins 아키텍처 비교

GitHub Actions 아키텍처

GitHub Actions는 SaaS 기반입니다. 사용자는 워크플로우 YAML 파일만 작성하면, GitHub이 Runner를 할당하고 실행합니다.

구성 요소	설명
Workflow 파일	`.github/workflows/`에 YAML로 정의
GitHub-hosted Runner	GitHub이 관리하는 일회성 VM (Ubuntu, Windows, macOS)
Self-hosted Runner	사용자가 직접 운영하는 실행 환경
Marketplace Actions	커뮤니티가 만든 재사용 가능한 액션

핵심 특징:

Ephemeral: 매 실행마다 깨끗한 VM이 할당되고, 실행 후 삭제됩니다. 빌드 간 오염이 없습니다.
관리 부담 최소: Runner 운영, 보안 패치, 스케일링을 GitHub이 처리합니다.
GitHub 종속: GitHub 저장소 외에서는 사용할 수 없습니다.

Jenkins 아키텍처

Jenkins는 Self-hosted 오픈소스입니다. 사용자가 직접 Jenkins Controller와 Agent를 운영합니다.

구성 요소	설명
Controller	작업 스케줄링, UI, 설정 관리 (Master)
Agent (Node)	실제 빌드를 실행하는 워커
Plugin	1,800개 이상의 확장 플러그인
Jenkinsfile	Pipeline을 코드로 정의 (Groovy DSL)

핵심 특징:

완전한 통제: 네트워크, 스토리지, 보안 정책을 직접 설계합니다.
높은 유연성: 어떤 SCM, 어떤 클라우드, 어떤 배포 대상이든 플러그인으로 연동 가능합니다.
운영 부담: Controller 가용성, Agent 스케일링, 플러그인 업데이트, 보안 패치를 직접 해야 합니다.

구조적 차이 요약

비교 항목	GitHub Actions	Jenkins
호스팅	SaaS (GitHub 관리)	Self-hosted (직접 운영)
실행 환경	Ephemeral VM (매번 새로 생성)	Persistent Agent (상시 실행)
설정 방식	YAML	Groovy DSL (Jenkinsfile)
확장성	Marketplace Actions	Plugins (1,800+)
SCM 연동	GitHub 전용	Git, SVN, Mercurial 등 다양
관리 대상	Workflow 파일만	Controller + Agent + Plugin + 인프라

3. 워크플로우 비교

GitHub Actions와 Jenkins 워크플로우 비교

같은 작업(빌드 → 테스트 → 배포)을 두 도구에서 어떻게 정의하는지 비교합니다.

GitHub Actions

name: CI/CD Pipeline
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run build

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

  deploy:
    needs: test
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Deploy to ECS
        run: aws ecs update-service --cluster prod --service api --force-new-deployment

특징:

on 블록으로 트리거를 선언적으로 정의합니다.
needs로 Job 간 의존성을 설정합니다.
environment로 배포 보호 규칙(수동 승인)을 적용합니다.
Marketplace Action을 uses로 간단히 가져다 씁니다.

Jenkins (Declarative Pipeline)

pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                sh 'npm ci'
                sh 'npm run build'
            }
        }

        stage('Test') {
            steps {
                sh 'npm test'
            }
        }

        stage('Deploy') {
            when {
                branch 'main'
            }
            input {
                message "프로덕션에 배포하시겠습니까?"
                ok "Deploy"
            }
            steps {
                sh 'aws ecs update-service --cluster prod --service api --force-new-deployment'
            }
        }
    }

    post {
        failure {
            slackSend channel: '#alerts', message: "빌드 실패: ${env.JOB_NAME}"
        }
    }
}

특징:

Groovy DSL로 작성합니다. 프로그래밍 언어이므로 조건부 로직, 반복, 함수 정의가 자유롭습니다.
input 블록으로 수동 승인을 구현합니다.
post 블록으로 성공/실패 후 처리를 정의합니다.
커스텀 로직이 복잡해질수록 Jenkins가 유리합니다. 다만 Groovy 학습 곡선이 있습니다.

워크플로우 정의 방식 비교

항목	GitHub Actions	Jenkins
언어	YAML (선언적)	Groovy DSL (프로그래밍 가능)
학습 곡선	낮음	중간~높음
조건부 로직	`if` 표현식 (제한적)	Groovy 문법으로 자유롭게
재사용	Reusable Workflow, Composite Action	Shared Library
트리거	`on` 블록 (push, PR, schedule 등)	Webhook, Poll SCM, Cron, Upstream Job
수동 승인	Environment Protection Rules	`input` 블록
병렬 실행	`matrix` 전략	`parallel` 블록

Tip
GitHub Actions의 YAML은 단순한 파이프라인에서 빠르게 작성할 수 있지만, 조건 분기가 복잡해지면 가독성이 떨어집니다. Jenkins의 Groovy는 반대로 초기 학습이 필요하지만, 복잡한 로직을 깔끔하게 표현할 수 있습니다. 파이프라인 복잡도가 판단 기준입니다.

4. 비용 비교

GitHub Actions와 Jenkins 비용 구조 비교

비용 구조가 근본적으로 다릅니다. GitHub Actions는 사용량 기반, Jenkins는 인프라 고정 비용입니다.

GitHub Actions 비용

항목	가격 (2026년 기준)
Public 저장소	무제한 무료
Private 저장소 (Free 플랜)	2,000분/월 무료
Private 저장소 (Team 플랜)	3,000분/월 무료
추가 사용량 (Linux)	$0.006/분
추가 사용량 (Windows)	$0.010/분
추가 사용량 (macOS)	$0.048/분
Self-hosted Runner	무료 (인프라 비용만)

2026년 1월 가격 인하가 적용된 기준입니다. 최신 가격은 GitHub Actions 가격 페이지에서 확인할 수 있습니다.

Jenkins 비용

항목	예상 비용
소프트웨어 라이선스	무료 (오픈소스)
Controller 서버	$50~200/월 (EC2 t3.large 기준)
Agent 서버 (2~4대)	$100~400/월
스토리지 (빌드 아티팩트)	$20~50/월
운영 인력	DevOps 엔지니어 인건비의 일부
총 인프라 비용	$180~680/월 (규모에 따라)

비용 시나리오 비교

시나리오 A: 소규모 팀 (5명, 일 5회 빌드, 빌드당 10분)

GitHub Actions: 월 약 1,500분 → Free 플랜(2,000분)으로 충분 → $0
Jenkins: Controller + Agent 최소 구성 → $180+/월

시나리오 B: 중규모 팀 (20명, 일 30회 빌드, 빌드당 15분)

GitHub Actions: 월 약 9,000분 → Team 플랜(3,000분) + 초과 6,000분 × $0.006 → 약 $36/월 + Team 플랜 비용
Jenkins: 고성능 Controller + Agent 3대 → 약 $400/월 (고정)

시나리오 C: 대규모 팀 (50명, 일 100회 빌드, 빌드당 20분)

GitHub Actions: 월 약 40,000분 → 초과 37,000분 × $0.006 → 약 $222/월 (Linux 기준)
Jenkins: Agent 6대 + 고가용성 구성 → 약 $680/월 (고정)

다만 시나리오 C에서 macOS 빌드가 포함되면 GitHub Actions 비용이 증가합니다. macOS 빌드가 월 5,000분이면 추가 $240이 발생합니다.

비용 판단 기준
단순히 금액만 비교하면 안 됩니다. Jenkins의 "운영 인력 비용"은 표에 포함되지 않습니다. DevOps 엔지니어가 Jenkins 관리에 주당 4시간을 쓴다면, 그 인건비를 고려해야 합니다. 반대로 GitHub Actions는 Self-hosted Runner를 사용하면 분당 비용을 제거할 수 있지만, Runner 관리 부담이 발생합니다.

5. 운영 부담 비교

운영 영역	GitHub Actions	Jenkins
초기 설정	YAML 파일 작성 (30분~)	서버 프로비저닝 + Jenkins 설치 + 플러그인 설정 (반나절~)
보안 패치	GitHub이 Runner에 자동 적용	직접 Jenkins + OS + 플러그인 업데이트
스케일링	자동 (GitHub이 Runner 할당)	Agent 수동 추가 또는 Auto Scaling 구성 필요
가용성	GitHub SLA (99.9%)	직접 이중화, 백업, 모니터링 구성
플러그인 관리	Marketplace (버전 고정)	호환성 충돌 직접 관리 (가장 큰 운영 부담)
디버깅	GitHub UI에서 로그 확인	Controller/Agent 로그 직접 분석
백업/복구	불필요 (Workflow는 Git에 저장)	Jenkins Home 디렉토리 정기 백업 필요

Jenkins 운영에서 자주 발생하는 문제

플러그인 충돌: A 플러그인을 업데이트하면 B 플러그인이 깨집니다. 의존성 관계가 복잡해질수록 업데이트가 두려워집니다.
Controller 다운: Jenkins Controller가 죽으면 모든 빌드가 중단됩니다. HA 구성이 없으면 단일 장애점입니다.
Agent 디스크 부족: 빌드 아티팩트와 Docker 이미지가 누적되어 디스크가 가득 찹니다. 정기 정리 크론잡이 필요합니다.
Groovy 보안 이슈: Pipeline에서 실행되는 Groovy 코드는 Controller에서 실행될 수 있어 Script Security 설정이 필요합니다.

GitHub Actions 운영에서 주의할 점

비용 예측 어려움: 빌드 횟수와 시간에 따라 비용이 변동합니다. 갑자기 PR이 많아지면 예상 외 비용이 발생합니다.
GitHub 장애 영향: GitHub에 장애가 나면 CI/CD도 멈춥니다. 2023-2024년에도 수 차례 장애가 있었습니다.
Workflow 복잡도 한계: 200줄 이상의 Workflow는 가독성이 급격히 떨어집니다. Reusable Workflow로 분리해야 합니다.
Self-hosted Runner 보안: PR 이벤트에서 Self-hosted Runner를 사용하면 외부 기여자의 악성 코드가 내부 네트워크에서 실행될 수 있습니다.

6. 보안 비교

Security Note
CI/CD 도구는 소스코드, 인프라 자격 증명, 프로덕션 배포 권한에 접근합니다. 도구의 보안 모델을 이해하지 않으면 공급망 공격의 진입점이 될 수 있습니다.

보안 항목	GitHub Actions	Jenkins
Secret 저장	GitHub Secrets (암호화)	Credentials Plugin (Jenkins 내부 암호화)
네트워크 격리	GitHub-hosted Runner는 공용 네트워크	완전한 네트워크 통제 가능
코드 실행 환경	Ephemeral (매번 삭제) → 잔존 데이터 없음	Persistent Agent → 빌드 간 데이터 잔존 가능
공급망 보안	Action SHA 고정으로 완화	Plugin 서명 검증 가능 (제한적)
감사 로그	GitHub Audit Log (Enterprise)	별도 구성 필요
접근 제어	Repository/Organization 권한 기반	Jenkins 자체 RBAC + LDAP/SAML 연동

보안 관점 선택 기준

GitHub Actions가 적합한 경우:

오픈소스 프로젝트나 코드가 공개되어도 되는 서비스
빌드 환경의 격리(Ephemeral VM)가 중요한 경우
Secret 관리를 단순화하고 싶은 경우 (GitHub Secrets + OIDC)

Jenkins가 적합한 경우:

소스코드가 외부 서버로 나가면 안 되는 규제 환경 (금융, 의료, 공공)
빌드 네트워크를 VPC 내부로 완전히 격리해야 하는 경우
사내 인증 시스템(LDAP, AD)과 통합해야 하는 경우
세밀한 권한 분리가 필요한 대규모 조직

7. 실무 선택 시나리오

시나리오 1: GitHub Actions 선택이 적합한 경우

상황: SaaS 서비스를 개발하는 8명 팀. GitHub을 사용하고, AWS에 배포합니다. 별도 DevOps 엔지니어 없이 백엔드 개발자가 CI/CD를 관리합니다.

선택 근거:

별도 인프라 운영 인력이 없으므로 SaaS가 적합합니다.
GitHub에 이미 코드가 있으므로 통합이 자연스럽습니다.
월 빌드량이 Free/Team 플랜으로 커버됩니다.
OIDC로 AWS 인증을 구성하면 장기 자격 증명이 불필요합니다.

주의할 점:

macOS 빌드가 필요하면 Self-hosted Runner를 검토합니다.
팀이 20명 이상으로 성장하면 비용 구조를 재검토합니다.

시나리오 2: Jenkins 선택이 적합한 경우

상황: 금융 서비스를 운영하는 40명 팀. BitBucket을 사용하고, 온프레미스 + AWS 하이브리드 환경입니다. 전담 DevOps 팀(3명)이 있습니다.

선택 근거:

BitBucket을 사용하므로 GitHub Actions를 쓸 수 없습니다.
소스코드가 내부 네트워크 밖으로 나가면 안 되는 규제가 있습니다.
온프레미스 + 클라우드 하이브리드 배포가 필요합니다.
전담 DevOps 팀이 Jenkins를 운영할 역량이 있습니다.
빌드 볼륨이 높아 고정 비용 모델이 유리합니다.

주의할 점:

Jenkins Controller HA 구성을 반드시 설계합니다.
플러그인 업데이트 정책(월 1회 등)을 정합니다.
Configuration as Code(JCasC) 플러그인으로 설정을 코드화합니다.

시나리오 3: 하이브리드 사용

상황: 15명 팀이 GitHub을 사용하지만, 특정 빌드는 내부 GPU 서버에서 실행해야 합니다.

구성:

CI(빌드, 테스트, 보안 스캔): GitHub Actions (GitHub-hosted Runner)
ML 모델 학습/빌드: Jenkins (내부 GPU Agent)
배포: GitHub Actions (Self-hosted Runner를 VPC 내부에 배치)

이렇게 강점을 조합하는 패턴도 실무에서 흔합니다. GitHub Actions에서 Jenkins 빌드를 트리거하거나, 반대로 Jenkins에서 GitHub API를 호출하는 방식으로 연동합니다.

8. 마이그레이션 고려사항

Jenkins → GitHub Actions 전환 시

고려사항	설명
Shared Library	Reusable Workflow 또는 Composite Action으로 재작성
Jenkinsfile 변환	YAML로 수동 전환 (자동 변환 도구는 제한적)
플러그인 대체	Marketplace에서 대응하는 Action 확인
Secret 마이그레이션	GitHub Secrets 또는 외부 Secret Manager로 이전
점진적 전환	신규 프로젝트부터 GitHub Actions 적용, 기존은 유지

GitHub Actions → Jenkins 전환 시

고려사항	설명
인프라 준비	Controller + Agent 서버 프로비저닝
운영 체계	모니터링, 백업, 보안 패치 프로세스 수립
YAML → Groovy	Declarative Pipeline 구문으로 변환
트리거 설정	GitHub Webhook 또는 Generic Webhook Trigger 플러그인
팀 교육	Groovy 기본 문법, Jenkins 관리 UI 교육

Tip
마이그레이션은 "빅뱅" 방식보다 점진적 전환이 안전합니다. 신규 서비스부터 새 도구를 적용하고, 안정성이 검증되면 기존 서비스를 순차적으로 전환하는 방식을 권장합니다. 양쪽을 동시에 운영하는 기간이 발생하지만, 전환 실패 시 롤백이 쉽습니다.

9. 종합 비교 테이블

비교 기준	GitHub Actions	Jenkins
호스팅	SaaS	Self-hosted
초기 설정 시간	30분	반나절~
운영 부담	낮음	높음
유연성	중간	매우 높음
학습 곡선	낮음 (YAML)	중간 (Groovy)
비용 모델	사용량 기반 (분당 과금)	고정 비용 (인프라)
소규모 팀	✅ 적합	❌ 과도함
대규모 팀	△ 비용 증가	✅ 규모의 경제
네트워크 격리	Self-hosted Runner 필요	기본 제공
SCM 종속	GitHub 전용	무관
플러그인/확장	Marketplace (17,000+ Actions)	Plugins (1,800+)
커뮤니티	빠르게 성장 중	성숙, 안정적

10. 선택 의사결정 플로우

팀 상황에 따른 선택 기준을 정리합니다.

1단계: SCM 확인

GitHub을 사용하고 있다면 → GitHub Actions를 우선 검토
GitLab을 사용한다면 → GitLab CI를 우선 검토
BitBucket이나 다른 SCM을 사용한다면 → Jenkins 또는 해당 SCM의 CI 도구 검토

2단계: 보안 요구사항 확인

소스코드가 외부로 나가면 안 된다 → Jenkins (또는 Self-hosted Runner)
네트워크 격리가 필수다 → Jenkins
특별한 보안 요구사항이 없다 → GitHub Actions

3단계: 운영 역량 확인

전담 DevOps 팀이 있다 → Jenkins 운영 가능
개발자가 CI/CD를 겸임한다 → GitHub Actions (운영 부담 최소화)

4단계: 비용 비교

월 빌드량이 2,000분 이하 → GitHub Actions (무료)
월 빌드량이 높고 macOS 빌드가 많다 → Jenkins (고정 비용이 유리)
빌드량이 변동이 심하다 → GitHub Actions (사용한 만큼만 과금)

11. 정리

GitHub Actions는 "시작이 빠르고 운영 부담이 적은" SaaS CI/CD입니다. GitHub을 사용하는 소규모~중규모 팀에 적합합니다.
Jenkins는 "유연성과 통제력이 높은" Self-hosted CI/CD입니다. 대규모 조직, 규제 환경, 복잡한 파이프라인에 적합합니다.
도구 선택은 "팀 규모 × 빌드 볼륨 × 보안 요구사항 × 운영 역량"의 조합으로 결정합니다.
하나를 선택해야 하는 것이 아닙니다. 강점을 조합하는 하이브리드 패턴도 실무에서 흔합니다.
"Jenkins가 레거시"라는 인식은 오해입니다. 2026년 현재에도 대규모 조직에서 활발히 사용되고 있습니다. 중요한 것은 도구의 나이가 아니라 팀 상황과의 적합성입니다.