From 8f91b5dec2b4c8b28b81ab2c40c06d7aa1cee351 Mon Sep 17 00:00:00 2001 From: Jordan Keister Date: Mon, 26 Aug 2024 15:12:47 -0500 Subject: [PATCH] document bundle metadata format troubleshooting Signed-off-by: Jordan Keister --- .../ROOT/pages/troubleshooting/index.adoc | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/modules/ROOT/pages/troubleshooting/index.adoc b/docs/modules/ROOT/pages/troubleshooting/index.adoc index ef130285..a6a656be 100644 --- a/docs/modules/ROOT/pages/troubleshooting/index.adoc +++ b/docs/modules/ROOT/pages/troubleshooting/index.adoc @@ -149,3 +149,23 @@ kubectl get secrets -o json | {auths: .} ' ---- + + +== Bundle properties are not permitted in a FBC fragment for OCP version + +Tasks may fail with an error message containing the string `bundle properties are not permitted in a FBC fragment for OCP version`. This means that your fragment needs to utilize the appropriate FBC bundle metadata format which aligns with your target catalog. Failure to do so will not display your package in the OpenShift WebUI properly. + +For OCP versions: +- _4.16 or earlier_, bundle metadata must use the `olm.bundle.object` format +- _4.17 or later_, bundle metadata must use the `olm.csv.metadata` format + +=== If you use `opm` tooling to generate your fragment + +Note: This assumes that opm is version v1.46.0 or later. + +If you generate your FBC using catalog template expansion or migration of existing catalogs, then you can choose to use `olm.csv.metadata` format by using the `--migrate-level=bundle-object-to-csv-metadata` flag. By default, the tool will output `olm.bundle.object` metadata format. + +=== If you use other tooling to generate your fragment + +If you rely on other tooling/processes to produce your fragment and currently use the `olm.bundle.object` bundle metadata format, then you may either adjust your tooling to align your bundle metadata format with the target OCP version or you may use `opm` to migrate your fragment's bundle metadata by using `opm render --migrate-level=bundle-object-to-csv-metadata [fragment-ref]` (where `fragment-ref` is a pullspec to the fragment or a path to a directory containing the fragment). +Please note that this process is lossy, so it only works when converting `olm.bundle.object` to `olm.csv.metadata` formats.