mTLS로 OTLP 엔드포인트 보호하기 (feat. Claude Code Hook)

클러스터 외부에서 OTLP Collector에 접근하려면

Kubernetes 클러스터 내부에 OpenTelemetry Collector(Alloy)를 운영하고 있습니다. 클러스터 내부 워크로드는 Service DNS로 텔레메트리를 전송할 수 있습니다:

1
alloy.observability.svc.cluster.local:4317

네트워크 정책으로 접근을 제한할 수 있고, 클러스터 내부 통신이라 별도 인증 없이도 신뢰할 수 있습니다.

그러나 클러스터 외부 워크로드는 Ingress를 통해 인터넷으로 노출된 엔드포인트를 사용해야 합니다:

1
https://otel.heeho.net

문제는 이 엔드포인트가 누구에게나 열려 있다는 것입니다. 아무나 텔레메트리 데이터를 보낼 수 있으면:

스팸 데이터로 백엔드 리소스 낭비
메트릭/로그 오염
잘못된 알림 발생

접근을 제한해야 합니다.

OTLP 엔드포인트 보안 방법

OpenTelemetry 공식 문서와 보안 가이드를 조사했습니다.

방법	설명	장점	단점
mTLS	클라이언트/서버 상호 인증서 검증	강력한 인증, Zero Trust 모델	인증서 관리 필요
API Key/Bearer Token	HTTP 헤더에 토큰 포함	구현 간단	토큰 노출 위험, 정적
OAuth2/OIDC	동적 토큰 발급	표준화, 세분화된 권한	복잡한 설정
IP 화이트리스트	허용된 IP만 접근	간단	동적 IP 대응 어려움

왜 TLS가 아니라 mTLS인가?

TLS와 mTLS의 핵심 차이:

구분	TLS	mTLS
서버 인증	✅ 서버가 인증서로 신원 증명	✅ 동일
클라이언트 인증	❌ 없음 (누구나 접속 가능)	✅ 클라이언트도 인증서 필요
검증 방향	단방향 (클라이언트 → 서버)	양방향 (상호 검증)

1
TLS:
2
클라이언트 ──────────────────→ 서버
3
           "서버가 맞는지 확인"
4
           (클라이언트는 누군지 모름)
5

6
mTLS:
7
클라이언트 ←─────────────────→ 서버
8
           "서로가 맞는지 확인"

TLS만 적용하면:

1
# HTTPS로 암호화는 되지만, 아무나 데이터를 보낼 수 있음
2
curl https://otel.heeho.net/v1/metrics -d '스팸 데이터'
3
# → 성공 (서버는 클라이언트가 누군지 모름)

mTLS를 적용하면:

1
# 인증서 없이는 접근 자체가 차단됨
2
curl https://otel.heeho.net/v1/metrics -d '스팸 데이터'
3
# → 400 Bad Request (인증서 없음)

mTLS를 선택한 이유

Zero Trust: 양방향 인증으로 클라이언트/서버 모두 신원 확인
토큰 노출 위험 없음: 인증서는 파일 시스템에 저장, 네트워크로 전송되지 않음
고정 클라이언트: Mac 1대 → 인증서 관리 부담 적음
OpenTelemetry 권장: 공식 문서에서 프로덕션 환경에 mTLS 권장

“In a production environment, use TLS certificates for secure communication or mTLS for mutual authentication.” — OpenTelemetry Collector Security Best Practices

아키텍처

1
flowchart LR
2
    subgraph External["External (Mac)"]
3
        Client["Claude Code<br/>+ 클라이언트 인증서"]
4
    end
5

6
    subgraph K8s["Kubernetes Cluster"]
7
        subgraph Ingress["Nginx Ingress"]
8
            IG["otel-http.heeho.net<br/>mTLS 검증"]
9
        end
10

11
        subgraph Obs["observability namespace"]
12
            Alloy["Alloy<br/>OTLP Collector"]
13
            Tempo["Tempo"]
14
            Prom["Prometheus"]
15
            Loki["Loki"]
