llm-wiki/raw/official-docs/k8s-logging-architecture-kubernetes-official.md

title, source_type, url, archive_url, vendor, related_branches, related_projects, tags, created

title	source_type	url	archive_url	vendor	related_branches	related_projects	tags	created
Kubernetes Logging Architecture — Official Docs	official-doc	https://kubernetes.io/docs/concepts/cluster-administration/logging/		Kubernetes / CNCF	feature-log-management-contract	ca-skeleton	official-doc ca-skeleton observability kubernetes stdout-logging log-routing	2026-06-13

Kubernetes Logging Architecture — Official Docs

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 source-summary-template 형식으로 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch (필수)

이 자료는 D4(production logging = stdout JSON default) 를 UNSUPPORTED_DECISION 에서 official-vendor-doc 증거 기반 결정으로 승격시키기 위해 수집되었다.

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-log-management-contract	D4: production logging = stdout JSON default — Kubernetes 공식 문서가 (a) stdout/stderr 직접 출력을 가장 권장 방식으로 명시, (b) streaming sidecar(file-tail)는 stdout 쓰기 불가 앱 전용 폴백, (c) file → stdout 이중 경로는 디스크 사용 2배 경고, (d) 단일 파일 앱은 /dev/stdout 목적지 설정 권장

출처 / Source

• 원본 URL: https://kubernetes.io/docs/concepts/cluster-administration/logging/
• 아카이브 URL: (미등록)
• 저자 / 조직: Kubernetes / CNCF
• 발행일: (지속 갱신 — CNCF 공식 문서)
• 마지막 확인일: 2026-06-13

왜 저장했는지 / Why archived

feature-log-management-contract D4 (production logging = stdout JSON default) 가 UNSUPPORTED_DECISION 상태로 표기되어 있었고, K8s 공식 문서가 이를 직접 뒷받침한다. stdout/stderr 직접 쓰기 권장, streaming sidecar 폴백 조건, 디스크 2배 경고, /dev/stdout 권장 — 네 가지 모두 원문 인용으로 확보하여 D4 승격 근거로 사용.

핵심 인용 / Key quotes (verbatim, 5문장)

[§ Pod and Container Logs — Basic Logging] "The easiest and most adopted logging method for containerized applications is writing to standard output and standard error streams."

[§ Streaming Sidecar Container] "This approach allows you to separate several log streams from different parts of your application, some of which can lack support for writing to stdout or stderr."

[§ Streaming Sidecar Container — disk usage] "Even for Pods that only have low CPU and memory usage (order of a couple of millicores for cpu and order of several megabytes for memory), writing logs to a file and then streaming them to stdout can double how much storage you need on the node."

[§ Streaming Sidecar Container — /dev/stdout] "If you have an application that writes to a single file, it's recommended to set /dev/stdout as the destination rather than implement the streaming sidecar container approach."

[§ Log Rotation] "You can configure two kubelet configuration settings, containerLogMaxSize (default 10Mi) and containerLogMaxFiles (default 5), using the kubelet configuration file."

Claims Extracted / 추출된 주장

이 자료가 직접 말하는 것만 claim 으로 분리한다.

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
LOG-K8S-C1	Kubernetes 환경에서 컨테이너 앱의 권장 로깅 방법은 stdout/stderr 직접 출력이며, 이것이 가장 널리 채택된 방식이다	[§ Basic Logging] "The easiest and most adopted logging method for containerized applications is writing to standard output and standard error streams."	official-vendor-doc	Kubernetes 위에서 실행되는 모든 컨테이너 앱	stdout 이외 방법(file, syslog 등)이 잘못됐다는 뜻은 아님. 단지 stdout 이 가장 단순하고 채택률이 높다는 사실만 주장
LOG-K8S-C2	Streaming sidecar 방식은 stdout/stderr 직접 쓰기가 불가능한 앱을 위한 폴백이다	[§ Streaming Sidecar Container] "some of which can lack support for writing to stdout or stderr."	official-vendor-doc	stdout 쓰기가 불가능한 레거시 앱	"stdout 을 쓸 수 있는 앱" 에도 streaming sidecar 를 쓰는 것이 잘못됐다고 직접 금지하지는 않음. 단지 폴백 시나리오로 제시
LOG-K8S-C3	파일에 로그를 쓴 뒤 stdout 으로 스트리밍하면 노드 디스크 사용이 2배가 될 수 있다	[§ Streaming Sidecar Container — disk usage] "writing logs to a file and then streaming them to stdout can double how much storage you need on the node."	official-vendor-doc	파일 → stdout 이중 경로를 쓰는 모든 Kubernetes Pod	CPU/메모리가 낮아도 이 비용이 발생한다는 것. 실제 2배를 항상 보장하는 게 아니라 "can double" (가능성 경고)
LOG-K8S-C4	단일 파일에 로그를 쓰는 앱은 streaming sidecar 대신 /dev/stdout 을 목적지로 설정하는 것이 권장된다	[§ Streaming Sidecar Container — /dev/stdout] "If you have an application that writes to a single file, it's recommended to set /dev/stdout as the destination rather than implement the streaming sidecar container approach."	official-vendor-doc	단일 파일에만 로그를 쓰도록 설계된 앱	다중 파일 출력 앱(여러 로그 스트림이 필요한 앱)에 대한 권장이 아님. 다중 스트림 분리가 필요하면 streaming sidecar 가 합리적 선택 (C2)
LOG-K8S-C5	kubelet 의 로그 로테이션 기본값은 파일당 최대 10Mi(containerLogMaxSize), 파일 수 최대 5개(containerLogMaxFiles)이며 kubectl logs 는 최신 로그 파일만 반환한다	[§ Log Rotation] "You can configure two kubelet configuration settings, containerLogMaxSize (default 10Mi) and containerLogMaxFiles (default 5)."	official-vendor-doc	Kubernetes 클러스터의 모든 노드 (kubelet 기본 설정)	장기 보존(long-term retention)이 된다는 뜻이 아님. 기본값 10Mi 로테이션 후 kubectl logs 로는 이전 로그 조회 불가. 외부 로그 플랫폼(ELK, Loki, CloudWatch 등) 없이는 retention 보장 불가

