api: move catalog sourcing fields to discriminated union

[joelanford]

In order for us to support sourcing bundles directly, as is requested in #597, we need the ClusterExtension API to be structured such that one and exactly one sourcing mechanism can be specified.

A discriminated union is a good solution to this problem. If this path is chosen, special attention should be paid to the definition of a discriminated union because it likely requires very specific validations to exist.

The fields that are currently in the spec root that are related to catalog sourcing are:

• packageName
• version
• channel
• upgradeConstraintPolicy

These fields should be moved to a discriminated union type that is specific to sourcing from catalogs.

Here's a rough sketch of what the new structure could look like:

spec:
  source:
    type: Catalog
    catalog:
      packageName: foo
      channel: bar
      version: 1.0.0
      upgradeConstraintPolicy: Enforce

If we have the above structure, there will be a logical place to add support for direct bundle installs in the future, like so:

spec:
  source:
    type: BundleImage
    bundleImage:
      ref: quay.io/acme-co/widget-operator-bundle:v1.0.0

[joelanford]

The main things in the above examples that I think are up for debate are:

1. The naming of spec.source. Should this be something like spec.resolutionSource or spec.bundleSource?
2. The naming of the Catalog type. Should this be ClusterCatalog? If we ever add a Catalog API, using Catalog in reference to ClusterCatalog objects could be confusing. Note: cluster-scoped ClusterExtensions would never be able to actually resolve from namespace-scoped Catalogs, so it wouldn't be a technical issue, just a UX/terminology concern.
3. (Not as important now, only important in #597) The naming of the BundleImage type. How much ground should this cover? Any bundles at all? Any bundles in an image registry? Just bundles that are Docker or OCI images (i.e. not custom OCI Artifacts)? If/when we support multiple bundle formats, would we need to differentiate the various formats with different types here?

[LalatenduMohanty]

/assign @everettraven

[everettraven]

Additional information on the motivation and technical details around the proposed implementation can be found in the v1 API Review RFC