16
        end
17
    end
18

19
    Client -->|"HTTPS + 클라이언트 인증서"| IG
20
    IG -->|"인증서 검증 통과"| Alloy
21
    Alloy --> Tempo
22
    Alloy --> Prom
23
    Alloy --> Loki

흐름:

클라이언트가 인증서와 함께 HTTPS 요청
Nginx Ingress가 클라이언트 인증서를 CA로 검증
검증 통과 시 Alloy로 프록시
검증 실패 시 400 Bad Request 반환

인증서 생성하기

1. CA (Certificate Authority) 생성

클라이언트 인증서를 서명할 CA를 먼저 만듭니다.

1
# 작업 디렉토리
2
mkdir -p ~/.certs/otlp && cd ~/.certs/otlp
3

4
# CA 개인키 생성 (4096bit RSA)
5
openssl genrsa -out client-ca.key 4096
6

7
# CA 인증서 생성 (10년 유효)
8
openssl req -new -x509 -days 3650 -key client-ca.key \
9
  -out client-ca.crt -subj "/CN=OTLP Client CA/O=homelab"

2. 클라이언트 인증서 생성

Mac에서 사용할 클라이언트 인증서를 생성합니다.

1
# 클라이언트 개인키
2
openssl genrsa -out mac-client.key 4096
3

4
# CSR (Certificate Signing Request) 생성
5
openssl req -new -key mac-client.key \
6
  -out mac-client.csr -subj "/CN=heeho-mac/O=homelab"
7

8
# CA로 서명하여 인증서 발급 (1년 유효)
9
openssl x509 -req -days 365 -in mac-client.csr \
10
  -CA client-ca.crt -CAkey client-ca.key -CAcreateserial \
11
  -out mac-client.crt
12

13
# CSR 삭제 (더 이상 필요 없음)
14
rm mac-client.csr
15

16
# 통합 PEM 파일 생성 (일부 클라이언트용)
17
cat mac-client.crt mac-client.key > mac-client.pem

생성된 파일 구조

1
~/.certs/otlp/
2
├── client-ca.crt    # CA 인증서 → Kubernetes에 등록
3
├── client-ca.key    # CA 개인키 → 안전하게 보관
4
├── client-ca.srl    # 시리얼 번호 (자동 생성)
5
├── mac-client.crt   # 클라이언트 인증서
6
├── mac-client.key   # 클라이언트 개인키
7
└── mac-client.pem   # 인증서+개인키 통합본

Kubernetes 설정하기

1. CA 인증서를 Secret으로 등록

Nginx Ingress가 클라이언트 인증서를 검증할 때 사용할 CA입니다.

1
kubectl create secret generic otel-client-ca \
2
  --from-file=ca.crt=~/.certs/otlp/client-ca.crt \
3
  -n observability

2. Alloy Ingress 설정

mTLS가 적용된 Ingress를 생성합니다.

1
# alloy.yaml (Helm values)
2
extraObjects:
3
  - apiVersion: networking.k8s.io/v1
4
    kind: Ingress
5
    metadata:
6
      name: alloy-otlp-http
7
      namespace: observability
8
      annotations:
9
        nginx.ingress.kubernetes.io/ssl-redirect: "true"
10
        # mTLS 핵심 설정
11
        nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
12
        nginx.ingress.kubernetes.io/auth-tls-secret: "observability/otel-client-ca"
13
        nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
14
    spec:
15
      ingressClassName: nginx
16
      rules:
17
        - host: otel-http.heeho.net
18
          http:
19
            paths:
20
              - path: /
21
                pathType: Prefix
22
                backend:
23
                  service:
24
                    name: alloy
25
                    port:
26
                      number: 4318 # OTLP HTTP
27
      tls:
28
        - secretName: wildcard.heeho.net
29
          hosts:
30
            - otel-http.heeho.net

핵심 annotation 설명:

Annotation	값	설명
`auth-tls-verify-client`	`on`	클라이언트 인증서 필수
`auth-tls-secret`	`observability/otel-client-ca`	검증에 사용할 CA Secret
`auth-tls-verify-depth`	`1`	인증서 체인 검증 깊이

