packaging/docker: gate releases on PPA readiness

rgerhards · rgerhards · commit 913709e55669 · 2026-03-20T18:46:16.000+01:00
Why: release-tagged container images should only be published after the
matching rsyslog packages are available in the correct Adiscon PPA.

Impact: manual release flows now use fixed stable and daily-stable
channels, derive the stable container tag automatically from
`RSYSLOG_VERSION`, and update `latest` only when explicitly requested.

Before/After: release-tagged image publishing was a manual sequence
without a package-availability gate or an explicit `latest` decision;
it is now an explicit release workflow with a lightweight PPA readiness
check and fixed channel rules.

Technical Overview:
The Docker image Makefile now adds explicit manual release targets:
`release_build`, `release_push`, and `release_publish`.

The stable channel uses `ppa:adiscon/v8-stable` and derives the image
tag from `RSYSLOG_VERSION` using `8.yymm.0` -&gt; `20yy-mm`. The
daily-stable channel uses `ppa:adiscon/daily-stable` and the fixed image
tag `daily-stable`.

Before any release build or push proceeds, a disposable Ubuntu container
checks that the selected channel exposes the requested rsyslog release
series. The real image build remains the source of truth for package
completeness.

`release_publish` updates `latest` only when `PUSH_LATEST=yes` is set.
The operator README now documents the channel rules, the stable tag
mapping, and the manual release workflow consistently with the Makefile.
AGENTS.md adds the same container guidance for future AI-driven changes.

With the help of AI-Agents: Codex
diff --git a/AGENTS.md b/AGENTS.md
@@ -37,6 +37,13 @@ Follow these three steps for a typical development task:
 - The container Makefile default version must stay clearly non-release.
   Use explicit `VERSION=...` values for release-like local rehearsals and for
   any publish automation.
+- Release-tagged container images are downstream of package publishing.
+  AI agents must not add or use release container flows that bypass the
+  Adiscon PPA readiness check.
+- Manual release flows use two fixed channels:
+  `stable` maps `8.yymm.0` to `20yy-mm` via `ppa:adiscon/v8-stable`,
+  and `daily-stable` uses `ppa:adiscon/daily-stable` with the fixed tag
+  `daily-stable`.
 - AI agents must not introduce release-looking fallback tags such as
   `2026-03` as the default local container build version.
 
diff --git a/packaging/docker/rsyslog/Makefile b/packaging/docker/rsyslog/Makefile
@@ -20,12 +20,29 @@ DEFAULT_VERSION = dev-local
 #   make all VERSION=2026-03
 VERSION ?= $(DEFAULT_VERSION)
 
+# Stable release targets derive the container tag from RSYSLOG_VERSION using
+# 8.yymm.0 -> 20yy-mm. Example: 8.2602.0 -> 2026-02.
+RELEASE_CHANNEL ?= stable
+RELEASE_VERSION = $(strip $(shell \
+	if [ "$(RELEASE_CHANNEL)" = "daily-stable" ]; then \
+		printf 'daily-stable\n'; \
+	elif printf '%s\n' "$(RSYSLOG_VERSION)" | grep -Eq '^8\.[0-9]{4}\.0$$'; then \
+		printf '%s\n' "$(RSYSLOG_VERSION)" | sed -E 's/^8\.([0-9]{2})([0-9]{2})\.0$$/20\1-\2/'; \
+	fi))
+
 # Default OCI metadata values for local builds.
 BUILD_DATE ?= $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
 VCS_REF ?= $(shell git rev-parse --short=12 HEAD 2>/dev/null || echo unknown)
 OCI_BUILD_ARGS = --build-arg BUILD_DATE="$(BUILD_DATE)" \
                  --build-arg VCS_REF="$(VCS_REF)"
 
+# Manual release publishing is downstream of PPA readiness. Operators must
+# provide the expected rsyslog release version explicitly before stable
+# release-tagged images are built or pushed. The readiness check keeps to
+# the minimum: confirm that the selected release channel exposes the
+# requested series.
+RELEASE_UBUNTU_VERSION ?= 24.04
+
 # Variable to control cache busting. Set to 'yes' to force a rebuild from scratch for all targets.
 # Example: make all REBUILD=yes
 REBUILD ?= no
