From ca8f01fa94a5275ab990a573476f30f30b22c634 Mon Sep 17 00:00:00 2001 From: Marco Nenciarini Date: Fri, 5 Dec 2025 13:40:29 +0100 Subject: [PATCH] docs: add image labels and annotations documentation Add comprehensive documentation section describing OCI-compliant labels and CloudNativePG-specific annotations available in extension images. This documents the labels added in #43, including pgmajor and OS distribution metadata, plus standard OCI image specification labels. Relates to #43 Signed-off-by: Marco Nenciarini --- README.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/README.md b/README.md index 597e271..faf8582 100644 --- a/README.md +++ b/README.md @@ -117,3 +117,44 @@ This scheme ensures: - Alignment with the upstream `postgres-containers` base images - Explicit PostgreSQL and extension versioning - Multi-distro support + +--- + +## Image Labels + +Each extension image includes OCI-compliant labels for runtime inspection +and tooling integration. These metadata fields enable CloudNativePG and +other tools to identify the base PostgreSQL version and OS distribution. + +### CloudNativePG-Specific Labels + +| Label | Description | Example | +| :--- | :--- | :--- | +| `io.cloudnativepg.image.base.name` | Base PostgreSQL container image | `ghcr.io/cloudnative-pg/postgresql:18-minimal-bookworm` | +| `io.cloudnativepg.image.base.pgmajor` | PostgreSQL major version | `18` | +| `io.cloudnativepg.image.base.os` | Operating system distribution | `bookworm` | + +### Standard OCI Labels + +In addition to CloudNativePG-specific labels, all images include standard OCI +annotations as defined by the [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/main/annotations.md): + +| Label | Description | +| :--- | :--- | +| `org.opencontainers.image.created` | Image creation timestamp | +| `org.opencontainers.image.version` | Extension version | +| `org.opencontainers.image.revision` | Git commit SHA | +| `org.opencontainers.image.title` | Human-readable image title | +| `org.opencontainers.image.description` | Image description | +| `org.opencontainers.image.source` | Source repository URL | +| `org.opencontainers.image.licenses` | License identifier (Apache-2.0) | + +You can inspect these labels using container tools: + +```bash +# Using docker buildx imagetools +docker buildx imagetools inspect --raw | jq '.annotations' + +# Using skopeo +skopeo inspect docker:// | jq '.Labels' +```