3. Helm 배포

1
helm upgrade alloy grafana/alloy -n observability -f alloy.yaml

mTLS 동작 확인하기

OTLP 엔드포인트는 POST 요청만 허용합니다. POST로 테스트합니다.

테스트 1: 인증서 없이 접근

1
curl -s -w "\nHTTP Status: %{http_code}\n" \
2
  -X POST https://otel-http.heeho.net/v1/metrics \
3
  -H "Content-Type: application/x-protobuf"

결과:

1
<html>
2
<head><title>400 No required SSL certificate was sent</title></head>
3
<body>
4
<center><h1>400 Bad Request</h1></center>
5
<center>No required SSL certificate was sent</center>
6
<hr><center>nginx</center>
7
</body>
8
</html>
9
HTTP Status: 400

인증서 없이는 Ingress 단계에서 차단됩니다.

테스트 2: 인증서로 접근

1
curl -s -w "\nHTTP Status: %{http_code}\n" \
2
  -X POST https://otel-http.heeho.net/v1/metrics \
3
  -H "Content-Type: application/json" \
4
  --cert ~/.certs/otlp/mac-client.crt \
5
  --key ~/.certs/otlp/mac-client.key \
6
  -d '{
7
    "resourceMetrics": [{
8
      "resource": {
9
        "attributes": [{"key": "service.name", "value": {"stringValue": "mtls-test"}}]
10
      },
11
      "scopeMetrics": [{
12
        "metrics": [{
13
          "name": "test.counter",
14
          "sum": {
15
            "dataPoints": [{"asInt": "1", "timeUnixNano": "1234567890000000000"}],
16
            "isMonotonic": true
17
          }
18
        }]
19
      }]
20
    }]
21
  }'

결과:

1
{"partialSuccess":{}}
2
HTTP Status: 200

HTTP 200과 JSON 응답이 반환되면 Alloy까지 정상 도달한 것입니다.

테스트 3: 잘못된 인증서로 접근

1
# 임시 인증서 생성 (등록된 CA가 아닌 self-signed)
2
openssl req -x509 -newkey rsa:2048 -keyout /tmp/fake.key -out /tmp/fake.crt \
3
  -days 1 -nodes -subj "/CN=fake" 2>/dev/null
4

5
# 접근 시도
6
curl -s -w "\nHTTP Status: %{http_code}\n" \
7
  -X POST https://otel-http.heeho.net/v1/metrics \
8
  --cert /tmp/fake.crt --key /tmp/fake.key

결과:

1
<html>
2
<head><title>400 The SSL certificate error</title></head>
3
<body>
4
<center><h1>400 Bad Request</h1></center>
5
<center>The SSL certificate error</center>
6
<hr><center>nginx</center>
7
</body>
8
</html>
9
HTTP Status: 400

등록된 CA가 서명하지 않은 인증서는 거부됩니다.

Claude Code Hook 연동하기

Claude Code는 Hook 시스템을 통해 세션과 도구 사용을 외부로 전송할 수 있습니다.

Claude Code Hook이란? Claude Code CLI가 특정 이벤트(세션 시작/종료, 도구 호출 등) 발생 시 사용자 정의 스크립트를 실행하는 기능입니다.
Hook 발동 시점 용도
SessionStart Claude Code 시작 세션 추적 시작
PostToolUse 도구 호출 완료 후 도구 사용 기록

Hook	발동 시점	용도
`SessionStart`	Claude Code 시작	세션 추적 시작
`PostToolUse`	도구 호출 완료 후	도구 사용 기록

Hook 스크립트에서 OpenTelemetry Python SDK를 사용해 mTLS로 보호된 OTLP 엔드포인트로 trace를 전송합니다. SessionStart에서 생성한 trace context를 저장하고, PostToolUse에서 이를 parent로 사용하여 하나의 세션을 하나의 trace로 추적합니다.

1. OTLP Tracer Hook 스크립트

