From e5f8c19d0e38f77141c8410dd675685cc31cc473 Mon Sep 17 00:00:00 2001 From: Liakhovskyi Vladyslav Date: Thu, 27 Aug 2026 15:11:41 +0300 Subject: [PATCH] docs: define OS and base image policy Set Debian Trixie defaults and bounded exceptions across hosts, virtual environments, CI, and OCI runtimes. AI-Impact: co-developed AI: cx --- modules/common/doc.md | 1 + shared/os-and-base-images.md | 54 ++++++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+) create mode 100644 shared/os-and-base-images.md diff --git a/modules/common/doc.md b/modules/common/doc.md index d293738..e34b626 100644 --- a/modules/common/doc.md +++ b/modules/common/doc.md @@ -9,6 +9,7 @@ This module defines baseline rules that apply to every repository regardless of # Strict rules - MUST reuse Taskfile workflow rules for all projects: [../taskfile/doc.md](../taskfile/doc.md). +- MUST follow the organization-wide OS and base image selection policy: [shared/os-and-base-images.md](../../shared/os-and-base-images.md). - MUST use Taskfile as the default workflow runner across modules. - MUST keep this module scoped to repository-wide baseline rules only; stack-specific rules belong in stack modules. - MUST require `task validate` to pass before merge. diff --git a/shared/os-and-base-images.md b/shared/os-and-base-images.md new file mode 100644 index 0000000..19c8e92 --- /dev/null +++ b/shared/os-and-base-images.md @@ -0,0 +1,54 @@ +# Overview +This policy defines the organization-wide defaults for operating systems and OCI-compatible base images. +Apply it when creating an environment or changing its OS or base image. Do not migrate a working environment solely +to conform to this policy unless the task explicitly includes that migration. + +# Decision order +Select an OS or base image in this order: + +1. Correctness and compatibility with the workload. +2. Security updates and upstream support. +3. Operability, including diagnostics and recovery. +4. Measured energy, CPU, memory, storage, and network efficiency. + +Image size alone does not demonstrate lower runtime energy consumption. Measure the real workload when energy or +resource efficiency is a goal. + +# Standard selection +Use this table before considering an alternative distribution or image family. + +| Environment | Default | Use when | +| --- | --- | --- | +| Bare metal, VM, CI runner, development environment, or other general-purpose environment | Debian Trixie | The environment needs a complete, stable OS and Debian is supported by the platform and workload. | +| OCI build, test, CI, or debugging stage | A Debian Trixie variant of the upstream tool image, otherwise `debian:trixie` | The stage needs a shell, package manager, build toolchain, or broader userspace. | +| OCI production runtime for a fully static binary | `gcr.io/distroless/static-debian13:nonroot` | The binary requires neither libc nor a shell or package manager. For Go, this normally means a build with `CGO_ENABLED=0`. | +| OCI production runtime with OS-level dependencies | `debian:trixie-slim` | The application needs glibc, shared libraries, runtime Debian packages, or shell-based diagnostics. | +| Third-party language, tool, application, or infrastructure service | Its supported Debian-based image variant | Upstream publishes and supports a Debian-based variant. Prefer Trixie when available. | + +Debian Trixie is the default OS release. Use an explicit release codename or version instead of floating aliases such +as `latest`. See the [Debian Trixie release information](https://www.debian.org/releases/trixie/) and the +[Debian Official Image](https://hub.docker.com/_/debian). + +# Strict rules +- MUST use Debian Trixie when selecting an OS for bare metal, virtual machines, CI runners, development environments, and other general-purpose environments unless an exception below applies. +- MUST prefer a supported Debian Trixie variant of a language, tool, application, or service image when upstream provides one. +- MUST use `debian:trixie` for custom general-purpose OCI build, test, CI, and debugging stages that need a shell, package manager, or broader userspace. +- MUST use `debian:trixie-slim` for production OCI runtimes that need glibc, shared libraries, runtime Debian packages, or shell-based diagnostics. +- MUST use `gcr.io/distroless/static-debian13:nonroot` for production OCI runtimes containing fully static binaries that need neither libc nor a shell or package manager. +- MUST separate build and runtime stages with a multi-stage build when the build environment contains tools or dependencies that the runtime does not need. +- MUST run production workloads as a non-root user unless the workload has a documented technical requirement for root. +- MUST verify required runtime assets, including CA certificates, timezone data, user and group entries, writable directories, and dynamic libraries. +- MUST NOT select an OS or base image from compressed size alone. +- MUST NOT migrate an existing working environment solely to enforce this policy unless migration is in scope for the task. + +The Distroless project documents the static image's contents, supported Debian 13 tags, and lack of a shell and package +manager in its [official repository](https://github.com/GoogleContainerTools/distroless). + +# Situational alternatives +- MAY use Alpine when upstream requires or explicitly recommends it, or when a measured footprint constraint justifies it and musl compatibility is verified by the relevant tests. +- MAY use Ubuntu LTS when hardware enablement, vendor support, CI infrastructure, or the hosting platform requires it. +- MUST prefer a supported Debian-based upstream image over another upstream variant unless maintainers explicitly recommend otherwise. +- MUST use the upstream official image when third-party software has no supported Debian-based image. +- MUST NOT rebuild third-party software images on Debian solely to satisfy the Debian default. +- MUST document which condition justified a situational alternative in the change or pull request. +- MUST obtain explicit user `Accept` before selecting any OS distribution or base image family not covered by this policy, and MUST document the approved exception in the relevant `Strict rules` section.