@@ -63,7 +80,8 @@ ETL_IMAGE_TAG = $(strip $(ETL_IMAGE_NAME):$(VERSION))
         minimal standard collector dockerlogs etl \
         build_minimal_image build_standard_image build_collector_image build_dockerlogs_image build_etl_image \
         push_minimal push_standard push_collector push_dockerlogs push_etl \
-        rebuild_all check_publish_version
+        rebuild_all check_publish_version check_release_inputs \
+        check_ppa_release_ready release_build release_push release_publish
 
 # Default target: Builds all functional images.
 # Assumed layering: minimal -> standard -> (collector, dockerlogs, etl)
@@ -169,6 +187,77 @@ check_publish_version:
 			echo "Using publishable VERSION=$(VERSION)" ;; \
 	esac
 
+check_release_inputs:
+	@if [ "$(RELEASE_CHANNEL)" = "stable" ] && [ -z "$(RSYSLOG_VERSION)" ]; then \
+		echo "ERROR: stable release targets require RSYSLOG_VERSION." >&2; \
+		echo "Example: make release_build RSYSLOG_VERSION=8.2602.0" >&2; \
+		exit 1; \
+	fi
+	@if [ -z "$(RELEASE_VERSION)" ]; then \
+		echo "ERROR: invalid release input for RELEASE_CHANNEL=$(RELEASE_CHANNEL)." >&2; \
+		echo "Stable example: make release_build RSYSLOG_VERSION=8.2602.0" >&2; \
+		echo "Daily example: make release_build RELEASE_CHANNEL=daily-stable" >&2; \
+		exit 1; \
+	fi
+	@if [ "$(VERSION)" != "$(DEFAULT_VERSION)" ] && [ "$(VERSION)" != "$(RELEASE_VERSION)" ]; then \
+		echo "ERROR: VERSION=$(VERSION) does not match derived release tag $(RELEASE_VERSION)." >&2; \
+		echo "Omit VERSION for release targets or set VERSION=$(RELEASE_VERSION)." >&2; \
+		exit 1; \
+	fi
+	@echo "Using release channel $(RELEASE_CHANNEL)"
+	@if [ -n "$(RSYSLOG_VERSION)" ]; then echo "Using rsyslog release version $(RSYSLOG_VERSION)"; fi
+	@echo "Derived container tag $(RELEASE_VERSION)"
+
+check_ppa_release_ready: check_release_inputs
+	@echo "--- Checking Adiscon PPA readiness for VERSION=$(RELEASE_VERSION) ---"
+	@docker run --rm ubuntu:$(RELEASE_UBUNTU_VERSION) bash -lc " \
+		set -e; \
+		export DEBIAN_FRONTEND=noninteractive; \
+		apt-get update >/dev/null; \
+		apt-get install -y --no-install-recommends ca-certificates software-properties-common >/dev/null; \
+		if [ \"$(RELEASE_CHANNEL)\" = \"daily-stable\" ]; then \
+			release_ppa=\"ppa:adiscon/daily-stable\"; \
+		else \
+			release_ppa=\"ppa:adiscon/v8-stable\"; \
+		fi; \
+		add-apt-repository -y \"\$$release_ppa\" >/dev/null; \
+		apt-get update >/dev/null; \
+		if [ \"$(RELEASE_CHANNEL)\" = \"daily-stable\" ]; then \
+			resolved_version=\"\$$(apt-cache madison rsyslog | awk 'NR==1 { print \$$3; exit }')\"; \
+		else \
+			resolved_version=\"\$$(apt-cache madison rsyslog | awk '\$$3 ~ /^$(RSYSLOG_VERSION)-/ { print \$$3; exit }')\"; \
+		fi; \
+		if [ -z \"\$$resolved_version\" ]; then \
+			if [ \"$(RELEASE_CHANNEL)\" = \"daily-stable\" ]; then \
+				echo \"ERROR: no rsyslog package is available in \$$release_ppa.\" >&2; \
+			else \
+				echo \"ERROR: no rsyslog package matching $(RSYSLOG_VERSION)-* is available in \$$release_ppa.\" >&2; \
+			fi; \
+			exit 1; \
+		fi; \
+		echo \"Resolved PPA package version \$$resolved_version from \$$release_ppa.\""
+	@if [ "$(RELEASE_CHANNEL)" = "daily-stable" ]; then \
+		echo "PPA is ready for daily-stable"; \
+	else \
+		echo "PPA is ready for rsyslog $(RSYSLOG_VERSION)"; \
+	fi
+
+release_build: check_ppa_release_ready
+	@echo "--- Manual release build for VERSION=$(RELEASE_VERSION) ---"
+	$(MAKE) all VERSION=$(RELEASE_VERSION)
+
+release_push: check_ppa_release_ready
+	@echo "--- Manual release push for VERSION=$(RELEASE_VERSION) ---"
+	$(MAKE) all_push VERSION=$(RELEASE_VERSION)
+
+release_publish: release_push
+	@if [ "$(PUSH_LATEST)" = "yes" ]; then \
+		echo "--- Updating latest tags for VERSION=$(RELEASE_VERSION) ---"; \
+		$(MAKE) push_latest VERSION=$(RELEASE_VERSION); \
+	else \
+		echo "Skipping latest tag update. Set PUSH_LATEST=yes to publish latest."; \
+	fi
+
 # --- Push Targets ---
 push_minimal: check_publish_version build_minimal_image
 	@echo "--- Pushing minimal image: $(MINIMAL_IMAGE_TAG) ---"
