김신건의 로그 - 위키 / devops

Shell Script: bash 기본과 실전 패턴

koa (김신건) — Mon, 29 Jun 2026 00:00:00 GMT

정의

Shell Script 는 shell (bash, zsh, sh) 커맨드를 파일로 저장하여 자동화하는 스크립트. DevOps, CI/CD, sysadmin 필수.

안전한 시작

#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'

-e: 명령 실패 시 즉시 종료
-u: 정의 안 된 변수 참조 시 오류
-o pipefail: pipe 안의 실패도 캐치
IFS: 안전한 word splitting

변수

name="Alice"
echo "Hello, $name"
echo "Hello, ${name}"

# 기본값
echo "${port:-8080}"           # $port 없으면 8080

# 필수
echo "${API_KEY:?required}"    # 없으면 error message

# 배열
arr=(a b c)
echo "${arr[0]}"
echo "${arr[@]}"

조건과 반복

if [[ -f "$file" ]]; then
    echo "exists"
fi

if [[ "$env" == "prod" ]]; then
    ...
elif [[ "$env" == "dev" ]]; then
    ...
fi

for f in *.log; do
    echo "$f"
done

while read -r line; do
    echo "$line"
done < input.txt

함수

greet() {
    local name="$1"
    echo "Hello, $name"
}

greet "World"

에러 처리

trap 'cleanup' EXIT ERR INT TERM

cleanup() {
    rm -f "$temp_file"
}

# 특정 명령 실패 허용
some_command || true

실전 패턴

stdin/stdout 처리

cat file.txt | grep pattern | wc -l
grep pattern < file.txt
grep pattern file.txt > out.txt 2>&1

인자 파싱

while getopts "hi:o:" opt; do
    case $opt in
        h) echo "usage: ..." ;;
        i) input="$OPTARG" ;;
        o) output="$OPTARG" ;;
        *) exit 1 ;;
    esac
done

함정