Strength 사용 근거

official-vendor-doc — Kubernetes 는 CNCF 공식 관리 프로젝트이며 이 페이지는 공식 개념 문서(concepts documentation). IETF RFC 또는 ISO 표준이 아니므로 official-standard 가 아닌 official-vendor-doc.

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • LOG-K8S-C1: Kubernetes 에서 stdout/stderr 직접 쓰기가 권장 및 가장 널리 채택된 방법
  • LOG-K8S-C2: Streaming sidecar 는 stdout 직접 쓰기 불가 앱의 폴백
  • LOG-K8S-C3: file → stdout 이중 경로 시 디스크 2배 위험
  • LOG-K8S-C4: 단일 파일 앱에는 /dev/stdout 설정 권장
  • LOG-K8S-C5: kubelet 기본 로테이션 설정 (10Mi / 5 files) + kubectl logs 최신 파일만 반환
• 이 자료가 증명하지 않는 것:
  • 장기 로그 보존(30일/180일/365일 등) — 외부 로그 플랫폼이 필수 (LOG-K8S-C5)
  • containerLogMaxSize 기본값이 운영 환경에 최적이라는 것 — 운영 트래픽에 따라 조정 필요
  • JSON 구조화 로그가 stdout 으로 나가야 한다는 것 — 이 문서는 포맷이 아닌 목적지(stdout/stderr) 만 다룸
  • Streaming sidecar 가 항상 잘못된 선택이라는 것 — 다중 스트림 필요 앱에는 합리적 옵션
  • 12-Factor App의 XI(Logs) 원칙과 동일한 내용임 — 별도 확인 필요 (동일 방향이지만 이 문서가 12-Factor 를 직접 인용하지 않음)
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • ca-tmpl 의 logback-spring.xml 이 stdout 만 기본 출력하는지, FILE_ENABLED=false default 가 K8s 환경에서도 동일하게 동작하는지 (actually-implemented — LoggingSettings.java 확인됨)
  • 운영 환경의 kubelet 로그 로테이션 설정이 기본값(10Mi)을 유지하는지 / 별도 설정 여부

메모 / Notes

• LOG-K8S-C1 은 D4 (UNSUPPORTED_DECISION → official-vendor-doc 승격) 의 핵심 근거. feature-log-management-contract Decision Evidence Map D4 행 갱신 대상.
• LOG-K8S-C3/C4 는 ca-tmpl 의 FILE_ENABLED=true 를 prod 에 실수로 활성화했을 때의 위험 (file appender prod 오활성화 엣지 케이스) 을 공식 문서로 뒷받침.
• LOG-K8S-C5 는 kubectl logs 만으로는 운영 로그 조회가 불충분함을 증명 — 외부 플랫폼(Loki 등) 필요성 근거.
• 추가로 봐야 할 동일 출처 페이지: 12-Factor App XI. Logs — LOG-K8S-C1 과 방향 일치하는지 cross-check 권장.

Related / 관련

• raw/official-docs/log-logback-mask-pattern-converter-official — Logback PatternLayout/masking converter spec (D1/D10 근거)
• raw/official-docs/log-ecs-schema-elastic-official — ECS log schema 비교 (D6 근거)
• raw/official-docs/log-otel-log-data-model-spec — OTel log signal spec (D7 근거)
• 이 자료를 인용한 wiki 요약: [[wiki/concepts/kubernetes-logging-architecture]] (생성 시)