~/.claude/hooks/otlp-tracer.py:

1
#!/usr/bin/env -S uv run --script
2
# /// script
3
# requires-python = ">=3.11"
4
# dependencies = [
5
#     "opentelemetry-sdk",
6
#     "opentelemetry-exporter-otlp-proto-http",
7
# ]
8
# ///
9
"""
10
OTLP Tracer for Claude Code
11
세션별로 하나의 Trace를 생성하고, 도구 사용을 child span으로 연결합니다.
12
"""
13

14
import json
15
import os
16
import sys
17
from pathlib import Path
18

19
STATE_DIR = Path.home() / ".claude" / "hooks" / "state"
20
STATE_DIR.mkdir(parents=True, exist_ok=True)
21

22
def get_otlp_exporter():
23
    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
24

25
    endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
26
    if not endpoint:
27
        return None
28

29
    return OTLPSpanExporter(
30
        endpoint=f"{endpoint}/v1/traces",
31
        client_certificate_file=os.environ.get("OTLP_CLIENT_CERTIFICATE"),
32
        client_key_file=os.environ.get("OTLP_CLIENT_KEY"),
33
        timeout=30,  # mTLS 첫 연결 시 SSL 세션 설정 시간 필요
34
    )
35

36
def get_tracer_provider():
37
    from opentelemetry.sdk.trace import TracerProvider
38
    from opentelemetry.sdk.trace.export import SimpleSpanProcessor
39
    from opentelemetry.sdk.resources import Resource
40

41
    exporter = get_otlp_exporter()
42
    if not exporter:
43
        return None
44

45
    resource = Resource.create({
46
        "service.name": "claude-code-hook",
47
        "service.version": "1.0.0",
48
    })
49

50
    provider = TracerProvider(resource=resource)
51
    provider.add_span_processor(SimpleSpanProcessor(exporter))
52
    return provider
53

54
def save_state(session_id, data):
55
    (STATE_DIR / f"otlp-{session_id}.json").write_text(json.dumps(data))
56

57
def load_state(session_id):
58
    state_file = STATE_DIR / f"otlp-{session_id}.json"
59
    if state_file.exists():
60
        return json.loads(state_file.read_text())
61
    return {}
62

63
def create_parent_context(trace_id_hex, span_id_hex):
64
    """저장된 trace/span ID로 parent context를 재구성합니다."""
65
    from opentelemetry import trace
66
    from opentelemetry.trace import SpanContext, TraceFlags
67

68
    parent_context = SpanContext(
69
        trace_id=int(trace_id_hex, 16),
70
        span_id=int(span_id_hex, 16),
71
        is_remote=False,
72
        trace_flags=TraceFlags(TraceFlags.SAMPLED),
73
    )
74
    return trace.set_span_in_context(trace.NonRecordingSpan(parent_context))
75

76
def handle_session_start(data, provider):
77
    """세션 시작 시 root span을 생성하고 context를 저장합니다."""
78
    tracer = provider.get_tracer("claude-code-hook")
79
    session_id = data.get("session_id", "unknown")
80

81
    with tracer.start_as_current_span("session") as span:
82
        span.set_attribute("session.id", session_id)
83
        span.set_attribute("session.cwd", data.get("cwd", ""))
84

85
        # child span을 위해 trace context 저장
86
        ctx = span.get_span_context()
87
        save_state(session_id, {
88
            "trace_id": format(ctx.trace_id, '032x'),
89
            "span_id": format(ctx.span_id, '016x'),
90
        })
91

92
def handle_post_tool_use(data, provider):
93
    """도구 사용을 세션의 child span으로 기록합니다."""
94
    from opentelemetry.context import attach, detach
95

96
    session_id = data.get("session_id", "unknown")
97
    tool_name = data.get("tool_name", "unknown")
98
    state = load_state(session_id)
99
    tracer = provider.get_tracer("claude-code-hook")
100

101
    # 저장된 context를 parent로 설정
102
    token = None
103
    if state.get("trace_id") and state.get("span_id"):
