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

---
title: "Kubernetes Logging Architecture — Official Docs"
source_type: official-doc
url: https://kubernetes.io/docs/concepts/cluster-administration/logging/
archive_url:
vendor: Kubernetes / CNCF
related_branches: [feature-log-management-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, observability, kubernetes, stdout-logging, log-routing]
created: 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](https://12factor.net/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]]` (생성 시)