@@ -242,6 +331,10 @@ help:
 	@echo "  all_push           - Builds and pushes all versioned images."
 	@echo "  tag_latest         - Tags all built images with ':latest' in their respective repositories."
 	@echo "  push_latest        - Pushes all ':latest' tagged images."
+	@echo "  release_build      - Validates PPA readiness, then builds a release-tagged image set."
+	@echo "  release_push       - Validates PPA readiness, then pushes release-tagged images."
+	@echo "  release_publish    - Runs release_push and optionally updates ':latest'."
+	@echo "                       Use PUSH_LATEST=yes to move latest."
 	@echo ""
 	@echo "Utility Targets:"
 	@echo "  clean              - Removes all local built and ':latest' images."
@@ -252,12 +345,21 @@ help:
 	@echo "                       Current default: $(VERSION)"
 	@echo "                       The default is intentionally non-release for local builds."
 	@echo "                       Publish/tag targets reject development-like values."
+	@echo "  RSYSLOG_VERSION    - Expected rsyslog release version, for example 8.2602.0."
+	@echo "                       Required for RELEASE_CHANNEL=stable."
+	@echo "  RELEASE_CHANNEL    - Release source. Defaults to stable."
+	@echo "                       stable -> ppa:adiscon/v8-stable and 8.yymm.0 -> 20yy-mm"
+	@echo "                       daily-stable -> ppa:adiscon/daily-stable and tag daily-stable"
+	@echo "  PUSH_LATEST        - Set to 'yes' to let release_publish update ':latest'."
+	@echo "  RELEASE_UBUNTU_VERSION - Ubuntu base used for the PPA readiness check."
 	@echo "  REBUILD            - Set to 'yes' to force a full rebuild, bypassing Docker build cache."
 	@echo "                       Example: make all REBUILD=yes"
 	@echo ""
 	@echo "Example Workflow:"
 	@echo "  1. Local smoke build: make all"
 	@echo "  2. Local release rehearsal: make VERSION=2026-03 all"
 	@echo "  3. Force a full rebuild of all images: make rebuild_all"
