Chapter 9. Troubleshooting catalog selection errors
Chapter 9. Troubleshooting catalog selection errors If bundle resolution fails because of ambiguity or because no catalog is selected, an error message is printed in the status.conditions field of the cluster extension. Perform the following actions to troubleshoot catalog selection errors: Refine your selection criteria using labels or expressions. Adjust your catalog priorities. Ensure that only one bundle matches your package name and version requirements. 9.1. Creating catalogs Catalog maintainers can create new catalogs in the file-based catalog format for use with Operator Lifecycle Manager (OLM) v1 on OpenShift Container Platform. 9.1.1. Creating a file-based catalog image You can use the opm CLI to create a catalog image that uses the plain text file-based catalog format (JSON or YAML), which replaces the deprecated SQLite database format. Prerequisites You have installed the opm CLI. You have podman version 1.9.3+. A bundle image is built and pushed to a registry that supports Docker v2-2 . Procedure Initialize the catalog: Create a directory for the catalog by running the following command: USD mkdir <catalog_dir> Generate a Dockerfile that can build a catalog image by running the opm generate dockerfile command: USD opm generate dockerfile <catalog_dir> \ -i registry.redhat.io/openshift4/ose-operator-registry-rhel9:v4.18 1 1 Specify the official Red Hat base image by using the -i flag, otherwise the Dockerfile uses the default upstream image. The Dockerfile must be in the same parent directory as the catalog directory that you created in the step: Example directory structure . 1 ├── <catalog_dir> 2 └── <catalog_dir>.Dockerfile 3 1 Parent directory 2 Catalog directory 3 Dockerfile generated by the opm generate dockerfile command Populate the catalog with the package definition for your Operator by running the opm init command: USD opm init <operator_name> \ 1 --default-channel=preview \ 2 --description=./README.md \ 3 --icon=./operator-icon.svg \ 4 --output yaml \ 5 > <catalog_dir>/index.yaml 6 1 Operator, or package, name 2 Channel that subscriptions default to if unspecified 3 Path to the Operator's README.md or other documentation 4 Path to the Operator's icon 5 Output format: JSON or YAML 6 Path for creating the catalog configuration file This command generates an olm.package declarative config blob in the specified catalog configuration file. Add a bundle to the catalog by running the opm render command: USD opm render <registry>/<namespace>/<bundle_image_name>:<tag> \ 1 --output=yaml \ >> <catalog_dir>/index.yaml 2 1 Pull spec for the bundle image 2 Path to the catalog configuration file Note Channels must contain at least one bundle. Add a channel entry for the bundle. For example, modify the following example to your specifications, and add it to your <catalog_dir>/index.yaml file: Example channel entry --- schema: olm.channel package: <operator_name> name: preview entries: - name: <operator_name>.v0.1.0 1 1 Ensure that you include the period ( . ) after <operator_name> but before the v in the version. Otherwise, the entry fails to pass the opm validate command. Validate the file-based catalog: Run the opm validate command against the catalog directory: USD opm validate <catalog_dir> Check that the error code is 0 : USD echo USD? Example output 0 Build the catalog image by running the podman build command: USD podman build . \ -f <catalog_dir>.Dockerfile \ -t <registry>/<namespace>/<catalog_image_name>:<tag> Push the catalog image to a registry: If required, authenticate with your target registry by running the podman login command: USD podman login <registry> Push the catalog image by running the podman push command: USD podman push <registry>/<namespace>/<catalog_image_name>:<tag> Additional resources opm CLI reference 9.1.2. Updating or filtering a file-based catalog image You can use the opm CLI to update or filter a catalog image that uses the file-based catalog format. By extracting the contents of an existing catalog image, you can modify the catalog as needed, for example: Adding packages Removing packages Updating existing package entries Detailing deprecation messages per package, channel, and bundle You can then rebuild the image as an updated version of the catalog. Note Alternatively, if you already have a catalog image on a mirror registry, you can use the oc-mirror CLI plugin to automatically prune any removed images from an updated source version of that catalog image while mirroring it to the target registry. For more information about the oc-mirror plugin and this use case, see the "Keeping your mirror registry content updated" section, and specifically the "Pruning images" subsection, of "Mirroring images for a disconnected installation using the oc-mirror plugin". Prerequisites You have the following on your workstation: The opm CLI. podman version 1.9.3+. A file-based catalog image. A catalog directory structure recently initialized on your workstation related to this catalog. If you do not have an initialized catalog directory, create the directory and generate the Dockerfile. For more information, see the "Initialize the catalog" step from the "Creating a file-based catalog image" procedure. Procedure Extract the contents of the catalog image in YAML format to an index.yaml file in your catalog directory: USD opm render <registry>/<namespace>/<catalog_image_name>:<tag> \ -o yaml > <catalog_dir>/index.yaml Note Alternatively, you can use the -o json flag to output in JSON format. Modify the contents of the resulting index.yaml file to your specifications: Important After a bundle has been published in a catalog, assume that one of your users has installed it. Ensure that all previously published bundles in a catalog have an update path to the current or newer channel head to avoid stranding users that have that version installed. To add an Operator, follow the steps for creating package, bundle, and channel entries in the "Creating a file-based catalog image" procedure. To remove an Operator, delete the set of olm.package , olm.channel , and olm.bundle blobs that relate to the package. The following example shows a set that must be deleted to remove the example-operator package from the catalog: Example 9.1. Example removed entries --- defaultChannel: release-2.7 icon: base64data: <base64_string> mediatype: image/svg+xml name: example-operator schema: olm.package --- entries: - name: example-operator.v2.7.0 skipRange: '>=2.6.0 <2.7.0' - name: example-operator.v2.7.1 replaces: example-operator.v2.7.0 skipRange: '>=2.6.0 <2.7.1' - name: example-operator.v2.7.2 replaces: example-operator.v2.7.1 skipRange: '>=2.6.0 <2.7.2' - name: example-operator.v2.7.3 replaces: example-operator.v2.7.2 skipRange: '>=2.6.0 <2.7.3' - name: example-operator.v2.7.4 replaces: example-operator.v2.7.3 skipRange: '>=2.6.0 <2.7.4' name: release-2.7 package: example-operator schema: olm.channel --- image: example.com/example-inc/example-operator-bundle@sha256:<digest> name: example-operator.v2.7.0 package: example-operator properties: - type: olm.gvk value: group: example-group.example.io kind: MyObject version: v1alpha1 - type: olm.gvk value: group: example-group.example.io kind: MyOtherObject version: v1beta1 - type: olm.package value: packageName: example-operator version: 2.7.0 - type: olm.bundle.object value: data: <base64_string> - type: olm.bundle.object value: data: <base64_string> relatedImages: - image: example.com/example-inc/example-related-image@sha256:<digest> name: example-related-image schema: olm.bundle --- To add or update deprecation messages for an Operator, ensure there is a deprecations.yaml file in the same directory as the package's index.yaml file. For information on the deprecations.yaml file format, see "olm.deprecations schema". Save your changes. Validate the catalog: USD opm validate <catalog_dir> Rebuild the catalog: USD podman build . \ -f <catalog_dir>.Dockerfile \ -t <registry>/<namespace>/<catalog_image_name>:<tag> Push the updated catalog image to a registry: USD podman push <registry>/<namespace>/<catalog_image_name>:<tag> Verification In the web console, navigate to the OperatorHub configuration resource in the Administration Cluster Settings Configuration page. Add the catalog source or update the existing catalog source to use the pull spec for your updated catalog image. For more information, see "Adding a catalog source to a cluster" in the "Additional resources" of this section. After the catalog source is in a READY state, navigate to the Operators OperatorHub page and check that the changes you made are reflected in the list of Operators. Additional resources Packaging format Schemas olm.deprecations schema Mirroring images for a disconnected installation using the oc-mirror plugin Keeping your mirror registry content updated Adding a catalog source to a cluster 9.2. Disconnected environment support in OLM v1 To support cluster administrators that prioritize high security by running their clusters in internet-disconnected environments, especially for mission-critical production workloads, Operator Lifecycle Manager (OLM) v1 includes cluster extension lifecycle management functionality that works within these disconnected environments, starting in OpenShift Container Platform 4.18. 9.2.1. About disconnected support and the oc-mirror plugin in OLM v1 Operator Lifecycle Manager (OLM) v1 supports disconnected environments starting in OpenShift Container Platform 4.18. After using the oc-mirror plugin for the OpenShift CLI ( oc ) to mirror the images required for your cluster to a mirror registry in your fully or partially disconnected environments, OLM v1 can function properly in these environments by utilizing either of the following sets of resources, depending on which oc-mirror plugin version you are using: ImageContentSourcePolicy resources, which are automatically generated by oc-mirror plugin v1, and ClusterCatalog resources, which must be manually created after using oc-mirror plugin v1 ImageDigestMirrorSet , ImageTagMirrorSet , and ClusterCatalog resources, which are all automatically generated by oc-mirror plugin v2 Note Starting in OpenShift Container Platform 4.18, oc-mirror plugin v2 is the recommended version for mirroring. For more information and procedures, see the Disconnected environments guide for the oc-mirror plugin version you plan to use. Additional resources Mirroring images for a disconnected installation using the oc-mirror plugin v1 Mirroring images for a disconnected installation using the oc-mirror plugin v2
mkdir <catalog_dir> opm generate dockerfile <catalog_dir> -i registry.redhat.io/openshift4/ose-operator-registry-rhel9:v4.18 1 . 1 ├── <catalog_dir> 2 └── <catalog_dir>.Dockerfile 3 opm init <operator_name> \ 1 --default-channel=preview \ 2 --description=./README.md \ 3 --icon=./operator-icon.svg \ 4 --output yaml \ 5 > <catalog_dir>/index.yaml 6 opm render <registry>/<namespace>/<bundle_image_name>:<tag> \ 1 --output=yaml >> <catalog_dir>/index.yaml 2 --- schema: olm.channel package: <operator_name> name: preview entries: - name: <operator_name>.v0.1.0 1 opm validate <catalog_dir> echo USD? 0 podman build . -f <catalog_dir>.Dockerfile -t <registry>/<namespace>/<catalog_image_name>:<tag> podman login <registry> podman push <registry>/<namespace>/<catalog_image_name>:<tag> opm render <registry>/<namespace>/<catalog_image_name>:<tag> -o yaml > <catalog_dir>/index.yaml --- defaultChannel: release-2.7 icon: base64data: <base64_string> mediatype: image/svg+xml name: example-operator schema: olm.package --- entries: - name: example-operator.v2.7.0 skipRange: '>=2.6.0 <2.7.0' - name: example-operator.v2.7.1 replaces: example-operator.v2.7.0 skipRange: '>=2.6.0 <2.7.1' - name: example-operator.v2.7.2 replaces: example-operator.v2.7.1 skipRange: '>=2.6.0 <2.7.2' - name: example-operator.v2.7.3 replaces: example-operator.v2.7.2 skipRange: '>=2.6.0 <2.7.3' - name: example-operator.v2.7.4 replaces: example-operator.v2.7.3 skipRange: '>=2.6.0 <2.7.4' name: release-2.7 package: example-operator schema: olm.channel --- image: example.com/example-inc/example-operator-bundle@sha256:<digest> name: example-operator.v2.7.0 package: example-operator properties: - type: olm.gvk value: group: example-group.example.io kind: MyObject version: v1alpha1 - type: olm.gvk value: group: example-group.example.io kind: MyOtherObject version: v1beta1 - type: olm.package value: packageName: example-operator version: 2.7.0 - type: olm.bundle.object value: data: <base64_string> - type: olm.bundle.object value: data: <base64_string> relatedImages: - image: example.com/example-inc/example-related-image@sha256:<digest> name: example-related-image schema: olm.bundle --- opm validate <catalog_dir> podman build . -f <catalog_dir>.Dockerfile -t <registry>/<namespace>/<catalog_image_name>:<tag> podman push <registry>/<namespace>/<catalog_image_name>:<tag>