104
        token = attach(create_parent_context(state["trace_id"], state["span_id"]))
105

106
    try:
107
        with tracer.start_as_current_span(f"tool:{tool_name}") as span:
108
            span.set_attribute("session.id", session_id)
109
            span.set_attribute("tool.name", tool_name)
110
    finally:
111
        if token:
112
            detach(token)
113

114
def main():
115
    input_data = json.load(sys.stdin)
116
    hook_event = input_data.get("hook_event_name", "")
117

118
    provider = get_tracer_provider()
119
    if not provider:
120
        sys.exit(0)
121

122
    if hook_event == "SessionStart":
123
        handle_session_start(input_data, provider)
124
    elif hook_event == "PostToolUse":
125
        handle_post_tool_use(input_data, provider)
126

127
    provider.force_flush()
128

129
if __name__ == "__main__":
130
    main()

스크립트에 실행 권한을 부여합니다:

1
chmod +x ~/.claude/hooks/otlp-tracer.py

Note: 첫 실행 시 uv가 의존성을 자동으로 다운로드합니다. 이후에는 캐시된 패키지를 사용하므로 빠르게 실행됩니다.

2. settings.json 설정

~/.claude/settings.json에 환경변수와 Hook을 등록합니다.

1
{
2
  "env": {
3
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otel-http.heeho.net",
4
    "OTLP_CLIENT_CERTIFICATE": "~/.certs/otlp/mac-client.crt",
5
    "OTLP_CLIENT_KEY": "~/.certs/otlp/mac-client.key",
6
    "REQUESTS_CA_BUNDLE": "/etc/ssl/cert.pem"
7
  },
8
  "hooks": {
9
    "SessionStart": [
10
      {
11
        "hooks": [
12
          {
13
            "type": "command",
14
            "command": "~/.claude/hooks/otlp-tracer.py",
15
            "timeout": 30
16
          }
17
        ]
18
      }
19
    ],
20
    "PostToolUse": [
21
      {
22
        "matcher": "*",
23
        "hooks": [
24
          {
25
            "type": "command",
26
            "command": "~/.claude/hooks/otlp-tracer.py",
27
            "timeout": 30
28
          }
29
        ]
30
      }
31
    ]
32
  }
33
}

주요 환경변수:

환경변수	설명
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP 엔드포인트 (mTLS 적용)
`OTLP_CLIENT_CERTIFICATE`	클라이언트 인증서 경로
`OTLP_CLIENT_KEY`	클라이언트 개인키 경로
`REQUESTS_CA_BUNDLE`	CA 번들 (macOS: `/etc/ssl/cert.pem`)

3. 동작 확인

Claude Code를 실행하고 Ingress 로그를 확인합니다:

1
kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx --tail=10 \
2
  | grep "OTel-OTLP-Exporter-Python"

결과:

1
"POST /v1/traces HTTP/1.1" 200 ... "OTel-OTLP-Exporter-Python/1.39.1" ... [observability-alloy-4318]

Python OTLP exporter가 mTLS 인증서로 Alloy에 trace를 전송한 것을 확인할 수 있습니다.

Tempo에서 trace를 조회하면 Claude Code 세션과 도구 사용 기록을 확인할 수 있습니다.

Tempo trace 조회

트러블슈팅

gRPC vs HTTP 프로토콜 선택

증상: gRPC 프로토콜로 OTLP 엔드포인트에 연결 실패

원인: Nginx Ingress를 통한 gRPC는 추가 설정 필요

gRPC는 HTTP/2 기반이지만, HTTPS 엔드포인트와 직접 호환되지 않습니다. Nginx Ingress를 통해 gRPC를 사용하려면:

backend-protocol: "GRPC" annotation 필요
클라이언트가 gRPC over TLS를 지원해야 함
일부 OTEL SDK는 이 조합에서 호환성 이슈 발생

해결: HTTP 프로토콜(http/protobuf)을 사용하고, OTLP HTTP 포트(4318)를 노출