quoting: $var 는 항상 "$var" (공백 처리)
[ vs [[: bash 는 [[ 가 안전 (short-circuit, no word splitting)
backtick vs $(): $( ) 가 nesting 가능
subshell: ( ) 안 변경은 밖에 반영 안 됨

참고

[[bash-arrays|Bash Arrays]]
[[shell-pipeline|Shell Pipeline]]

[CI/CD] GitHub Actions: workflow, action, runner

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

GitHub Actions = GitHub 내장 CI/CD. YAML workflow + marketplace action. 2018 출시 → Travis CI 대체.

구조

flowchart TB
    Trigger[Trigger<br/>push, PR, schedule, ...] --> WF[Workflow]
    WF --> Job1["Job 1<br/>(runner)"]
    WF --> Job2[Job 2]
    Job1 --> Step1["Step 1 (action 또는 script)"]
    Job1 --> Step2[Step 2]

Workflow YAML

name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123:role/gh-deploy
          aws-region: us-east-1
      - run: aws s3 sync ./dist s3://my-bucket

Trigger 종류

Trigger	의미
`push`	branch / tag push
`pull_request`	PR open / sync
`schedule`	cron
`workflow_dispatch`	수동 실행
`workflow_call`	다른 workflow 가 호출
`repository_dispatch`	외부 API
`release`	release published
`issue_comment`	comment

Runner

종류	의미
GitHub-hosted	Ubuntu/Windows/macOS, 매번 fresh
Self-hosted	자체 VM, 빠름, 보안 책임
Larger runners	GitHub-hosted 의 강한 사양
ARC (Actions Runner Controller)	K8s 위 self-hosted

Marketplace Action

- uses: actions/checkout@v4
- uses: actions/setup-python@v5
  with: { python-version: '3.13' }
- uses: docker/build-push-action@v6
- uses: actions/cache@v4
- uses: aws-actions/configure-aws-credentials@v4

OIDC + AWS (long-term key 없이)

자세한 건 [[aws-sts-assume-role]] 의 OIDC.

permissions:
  id-token: write
steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123:role/gh-deploy
      aws-region: us-east-1

Matrix Build

strategy:
  fail-fast: false
  matrix:
    os: [ubuntu-latest, macos-latest]
    node: [20, 22]
    include:
      - os: ubuntu-latest
        node: 22
        coverage: true
    exclude:
      - os: macos-latest
        node: 20

N × M 조합 자동 실행.

Reusable Workflow

# .github/workflows/reusable-deploy.yml
on:
  workflow_call:
    inputs:
      env:
        required: true
        type: string

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps: [...]

# 호출
jobs:
  call:
    uses: ./.github/workflows/reusable-deploy.yml
    with: { env: prod }

Composite Action

action.yml:

name: 'Setup Node + cache'
runs:
  using: 'composite'
  steps:
    - uses: actions/setup-node@v4
    - uses: actions/cache@v4
    - run: npm ci
      shell: bash

보안

✓ PR fork 의 secret 노출 방지 (pull_request_target 주의)
✓ Action SHA pinning (uses: actions/checkout@<sha>)
✓ OIDC (long-term key 회피)
✓ Permissions 최소화 (permissions: 명시)
✓ Secrets 환경 분리 (environment)

흔한 함정

[!WARNING]

pull_request_target + checkout PR code = 코드 인젝션 가능. PR 의 코드는 pull_request 만.

Long-term AWS key = 누출 위험. OIDC 권장.

uses: action@main = action 변경에 영향 받음. SHA pinning.

Self-hosted runner 의 fork PR = 임의 코드 실행. fork 차단 또는 GitHub-hosted.

[GitOps] ArgoCD: Kubernetes GitOps

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

ArgoCD = Kubernetes 의 GitOps 컨트롤러. Git 리포지토리의 manifest 가 source of truth → cluster 가 자동 동기화.

GitOps 원칙

flowchart LR
    Dev[Dev] -->|commit / PR| Git["Git repo<br/>(manifest)"]
    Git --> ArgoCD[ArgoCD]
    ArgoCD -->|continuously sync| Cluster[K8s Cluster]
    Cluster -->|state| Compare
    Git -->|desired| Compare
    Compare -->|drift| ArgoCD

원칙	의미
Git = source of truth	모든 변경 이 git 으로
Declarative	YAML / Helm / Kustomize
Auto-sync	git 변경 → cluster 자동 적용
Auto-healing	manual 변경도 git 으로 복구
Observable	UI / API 로 항상 상태 가시

Application 정의

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/manifests
    targetRevision: main
    path: apps/web/overlays/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: web
  syncPolicy:
    automated:
      prune: true       # git 에서 제거된 자원 → 삭제
      selfHeal: true    # 수동 변경 → git 으로 복구
    syncOptions:
      - CreateNamespace=true

동작

sequenceDiagram
    Dev->>Git: commit manifest 변경
    loop 매 3분 (또는 webhook)
        ArgoCD->>Git: pull
    end
    ArgoCD->>Cluster: compare desired vs actual
    alt drift
        ArgoCD->>Cluster: kubectl apply
    end
    ArgoCD-->>Dev: UI 에 sync status

App of Apps 패턴

flowchart TB
    Root[Root Application] --> App1[App: web]
    Root --> App2[App: api]
    Root --> App3[App: worker]
    Root --> App4[App: redis]

Application 자체를 git 에서 관리. 새 service 추가 = git PR 만.

ApplicationSet

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata: { name: cluster-bootstrap }
spec:
  generators:
    - clusters: {}    # 모든 등록된 cluster
  template:
    metadata: { name: '{{name}}-monitoring' }
    spec:
      source:
        repoURL: ...
        path: 'clusters/{{name}}/monitoring'
      destination:
        server: '{{server}}'

수많은 cluster / namespace 에 동일 app 자동 배포.

ArgoCD vs Flux

항목	ArgoCD	Flux
UI	강력	없음 (Weave GitOps UI 별도)
학습 곡선	중간	낮음
단순성	중간	높음
Multi-tenancy	강	보통
Notification	built-in	Alertmanager 통합

2026 시점 ArgoCD 가 더 인기. UI + 다양 source (Helm, Kustomize, Jsonnet, …).

Argo Rollouts (Progressive Delivery)

apiVersion: argoproj.io/v1alpha1
kind: Rollout
metadata: { name: web }
spec:
  replicas: 10
  strategy:
    canary:
      steps:
        - setWeight: 10
        - pause: { duration: 5m }
        - setWeight: 30
        - pause: { duration: 5m }
        - setWeight: 50
        - pause: { duration: 10m }
        - setWeight: 100
      analysis:
        templates:
          - templateName: success-rate

progressive rollout + 자동 metric 분석 + 실패 시 자동 롤백.

CI/CD 분리 (Push vs Pull)

flowchart LR
    subgraph "Push-based (옛)"
        CI1[CI] -->|kubectl apply| Cluster1
    end
    subgraph "Pull-based (GitOps)"
        CI2[CI] -->|update manifest| Git
        Argo[ArgoCD] -->|pull + apply| Cluster2
    end

Pull (GitOps)	Push
안전 (cluster credential 외부 없음)	CI 가 cluster 접근
자동 복구	한 번 실행 후 끝
감사 (git log)	CI history
다중 cluster 쉬움	어렵

흔한 함정

[!WARNING]

수동 kubectl apply = ArgoCD 가 git 으로 복구. 모든 변경은 git PR.

Secret 의 git 평문 = SOPS / Sealed Secrets / External Secrets.

거대한 단일 App = 부분 sync 어려움. 작은 App 으로.

Webhook 미설정 = 3분 polling 지연. GitHub webhook 권장.

[GitOps] 패턴: 단일 vs 다중 repo, environment promotion

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

GitOps 4가지 원칙 (OpenGitOps)

Declarative: 시스템 원하는 상태 가 선언적 (YAML).
Versioned and Immutable: Git 으로 버전 + 불변.
Pulled Automatically: 시스템이 자동 fetch + apply.
Continuously Reconciled: 지속적 desired vs actual 비교 + 수정.

Repo 구조 패턴

flowchart TD
    Q{Repo 구조}
    Q --> Mono[Monorepo<br/>app + manifest 함께]
    Q --> Two[2-repo<br/>app code / manifest 분리]
    Q --> Multi[Multi-repo<br/>app / manifest / infra 각자]

1. Monorepo (app + manifest)

my-repo/
├── src/         (app code)
├── k8s/         (manifest)
└── .github/workflows/

장점: 단순. 단점: app PR 이 인프라 변경 동시 일으킴 → 위험.

2. 2-repo (권장)

app-repo/
├── src/
└── .github/workflows/
    └── build.yml (image push to ECR)

manifest-repo/
├── apps/
│   └── web/
│       └── deployment.yaml (image: ...:abc123)
└── argocd/
    └── applications.yaml

CI 가 새 image → manifest repo 의 yaml 의 image tag 자동 update → ArgoCD 가 cluster 동기화.

3. Multi-repo

각 app, 각 component, 각 cluster 별 repo. 큰 조직.

Environment Promotion

flowchart LR
    Dev[dev branch] -->|PR| Stage[stage branch]
    Stage -->|PR| Prod[prod branch]
    Argo_Dev[ArgoCD dev cluster] -.watch.-> Dev
    Argo_Stage -.watch.-> Stage
    Argo_Prod -.watch.-> Prod

또는 디렉토리 분리:

manifests/
├── overlays/
│   ├── dev/      → dev cluster
│   ├── stage/    → stage cluster
│   └── prod/     → prod cluster
└── base/         → 공통

Kustomize + ArgoCD app 별 path 분리.

Image Updater

flowchart LR
    CI -->|push| Registry[(Container Registry)]
    Updater[ArgoCD Image Updater<br/>또는 Renovate] -.poll.-> Registry
    Updater -->|PR / commit| Manifest[manifest repo]
    Argo -->|sync| Cluster

도구	의미
ArgoCD Image Updater	tag 정책 기반 자동
Renovate	dependency 갱신 PR
Flux Image Automation	Flux 내장

Secret 처리 (git 안전)

flowchart TD
    Q[Secret 처리]
    Q --> Sealed[Sealed Secrets]
    Q --> ESO[External Secrets Operator]
    Q --> SOPS[SOPS + KMS]
    Q --> Vault[Vault Agent / CSI]

자세한 건 [[k8s-configmap-secret]].

Multi-cluster GitOps

flowchart LR
    Git[Manifest repo]
    Git --> Argo1[ArgoCD on cluster-dev]
    Git --> Argo2[ArgoCD on cluster-prod-us]
    Git --> Argo3[ArgoCD on cluster-prod-eu]
    Argo1 --> ClusterDev
    Argo2 --> ProdUS
    Argo3 --> ProdEU

또는 중앙 ArgoCD + 다중 cluster credential:

apiVersion: v1
kind: Secret
type: stringData:
  name: prod-us-cluster
  server: https://k8s.prod-us.example.com
  config: |
    { "bearerToken": "..." }

Drift Detection

상황	ArgoCD 동작
수동 `kubectl edit`	Out of Sync 표시 + selfHeal 시 자동 복구
Git update	Sync 트리거
Image tag 변경	Image Updater 가 manifest commit

흔한 함정

[!WARNING]

수동 hotfix = git 우회. 항상 git 으로.

Branch 정책 부재 = main 직접 push. PR + 리뷰 + branch protection.

모든 cluster 같은 manifest = 환경별 차이 못 표현. Kustomize / Helm values.

거대한 PR = ArgoCD 가 한 번에 모든 변경 적용. 작은 PR 권장.

[Observability] OpenTelemetry: 표준화된 trace/metric/log

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

OpenTelemetry (OTel) = observability 의 vendor-neutral 표준. CNCF. trace + metric + log 의 SDK + protocol (OTLP) + collector. 2019 출범 (OpenTracing + OpenCensus 합병).

3 signal

flowchart LR
    OTel[OpenTelemetry]
    OTel --> T[Trace]
    OTel --> M[Metric]
    OTel --> L[Log]
    T --> Span["Distributed span tree"]
    M --> Hist["Counter, Gauge, Histogram"]
    L --> Structured["Structured log + trace context"]

아키텍처

flowchart LR
    App[App + OTel SDK] -->|OTLP gRPC/HTTP| Coll[OTel Collector]
    Coll --> Jaeger[Jaeger / Tempo]
    Coll --> Prom[Prometheus / Mimir]
    Coll --> Loki[Loki / ELK]
    Coll --> DD[Datadog]
    Coll --> NR[New Relic]

Vendor lock-in 없음. SDK 는 표준. 어떤 backend 라도 collector 가 라우팅.

Trace = Span Tree

flowchart TB
    R["Root span: HTTP GET /api/order/42"]
    R --> A["Span: auth.verify (15ms)"]
    R --> B["Span: db.query orders (50ms)"]
    R --> C["Span: db.query items (40ms)"]
    R --> D["Span: payment.charge (200ms)"]
    D --> E["Span: stripe.api (180ms)"]

각 span:

{
  "traceId": "abc123...",
  "spanId": "def456",
  "parentSpanId": "xyz789",
  "name": "db.query",
  "kind": "CLIENT",
  "startTime": "...",
  "endTime": "...",
  "attributes": {
    "db.statement": "SELECT * FROM orders WHERE id=?",
    "db.system": "postgresql"
  },
  "events": [...],
  "status": { "code": "OK" }
}

Context Propagation (W3C)

traceparent: 00-abc123def456789...-1111222233334444-01
tracestate: vendor1=value1,vendor2=value2

모든 HTTP 호출에 traceparent 헤더. 다른 service 가 같은 trace 의 child span 생성.

Auto-instrumentation

# Java agent (코드 변경 없이)
java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.service.name=order-service \
  -Dotel.exporter.otlp.endpoint=http://collector:4317 \
  -jar app.jar

# Python
opentelemetry-instrument --traces_exporter otlp python app.py

# Node
NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register" \
OTEL_SERVICE_NAME=order-service \
node app.js

코드 1 줄 변경 없이 HTTP/gRPC/DB 호출이 자동 instrumented.

Manual Instrumentation


const tracer = trace.getTracer('my-service');

async function processOrder(orderId: string) {
  const span = tracer.startSpan('processOrder', {
    attributes: { 'order.id': orderId },
  });
  try {
    const order = await fetchOrder(orderId);
    span.setAttribute('order.total', order.total);
    await charge(order);
    span.setStatus({ code: SpanStatusCode.OK });
  } catch (e) {
    span.recordException(e);
    span.setStatus({ code: SpanStatusCode.ERROR });
    throw e;
  } finally {
    span.end();
  }
}

OTel Collector

receivers:
  otlp:
    protocols:
      grpc:
      http:
  prometheus:
    config:
      scrape_configs: [...]

processors:
  batch:
  memory_limiter:
  attributes:
    actions:
      - key: env
        value: prod
        action: insert

exporters:
  otlp/jaeger:
    endpoint: jaeger:4317
  prometheus:
    endpoint: 0.0.0.0:8889
  loki:
    endpoint: http://loki:3100/loki/api/v1/push

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, attributes]
      exporters: [otlp/jaeger]
    metrics:
      receivers: [otlp, prometheus]
      processors: [batch]
      exporters: [prometheus]
    logs:
      receivers: [otlp]
      exporters: [loki]

Sampling

flowchart TD
    Q[Sampling 종류]
    Q --> Head[Head sampling<br/>요청 시작 시 결정]
    Q --> Tail[Tail sampling<br/>모든 span 모은 후 결정]
    Q --> Adaptive[Adaptive<br/>traffic 비례]

Head: 100% trace 보존 불가능 → 1-10%.
Tail: 에러 / 느린 trace 만 보존 → 더 의미있는 데이터.

OpenTelemetry vs Vendor

	OTel	DataDog APM	New Relic
표준	예 (CNCF)	proprietary	proprietary
Lock-in	없음	강함	강함
기능	표준 기능	advanced UI/AI	동일
가격	자체 호스팅 무료	비쌈	비쌈
추세	2026 표준	OTel 통합 진행	OTel 통합

흔한 함정

[!WARNING]

모든 trace 보존 = 비용 폭증. sampling 필수.

PII (이메일, password) 가 attribute 에 = log 노출. redact processor 필수.

Context propagation 미구현 = trace 가 service 경계에서 끊김. SDK 의 instrumentation 확인.

OTel SDK + vendor SDK 동시 사용 = 충돌. OTel only 권장.

[Observability] Prometheus: pull 기반 메트릭, PromQL

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Prometheus = pull 기반 시계열 metric 시스템. PromQL 로 쿼리. CNCF graduated. 2026 클라우드 네이티브 메트릭 표준.

아키텍처

flowchart LR
    App1[App + /metrics] -.HTTP GET.-> Prom[Prometheus]
    App2[App + /metrics] -.HTTP GET.-> Prom
    NodeEx[node-exporter] -.HTTP GET.-> Prom
    KSM[kube-state-metrics] -.HTTP GET.-> Prom
    Prom --> TSDB[(Time Series DB)]
    Prom --> AM[Alertmanager]
    AM --> Slack[Slack / PagerDuty / Email]
    Prom --> Grafana

Pull 모델: Prometheus 가 각 target 의 /metrics 정기 scrape. Push 가 아닌 이유: target healthy 자동 확인, scrape interval 통제.

Exposition Format

# HELP http_requests_total Total HTTP requests
# TYPE http_requests_total counter
http_requests_total{method="GET",status="200",path="/api/users"} 1234
http_requests_total{method="POST",status="201",path="/api/orders"} 567

# HELP http_request_duration_seconds Request duration
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.1"} 5000
http_request_duration_seconds_bucket{le="0.5"} 5800
http_request_duration_seconds_bucket{le="1.0"} 5900
http_request_duration_seconds_bucket{le="+Inf"} 6000
http_request_duration_seconds_sum 412.5
http_request_duration_seconds_count 6000

4가지 메트릭 타입

타입	의미	예
Counter	단조 증가	requests_total
Gauge	임의 변동	memory_usage_bytes
Histogram	분포 (bucket)	request_duration_seconds
Summary	quantile (클라이언트 계산)	request_duration_quantile

PromQL 예시

# 요청률 (5분)
rate(http_requests_total[5m])

# 에러 비율
sum(rate(http_requests_total{status=~"5.."}[5m]))
  / sum(rate(http_requests_total[5m]))

# 평균 응답 시간
rate(http_request_duration_seconds_sum[5m])
  / rate(http_request_duration_seconds_count[5m])

# p95 latency (histogram_quantile)
histogram_quantile(0.95,
  sum by (le, service) (rate(http_request_duration_seconds_bucket[5m]))
)

# 메모리 사용량 (gauge)
process_resident_memory_bytes

# CPU 사용률
rate(process_cpu_seconds_total[1m])

# 가용성 (up)
avg_over_time(up{job="api"}[5m])

Exporter

Exporter	메트릭
node-exporter	Linux node (CPU, RAM, disk, network)
kube-state-metrics	K8s 객체 상태
cAdvisor	container metric (K8s 기본 포함)
postgres_exporter	PG 통계
redis_exporter	Redis
blackbox_exporter	HTTP/TCP probe
nginx-exporter	nginx

4 Golden Signals (Google SRE)

flowchart TD
    G[4 Golden Signals]
    G --> Lat[Latency]
    G --> Tra[Traffic]
    G --> Err[Errors]
    G --> Sat[Saturation]

모든 서비스 대시보드의 기본 4. 이 4 가지면 대부분의 문제 발견.

Alertmanager

# Alert rule
groups:
  - name: api
    rules:
      - alert: HighErrorRate
        expr: |
          sum(rate(http_requests_total{status=~"5.."}[5m]))
            / sum(rate(http_requests_total[5m])) > 0.05
        for: 5m
        labels: { severity: page }
        annotations:
          summary: "5xx rate > 5%"

# Alertmanager 설정
route:
  group_by: [alertname, severity]
  receiver: slack
  routes:
    - match: { severity: page }
      receiver: pagerduty
receivers:
  - name: slack
    slack_configs:
      - api_url: https://hooks.slack.com/...
  - name: pagerduty
    pagerduty_configs:
      - service_key: ...

Long-Term Storage

	Local TSDB	Thanos	Mimir	Cortex
Retention	15일 기본	무제한 (S3)	무제한	무제한
HA	없음	있음	있음	있음
Multi-tenancy	없음	있음	있음	있음

수년 retention + 다중 cluster = Thanos / Mimir.

Recording Rule

- record: job:http_requests:rate5m
  expr: sum by (job) (rate(http_requests_total[5m]))

자주 쓰는 쿼리 결과 미리 계산. 대시보드 속도 ↑.

흔한 함정

[!WARNING]

Label cardinality 폭증 = user_id, request_id 같은 고유 값 을 label 로. 메모리 / disk 폭발.

rate() 의 짧은 range = scrape interval 보다 작으면 NaN.

Counter reset 인식 못함 = rate() 가 자동. increase() 와 차이.

Push 가 필요한 경우 = Pushgateway 사용 (batch job 등). 일반 service 는 pull.

[Observability] SLI / SLO / SLA / Error Budget

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

	의미
SLI (Indicator)	측정 값 (예: 5xx 비율)
SLO (Objective)	목표 (예: 99.9% 가용성)
SLA (Agreement)	계약 (위반 시 환불 / 페널티)
Error Budget	허용 가능한 실패 양

관계

flowchart LR
    SLI["SLI 측정<br/>#quot;5xx rate = 0.02%#quot;"]
    SLO["SLO 목표<br/>#quot;5xx < 0.1%#quot;"]
    SLA["SLA 계약<br/>#quot;가용성 99.9%, 미만 시 10% 환불#quot;"]
    EB["Error Budget<br/>#quot;30일 중 43분 다운 OK#quot;"]
    SLI --> Compare{비교}
    SLO --> Compare
    Compare --> EB

좋은 SLI 4 카테고리

카테고리	예시
Availability	성공 응답 비율
Latency	p95, p99 응답 시간
Throughput	처리량 (req/s)
Correctness	비율로 측정 가능한 정확성

Google SRE: user-facing 측면 → 서버 CPU 같은 내부 metric 보다 사용자 경험.

SLO 설정 예시

가용성 SLI = 성공_응답 / 총_응답
SLO = 30일 중 99.9% 이상

→ Error Budget = 30일 × 24h × 60min × (1 - 0.999)
              = 43.2 분 / 월

flowchart LR
    Time[30일 = 43200분]
    Budget[Error Budget: 43.2분]
    Time --> Bar
    Budget --> Bar
    Bar["사용한 ERROR: ▓▓▓░░░░░░░ 12분 / 43.2분 (28%)"]

Error Budget Policy

flowchart TD
    Q{Budget 소진}
    Q -->|0-50%| Normal[정상 운영 + 빠른 개발]
    Q -->|50-90%| Caution[변경 주의 + 위험 평가]
    Q -->|90-100%| Freeze[*새 feature 동결*<br/>reliability 작업만]
    Q -->|100% 초과| Stop[모든 risky 변경 중단]

Error budget 의 행동 contract. 단순 메트릭이 아닌 조직 정책.

SLO 계산 (PromQL)

# 30일 가용성
sum_over_time(
  (sum(rate(http_requests_total{status!~"5.."}[1m]))
    / sum(rate(http_requests_total[1m])))[30d:1m]
)
/ count_over_time((sum(rate(http_requests_total[1m])))[30d:1m])

# Budget 남은 %
1 - (
  (1 - currentAvailability) / (1 - SLO_target)
)

SLA 예시 (실제 SaaS)

SaaS	SLA
AWS S3	99.99% (월) - 미만 시 service credit
GitHub	99.9% (분기)
Stripe	99.999% (페이먼트)

내부 SLO 는 SLA 보다 더 엄격 하게 (margin).

Burn Rate Alert

flowchart LR
    Fast[빠른 소진: 1시간 5% 소진 → 즉시 page]
    Slow[느린 소진: 6시간 10% 소진 → ticket]

# fast burn (1h 의 budget 소진 속도가 14.4x)
(
  sum(rate(http_5xx[1h])) / sum(rate(http_total[1h]))
) > (14.4 * 0.001)   # SLO = 0.999 → error = 0.001

단순 threshold alert 보다 budget 소진 속도 가 의미.

흔한 함정

[!WARNING]

SLO 가 서버 metric (CPU 95%) = 사용자 경험과 무관. user-facing.

너무 높은 SLO (99.999%) = 불가능 + 비용 폭증. 비즈니스에 맞는 수준.

SLA = SLO = SLA 는 계약, SLO 는 내부 목표 (더 엄격).

Budget 정책 부재 = SLO 만 측정하고 행동 없음. 무의미.

[Voice AI] P50/P95/P99: latency 분포와 SLO

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

P50 / P95 / P99 = latency 분포의 분위수. 평균은 outlier 에 가려져 무의미. 음성 에이전트의 사용자 경험 은 p95/p99 가 결정.

[!IMPORTANT] 평균 응답 시간 800ms 라도 P99 = 5초 면 100명 중 1명은 5초 대기. 음성 = “한 번 깨지면 대화 망함”.

Percentile 정의

정렬된 latency 값 100개 중:
- P50 (median) = 50번째 값
- P95 = 95번째 값
- P99 = 99번째 값
- P99.9 = 99.9번째 값

flowchart LR
    Hist["응답 시간 분포 (긴 꼬리)"] --> P50["P50 = 500ms<br/>(중간값)"]
    Hist --> P95["P95 = 1200ms<br/>(95% 이내)"]
    Hist --> P99["P99 = 3500ms<br/>(99% 이내)"]
    Hist --> P999["P99.9 = 8000ms<br/>(0.1% outlier)"]

분포 시각화

Tail (3초+) 이 작아 보이지만 사용자 입장에서는 치명적.

평균 vs Percentile

# 가상 latency 데이터 (음성 응답)
latencies = [
    *[500] * 95,    # 95명이 500ms
    *[1000] * 4,    # 4명이 1초
    *[5000] * 1,    # 1명이 5초 (timeout 직전)
]

print(f"평균: {sum(latencies) / len(latencies):.0f}ms")
# → 평균: 590ms ← "괜찮네"

import numpy as np
print(f"P50: {np.percentile(latencies, 50):.0f}ms")
print(f"P95: {np.percentile(latencies, 95):.0f}ms")
print(f"P99: {np.percentile(latencies, 99):.0f}ms")
# → P50: 500ms, P95: 500ms, P99: 5000ms ← "1%가 5초!"

측정: HDR Histogram

from hdrh.histogram import HdrHistogram

# 1ms ~ 60s, 3 자리 정밀도
hist = HdrHistogram(1, 60_000, 3)

for latency_ms in latencies:
    hist.record_value(latency_ms)

print(f"P50: {hist.get_value_at_percentile(50)}ms")
print(f"P95: {hist.get_value_at_percentile(95)}ms")
print(f"P99: {hist.get_value_at_percentile(99)}ms")
print(f"P99.9: {hist.get_value_at_percentile(99.9)}ms")

측정 도구	의미
HDR Histogram	정확, 고정 메모리
t-digest	분산 환경, 합치기 좋음
Prometheus Histogram	분산 + 시각화
CloudWatch p metric*	비싸지만 편함

분산 환경: t-digest

from tdigest import TDigest

digest = TDigest()
for v in latencies:
    digest.update(v)

# 여러 노드의 digest 합치기
node1_digest + node2_digest + ...

# percentile query
digest.percentile(95)

각 노드의 digest 를 Redis 에 저장 → 주기적 머지. 전역 percentile.

Coordinated Omission

Gil Tene 의 유명한 문제. 측정 시 느린 요청 동안 측정도 못 하는 → 진짜 latency 보다 좋게 나옴.

# ❌ 잘못된 측정
while True:
    start = time.time()
    do_request()
    elapsed = time.time() - start
    record(elapsed)
    # 만약 request 가 10초 걸렸으면, 그 10초간 *추가 측정 못 함*

# ✓ Coordinated omission 보정
expected_rate_ms = 100  # 100ms 마다 1개
last_send = time.time()
while True:
    target = last_send + expected_rate_ms / 1000
    sleep_until(target)
    start = time.time()

    # *예정된 시간이 지났는데 보내지 못한 시간* 도 latency 에 포함
    expected_start = target
    do_request()
    elapsed = time.time() - expected_start   # ← 보정

    record(elapsed)
    last_send = target

Voice Agent SLO

Metric	P50	P95	P99
End-to-end	700ms	1200ms	2000ms
STT	200ms	400ms	800ms
LLM TTFT	300ms	600ms	1500ms
TTS TTFB	150ms	300ms	700ms
Network RTT	30ms	80ms	200ms

[!IMPORTANT] P99 가 1초 이상 이면 1% 사용자가 어색한 대화. 음성 SLO 는 P99 기준.

단계별 분석

class LatencyTracker:
    def __init__(self):
        self.stages = defaultdict(HdrHistogram)

    def record(self, stage: str, latency_ms: int):
        self.stages[stage].record_value(latency_ms)

    def report(self):
        for stage, hist in self.stages.items():
            print(f"{stage}:")
            for p in [50, 95, 99, 99.9]:
                print(f"  P{p}: {hist.get_value_at_percentile(p)}ms")

# 사용
tracker.record('stt', stt_elapsed)
tracker.record('llm_ttft', llm_ttft)
tracker.record('tts_ttfb', tts_ttfb)
tracker.record('end_to_end', total)

SLO / Error Budget

자세한 건 [[slo-sli-error-budget]].

SLO: 30일 동안 P95 end-to-end < 1500ms
Error Budget = 30일 × 24h × 60min × 5% = 2160분

P95 > 1500ms 인 1분 = budget 1분 소진
budget 소진 → feature freeze + reliability 작업

흔한 함정

[!WARNING]

평균만 봄 = outlier 무시. P95/P99 필수.

Prometheus histogram bucket 부정확 = bucket 범위 밖이면 정확도 손실. HDR / t-digest 권장.

Coordinated omission = 실측이 너무 좋아 보임. 보정 필요.

샘플링 너무 적음 = P99 의미 X. 최소 1000+ 샘플.

[DevOps] 무중단 배포: Blue-Green, Canary, Rolling, Expand-Contract

koa (김신건) — Wed, 24 Jun 2026 00:00:00 GMT

정의

무중단 배포 (Zero-Downtime Deployment) 는 서비스 가동을 멈추지 않고 새 버전을 배포하는 일련의 전략. 핵심 도전 4가지:

트래픽 전환: 어떻게 라우팅을 안전하게?
세션 / 인플라이트 요청: 진행 중 요청 보호
DB 스키마 변경: 두 버전 동시 동작 가능해야
롤백 보장: 실패 시 즉시 이전 버전으로

전략 매트릭스:

전략	인프라 비용	롤백 속도	점진성	복잡도
Blue-Green	2배	즉시 (스위치)	없음 (한 번에)	낮음
Rolling Update	1배	느림 (재배포)	있음 (pod 단위)	낮음
Canary	1.x배	빠름 (canary 제거)	정밀 (트래픽 %)	중간
A/B Test	1.x배	즉시 (flag off)	사용자 segment	높음
Feature Flag	1배	즉시 (flag off)	코드 path 단위	높음

Blue-Green Deployment

두 환경 (Blue, Green) 을 동시에 운영, 라우터로 한쪽만 활성:

[현재 활성: Blue]
Router → Blue (v1, traffic 100%)
         Green (v2, idle, 배포 중)

[배포 완료, smoke test 통과]
Router → Green (v2, traffic 100%)
         Blue (v1, standby for rollback)

[안정 후 다음 배포]
Router → Green (v2, traffic 100%)
         Blue (v3 배포 중)

장점:

즉시 스위치 + 즉시 롤백: 라우터 변경만
운영 환경에서 최종 테스트: 같은 인프라
재해 복구 연습: 매 배포마다 hot-standby 검증

단점:

2배 인프라 비용: 두 환경 항상 가동
DB 공유 처리: 두 버전이 같은 DB → 스키마 호환 필수 (expand-contract)
인플라이트 요청 손실 위험: 스위치 시점에 처리 중이던 요청
all-or-nothing: 점진 배포 불가

인플라이트 요청 처리

# K8s 의 graceful shutdown
spec:
  terminationGracePeriodSeconds: 30
  containers:
    - lifecycle:
        preStop:
          exec:
            command: ["sh", "-c", "sleep 5"]   # readiness 빠지는 시간

readiness false → LB 가 제외 → 신규 요청 안 받음 → 진행 요청 완료 대기 → SIGTERM → graceful shutdown.

Spring Boot 의 server.shutdown: graceful + spring.lifecycle.timeout-per-shutdown-phase: 30s 와 조합 ([[spring-boot-webserver-configuration]] 참고).

Rolling Update (K8s 기본)

pod 를 한 번에 N개씩 교체:

apiVersion: apps/v1
kind: Deployment
spec:
  replicas: 10
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 25%          # 임시로 추가 가능한 pod %
      maxUnavailable: 25%    # 동시 unavailable 허용 %

flow:

새 ReplicaSet 생성, pod 1개 시작
readiness OK → LB 추가, 옛 pod 1개 제거
반복

장점:

인프라 비용 1배 (혹은 약간 +)
K8s native: 추가 도구 없음
점진성: pod 1개씩 = 영향 최소

단점:

두 버전 동시 운영 시간 길다: 5~10분 (큰 cluster 면 30분+)
롤백 느림: 다시 rolling 으로 이전 버전 배포
두 버전 호환성 필수: DB / API contract 양방향

Canary Deployment

일부 트래픽만 새 버전으로 보내 검증:

[Phase 1] 1% canary
Router → 99% v1, 1% v2

[Phase 2] 안정 → 5% → 25% → 50% → 100%
Router → v2 로 점진 증가

[중간 실패 시] canary 즉시 제거
Router → 100% v1

K8s + Istio / Linkerd / Argo Rollouts 같은 service mesh / progressive delivery 도구로 구현:

apiVersion: argoproj.io/v1alpha1
kind: Rollout
spec:
  strategy:
    canary:
      steps:
        - setWeight: 1
        - pause: { duration: 10m }
        - setWeight: 5
        - pause: { duration: 30m }
        - setWeight: 25
        - pause: { duration: 1h }
        - setWeight: 50
        - pause: { duration: 1h }
        - setWeight: 100
      analysis:
        templates:
          - templateName: success-rate
          - templateName: latency

자동 분석: 에러율 / latency / 비즈니스 metric 이 SLO 위반 시 자동 rollback.

장점:

실제 사용자에 미세 검증: 합성 테스트로 못 잡는 버그 발견
빠른 롤백
자동 분석 + 자동 진행

단점:

복잡한 인프라 (service mesh 또는 Argo Rollouts)
두 버전 호환성 필수
canary 가 너무 작으면 통계 의미 없음: 1% 가 충분한 트래픽이어야

A/B Testing vs Canary

항목	Canary	A/B Test
목적	새 코드 안전성 검증	비즈니스 가설 검증
라우팅 기준	트래픽 % (random)	사용자 segment (cookie, user_id)
측정 metric	에러율 / latency / SLO	conversion / CTR / revenue
기간	시간 단위	일~주
결정 주체	SRE / 자동화	PM / data scientist

같은 인프라 위에서 동작하지만 의도가 다름. A/B 가 더 오래 지속.

Feature Flag

코드 path 단위 토글. 배포와 release 분리:

@Service
class CheckoutService {
    private final FeatureFlagClient flags;

    public Order checkout(Cart cart, User user) {
        if (flags.isEnabled("new-checkout-v2", user)) {
            return newCheckoutFlow(cart, user);
        }
        return legacyCheckoutFlow(cart, user);
    }
}

flag 종류 (Martin Fowler 분류):

종류	수명	동적성	예시
Release toggle	짧음 (배포 후 제거)	정적	”new-feature-x”
Experiment toggle	중간 (A/B 끝나면 제거)	사용자별	”checkout-variant-a”
Ops toggle	길음	실시간	”circuit-breaker”, “rate-limit”
Permission toggle	영구	사용자별	”premium-feature”

도구: LaunchDarkly, Unleash, Flagsmith, Split.io, 또는 자체 구현 (DB + Redis 캐시).

spring:
  cloud:
    config:
      enabled: true
# 또는 Redis hash 기반

flag 평가는 hot path 에 있으므로 로컬 캐시 + 백그라운드 sync 가 권장.

DB Migration: Expand-Contract

무중단 배포의 가장 어려운 부분. 두 버전 동시 동작 가능한 스키마 필요.

위험 변경 예: 컬럼 rename `email_addr` → `email`

❌ 위험한 single-step:

ALTER TABLE users RENAME COLUMN email_addr TO email;
-- 배포 동시에: 옛 코드는 email_addr, 새 코드는 email
-- 둘 중 하나 무조건 깨짐

✓ Expand-Contract (4단계):

Step 1: Expand : 새 컬럼 추가 (NULL 허용)

ALTER TABLE users ADD COLUMN email VARCHAR(255);

배포: 없음. 옛 코드 정상.

Step 2: Backfill : 데이터 복사

UPDATE users SET email = email_addr WHERE email IS NULL;
-- 대용량이면 배치 (1000 row 씩)

배포: 없음. 옛 코드 정상.

Step 3: Dual-write : 새 코드 배포 (둘 다 쓰고 새 컬럼 읽기)

user.setEmail(email);
user.setEmailAddr(email);   // 호환을 위해 둘 다 쓰기

배포: 새 코드. 옛 코드 / 새 코드 모두 정상.

Step 4: Contract : 옛 코드 모두 사라진 후 + 충분한 안정 기간

ALTER TABLE users DROP COLUMN email_addr;
-- 옛 컬럼 제거

배포: 없음. 옛 코드 이제 없으므로 안전.

각 step 마다 rollback point. 한 번에 1 단계만, 충분한 검증 후 다음.

NOT NULL 추가

❌ 단일 step:

ALTER TABLE users ALTER COLUMN email SET NOT NULL;
-- 기존 NULL row 가 있으면 실패, lock 발생

✓ 다단계:

backfill (NULL 채우기)
코드가 항상 NOT NULL 으로 쓰도록 배포
constraint 추가 (NOT VALID 으로 lock 없이) → VALIDATE

PostgreSQL 의 ADD CONSTRAINT ... NOT VALID + VALIDATE CONSTRAINT 분리가 lock 없이.

인덱스

-- PostgreSQL
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);

-- MySQL 8+
ALTER TABLE users ADD INDEX idx_email (email), ALGORITHM=INPLACE, LOCK=NONE;

CONCURRENTLY / ALGORITHM=INPLACE 가 lock 회피.

외래키

-- 1. 추가 (validate 없이)
ALTER TABLE orders ADD CONSTRAINT fk_user FOREIGN KEY (user_id) REFERENCES users(id) NOT VALID;
-- 2. 검증 (lock 적음)
ALTER TABLE orders VALIDATE CONSTRAINT fk_user;

Backward / Forward Compatibility

배포 중 두 버전 동시 동작 → 양방향 호환:

API

항상 추가만: 새 field 는 optional default, 제거는 deprecation 후 충분한 시간
버전 prefix (/v1/, /v2/): breaking change 시 새 경로
JSON unknown field 무시: Jackson @JsonIgnoreProperties(ignoreUnknown = true)

Message Queue

Avro / Protobuf schema evolution: 옵션 필드 추가 OK, 제거는 deprecation
새 producer + 옛 consumer: 새 field 무시
옛 producer + 새 consumer: default 값 사용

직렬화 (Java)

serialVersionUID 유지: 옛 클래스 인스턴스 deserialize 가능
field 제거 금지 (충분한 transition 기간 전까지)
Jackson polymorphic deserialization 주의: @JsonTypeInfo

헬스체크 + readiness 분리

K8s 의 3가지 probe:

Probe	실패 시 동작	사용
startupProbe	컨테이너 재시작 (initial delay 길게)	느린 시작 (JVM, DB pool warmup)
livenessProbe	컨테이너 재시작	복구 불가 상태 (deadlock, OOM)
readinessProbe	LB 에서 제외 (재시작 X)	일시적 unavailable (DB 연결 끊김)

Spring Boot 의 /actuator/health/liveness + /actuator/health/readiness 가 표준 매핑 ([[spring-boot-container-deployment]]).

Outbox 패턴 (DB + 메시지 큐 일관성)

DB 트랜잭션 + Kafka publish 가 atomic 하지 않음 (분산 트랜잭션 회피):

[종래 문제]
INSERT order → 성공
kafka.publish(OrderPlaced) → 실패 (네트워크)
→ DB 에 order 있지만 알림 없음 = inconsistent

[Outbox 패턴]
TRANSACTION:
  INSERT order
  INSERT outbox(event=OrderPlaced, status=pending)
COMMIT

[별도 worker]
SELECT outbox WHERE status=pending
  → Kafka publish
  → UPDATE outbox SET status=sent

@TransactionalEventListener(phase=AFTER_COMMIT) 도 비슷한 효과 (단, 워커 인스턴스 죽으면 event 손실 → outbox 가 더 안전).

함정과 베스트 프랙티스

DB schema 변경은 항상 expand-contract: single-step 은 무중단 X
graceful shutdown + preStop sleep: K8s 환경 필수
readiness 와 liveness 분리: 일시 문제로 재시작 폭주 회피
session affinity 최소화: blue-green / rolling 시 세션 분실 위험 → 외부 store (Redis)
canary 자동 분석 + 자동 rollback: 사람의 판단 늦음
feature flag 정리: release toggle 은 배포 후 즉시 제거 (코드 cruft 방지)
API breaking change = 새 버전 endpoint: 옛 endpoint 충분 기간 유지
테스트 환경에서 무중단 시나리오 연습: 진짜 배포 때 처음 보면 늦음
rollback 도 무중단: forward 만 가능하면 디자인 결함

김신건의 로그 - 위키 / devops

Shell Script: bash 기본과 실전 패턴

정의

안전한 시작

변수

조건과 반복

함수

에러 처리

실전 패턴

stdin/stdout 처리

인자 파싱

함정

참고

[CI/CD] GitHub Actions: workflow, action, runner

정의

구조

Workflow YAML

Trigger 종류

Runner

Marketplace Action

OIDC + AWS (long-term key 없이)

Matrix Build

Reusable Workflow

Composite Action

보안

흔한 함정

관련 위키

[GitOps] ArgoCD: Kubernetes GitOps

정의

GitOps 원칙

Application 정의

동작

App of Apps 패턴

ApplicationSet

ArgoCD vs Flux

Argo Rollouts (Progressive Delivery)

CI/CD 분리 (Push vs Pull)

흔한 함정

관련 위키

[GitOps] 패턴: 단일 vs 다중 repo, environment promotion

GitOps 4가지 원칙 (OpenGitOps)

Repo 구조 패턴

1. Monorepo (app + manifest)

2. 2-repo (권장)

3. Multi-repo

Environment Promotion

Image Updater

Secret 처리 (git 안전)

Multi-cluster GitOps

Drift Detection

흔한 함정

관련 위키

[Observability] OpenTelemetry: 표준화된 trace/metric/log

정의

3 signal

아키텍처

Trace = Span Tree

Context Propagation (W3C)

Auto-instrumentation

Manual Instrumentation

OTel Collector

Sampling

OpenTelemetry vs Vendor

흔한 함정

관련 위키

[Observability] Prometheus: pull 기반 메트릭, PromQL

정의

아키텍처

Exposition Format

4가지 메트릭 타입

PromQL 예시

Exporter

4 Golden Signals (Google SRE)

Alertmanager

Long-Term Storage

Recording Rule

흔한 함정

관련 위키

[Observability] SLI / SLO / SLA / Error Budget

정의

위험 변경 예: 컬럼 rename `email_addr` → `email`