Fix docs

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

Together with fixing snippets & outputs this fixes some rendering issues.

Signed-off-by: Mikalai Radchuk <[email protected]>

Author: Mikalai Radchuk

docs/concepts/crd-upgrade-safety.md

@@ -61,18 +61,18 @@ kind: ClusterExtension
 metadata:
     name: clusterextension-sample
 spec:
+    namespace: default
+    serviceAccount:
+      name: argocd-installer
     source:
       sourceType: Catalog
       catalog:
         packageName: argocd-operator
         version: 0.6.0
     install:
-      namespace: default
-      serviceAccount:
-        name: argocd-installer
       preflight:
         crdUpgradeSafety:
-          disabled: true
+          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

@@ -63,8 +63,8 @@ where setting the `upgradeConstraintPolicy` to:
 
 OLM supports Semver to provide a simplified way for package authors to define compatible upgrades. According to the Semver standard, releases within a major version (e.g. `>=1.0.0 <2.0.0`) must be compatible. As a result, package authors can publish a new package version following the Semver specification, and OLM assumes compatibility. Package authors do not have to explicitly define upgrade edges in the catalog.
 
-> [!NOTE]
-> Currently, OLM 1.0 does not support automatic upgrades to the next major version. You must manually verify and perform major version upgrades. For more information about major version upgrades, see [Manually verified upgrades and downgrades](#manually-verified-upgrades-and-downgrades).
+!!! note
+    Currently, OLM 1.0 does not support automatic upgrades to the next major version. You must manually verify and perform major version upgrades. For more information about major version upgrades, see [Manually verified upgrades and downgrades](#manually-verified-upgrades-and-downgrades).
 
 ### Upgrades within the major version zero
 

docs/contribute/developer.md

@@ -3,10 +3,10 @@
 
 The following `make run` starts a [KIND](https://sigs.k8s.io/kind) cluster for you to get a local cluster for testing, see the manual install steps below for how to run against a remote cluster.
 
-> [!NOTE]
-> You will need a container runtime environment, like Docker, or experimentally, Podman, installed, to run Kind.
-> 
-> If you are on MacOS, see [Special Setup for MacOS](#special-setup-for-macos).
+!!! note
+    You will need a container runtime environment, like Docker, or experimentally, Podman, installed, to run Kind.
+
+    If you are on MacOS, see [Special Setup for MacOS](#special-setup-for-macos).
 
 ### Quickstart Installation
 
@@ -20,9 +20,9 @@ This will build a local container image of the operator-controller, create a new
 
 ### To Install Any Given Release
 
-> [!CAUTION]  
-> Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
-> may affect an existing installation of cert-manager and cause cluster instability.
+!!! warning
+    Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
+    may affect an existing installation of cert-manager and cause cluster instability.
 
 The latest version of Operator Controller can be installed with the following command:
 

docs/getting-started/olmv1_getting_started.md

@@ -2,9 +2,9 @@
 
 The following script will install OLMv1 on a Kubernetes cluster. If you don't have one, you can deploy a Kubernetes cluster with [KIND](https://sigs.k8s.io/kind).
 
-> [!CAUTION]  
-> Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
-> may affect an existing installation of cert-manager and cause cluster instability.
+!!! warning
+    Operator-Controller depends on [cert-manager](https://cert-manager.io/). Running the following command
+    may affect an existing installation of cert-manager and cause cluster instability.
 
 The latest version of Operator Controller can be installed with the following command:
 
@@ -44,7 +44,7 @@ spec:
     type: Image
     image:
       ref: quay.io/operatorhubio/catalog:latest
-      pollInterval: 10m
+      pollIntervalMinutes: 10
 EOF
 ```
 
@@ -78,7 +78,7 @@ and on the extension upgrade process [here](../tutorials/upgrade-extension.md).
 
 ```bash
 # Update to v0.11.0
-kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"content-management": {"version": "0.11.0"}}}}'
+kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}'
 
 ```
 
@@ -106,10 +106,10 @@ kubectl delete namespace argocd
 
 ```bash
 # Delete installer service account cluster roles
-kubectl delete clusterrole argocd-installer-clusterrole && kubectl delete clusterrole argocd-rbac-clusterrole
+kubectl delete clusterrole argocd-installer-clusterrole && kubectl delete clusterrole argocd-installer-rbac-clusterrole
 ```
 
 ```bash
 # Delete installer service account cluster role bindings
-kuebctl delete clusterrolebinding argocd-installer-binding && kubectl delete clusterrolebinding argocd-rbac-binding
+kubectl delete clusterrolebinding argocd-installer-binding && kubectl delete clusterrolebinding argocd-installer-rbac-binding
 ```

docs/tutorials/add-catalog.md

@@ -29,35 +29,33 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https://
     apiVersion: olm.operatorframework.io/v1alpha1
     kind: ClusterCatalog
     metadata:
-      name: operatorhubio
+      name: <catalog_name>
     spec:
       source:
         type: Image
         image:
           ref: <catalog_image>
-          pollInterval: <poll_interval_duration>
+          pollIntervalMinutes: <poll_interval_duration>
     ```
 
     `catalog_name`
     :   Specifies the image reference for the catalog you want to install, such as `quay.io/operatorhubio/catalog:latest`.
 
     `poll_interval_duration`
-    :   Specifies the interval for polling the remote registry for newer image digests.
-            The default value is `24h`.
-            Valid units include seconds (`s`), minutes (`m`), and hours (`h`).
-            To disable polling, set a zero value, such as `0s`.
+    :   Specifies the number of minutes for polling the remote registry for newer image digests.
+            This field is optional. To disable polling, unset the field.
 
     ``` yaml title="Example `operatorhubio.yaml` CR"
     apiVersion: olm.operatorframework.io/v1alpha1
     kind: ClusterCatalog
     metadata:
-      name: operatorhub
+      name: operatorhubio
     spec:
       source:
         type: Image
         image:
           ref: quay.io/operatorhubio/catalog:latest
-          pollInterval: 10m
+          pollIntervalMinutes: 10
     ```
 
 2. Apply the ClusterCatalog CR:
@@ -81,8 +79,8 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https://
         ```
 
         ``` terminal title="Example output"
-        NAME           LASTUNPACKED   AGE
-        operatorhubio  9m31s          9m55s
+        NAME            LASTUNPACKED   SERVING   AGE
+        operatorhubio   18s            True      27s
         ```
 
     * Check the status of your catalog:
@@ -99,40 +97,41 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https://
         API Version:  olm.operatorframework.io/v1alpha1
         Kind:         ClusterCatalog
         Metadata:
-        Creation Timestamp:  2024-10-02T19:51:24Z
-        Finalizers:
+          Creation Timestamp:  2024-11-11T13:19:12Z
+          Finalizers:
             olm.operatorframework.io/delete-server-cache
-        Generation:        1
-        Resource Version:  33321
-        UID:               52894532-0646-41a5-8285-c7f48bba49e4
+          Generation:        1
+          Resource Version:  2143
+          UID:               2cebaf11-7a5c-4813-bef3-58ac2e373057
         Spec:
-          Priority:  0
+          Availability Mode:  Available
+          Priority:           0
           Source:
             Image:
-              Poll Interval:  10m0s
-              Ref:            quay.io/operatorhubio/catalog:latest
-            Type:             Image
+              Poll Interval Minutes:  10
+              Ref:                    quay.io/operatorhubio/catalog:latest
+            Type:                     Image
         Status:
           Conditions:
-            Last Transition Time:  2024-03-12T19:35:34Z
+            Last Transition Time:  2024-11-11T13:19:21Z
             Message:               Successfully unpacked and stored content from resolved source
-            Observed Generation:   2
+            Observed Generation:   1
             Reason:                Succeeded
-            Status:                False
+            Status:                True
             Type:                  Progressing
-            Last Transition Time:  2024-03-12T19:35:34Z
+            Last Transition Time:  2024-11-11T13:19:21Z
             Message:               Serving desired content from resolved source
-            Observed Generation:   2
+            Observed Generation:   1
             Reason:                Available
             Status:                True
             Type:                  Serving
-          URLs:
-            Base:                  https://catalogd-server.olmv1-system.svc/catalogs/operatorhubio
-          Last Unpacked:           2024-03-12T19:35:34Z
+          Last Unpacked:           2024-11-11T13:19:21Z
           Resolved Source:
             Image:
-              Last Successful Poll Attempt:  2024-03-12T19:35:26Z
-              Ref:                           quay.io/operatorhubio/catalog@sha256:dee29aaed76fd1c72b654b9bc8bebc4b48b34fd8d41ece880524dc0c3c1c55ec
-            Type:                            Image
-        Events:                              <none>
+              Ref:  quay.io/operatorhubio/catalog@sha256:025cb23665449d8974102dda042c2e25bd3cb9138791971748f48d57c90a21d8
+            Type:   Image
+          Urls:
+            Base:  https://catalogd-service.olmv1-system.svc/catalogs/operatorhubio
+        Events:    <none>
+
         ```

docs/tutorials/downgrade-extension.md

@@ -26,7 +26,7 @@ Custom Resource Definitions (CRDs) ensure that the resources used by the `Cluste
 
 **Disable CRD Safety Check Configuration:**
 
-Add the `crdUpgradeSafety` field and set its `policy` to `Disabled` in the `ClusterExtension` resource under the `preflight` section.
+Add the `crdUpgradeSafety` field and set its `enforcement` to `None` in the `ClusterExtension` resource. This configuration disables CRD safety checks during the downgrade process.
 
 **Example:**
 
@@ -36,29 +36,27 @@ kind: ClusterExtension
 metadata:
   name: example-extension
 spec:
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
   install:
     preflight:
       crdUpgradeSafety:
-        policy: Disabled
-    namespace: argocd
-    serviceAccount:
-      name: argocd-installer
+        enforcement: None
   source:
     sourceType: Catalog
     catalog:
       packageName: argocd-operator
       version: 0.6.0
-      upgradeConstraintPolicy: SelfCertified
 ```
 
-** Disable CRD Upgrade Safety Check:**
+**Command Example:**
 
-**Patch the ClusterExtension Resource:**
+If you prefer using the command line, you can use `kubectl` to modify the upgrade CRD safety check configuration.
 
-   ```bash
-   kubectl patch clusterextension <extension_name> --patch '{"spec":{"install":{"preflight":{"crdUpgradeSafety":{"policy":"Disabled"}}}}}' --type=merge
-   ```
-   Kubernetes will apply the updated configuration, disabling CRD safety checks during the downgrade process.
+```bash
+kubectl patch clusterextension example-extension --patch '{"spec":{"install":{"preflight":{"crdUpgradeSafety":{"enforcement":"None"}}}}}' --type=merge
+```
 
 ### 2. Ignoring Catalog Provided Upgrade Constraints
 
@@ -76,24 +74,27 @@ kind: ClusterExtension
 metadata:
   name: example-extension
 spec:
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
+  install:
+    preflight:
+      crdUpgradeSafety:
+        enforcement: None
   source:
     sourceType: Catalog
     catalog:
       packageName: argocd-operator
       version: 0.6.0
       upgradeConstraintPolicy: SelfCertified
-  install:
-    namespace: argocd
-    serviceAccount:
-      name: argocd-installer
 ```
 
 **Command Example:**
 
 If you prefer using the command line, you can use `kubectl` to modify the upgrade constraint policy.
 
 ```bash
-kubectl patch clusterextension <extension_name> --patch '{"spec":{"upgradeConstraintPolicy":"SelfCertified"}}' --type=merge
+kubectl patch clusterextension example-extension --patch '{"spec":{"source": {"catalog":{"upgradeConstraintPolicy":"SelfCertified"}}}}' --type=merge
 ```
 
 ### 3. Executing the Downgrade
@@ -102,34 +103,38 @@ Once the CRD safety checks are disabled and upgrade constraints are set, you can
 
 1. **Edit the ClusterExtension Resource:**
 
-   Modify the `ClusterExtension` custom resource to specify the target version and adjust the upgrade constraints.
+    Modify the `ClusterExtension` custom resource to specify the target version and adjust the upgrade constraints.
 
-   ```bash
-   kubectl edit clusterextension <extension_name>
-   ```
+    ```bash
+    kubectl edit clusterextension example-extension
+    ```
 
 2. **Update the Version:**
 
-   Within the YAML editor, update the `spec` section as follows:
-
-   ```yaml
-   apiVersion: olm.operatorframework.io/v1alpha1
-   kind: ClusterExtension
-   metadata:
-     name: <extension_name>
-   spec:
-     source:
-       sourceType: Catalog
-       catalog:
-         packageName: <package_name>
-         version: <target_version>
-     install:
-       namespace: <namespace>
-       serviceAccount:
-         name: <service_account>
-   ```
-
-   - **`version`:** Specify the target version you wish to downgrade to.
+    Within the YAML editor, update the `spec` section as follows:
+
+    ```yaml
+    apiVersion: olm.operatorframework.io/v1alpha1
+    kind: ClusterExtension
+    metadata:
+      name: example-extension
+    spec:
+      namespace: argocd
+      serviceAccount:
+        name: argocd-installer
+      install:
+        preflight:
+          crdUpgradeSafety:
+            enforcement: None
+      source:
+        sourceType: Catalog
+        catalog:
+          packageName: argocd-operator
+          version: <target_version>
+          upgradeConstraintPolicy: SelfCertified
+    ```
+
+    - **`<target_version>`:** Specify the target version you wish to downgrade to.
 
 3. **Apply the Changes:**
 
@@ -144,7 +149,7 @@ After completing the downgrade, verify that the `ClusterExtension` is functionin
 1. **Check the Status of the ClusterExtension:**
 
    ```bash
-   kubectl get clusterextension <extension_name> -o yaml
+   kubectl get clusterextension example-extension -o yaml
    ```
 
    Ensure that the `status` reflects the target version and that there are no error messages.