# OLMv1 CLI ClusterCatalog content discovery
## ClusterCatalog content listing for kubectl-operator plugin

While OLMv1 represents a significant simplification of extension lifecycle management, it introduced a major UX deficiency at the command line. Users currently must know the exact package name, available versions, or specific version ranges a priori for installation and upgrade operations. Discovering this required metadata, which currently involves low-level tasks like unpacking FBCs or querying the on-cluster catalogd-service, is a frustrating, non-standard process, effectively abandoning the clean catalog introspection provided by the OLMv0 kubectl-operator and its PackageManifest CRs. To restore this critical CLI parity, this RFC proposes a new catalog search command to securely expose the Catalogd API off-cluster in trusted environments.

### Approach
The main requirement is to expose the on-cluster API provided by the catalogd-service to provide consistent behavior with the catalog discovery offered through Openshift Console.

For this, a port-forwarding connection is opened to the catalogd-service, which can then be queried at the `api/v1/all` endpoint to list the entirety of a catalog's contents.

The steps involved are as follows:

1. For each ClusterCatalog with a non-empty `status.urls.base` field, parse the url to obtain the service endpoint, and therefore the service name and namespace. e.g, `https://catalogd-service.olmv1-system.svc/catalogs/operatorhubio` => `{Namespace: olmv1-system, Name: catalogd-service}`
2. Load the root CAs to access the endpoint from the appropriate secret for `catalogd`. This is secret can be located either by the service name if managed by cert-manager, or via the `service.beta.openshift.io/serving-cert-secret-name` annotation on the `openshift-catalogd/catalogd-service`.
3. Through a long-lived https request, stream the contents from the endpoint in a user friendly format (tabular, yaml or json).

The simplest implementation of this may look like:

$ kubectl operator olmv1 search catalog --help

Search catalogs for installable operators matching parameters

Usage:
  operator olmv1 search catalog [flags]

Aliases:
  catalog, catalogs

Flags:
  -o, --output string               output format. One of: (yaml|json|table)

Additionally, the command may be made more user-friendly by:
- allowing searches limited to specific ClusterCatalogs
- implementing search for a specific package and its versions
- having `--list-versions` support for showing all available versions of the packages on cluster, and reducing output clutter by omitting this info otherwise.

This implementation makes use of the existing catalogd-service API. This ensures that the listed contents are identical to what is available on-cluster.

### Competition​ ​(alternatives)
1. Catalogd Gateway:
- Maintain a gateway or ingress to the on-cluster catalogd-service. This is the kubernetes recommended way of exposing services, but requires either detecting an existing gateway for use, or shipping a default gateway, solely for use by the kubectl-operator plugin, adding bloat to the shipped payload.
3. Nodeport Service:
- Expose the `catalogd-service` via a NodePort, eliminating the need for port-forwarding. This, however, means there is an external service port at all times to catalogd, which is another surface to cover.
4. Unpacking FBC contents locally:
- Have users pull ClusterCatalog images locally, then either render them via `opm` or unpack their contents to query the underlying FBC via tools like `jq`. Requires access to the ClusterCatalog image repositories locally, and knowledge of FBC structure for writing `jq` queries.
5. OpenShift Console:
- Restrict catalog querying to OpenShift Console. Limits what a user can do from the CLI without tools like `opm` to render ClusterCatalog image contents, or `dcp` to unpack them.

### Non-goals
This document does not attempt to refine the existing catalogd-service API for granular search.

### Key Dependencies and Open Questions:
- consistency for the `status.urls.base` endpoints, and support for additional endpoints under urls: is there a better way to find the serving urls and services besides parsing the endpoints? How will this fare if extending to refer to off-cluster catalog servers, if supported in future?