-	@echo "  4. Push all release-tagged images: make VERSION=2026-03 all_push"
-	@echo "  5. Tag and push latest for a release build: make VERSION=2026-03 push_latest"
+	@echo "  4. Check PPA readiness: make check_ppa_release_ready RSYSLOG_VERSION=8.2602.0"
+	@echo "  5. Manual release push: make release_push RSYSLOG_VERSION=8.2602.0"
+	@echo "  6. Release push plus latest: make release_publish RSYSLOG_VERSION=8.2602.0 PUSH_LATEST=yes"
+	@echo "  7. Daily channel build: make release_build RELEASE_CHANNEL=daily-stable"
diff --git a/packaging/docker/rsyslog/README.md b/packaging/docker/rsyslog/README.md
@@ -31,6 +31,13 @@ The build system treats `VERSION` as the source of truth for image tags.
 Release automation must pass the intended stable version explicitly
 instead of relying on the Makefile default.
 
+Stable container tags are expected to follow the rsyslog release train:
+
+- rsyslog release version `8.2602.0`
+- container image tag `2026-02`
+
+The stable-channel mapping rule is: `8.yymm.0` becomes `20yy-mm`.
+
 ## Publishing rules
 
 Publish and `latest` tagging targets reject development-style versions:
@@ -50,6 +57,91 @@ make VERSION=2026-03 all_push
 make VERSION=2026-03 push_latest
 ```
 
+## PPA readiness comes first
+
+Release-tagged container images must only be built and pushed after the
+matching rsyslog packages are already available in the correct Adiscon
+PPA.
+
+This is a hard prerequisite because the image build installs rsyslog
+packages from the PPA at build time. A release-like container tag is
+incorrect if the requested rsyslog release series is not yet present
+there.
+
+By default, the manual release flow uses the stable channel:
+
+- `RELEASE_CHANNEL=stable`
+- PPA: `ppa:adiscon/v8-stable`
+- tag mapping: `8.yymm.0` -> `20yy-mm`
+
+Warning: this workflow assumes the selected PPA still publishes the
+requested rsyslog release series. In practice, PPAs commonly expose only
+the currently published package versions for a given Ubuntu series. Once
+the PPA advances, older stable container sets may no longer be
+rebuildable from it.
+
+For the daily channel:
+
+- `RELEASE_CHANNEL=daily-stable`
+- PPA: `ppa:adiscon/daily-stable`
+- image tag: `daily-stable`
+
+Manual release targets therefore require:
+
+- `RSYSLOG_VERSION` for the stable channel
+- `RELEASE_CHANNEL=daily-stable` for the daily channel
+
+The release readiness check resolves the newest matching `rsyslog`
+package for the selected channel. The real image build remains the source
+of truth for package completeness and will fail if required packages are
+still missing.
+
+The readiness check runs in a disposable Ubuntu container and does not
+modify the host system's apt sources.
+
+## Manual release flow
+
+1. Determine the container tag from the rsyslog release tag.
+   Example: `8.2602.0` and `v.26-02.0` both map to `2026-02`.
+2. Verify PPA readiness:
+
+```bash
+make check_ppa_release_ready RSYSLOG_VERSION=8.2602.0
+```
+
+This looks up the newest `8.2602.0-*` package published in the Adiscon
+PPA. If the PPA is not ready for that release series, the check fails
+early. If subpackages are still missing, the actual image build fails.
+
+3. Build the release-tagged image family:
+
+```bash
+make release_build RSYSLOG_VERSION=8.2602.0
+```
+
+4. Push the release-tagged images:
+
+```bash
+make release_push RSYSLOG_VERSION=8.2602.0
+```
+
+5. Update `latest` only when that is intended:
+
+```bash
+make release_publish RSYSLOG_VERSION=8.2602.0 PUSH_LATEST=yes
+```
+
+If `PUSH_LATEST` is not set to `yes`, `release_publish` pushes only the
+versioned images and leaves `latest` unchanged.
+
+For the daily channel:
+
+```bash
+make check_ppa_release_ready RELEASE_CHANNEL=daily-stable
+make release_build RELEASE_CHANNEL=daily-stable
+make release_push RELEASE_CHANNEL=daily-stable
+```
+
 ## CI guidance
 
 CI validation jobs should use non-release tags such as `ci-<sha>`.
