From 562d59fc9b7a622eb02e64e5c00ee9af701f957e Mon Sep 17 00:00:00 2001 From: Michele Baldessari Date: Wed, 15 Apr 2026 13:33:58 +0200 Subject: [PATCH 1/2] Add somre readme improvements for custom catalog --- README.md | 175 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 167 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index b279749..aca302c 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,9 @@ A catalog of [Validated Patterns](https://validatedpatterns.io) metadata, served The `generate-catalog.sh` script queries the GitHub API for all repositories tagged with `pattern` in the `validatedpatterns` and `validatedpatterns-sandbox` organizations. For each repository it: 1. Fetches `pattern-metadata.yaml` and normalizes it into a consistent schema -2. Fetches `values-secret.yaml.template` if present -3. Writes per-pattern files under `catalog//` -4. Generates a `catalog/catalog.yaml` index listing all discovered patterns +1. Fetches `values-secret.yaml.template` if present +1. Writes per-pattern files under `catalog//` +1. Generates a `catalog/catalog.yaml` index listing all discovered patterns The resulting `catalog/` directory is served by an nginx container image that the patterns-operator deploys on-cluster. @@ -55,16 +55,175 @@ pushes to `main` or `stable-v1` when files in `catalog/`, `templates/`, or the workflow itself change: 1. **validate-yaml** — validates all YAML files under `catalog/` with `yamllint` -2. **build-container** — builds the image for amd64 and arm64 in parallel on native runners -3. **push-multiarch-manifest** — assembles a multi-arch manifest, pushes to Quay, and signs with cosign (only in the upstream `validatedpatterns/pattern-ui-catalog` repo) +1. **build-container** — builds the image for amd64 and arm64 in parallel on native runners +1. **push-multiarch-manifest** — assembles a multi-arch manifest, pushes to Quay, and signs with cosign (only in the upstream `validatedpatterns/pattern-ui-catalog` repo) -| Branch | Image tag | +| Branch | Image tag | |-------------|---------------| -| `main` | `:latest` | -| `stable-v1` | `:stable-v1` | +| `main` | `:latest` | +| `stable-v1` | `:stable-v1` | The workflow requires `QUAY_USERNAME` and `QUAY_PASSWORD` secrets configured in a `quay` environment. +## Creating a custom catalog + +You can build your own catalog image containing a curated set of patterns. This +is useful when you maintain internal or third-party patterns that are not part of +the upstream `validatedpatterns` organizations. + +### 1. Prepare the catalog directory + +Create a `catalog/` tree with the following structure: + +```txt +catalog/ + catalog.yaml + my-pattern/pattern.yaml + my-pattern/values-secret.yaml.template # optional + another-pattern/pattern.yaml +``` + +**`catalog/catalog.yaml`** — the index file listing every pattern in the catalog: + +```yaml +generated_at: "2026-04-15T00:00:00Z" +generator_version: "1.0" +catalog_description: "My custom pattern catalog" +patterns: + - my-pattern + - another-pattern +``` + +**`catalog//pattern.yaml`** — metadata for each pattern. Required fields +are defined by `pattern.schema.json`; a minimal example: + +```yaml +metadata_version: "1.0" +name: my-pattern +pattern_version: "1.0" +display_name: My Pattern +repo_url: https://github.com/my-org/my-pattern +docs_repo_url: https://github.com/my-org/my-pattern-docs +issues_url: https://github.com/my-org/my-pattern/issues +docs_url: https://my-org.github.io/my-pattern/ +ci_url: https://my-org.github.io/my-pattern/ci +tier: sandbox # maintained | tested | sandbox +owners: + - my-github-user +requirements: + hub: + compute: + aws: + replicas: 3 + type: m5.2xlarge + controlPlane: + aws: + replicas: 3 + type: m5.xlarge +extra_features: + hypershift_support: false + spoke_support: false +external_requirements: null +org: my-org +spoke: null +``` + +You can optionally validate your files against the JSON schemas shipped in this +repository: + +```sh +make schema-validate +``` + +### 2. Build and push the image + +Override `UPLOADREGISTRY` (and optionally `VERSION`) to point at your own +registry: + +```sh +make UPLOADREGISTRY=quay.io/my-org VERSION=1.0.0 pattern-ui-catalog-build +make UPLOADREGISTRY=quay.io/my-org VERSION=1.0.0 pattern-ui-catalog-push +``` + +This produces `quay.io/my-org/pattern-ui-catalog:1.0.0`. + +### 3. Point the patterns-operator at your catalog image + +The [patterns-operator](https://github.com/validatedpatterns/patterns-operator) +reads an optional `catalog.image` key from its ConfigMap. By default it deploys +`quay.io/validatedpatterns/pattern-ui-catalog:stable-v1`. To override it, patch +(or create) the `patterns-operator-config` ConfigMap in the operator namespace +(`patterns-operator` by default): + +```sh +oc patch configmap patterns-operator-config \ + -n patterns-operator \ + --type merge \ + -p '{"data":{"catalog.image":"quay.io/my-org/pattern-ui-catalog:1.0.0"}}' +``` + +If the ConfigMap does not exist yet: + +```sh +oc create configmap patterns-operator-config \ + -n patterns-operator \ + --from-literal=catalog.image=quay.io/my-org/pattern-ui-catalog:1.0.0 +``` + +The operator picks up the change on its next reconciliation loop and performs a +rolling update of the catalog deployment. + +## Authenticated container registries + +If your custom catalog image is hosted on a registry that requires +authentication (e.g. a private Quay repository), you need to configure a pull +secret so that the cluster can pull the image. + +### 1. Create a pull secret + +Create an authentication secret in the operator namespace: + +```sh +oc create secret docker-registry my-catalog-pull-secret \ + -n patterns-operator \ + --docker-server=quay.io \ + --docker-username='' \ + --docker-password='' +``` + +### 2. Link the secret to the operator service account + +The catalog deployment runs under the `patterns-operator-controller-manager` +service account. Link the pull secret to it: + +```sh +oc secrets link patterns-operator-controller-manager my-catalog-pull-secret \ + -n patterns-operator \ + --for=pull +``` + +### 3. Alternative: global pull secret + +If multiple workloads need access to the same registry, you can add the +credentials to the cluster-wide pull secret instead. Extract the current secret, +merge your credentials, and apply: + +```sh +oc get secret/pull-secret -n openshift-config --template='{{index .data ".dockerconfigjson" | base64decode}}' > /tmp/pull-secret.json + +# Authenticate to your registry (this merges the new entry into the file) +oc registry login --registry=quay.io \ + --auth-basic=':' \ + --to=/tmp/pull-secret.json + +oc set data secret/pull-secret -n openshift-config \ + --from-file=.dockerconfigjson=/tmp/pull-secret.json +``` + +> **Note:** Updating the global pull secret triggers a rolling reboot of all +> nodes in the cluster. Prefer the per-service-account approach when only the +> catalog needs access. + ## Repository structure ``` From 666bfc791be12df8c3f319e7bae264ca4681eac4 Mon Sep 17 00:00:00 2001 From: Michele Baldessari Date: Wed, 15 Apr 2026 13:57:36 +0200 Subject: [PATCH 2/2] Add custom github org mention and values secret mention --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index aca302c..9405951 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,22 @@ You can build your own catalog image containing a curated set of patterns. This is useful when you maintain internal or third-party patterns that are not part of the upstream `validatedpatterns` organizations. +If the patterns you want to include are all hosted on GitHub you can just run the +following script: + +```sh +TOPIC=pattern ORGS="org1 org2" make generate-catalog +``` + +The above script will generate the catalog bit by using +any repo with the `pattern` topic (topics are some sort of tags on GitHub) +in `org1` and `org2` on github. Then you can just skip to section +[Build and push the image](#2-build-and-push-the-image). + +```sh +make UPLOADREGISTRY=quay.io/ pattern-ui-catalog-build pattern-ui-catalog-push +``` + ### 1. Prepare the catalog directory Create a `catalog/` tree with the following structure: @@ -128,6 +144,9 @@ org: my-org spoke: null ``` +**`catalog//values-secret.yaml.template`** - metadata for secret material +for the pattern. See [here](https://validatedpatterns.io/learn/secrets-management-in-the-validated-patterns-framework/) for more information. + You can optionally validate your files against the JSON schemas shipped in this repository: