# googlecontainertools/distroless architecture

> Architecture diagram of the GitHub repository googlecontainertools/distroless, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlecontainertools/distroless
- Repository: https://github.com/googlecontainertools/distroless

## Overview

Distroless provides minimal Debian-based container images containing an application’s runtime dependencies, without package managers or shells. The user-facing workflow is to select a suitable image, add the application artifact (commonly through a multi-stage build), then run the resulting container. The tree identifies image-family definitions, OCI helpers, package metadata tools, and signing code; the README documents the product’s image families and verification guidance. Several implementation links are therefore shown as unverified rather than inferred from directory names.

Main entry points: [`private/oci/defs.bzl`](https://github.com/googlecontainertools/distroless/blob/main/private/oci/defs.bzl) (OCI definitions), [`base/base.bzl`](https://github.com/googlecontainertools/distroless/blob/main/base/base.bzl) (Base images), [`static/static.bzl`](https://github.com/googlecontainertools/distroless/blob/main/static/static.bzl) (Static images), [`cc/cc.bzl`](https://github.com/googlecontainertools/distroless/blob/main/cc/cc.bzl) (C/C++ images)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_base["Base images"]
  node_debian["Debian 13 inputs"]
  node_static["Static images<br/>[static.bzl]"]
  node_baseimg["Base images<br/>[base.bzl]"]
  node_cc["C/C++ images<br/>[cc.bzl]"]
end

subgraph group_runtimes["Language runtimes"]
  node_java["Java images<br/>[java.bzl]"]
  node_node["Node.js images<br/>[nodejs.bzl]"]
  node_python["Python images<br/>[python.bzl]"]
  node_go["Go image helper<br/>[go_image.bzl]"]
  node_rust["Rust image helper<br/>[rust_image.bzl]"]
  node_javahelper["Java image helper<br/>[java_image.bzl]"]
  node_cchelper["C/C++ image helper<br/>[cc_image.bzl]"]
end

subgraph group_assembly["Image assembly"]
  node_oci["OCI definitions<br/>[defs.bzl]"]
  node_sign["Image signing<br/>[sign_and_push.bzl]"]
end

subgraph group_metadata["Image metadata"]
  node_debspdx["Debian SPDX<br/>[debian_spdx.go]"]
  node_pkgspdx["Package SPDX<br/>[package_spdx.go]"]
  node_ocispdx["Image SPDX<br/>[oci_image_spdx.go]"]
end

subgraph group_consumption["Image use"]
  node_container["Distroless container"]
end

node_user(("Image user"))
node_app["Application artifact"]

node_user -->|"selects image"| node_static
node_user -->|"selects image"| node_baseimg
node_user -->|"selects image"| node_cc
node_user -->|"selects image"| node_java
node_user -->|"selects image"| node_node
node_user -->|"selects image"| node_python
node_app -->|"copies into"| node_container
node_debian -.->|"provides base"| node_baseimg
node_static -.->|"assembles image"| node_oci
node_baseimg -.->|"assembles image"| node_oci
node_cc -.->|"uses helper"| node_cchelper
node_java -.->|"uses helper"| node_javahelper
node_node -.->|"assembles image"| node_oci
node_python -.->|"assembles image"| node_oci
node_go -.->|"builds image"| node_oci
node_rust -.->|"builds image"| node_oci
node_oci -.->|"produces image"| node_container
node_sign -.->|"signs image"| node_container
node_user -->|"verifies image"| node_sign
node_debspdx -.->|"records package data"| node_pkgspdx
node_ocispdx -.->|"describes image"| node_container

click node_debian "https://github.com/googlecontainertools/distroless/tree/main/private/repos/deb"
click node_static "https://github.com/googlecontainertools/distroless/blob/main/static/static.bzl"
click node_baseimg "https://github.com/googlecontainertools/distroless/blob/main/base/base.bzl"
click node_cc "https://github.com/googlecontainertools/distroless/blob/main/cc/cc.bzl"
click node_java "https://github.com/googlecontainertools/distroless/blob/main/java/java.bzl"
click node_node "https://github.com/googlecontainertools/distroless/blob/main/nodejs/nodejs.bzl"
click node_python "https://github.com/googlecontainertools/distroless/blob/main/python3/python.bzl"
click node_go "https://github.com/googlecontainertools/distroless/blob/main/private/oci/go_image.bzl"
click node_rust "https://github.com/googlecontainertools/distroless/blob/main/private/oci/rust_image.bzl"
click node_javahelper "https://github.com/googlecontainertools/distroless/blob/main/private/oci/java_image.bzl"
click node_cchelper "https://github.com/googlecontainertools/distroless/blob/main/private/oci/cc_image.bzl"
click node_oci "https://github.com/googlecontainertools/distroless/blob/main/private/oci/defs.bzl"
click node_sign "https://github.com/googlecontainertools/distroless/blob/main/private/oci/sign_and_push.bzl"
click node_debspdx "https://github.com/googlecontainertools/distroless/blob/main/private/pkg/debian_spdx.go"
click node_pkgspdx "https://github.com/googlecontainertools/distroless/blob/main/private/pkg/package_spdx.go"
click node_ocispdx "https://github.com/googlecontainertools/distroless/blob/main/private/pkg/oci_image_spdx.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_debian,node_static,node_baseimg,node_cc,node_user toneBlue
class node_java,node_node,node_python,node_go,node_rust,node_javahelper,node_cchelper toneAmber
class node_oci,node_sign toneMint
class node_debspdx,node_pkgspdx,node_ocispdx toneRose
class node_container,node_app toneIndigo
```

## Components

### Base images

- [Debian 13 inputs](https://github.com/googlecontainertools/distroless/tree/main/private/repos/deb): `private/repos/deb`
- [Static images](https://github.com/googlecontainertools/distroless/blob/main/static/static.bzl): `static/static.bzl`
- [Base images](https://github.com/googlecontainertools/distroless/blob/main/base/base.bzl): `base/base.bzl`
- [C/C++ images](https://github.com/googlecontainertools/distroless/blob/main/cc/cc.bzl): `cc/cc.bzl`

### Language runtimes

- [Java images](https://github.com/googlecontainertools/distroless/blob/main/java/java.bzl): `java/java.bzl`
- [Node.js images](https://github.com/googlecontainertools/distroless/blob/main/nodejs/nodejs.bzl): `nodejs/nodejs.bzl`
- [Python images](https://github.com/googlecontainertools/distroless/blob/main/python3/python.bzl): `python3/python.bzl`
- [Go image helper](https://github.com/googlecontainertools/distroless/blob/main/private/oci/go_image.bzl): `private/oci/go_image.bzl`
- [Rust image helper](https://github.com/googlecontainertools/distroless/blob/main/private/oci/rust_image.bzl): `private/oci/rust_image.bzl`
- [Java image helper](https://github.com/googlecontainertools/distroless/blob/main/private/oci/java_image.bzl): `private/oci/java_image.bzl`
- [C/C++ image helper](https://github.com/googlecontainertools/distroless/blob/main/private/oci/cc_image.bzl): `private/oci/cc_image.bzl`

### Image assembly

- [OCI definitions](https://github.com/googlecontainertools/distroless/blob/main/private/oci/defs.bzl): `private/oci/defs.bzl`
- [Image signing](https://github.com/googlecontainertools/distroless/blob/main/private/oci/sign_and_push.bzl): `private/oci/sign_and_push.bzl`

### Image metadata

- [Debian SPDX](https://github.com/googlecontainertools/distroless/blob/main/private/pkg/debian_spdx.go): `private/pkg/debian_spdx.go`
- [Package SPDX](https://github.com/googlecontainertools/distroless/blob/main/private/pkg/package_spdx.go): `private/pkg/package_spdx.go`
- [Image SPDX](https://github.com/googlecontainertools/distroless/blob/main/private/pkg/oci_image_spdx.go): `private/pkg/oci_image_spdx.go`

### Image use

- **Distroless container**

### Other components

- **Image user**
- **Application artifact**

## Connections

- Image user → Static images: selects image (evidence: `README.md`)
- Image user → Base images: selects image (evidence: `README.md`)
- Image user → C/C++ images: selects image (evidence: `README.md`)
- Image user → Java images: selects image (evidence: `README.md`)
- Image user → Node.js images: selects image (evidence: `README.md`)
- Image user → Python images: selects image (evidence: `README.md`)
- Application artifact → Distroless container: copies into (evidence: `README.md`)
- Debian 13 inputs → Base images: provides base
- Static images → OCI definitions: assembles image
- Base images → OCI definitions: assembles image
- C/C++ images → C/C++ image helper: uses helper
- Java images → Java image helper: uses helper
- Node.js images → OCI definitions: assembles image
- Python images → OCI definitions: assembles image
- Go image helper → OCI definitions: builds image
- Rust image helper → OCI definitions: builds image
- OCI definitions → Distroless container: produces image
- Image signing → Distroless container: signs image
- Image user → Image signing: verifies image (evidence: `README.md`)
- Debian SPDX → Package SPDX: records package data
- Image SPDX → Distroless container: describes image
