Fix docs: "Conceptual Guides" section (#1473)

There were several intentional breaking changes in the API
which are now included in v0.18.0 release.

This commit mostly focuses on updating the documentation to
reflect API changes. This includes making sure that snippets
and example outputs match the current state of the project.

Relevant PRs:
* #1439
* #1434

Signed-off-by: Mikalai Radchuk <mradchuk@redhat.com>

Author: m1kola

docs/concepts/controlling-catalog-selection.md

@@ -21,16 +21,21 @@ To select a specific catalog by name, you can use the `matchLabels` field in you
 apiVersion: olm.operatorframework.io/v1
 kind: ClusterExtension
 metadata:
-  name: my-extension
+  name: argocd
 spec:
-  packageName: my-package
-  catalog:
-    selector:
-      matchLabels:
-        olm.operatorframework.io/metadata.name: my-content-management
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
+  source:
+    sourceType: Catalog
+    catalog:
+      packageName: argocd-operator
+      selector:
+        matchLabels:
+          olm.operatorframework.io/metadata.name: operatorhubio
 ```
 
-In this example, only the catalog named `my-catalog` will be considered when resolving `my-package`.
+In this example, only the catalog named `operatorhubio` will be considered when resolving `argocd-operator`.
 
 ### Selecting Catalogs by Labels
 
@@ -42,13 +47,18 @@ If you have catalogs labeled with specific metadata, you can select them using `
 apiVersion: olm.operatorframework.io/v1
 kind: ClusterExtension
 metadata:
-  name: my-extension
+  name: argocd
 spec:
-  packageName: my-package
-  catalog:
-    selector:
-      matchLabels:
-        example.com/support: "true"
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
+  source:
+    sourceType: Catalog
+    catalog:
+      packageName: argocd-operator
+      selector:
+        matchLabels:
+          example.com/support: "true"
 ```
 
 This selects catalogs labeled with `example.com/support: "true"`.
@@ -59,17 +69,22 @@ This selects catalogs labeled with `example.com/support: "true"`.
 apiVersion: olm.operatorframework.io/v1
 kind: ClusterExtension
 metadata:
-  name: my-extension
+  name: argocd
 spec:
-  packageName: my-package
-  catalog:
-    selector:
-      matchExpressions:
-        - key: example.com/support
-          operator: In
-          values:
-            - "gold"
-            - "platinum"
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
+  source:
+    sourceType: Catalog
+    catalog:
+      packageName: argocd-operator
+      selector:
+        matchExpressions:
+          - key: example.com/support
+            operator: In
+            values:
+              - "gold"
+              - "platinum"
 ```
 
 This selects catalogs where the label `example.com/support` has the value `gold` or `platinum`.
@@ -84,16 +99,21 @@ You can exclude catalogs by using the `NotIn` or `DoesNotExist` operators in `ma
 apiVersion: olm.operatorframework.io/v1
 kind: ClusterExtension
 metadata:
-  name: my-extension
+  name: argocd
 spec:
-  packageName: my-package
-  catalog:
-    selector:
-      matchExpressions:
-        - key: olm.operatorframework.io/metadata.name
-          operator: NotIn
-          values:
-            - unwanted-content-management
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
+  source:
+    sourceType: Catalog
+    catalog:
+      packageName: argocd-operator
+      selector:
+        matchExpressions:
+          - key: olm.operatorframework.io/metadata.name
+            operator: NotIn
+            values:
+              - unwanted-catalog
 ```
 
 This excludes the catalog named `unwanted-catalog` from consideration.
@@ -104,14 +124,19 @@ This excludes the catalog named `unwanted-catalog` from consideration.
 apiVersion: olm.operatorframework.io/v1
 kind: ClusterExtension
 metadata:
-  name: my-extension
+  name: argocd
 spec:
-  packageName: my-package
-  catalog:
-    selector:
-      matchExpressions:
-        - key: example.com/support
-          operator: DoesNotExist
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
+  source:
+    sourceType: Catalog
+    catalog:
+      packageName: argocd-operator
+      selector:
+        matchExpressions:
+          - key: example.com/support
+            operator: DoesNotExist
 ```
 
 This selects catalogs that do not have the `example.com/support` label.
@@ -200,11 +225,16 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
     metadata:
       name: install-my-operator
     spec:
-      packageName: my-operator
-      catalog:
-        selector:
-          matchLabels:
-            example.com/support: "true"
+      namespace: my-operator-ns
+      serviceAccount:
+        name: my-operator-installer
+      source:
+        sourceType: Catalog
+        catalog:
+          packageName: my-operator
+          selector:
+            matchLabels:
+              example.com/support: "true"
     ```
 
 3. **Apply the Resources**

docs/concepts/crd-upgrade-safety.md

@@ -53,26 +53,26 @@ not cause the CRD Upgrade Safety preflight check to halt the upgrade:
 ## Disabling CRD Upgrade Safety
 
 The CRD Upgrade Safety preflight check can be entirely disabled by adding the
-`preflight.crdUpgradeSafety.disabled` field with a value of "true" to the ClusterExtension of the CRD.
+`.spec.install.preflight.crdUpgradeSafety.enforcement` field with a value of `None` to the `ClusterExtension` of the CRD.
 
 ```yaml
 apiVersion: olm.operatorframework.io/v1
 kind: ClusterExtension
 metadata:
-    name: clusterextension-sample
+  name: argocd
 spec:
-    source:
-      sourceType: Catalog
-      catalog:
-        packageName: argocd-operator
-        version: 0.6.0
-    install:
-      namespace: default
-      serviceAccount:
-        name: argocd-installer
-      preflight:
-        crdUpgradeSafety:
-          disabled: true
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
+  source:
+    sourceType: Catalog
+    catalog:
+      packageName: argocd-operator
+      version: 0.6.0
+  install:
+    preflight:
+      crdUpgradeSafety:
+        enforcement: None
 ```
 
 You cannot disable individual field validators. If you disable the CRD Upgrade Safety preflight check, all field validators are disabled.

docs/concepts/upgrade-support.md

@@ -15,7 +15,7 @@ It also introduces an API to enable independently verified upgrades and downgrad
 
 When determining upgrade edges, also known as upgrade paths or upgrade constraints, for an installed cluster extension, Operator Lifecycle Manager (OLM) v1 supports [legacy OLM semantics](https://olm.operatorframework.io/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/) by default. This support follows the behavior from legacy OLM, including `replaces`, `skips`, and `skipRange` directives, with a few noted differences.
 
-By supporting legacy OLM semantics, OLM v1 now honors the upgrade graph from catalogs accurately.
+By supporting legacy OLM semantics, OLM v1 honors the upgrade graph from catalogs accurately.
 
 If there are multiple possible successors, OLM v1 behavior differs in the following ways:
 
@@ -29,7 +29,7 @@ Consider the following set of file-based catalog (FBC) channel entries:
   - name: example.v3.0.0
     skips: ["example.v2.0.0"]
   - name: example.v2.0.0
-    skipRange: >=1.0.0 <2.0.0
+    skipRange: ">=1.0.0 <2.0.0"
   ```
 
 If `1.0.0` is installed, OLM v1 behavior differs in the following ways:
@@ -39,18 +39,21 @@ If `1.0.0` is installed, OLM v1 behavior differs in the following ways:
 
 You can change the default behavior of the upgrade constraints by setting the `upgradeConstraintPolicy` parameter in your cluster extension's custom resource (CR).
 
-``` yaml hl_lines="10"
+``` yaml hl_lines="14"
 apiVersion: olm.operatorframework.io/v1
 kind: ClusterExtension
 metadata:
   name: <extension_name>
 spec:
-  installNamespace: <namespace>
-  packageName: <package_name>
+  namespace: <namespace>
   serviceAccount:
     name: <service_account>
-  upgradeConstraintPolicy: SelfCertified
-  version: "<version_or_version_range>"
+  source:
+    sourceType: Catalog
+    catalog:
+      packageName: <package_name>
+      version: "<version_or_version_range>"
+      upgradeConstraintPolicy: SelfCertified
 ```
 
 Setting the `upgradeConstraintPolicy` to:
@@ -82,26 +85,25 @@ You must verify and perform upgrades manually in cases where automatic upgrades
 !!! warning
     If you want to force an upgrade manually, you must thoroughly verify the outcome before applying any changes to production workloads. Failure to test and verify the upgrade might lead to catastrophic consequences such as data loss.
 
-As a package admin, if you must upgrade or downgrade to version that might be incompatible with the currently installed version, you can set the `.spec.upgradeConstraintPolicy` field to `SelfCertified` on the relevant `ClusterExtension` resource.
+As a package admin, if you must upgrade or downgrade to version that might be incompatible with the currently installed version, you can set the `.spec.source.catalog.upgradeConstraintPolicy` field to `SelfCertified` on the relevant `ClusterExtension` resource.
 
 If you set the field to `SelfCertified`, no upgrade constraints are set on the package. As a result, you can change the version to any version available in the catalogs for a given package.
 
-Example `ClusterExtension` with `.spec.upgradeConstraintPolicy` field set to `SelfCertified`:
+Example `ClusterExtension` with `.spec.source.catalog.upgradeConstraintPolicy` field set to `SelfCertified`:
 
 ```yaml
 apiVersion: olm.operatorframework.io/v1
 kind: ClusterExtension
 metadata:
   name: extension-sample
 spec:
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
   source:
     sourceType: Catalog
     catalog:
       packageName: argocd-operator
       version: 0.6.0
       upgradeConstraintPolicy: SelfCertified
-  install:
-    namespace: argocd
-    serviceAccout:
-      name: argocd-installer
 ```

docs/concepts/version-ranges.md

@@ -31,7 +31,7 @@ You define a version range by adding a comparison string to the `spec.version` f
 To specify a version range, use a range comparison similar to the following example:
 
 ```yaml
-version: >=3.0, <3.6
+version: ">=3.0, <3.6"
 ```
 
 #### Wildcards in comparisons