110 lines
8.8 KiB
Markdown
110 lines
8.8 KiB
Markdown
---
|
|
title: "GoogleContainerTools/distroless — Language focused docker images, minus the operating system"
|
|
source_type: official-doc
|
|
url: https://github.com/GoogleContainerTools/distroless
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-skeleton, container, runtime, distroless, base-image, security, official-doc, branch:feature-container-runtime-contract]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-container-runtime-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# GoogleContainerTools/distroless — Language focused docker images, minus the operating system
|
|
|
|
> Layer: `raw/official-docs/` — Google이 maintain 하는 distroless base image 프로젝트 README 원문 발췌.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-container-runtime-contract]] | Group G-D container runtime 대안 1 (Distroless) 의 baseline 사실 — image size, shell 부재, `:debug` variant 의 정확한 정의 |
|
|
|
|
특정 branch 없이 foundational 조사로 수집한 경우:
|
|
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] — ca-tmpl base image default 의사결정의 외부 비교 기준
|
|
|
|
## 컨텍스트 / 왜 저장했는지
|
|
|
|
ca-tmpl `feature-container-runtime-contract` 의 결정 — base image 기본값은 **Temurin JRE slim** 이고 distroless 는 "debug runbook 보강 후 허용"으로 제한됨. 본 source 는 대안 1: **Distroless Java** 채택 시 trade-off 를 baseline 으로 비교하기 위한 원문.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://github.com/GoogleContainerTools/distroless
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: Google Container Tools
|
|
- 발행일: 지속 업데이트 (README 기준, fetched 2026-05-27)
|
|
- 마지막 확인일: 2026-05-27
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§What are distroless images] "'Distroless' images contain only your application and its runtime dependencies."
|
|
|
|
> [§What are distroless images] "They do not contain package managers, shells or any other programs you would expect to find in a standard Linux distribution."
|
|
|
|
> [§Why use distroless] "Restricting what's in your runtime container to precisely what's necessary for your app is a best practice employed by Google and other tech giants."
|
|
|
|
> [§Why use distroless] "It improves the signal to noise of scanners (e.g. CVE) and reduces the burden of establishing provenance to just what you need."
|
|
|
|
> [§Image sizes] "The smallest distroless image, `gcr.io/distroless/static-debian13`, is around 2 MiB. That's about 50% of the size of `alpine` (~5 MiB), and less than 2% of the size of `debian` (124 MiB)."
|
|
|
|
> [§Debug images] "Distroless images are minimal and lack shell access. The `:debug` image set for each language provides a busybox shell to enter."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| CDG-C1 | Distroless 이미지는 application 과 runtime dependency 만 포함하고 package manager · shell · 기타 표준 Linux distribution 의 일반 도구를 포함하지 않는다 | [§What are distroless images] "'Distroless' images contain only your application and its runtime dependencies. They do not contain package managers, shells or any other programs you would expect to find in a standard Linux distribution." | `official-vendor-doc` | distroless `:nonroot` / `:latest` (non-debug) variants | distroless 가 모든 언어 런타임에 동일 형태로 제공된다는 뜻은 아님 — Java/Python/Node 등 variant 별 차이 있음 |
|
|
| CDG-C2 | distroless 채용 명분은 "runtime container 에 정확히 필요한 것만 두는 것" 이며 Google 및 다른 대기업이 채택한 best practice 로 기술됨 | [§Why use distroless] "Restricting what's in your runtime container to precisely what's necessary for your app is a best practice employed by Google and other tech giants." | `official-vendor-doc` | container 최소화 정책 일반 | "best practice" 가 industry-wide consensus 라는 의미는 아님 — Google 의 self-claim |
|
|
| CDG-C3 | distroless 는 CVE scanner 의 signal-to-noise 를 개선하고 provenance 입증 부담을 application 의존성으로 한정한다 | [§Why use distroless] "It improves the signal to noise of scanners (e.g. CVE) and reduces the burden of establishing provenance to just what you need." | `official-vendor-doc` | supply-chain security 정책 (SBOM/SLSA) 채택 환경 | 구체적 CVE 감소 수치 / 특정 scanner 와의 정합성은 본 인용 범위 밖 |
|
|
| CDG-C4 | `gcr.io/distroless/static-debian13` 이미지 크기는 약 2 MiB 로 alpine (~5 MiB) 의 약 50%, debian (124 MiB) 의 2% 미만이다 | [§Image sizes] "The smallest distroless image, `gcr.io/distroless/static-debian13`, is around 2 MiB. That's about 50% of the size of `alpine` (~5 MiB), and less than 2% of the size of `debian` (124 MiB)." | `official-vendor-doc` | `static-debian13` distroless variant (Java/Python 런타임 포함 variant 는 더 큼) | Java/Python 런타임 포함 distroless 이미지의 크기는 본 인용에 명시되지 않음 — Java distroless 는 JRE 포함으로 수십 MB |
|
|
| CDG-C5 | distroless 이미지는 shell 이 없으며, debugging 용도로는 각 언어별 `:debug` variant 가 busybox shell 을 제공한다 | [§Debug images] "Distroless images are minimal and lack shell access. The `:debug` image set for each language provides a busybox shell to enter." | `official-vendor-doc` | `:debug` tag 가 제공되는 언어별 distroless 이미지 | `kubectl exec` 외의 진단 방법 (ephemeral container, sidecar) 의 가능 여부는 본 인용 범위 밖 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `CDG-C1`: distroless 의 정의 (package manager/shell 부재)
|
|
- `CDG-C2`, `CDG-C3`: Google 의 채택 명분 (CVE noise 감소, provenance 단순화) — **Google self-claim 임을 명시**
|
|
- `CDG-C4`: `static-debian13` variant 의 정확한 크기 비교 baseline
|
|
- `CDG-C5`: `:debug` variant 의 존재와 busybox shell 제공 사실
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- distroless 가 모든 production 환경에서 정답이라는 일반화 — Google 의 self-claim 이며 official-standard 가 아님
|
|
- Java distroless (`gcr.io/distroless/java-debian12` 등) 의 정확한 이미지 크기 (README 의 2 MiB 는 `static-debian13` 기준)
|
|
- distroless 채택 시 jcmd/jstack/heap dump 같은 in-container 진단의 대체 워크플로우
|
|
- SLSA/SBOM 정책과의 자동 정합성 (별도 cosign/sigstore 설정 필요)
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- ca-tmpl 에서 Spring Boot fat jar + Temurin JRE 를 distroless `java` variant 로 옮길 때의 실제 image 크기 측정
|
|
- `:debug` variant 의 prod-time 사용 정책 (rollback 시점, ops on-call 의 권한 모델)
|
|
- `kubectl debug --image=...` ephemeral container 패턴으로 distroless prod pod 디버깅이 가능한지 검증
|
|
|
|
## 메모 / Notes (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용 아님. ca-tmpl `feature-container-runtime-contract` 결정 컨텍스트 해석.
|
|
|
|
- 적용 시나리오: 보안 요구가 강한 prod 환경, supply chain risk surface 축소가 우선인 경우.
|
|
- 장점:
|
|
- shell/package manager 부재로 공격 표면이 좁다 (CVE count 감소).
|
|
- 이미지 크기가 매우 작다 (단, Java distroless 는 JRE 포함으로 README 의 2 MiB 보다 큼).
|
|
- SLSA / SBOM 정책과 잘 맞는다 (Google 이 직접 sign).
|
|
- 단점:
|
|
- shell 이 없어 `kubectl exec` 디버깅 불가. `:debug` variant 또는 ephemeral container 필요.
|
|
- heap dump 추출, jcmd, jstack 같은 in-container 진단이 어렵다 (별도 sidecar 또는 외부 도구 필요).
|
|
- JDK 가 아닌 JRE 만 들어있어 application 측 진단 도구 호출 시 빌드 단계에서 같이 packaging 필요.
|
|
- ca-tmpl 과의 차이: ca-tmpl 은 Temurin JRE slim 을 기본값으로 두어 운영자 친숙도와 디버깅 가능성을 우선. distroless 는 "debug runbook 이 있을 때만 허용".
|
|
- testability 영향: 중립 — 빌드는 multi-stage 로 동일 패턴.
|
|
- 보안 영향: 상 — CVE surface 감소가 가장 큰 이점.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc:
|
|
- [[raw/official-docs/container-alpine-java-musl-tradeoffs]] — 대안 2 Alpine + Temurin
|
|
- [[raw/official-docs/container-graalvm-native-image-spring-boot]] — 대안 3 GraalVM native-image
|
|
- 적용 branch-note:
|
|
- [[raw/branch-notes/feature-container-runtime-contract]]
|
|
- canonical contract 섹션:
|
|
- `wiki/projects/ca-skeleton-operational-contract` 의 container runtime canonical section (예정)
|
|
- 대안 그룹: **Group G-D — Container runtime** (대안 5종: Temurin JRE slim / Distroless / Alpine+Temurin / GraalVM native-image / Multi-stage debug variant)
|
|
- 본 source 의 위치: 대안 1 — Distroless (Google)
|