Fix docs: "How to" section

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 <[email protected]>

docs/howto/catalog-queries.md

@@ -1,15 +1,30 @@
 # Catalog queries
 
+After you [add a catalog of extensions](../tutorials/add-catalog.md) to your cluster, you must port forward your catalog as a service.
+Then you can query the catalog by using `curl` commands and the `jq` CLI tool to find extensions to install.
+
+## Prerequisites
+
+* You have added a ClusterCatalog of extensions, such as [OperatorHub.io](https://operatorhub.io), to your cluster.
+* You have installed the `jq` CLI tool.
+
 !!! note
     By default, Catalogd is installed with TLS enabled for the catalog webserver.
     The following examples will show this default behavior, but for simplicity's sake will ignore TLS verification in the curl commands using the `-k` flag.
 
+You also need to port forward the catalog server service:
+
+``` terminal
+kubectl -n olmv1-system port-forward svc/catalogd-service 8443:443
+```
 
-You can use the `curl` command with `jq` to query catalogs that are installed on your cluster.
+Now you can use the `curl` command with `jq` to query catalogs that are installed on your cluster.
 
 ``` terminal title="Query syntax"
 curl -k https://localhost:8443/catalogs/operatorhubio/api/v1/all | <query>
 ```
+`<query>`
+: One of the `jq` queries from this document
 
 ## Package queries
 
@@ -28,36 +43,66 @@ curl -k https://localhost:8443/catalogs/operatorhubio/api/v1/all | <query>
     jq -s '.[] | select( .schema == "olm.package") | select( .name == "<package_name>")'
     ```
 
+    `<package_name>`
+    : Name of the package from the catalog you are querying.
+
 * Catalog blobs in a package:
     ``` terminal
     jq -s '.[] | select( .package == "<package_name>")'
     ```
 
+    `<package_name>`
+    : Name of the package from the catalog you are querying.
+
 ## Channel queries
 
 * Channels in a package:
     ``` terminal
     jq -s '.[] | select( .schema == "olm.channel" ) | select( .package == "<package_name>") | .name'
     ```
 
+    `<package_name>`
+    : Name of the package from the catalog you are querying.
+
 * Versions in a channel:
     ``` terminal
     jq -s '.[] | select( .package == "<package_name>" ) | select( .schema == "olm.channel" ) | select( .name == "<channel_name>" ) | .entries | .[] | .name'
     ```
 
+    `<package_name>`
+    : Name of the package from the catalog you are querying.
+
+    `<channel_name>`
+    : Name of the channel for a given package.
+
 * Latest version in a channel and upgrade path:
     ``` terminal
-    jq -s '.[] | select( .schema == "olm.channel" ) | select ( .name == "<channel>") | select( .package == "<package_name>")'
+    jq -s '.[] | select( .schema == "olm.channel" ) | select ( .name == "<channel_name>") | select( .package == "<package_name>")'
     ```
 
+    `<package_name>`
+    : Name of the package from the catalog you are querying.
+
+    `<channel_name>`
+    : Name of the channel for a given package.
+
 ## Bundle queries
 
 * Bundles in a package:
     ``` terminal
     jq -s '.[] | select( .schema == "olm.bundle" ) | select( .package == "<package_name>") | .name'
     ```
 
+    `<package_name>`
+    : Name of the package from the catalog you are querying.
+
 * Bundle dependencies and available APIs:
     ``` terminal
     jq -s '.[] | select( .schema == "olm.bundle" ) | select ( .name == "<bundle_name>") | select( .package == "<package_name>")'
     ```
+
+    `<package_name>`
+    : Name of the package from the catalog you are querying.
+
+    `<bundle_name>`
+    : Name of the bundle for a given package.

docs/howto/how-to-channel-based-upgrades.md

@@ -10,19 +10,18 @@ kind: ClusterExtension
 metadata:
   name: argocd
 spec:
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
   source:
     sourceType: Catalog
     catalog:
       packageName: argocd-operator
       # Automatically upgrade to the latest version found in the preview and dev-preview channels
       channels: [dev-preview, preview]
-  install:
-    namespace: argocd
-    serviceAccount:
-      name: argocd-installer
 ```
 
-Note that the `version` field also accepts a version range to further restrict the set of possible upgradable operator versions.
+Note that the `version` field also supports [version pinning](./how-to-pin-version.md) and [version ranges](./how-to-version-range-upgrades.md) to further restrict the set of possible upgradable operator versions.
 
 Example:
 
@@ -32,14 +31,15 @@ kind: ClusterExtension
 metadata:
   name: argocd
 spec:
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
   source:
     sourceType: Catalog
     catalog:
       packageName: argocd-operator
       channels: [stable] # Automatically upgrade to the latest version found in ‘stable’
-      version: “!1.3.2” # Don’t allow version 1.3.2
-  install:
-    namespace: argocd
-    serviceAccount:
-      name: argocd-installer
+      version: "!=1.3.2" # Don’t allow version 1.3.2
 ```
+
+For more information on SemVer version ranges see [version ranges](../concepts/version-ranges.md)

docs/howto/how-to-pin-version.md

@@ -10,15 +10,14 @@ kind: ClusterExtension
 metadata:
   name: argocd
 spec:
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
   source:
     sourceType: Catalog
     catalog:
         packageName: argocd-operator
         version: 0.6.0 # Pin argocd-operator to v0.6.0
-  install:
-    namespace: argocd
-    serviceAccount:
-      name: argocd-installer
 ```
 
 For more information on SemVer version ranges see [version ranges](../concepts/version-ranges.md)

docs/howto/how-to-version-range-upgrades.md

@@ -10,15 +10,14 @@ kind: ClusterExtension
 metadata:
   name: argocd
 spec:
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
   source:
     sourceType: Catalog
     catalog:
       packageName: argocd-operator
       version: ">=3.0, <3.6"  # Install versions from v3.0.0 up to, but not including, v3.6.0
-  install:
-    namespace: argocd
-    serviceAccount:
-      name: argocd-installer
 ```
 
 For more information on SemVer version ranges see [version-ranges](../concepts/version-ranges.md)

docs/howto/how-to-z-stream-upgrades.md

@@ -10,15 +10,14 @@ kind: ClusterExtension
 metadata:
   name: argocd
 spec:
+  namespace: argocd
+  serviceAccount:
+    name: argocd-installer
   source:
     sourceType: Catalog
     catalog:
       packageName: argocd-operator
-      version: “~2.3" # Automatically upgrade patch releases for v2.3
-  install:
-    namespace: argocd
-    serviceAccount:
-      name: argocd-installer
+      version: "~2.3" # Automatically upgrade patch releases for v2.3
 ```
 
 For more information on SemVer version ranges see [version ranges](../concepts/version-ranges.md)