프로토콜	전송 방식	Ingress 설정	호환성
`grpc`	HTTP/2 + Protobuf	`backend-protocol: "GRPC"`	일부 클라이언트 이슈
`http/protobuf`	HTTP/1.1 + Protobuf	기본 HTTP	대부분 호환

Python SDK의 OTLPSpanExporter는 HTTP 프로토콜을 사용하므로 별도 설정 없이 mTLS와 잘 동작합니다.

정리

외부 OTLP 엔드포인트에 mTLS를 적용하면:

요청	결과
인증서 없음	400 Bad Request
잘못된 인증서	400 Bad Request
올바른 인증서	200 OK (Alloy 도달)

최종 아키텍처:

1
Claude Code Hook (SessionStart, PostToolUse)
2
       ↓
3
  otlp-tracer.py (OpenTelemetry Python SDK)
4
       ↓ mTLS (클라이언트 인증서)
5
  Nginx Ingress (otel-http.heeho.net)
6
       ↓
7
  Alloy (OTLP Receiver :4318)
8
       ↓
9
  Tempo (Traces)

DevOps 관점에서 얻은 것:

Zero Trust 네트워크: 클러스터 외부 통신도 상호 인증
Observability 파이프라인 보안: 텔레메트리 데이터 위변조 방지
Kubernetes Ingress 활용: 애플리케이션 변경 없이 mTLS 적용
Claude Code 확장성: Hook 시스템으로 다양한 텔레메트리 통합 가능

OpenTelemetry 공식 문서에서도 프로덕션 환경에 mTLS를 권장합니다. 외부에서 OTLP 데이터를 받아야 한다면 mTLS 적용을 고려해보세요.

mTLS로 OTLP 엔드포인트 보호하기 (feat. Claude Code Hook)

클러스터 외부에서 OTLP Collector에 접근하려면

OTLP 엔드포인트 보안 방법

왜 TLS가 아니라 mTLS인가?

mTLS를 선택한 이유

아키텍처

인증서 생성하기

1. CA (Certificate Authority) 생성

2. 클라이언트 인증서 생성

생성된 파일 구조

Kubernetes 설정하기

1. CA 인증서를 Secret으로 등록

2. Alloy Ingress 설정

3. Helm 배포

mTLS 동작 확인하기

테스트 1: 인증서 없이 접근

테스트 2: 인증서로 접근

테스트 3: 잘못된 인증서로 접근

Claude Code Hook 연동하기

1. OTLP Tracer Hook 스크립트

2. settings.json 설정

3. 동작 확인

트러블슈팅

gRPC vs HTTP 프로토콜 선택

정리

참고 자료

관련 콘텐츠

HTTP/2와 gRPC 이해하기

LinkedIn에서 발견한 Tencent WeKnora, GraphRAG PoC하고 PR까지 Merged

Claude Code로 포트폴리오 + 기술 블로그 운영하기

댓글

삶을 기록하는 두 축

클러스터 외부에서 OTLP Collector에 접근하려면

OTLP 엔드포인트 보안 방법

왜 TLS가 아니라 mTLS인가?

mTLS를 선택한 이유

아키텍처

인증서 생성하기

1. CA (Certificate Authority) 생성

2. 클라이언트 인증서 생성

생성된 파일 구조

Kubernetes 설정하기

1. CA 인증서를 Secret으로 등록

2. Alloy Ingress 설정

3. Helm 배포

mTLS 동작 확인하기

테스트 1: 인증서 없이 접근

테스트 2: 인증서로 접근

테스트 3: 잘못된 인증서로 접근

Claude Code Hook 연동하기

1. OTLP Tracer Hook 스크립트

2. settings.json 설정

3. 동작 확인

트러블슈팅

gRPC vs HTTP 프로토콜 선택

정리

참고 자료

관련 콘텐츠

HTTP/2와 gRPC 이해하기

LinkedIn에서 발견한 Tencent WeKnora, GraphRAG PoC하고 PR까지 Merged

Claude Code로 포트폴리오 + 기술 블로그 운영하기

댓글