From f097385908a5c51cf7fd3b513bc87f8c63b386ee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Niccol=C3=B2=20Fei?= <niccolo.fei@enterprisedb.com>
Date: Tue, 9 Sep 2025 12:35:33 +0200
Subject: [PATCH] chore: migrate rolling tags to bake system images (#297)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #284
Closes #285

Signed-off-by: Niccolò Fei <niccolo.fei@enterprisedb.com>
Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
Co-authored-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
---
 README.md       | 51 +++++++++++++++++++++++++++++++++++++++++++++++++
 docker-bake.hcl | 14 +++++++++++---
 2 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 68d29c12..d7a7ff3c 100644
--- a/README.md
+++ b/README.md
@@ -118,6 +118,57 @@ and include Barman Cloud binaries.
 > should plan to migrate to either a `minimal` or `standard` image together
 > with the Barman Cloud plugin—or adopt another supported backup solution.
 
+## Image Tags
+
+Each image is identified by its digest and a main tag of the form:
+
+```
+MM.mm-TS-TYPE-OS
+```
+
+where:
+
+- `MM` is the PostgreSQL major version (e.g. `16`)
+- `mm` is the PostgreSQL minor version (e.g. `10`)
+- `TS` is the build timestamp with minute precision (e.g. `202509090953`)
+- `TYPE` is image type (e.g. `minimal`)
+- `OS` is the underlying distribution (e.g. `trixie`)
+
+For example: `16.10-202509090953-minimal-trixie`.
+
+### Rolling Tags
+
+In addition to fully qualified tags, rolling tags are available in the
+following formats:
+
+- `MM.mm-TYPE-OS`: latest image for a given PostgreSQL *minor* version
+  (`16.10`) of a specific type (`minimal`) on a Debian version (`trixie`).
+  For example: `16.10-minimal-trixie`.
+- `MM-TYPE-OS`: latest image for a given PostgreSQL *major* version (`16`) of
+  a specific type (`minimal`) on a Debian version (`trixie`).
+  For example: `16-minimal-trixie`.
+
+### Recommendation
+
+While the most reliable way to reference an image is by its digest, the
+`MM.mm-TYPE-OS` tag usually provides a good balance between stability and
+convenience for most use cases.
+
+### Deprecated Rolling Tags
+
+For historical reasons, the `system` image also carries two additional rolling
+tags:
+
+- `MM.mm`: latest `system` image for a given PostgreSQL *minor* version (e.g.
+  `16.10`) on Debian `bullseye`.
+- `MM`: latest `system` image for a given PostgreSQL *major* version (e.g.
+  `16`) on Debian `bullseye`.
+
+**IMPORTANT:** These tags are **deprecated** and will be **removed when
+`bullseye` images reach end of life**. Please migrate to one of the supported
+tag formats that explicitly include both the **image type** and the
+**distribution version** (e.g. `16.10-minimal-trixie`).
+
 ## Build Attestations
 
 CNPG PostgreSQL Container Images are built with the following attestations to
diff --git a/docker-bake.hcl b/docker-bake.hcl
index 372424a3..36f754c8 100644
--- a/docker-bake.hcl
+++ b/docker-bake.hcl
@@ -70,11 +70,11 @@ target "default" {
   ]
   dockerfile = "Dockerfile"
   name = "postgresql-${index(split(".",cleanVersion(pgVersion)),0)}-${tgt}-${distroVersion(base)}"
-  tags = [
+  tags = concat([
     "${fullname}:${index(split(".",cleanVersion(pgVersion)),0)}-${tgt}-${distroVersion(base)}",
     "${fullname}:${cleanVersion(pgVersion)}-${tgt}-${distroVersion(base)}",
-    "${fullname}:${cleanVersion(pgVersion)}-${formatdate("YYYYMMDDhhmm", now)}-${tgt}-${distroVersion(base)}"
-  ]
+    "${fullname}:${cleanVersion(pgVersion)}-${formatdate("YYYYMMDDhhmm", now)}-${tgt}-${distroVersion(base)}",
+  ], (tgt == "system" && distroVersion(base) == "bullseye") ? getRollingTags("${fullname}", pgVersion) : [])
   context = "."
   target = "${tgt}"
   args = {
@@ -170,3 +170,11 @@ function getPgVersions {
     ]
   )
 }
+
+function getRollingTags {
+    params = [ imageName, pgVersion ]
+    result = [
+      format("%s:%s", imageName, pgVersion),
+      format("%s:%s", imageName, getMajor(pgVersion))
+    ]
+}