feat: add reusable GitHub Action to generate ImageCatalogs (#323)

Introduces a composite action that wraps `catalogs_generator.py` to generate CloudNativePG ImageCatalog YAMLs from a container registry. Supports multiple image types, distributions, and custom family prefixes. Generates a `kustomization.yaml` for easy deployment of all catalogs. Related to cloudnative-pg/postgis-containers#100 Closes #324 Signed-off-by: Niccolò Fei <niccolo.fei@enterprisedb.com> Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com> Signed-off-by: Marco Nenciarini <marco.nenciarini@enterprisedb.com> Co-authored-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com> Co-authored-by: Marco Nenciarini <marco.nenciarini@enterprisedb.com>
2025-09-24 18:14:03 +02:00
parent 607f425c34
commit 15d90eebd4
4 changed files with 296 additions and 29 deletions
--- a/.github/actions/generate-catalogs/README.md
+++ b/.github/actions/generate-catalogs/README.md
@@ -0,0 +1,117 @@
+# Image Catalogs Generator Action
+
+This composite GitHub Action generates [CloudNativePG ImageCatalogs](https://cloudnative-pg.io/documentation/current/image_catalog/)
+from a container registry.
+It wraps the [`catalogs_generator.py`](./catalogs_generator.py) script and makes it easy to
+run inside CI pipelines.
+
+---
+
+## How it works
+
+1. The script retrieves all image tags from a container registry.
+2. A regular expression is applied to select the tags to include in the ImageCatalog.
+3. Matching tags are sorted using [semantic versioning](https://semver.org/).
+4. For each PostgreSQL major version, the latest matching tag is chosen.
+5. The action generates:
+
+   - One `ClusterImageCatalog` YAML file per requested distribution and image
+     type
+   - A `kustomization.yaml` to install/update all cluster catalogs at once
+
+---
+
+## Inputs
+
+| Name            | Required  | Description                                                                     | Example                             |
+| --------------- | --------- | ------------------------------------------------------------------------------- | ----------------------------------- |
+| `registry`      | ✅ yes    | The container registry to query.                                                | `ghcr.io/cloudnative-pg/postgresql` |
+| `image-types`   | ✅ yes    | Comma-separated list of image types.                                            | `minimal,standard`                  |
+| `distributions` | ✅ yes    | Comma-separated list of supported OS distributions.                             | `bookworm,trixie`                   |
+| `regex`         | ✅ yes    | Regular expression used to match image tags.                                    | *See [Regex](#regex)*               |
+| `output-dir`    | ✅ yes    | Directory where generated catalogs will be written.                             | `./`                                |
+| `family`        | ❌ no     | Family name for generated catalogs (filename prefix). Defaults to `postgresql`. | `my-custom-family`                  |
+
+---
+
+## Regex
+
+The `regex` input defines which tags are added to the `ClusterImageCatalog`.
+
+- The **first capturing group** must be the PostgreSQL major version:
+
+    - `(\d+)` → e.g. `18`
+
+- Subsequent capturing groups are optional and may include:
+
+    - an additional version: `(\d+(?:\.\d+)+)` → e.g. `1.2.3`
+    - a 12 digit timestamp: `(\d{12})` → e.g. `202509161052`
+
+**Examples:**
+
+```regex
+# Matches '18-202509161052', '18.1-202509161052', etc.
+'(\d+)(?:\.\d+|beta\d+|rc\d+|alpha\d+)-(\d{12})'
+
+# Matches '18-3.0.6-202509161052', '18.1-3.0.6-202509161052', etc.
+'(\d+)(?:\.\d+|beta\d+|rc\d+|alpha\d+)-(\d+(?:\.\d+){1,3})-(\d{12})'
+```
+
+> **Note:** Each `image-types` and `distributions` will be combined together
+> to form a suffix, `-<img_type>-<distribution>`, which will internally be
+> appended to the `regex` provided. Tags that do not contain explicit
+> image type and distribution as a suffix are currently not supported.
+
+---
+
+### Family
+
+The optional `family` input customizes:
+
+1. **File prefix**: `<family>-minimal-trixie.yaml`
+2. **`metadata.name`** in the ImageCatalog: `<family>-minimal-trixie`
+3. **`images.cnpg.io/family` label** on the ImageCatalog object
+
+If not specified it defaults to `postgresql`.
+
+---
+
+## Usage
+
+Example workflow:
+
+```
+jobs:
+  generate-catalogs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate image catalogs
+        uses: cloudnative-pg/postgres-containers/.github/actions/generate-catalogs@main
+        with:
+          registry: ghcr.io/cloudnative-pg/postgresql
+          image-types: minimal,standard
+          distributions: bookworm,trixie
+          regex: '(\d+)(?:\.\d+|beta\d+|rc\d+|alpha\d+)-(\d{12})'
+          output-dir: .
+```
+
+This generates:
+
+```
+./catalog-minimal-bookworm.yaml
+./catalog-standard-bookworm.yaml
+./catalog-minimal-trixie.yaml
+./catalog-standard-trixie.yaml
+```
+
+The generated `kustomization.yaml` will look like:
+
+```
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+- catalog-minimal-bookworm.yaml
+- catalog-standard-bookworm.yaml
+- catalog-minimal-trixie.yaml
+- catalog-standard-trixie.yaml
+```