From 1df52c71e52bc6b46c9ecbb1462254c9a89b61ca Mon Sep 17 00:00:00 2001
From: Per Goncalves da Silva <perdasilva@redhat.com>
Date: Fri, 6 Sep 2024 18:37:53 +0200
Subject: [PATCH] :book:[Docs] Update quickstart documentation (#1225)

Signed-off-by: Per Goncalves da Silva <pegoncal@redhat.com>
Co-authored-by: Per Goncalves da Silva <pegoncal@redhat.com>
---
 README.md                                     | 172 ++++++------------
 ...ges.md => exploring-available-packages.md} |   2 +
 docs/Tasks/installing-an-extension.md         |  13 +-
 ...ension.md => uninstalling-an-extension.md} |   4 +
 .../Tasks/create-installer-service-account.md |   3 +
 docs/drafts/Tasks/downgrading-an-extension.md |   3 +
 docs/drafts/Tasks/upgrading-an-extension.md   | 169 +++++++++++++++++
 docs/drafts/refs/olmv1-limitations.md         |   3 +
 mkdocs.yml                                    |   4 +-
 9 files changed, 243 insertions(+), 130 deletions(-)
 rename docs/Tasks/{explore-available-packages.md => exploring-available-packages.md} (99%)
 rename docs/Tasks/{uninstall-an-extension.md => uninstalling-an-extension.md} (86%)
 create mode 100644 docs/drafts/Tasks/create-installer-service-account.md
 create mode 100644 docs/drafts/Tasks/downgrading-an-extension.md
 create mode 100644 docs/drafts/Tasks/upgrading-an-extension.md
 create mode 100644 docs/drafts/refs/olmv1-limitations.md

diff --git a/README.md b/README.md
index 822bab9b2..275486209 100644
--- a/README.md
+++ b/README.md
@@ -17,16 +17,12 @@ OLM v1 consists of two different components:
 * operator-controller (this repository)
 * [catalogd](https://github.com/operator-framework/catalogd)
 
-For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](./docs/olmv1_overview.md).
-
-## Getting Started
-You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.
-
-> [!NOTE]
-> Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
+For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/olmv1_overview.md).
 
 ### Installation
 
+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.
@@ -37,10 +33,24 @@ The latest version of Operator Controller can be installed with the following co
 curl -L -s https://github.com/operator-framework/operator-controller/releases/latest/download/install.sh | bash -s
 ```
 
-### Create a ClusterCatalog
+## Getting Started with OLM v1
+
+This quickstart procedure will guide you through the following processes:
+* Deploying a catalog
+* Installing, upgrading, or downgrading an extension
+* Deleting catalogs and extensions
+
+### Create a Catalog
 
-The ClusterCatalog resource supports file-based catalog ([FBC](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs)) images.
-The following example uses the official [OperatorHub](https://operatorhub.io) catalog.
+OLM v1 is designed to source content from an on-cluster catalog in the file-based catalog ([FBC](https://olm.operatorframework.io/docs/reference/file-based-catalogs/#docs)) format.
+These catalogs are deployed and configured through the `ClusterCatalog` resource. More information on adding catalogs
+can be found [here](./docs/Tasks/adding-a-catalog).
+
+The following example uses the official [OperatorHub](https://operatorhub.io) catalog that contains many different
+extensions to choose from. Note that this catalog contains packages designed to work with OLM v0, and that not all packages
+will work with OLM v1. More information on catalog exploration and content compatibility can be found [here](./docs/refs/catalog-queries.md). 
+
+To create the catalog, run the following command:
 
 ```bash
 # Create ClusterCatalog
@@ -58,148 +68,70 @@ spec:
 EOF
 ```
 
+Once the catalog is unpacked successfully, its content will be available for installation.
+
 ```bash
 # Wait for the ClusterCatalog to be unpacked
 kubectl wait --for=condition=Unpacked=True clustercatalog/operatorhubio --timeout=60s
 ```
 
-### Install Cluster Extension
+### Install a Cluster Extension
+
+For simplicity, the following example manifest includes all necessary resources to install the ArgoCD operator. 
+The manifest includes installation namespace, installer service account and associated minimal set of RBAC permissions 
+needed for installation, and the ClusterExtension resource, which specifies the name and version of the extension to install.
+More information on installing extensions can be found [here](docs/Tasks/installing-an-extension).
 
 ```bash
 # Apply the sample ClusterExtension. Manifest already includes
 # namespace and adequately privileged service account
-kubectl apply -f config/samples/olm_v1alpha1_clusterextension.yaml
-```
-
-#### Upgrade/Downgrade
-
-```bash
-# Update the required version
-kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"version": "0.11.0"}}'
-```
-
-#### Uninstall
-
-```bash
-# Delete cluster extension and residing namespace
-kubectl delete clusterextension/argocd && kubectl delete namespace argocd
-```
-
-```bash
-# Delete cluster-scoped resources
-kubectl delete --ignore-not-found=true -f config/samples/olm_v1alpha1_clusterextension.yaml 
+kubectl apply -f https://raw.githubusercontent.com/operator-framework/operator-controller/main/config/samples/olm_v1alpha1_clusterextension.yaml
 ```
 
-### Advanced Usage
-
-> [!WARNING]
-> The scripts referenced in this section are best-effort and may not always work as
-> intended. They are provided as a stopgap until we can offer production grade tooling
-> for tasks such as: searching the catalog, discovering supported bundles, and determining
-> the least-privilege set of permissions required by the installer service account to install
-> the content.
+### Upgrade the Cluster Extension
 
-#### Installation
-
-An extension needs a namespace in which to be installed and a service account with sufficient
-privileges to install the content. For instance:
+To upgrade the installed extension, update the version field in the ClusterExtension resource. Note that
+there must be CRD compatibility between the versions being upgraded, and the target version must be
+compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md), 
+compatible with OLM v1. More information on CRD upgrade safety can be found [here](./docs/refs/crd-upgrade-safety.md), 
+and on the extension upgrade process [here](./docs/drafts/Tasks/upgrading-an-extension).
 
 ```bash
-# Create argocd namespace for the argocd-operator
-kubectl create ns argocd
-```
+# Update to v0.11.0
+kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}'
 
-```bash
-# Create installer service account
-kubectl create serviceaccount -n argocd-system argocd-installer
 ```
 
-> [!WARNING]
-> We work around the absence of reliable tooling to determine the set of least privileges
-> for the installer service account to be able to install a given bundle by giving
-> the installer service account cluster admin privileges.
-> This is not an option for production clusters due to the security implications.
-> The OLM community is working hard to bridge this tooling gap.
+For information on the downgrade process, see [here](./docs/drafts/Tasks/downgrading-an-extension.md).
 
-```bash
-# Give service account cluster admin privileges
-# This works with KIND - consult documentation for instructions on how
-# to grant admin privileges for your kubernetes distribution 
-kubectl create clusterrolebinding "argocd-operator-installer-cluster-admin" \
-    --clusterrole=cluster-admin \
-    --serviceaccount="argocd-system:argocd-operator-installer"
-```
+### Uninstall the Cluster Extension
 
-```bash
-# Apply ClusterExtension
-cat <<EOF
-apiVersion: olm.operatorframework.io/v1alpha1
-kind: ClusterExtension
-metadata:
-  name: argocd
-spec:
-  installNamespace: argocd-system
-  packageName: argocd-operator
-  version: 0.6.0
-  serviceAccount:
-    name: argocd-operator-installer
-EOF | kubectl apply -f -
-```
+To uninstall an extension, delete the ClusterExtension resource. This will trigger the uninstallation process, which will
+remove all resources created by the extension. More information on uninstalling extensions can be found [here](./docs/Tasks/uninstalling-an-extension).
 
 ```bash
-# Wait for installation to finish successfully
-kubectl wait --for=condition=Success=True clusterextension/argocd --timeout=60s
+# Delete cluster extension and residing namespace
+kubectl delete clusterextension/argocd
 ```
 
-#### Finding Content
+#### Cleanup
 
-The catalog content can be downloaded locally as a json file and queried using tools like [jq](The catalog content can be downloaded locally as a json file and queried using tools like [jq](The catalog content can be downloaded locally as a json file and queried using tools like [jq](https://jqlang.github.io/jq/).
-The _catalogd-catalogserver_ service in the _olmv1-system_ namespace provides an endpoint from which to
-download the catalog. This endpoint can be found in the status (.status.contentURL). 
-
-The [download-catalog.sh](hack/tools/catalogs/download-catalog) script automates this process:
+Extension installation requires the creation of a namespace, an installer service account, and its RBAC. Once the
+extension is uninstalled, these resources can be cleaned up.
 
 ```bash
-# Download the catalog provided by the unpacked ClusterCatalog called operatorhuio
-# The catalog will be downloaded to operatorhubio-catalog.json
-./hack/tools/catalogs/download-catalog operatorhubio
+# Delete namespace, and by extension, the installer service account, Role, and RoleBinding
+kubectl delete namespace argocd
 ```
 
-OLM v1 currently supports the installation of bundles that:
-- support the 'AllNamespaces' install mode
-- do not have any package or gvk dependencies
-- do not have webhooks
-
-The [list-compatible-bundles.sh](hack/tools/catalogs/list-compatible-bundles) script attempts
-to filter out unsupported bundles:
-
 ```bash
-# Returns a JSON array of {packageName: "", versions: ["", ...]} objects
-# This array can be further queried with jq
-./hack/tools/catalogs/list-compatible-bundles < operatorhubio-catalog.json
-# The -r option also allows you to define a regular expression for the package name
-# for futher filtering
-./hack/tools/catalogs/list-compatible-bundles -r 'argocd' < operatorhubio-catalog.json
+# Delete installer service account cluster roles
+kubectl delete clusterrole argocd-installer-clusterrole && kubectl delete clusterrole argocd-rbac-clusterrole
 ```
 
-#### Determining Service Account Privileges
-
-The installer service account needs sufficient privileges to create the bundle's resources,
-as well as to assign RBAC to those resources. This information can be derived from the 
-bundle's ClusterServiceVersion manifest.
-
-The [install-bundle.sh](hack/tools/catalogs/bundle-manifests) script generates all required
-manifests for a bundle installation (including Namespace, and ClusterExtension resources), but can also
-be used to determine the RBAC for the installer service account:
-
 ```bash
-# Get RBAC for a ClusterExtension called 'argocd'
-# using package 'argocd-operator' at version '0.6.0'
-# in namespace 'argocd-system'
-RBAC_ONLY=1 ./hack/tools/catalogs/bundle-manifests argocd argocd-operator 0.6.0 argocd-system < operatorhubio-catalog.json
-# Or, let the script do all the heavy lifting (creation of Namespace, and ClusterExtension, as well as
-# the ServiceAccount and all required RBAC
-./hack/tools/catalogs/bundle-manifests argocd argocd-operator 0.6.0 argocd-system < operatorhubio-catalog.json | kubectl apply -f -
+# Delete installer service account cluster role bindings
+kuebctl delete clusterrolebinding argocd-installer-binding && kubectl delete clusterrolebinding argocd-rbac-binding
 ```
 
 ## License
diff --git a/docs/Tasks/explore-available-packages.md b/docs/Tasks/exploring-available-packages.md
similarity index 99%
rename from docs/Tasks/explore-available-packages.md
rename to docs/Tasks/exploring-available-packages.md
index 001867dd2..eb3e1499a 100644
--- a/docs/Tasks/explore-available-packages.md
+++ b/docs/Tasks/exploring-available-packages.md
@@ -1,3 +1,5 @@
+# Exploring Available Packages
+
 After you add a catalog of extensions 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.
 
diff --git a/docs/Tasks/installing-an-extension.md b/docs/Tasks/installing-an-extension.md
index 680b8ca80..81a687042 100644
--- a/docs/Tasks/installing-an-extension.md
+++ b/docs/Tasks/installing-an-extension.md
@@ -3,16 +3,13 @@
 In Operator Lifecycle Manager (OLM) 1.0, Kubernetes extensions are scoped to the cluster.
 After you add a catalog to your cluster, you can install an extension by creating a custom resource (CR) and applying it.
 
-!!! important
-
-    Currently, extensions that use webhooks or target a single or specified set of namespaces cannot be installed.
-    Extensions must not include webhooks and must use the `AllNamespaces` install mode.
-
-
 ## Prerequisites
 
-* The `jq` CLI tool is installed.
-* You have added a catalog to your cluster.
+* A deployed and unpacked catalog
+* The name, and optionally version, or channel, of the extension to be installed
+* The extension must be compatible with OLM 1.0 (see [current OLM v1 limitations](../drafts/refs/olmv1-limitations.md))
+* An existing namespace in which to install the extension
+* A suitable service account for installation (more information can be found [here](../drafts/Tasks/create-installer-service-account.md))
 
 ## Procedure
 
diff --git a/docs/Tasks/uninstall-an-extension.md b/docs/Tasks/uninstalling-an-extension.md
similarity index 86%
rename from docs/Tasks/uninstall-an-extension.md
rename to docs/Tasks/uninstalling-an-extension.md
index 06105b234..575a7602a 100644
--- a/docs/Tasks/uninstall-an-extension.md
+++ b/docs/Tasks/uninstalling-an-extension.md
@@ -32,3 +32,7 @@ You can uninstall a Kubernetes extension and its associated custom resource defi
     ``` text title="Example output"
     No resources found
     ```
+  
+### Cleanup
+
+* Remove the extension namespace, and installer service account cluster-scoped RBAC resources (if applicable).
diff --git a/docs/drafts/Tasks/create-installer-service-account.md b/docs/drafts/Tasks/create-installer-service-account.md
new file mode 100644
index 000000000..e66c06076
--- /dev/null
+++ b/docs/drafts/Tasks/create-installer-service-account.md
@@ -0,0 +1,3 @@
+# Create Installer Service Account
+
+Placeholder. We need to document this.
\ No newline at end of file
diff --git a/docs/drafts/Tasks/downgrading-an-extension.md b/docs/drafts/Tasks/downgrading-an-extension.md
new file mode 100644
index 000000000..58d9ec846
--- /dev/null
+++ b/docs/drafts/Tasks/downgrading-an-extension.md
@@ -0,0 +1,3 @@
+# Downgrade an Extension
+
+Placeholder. This topic is under development.
\ No newline at end of file
diff --git a/docs/drafts/Tasks/upgrading-an-extension.md b/docs/drafts/Tasks/upgrading-an-extension.md
new file mode 100644
index 000000000..648093e87
--- /dev/null
+++ b/docs/drafts/Tasks/upgrading-an-extension.md
@@ -0,0 +1,169 @@
+# Upgrading an Extension
+
+Existing extensions can be upgraded by updating the version field in the ClusterExtension resource.
+
+For information on downgrading an extension, see [Downgrade an Extension](downgrading-an-extension).
+
+## Prerequisites
+
+* You have an extension installed
+* The target version is compatible with OLM v1 (see [OLM v1 limitations](../refs/olmv1-limitations.md))
+* CRD compatibility between the versions being upgraded or downgraded (see [CRD upgrade safety](../../refs/crd-upgrade-safety.md))
+* The installer service account's RBAC permissions are adequate for the target version (see [Minimal RBAC for Installer Service Account](create-installer-service-account.md))
+
+For more detailed information see [Upgrade Support](../upgrade-support.md).
+
+## Procedure
+
+Suppose we have successfully created and installed v0.5.0 of the ArgoCD operator with the following `ClusterExtension`:
+
+``` yaml title="Example CR"
+apiVersion: olm.operatorframework.io/v1alpha1
+kind: ClusterExtension
+metadata:
+  name: argocd
+spec:
+  source:
+    sourceType: Catalog
+    catalog:
+      packageName: argocd-operator
+      version: 0.5.0
+  install:
+    namespace: argocd
+    serviceAccount:
+      name: argocd-installer
+```
+
+* Update the version field in the ClusterExtension resource:
+
+    ``` terminal
+      kubectl apply -f - <<EOF
+      apiVersion: olm.operatorframework.io/v1alpha1
+      kind: ClusterExtension
+        metadata:
+          name: argocd
+        spec:
+          source:
+            sourceType: Catalog
+            catalog:
+              packageName: argocd-operator
+              version: 0.6.0 # Update to version 0.6.0
+          install:
+            namespace: argocd
+            serviceAccount:
+              name: argocd-installer
+      EOF
+    ```
+
+    ??? success
+    ``` text title="Example output"
+    clusterextension.olm.operatorframework.io/argocd-operator configured
+    ```
+
+    Alternatively, you can use `kubectl patch` to update the version field:
+
+    ``` terminal
+    kubectl patch clusterextension <extension_name> --type='merge' -p '{"spec": {"source": {"catalog": {"version": "<target_version>"}}}}'
+    ```
+
+    `extension_name`
+    : Specifies the name defined in the `metadata.name` field of the extension's CR.
+    
+    `target_version`
+    : Specifies the version to upgrade or downgrade to.
+
+    ??? success
+      ``` text title="Example output"
+      clusterextension.olm.operatorframework.io/argocd-operator patched
+      ```
+
+### Verification
+
+* Verify that the Kubernetes extension is deleted:
+
+    ``` terminal
+    kubectl get clusterextension.olm.operatorframework.io/<extension_name>
+    ```
+
+    ??? success
+      ``` text title="Example output"
+      Name:         argocd
+      Namespace:    
+      Labels:       olm.operatorframework.io/owner-kind=ClusterExtension
+                    olm.operatorframework.io/owner-name=argocd
+      Annotations:  <none>
+      API Version:  olm.operatorframework.io/v1alpha1
+      Kind:         ClusterExtension
+      Metadata:
+        Creation Timestamp:  2024-09-06T13:38:38Z
+        Finalizers:
+          olm.operatorframework.io/cleanup-unpack-cache
+          olm.operatorframework.io/cleanup-contentmanager-cache
+        Generation:        5
+        Resource Version:  21167
+        UID:               5abdf57d-aedc-45d4-ba0d-a86e785fd34a
+      Spec:
+        Install:
+          Namespace:  argocd
+          Service Account:
+            Name:  argocd-installer
+        Source:
+          Catalog:
+            Package Name:  argocd-operator
+          Selector:
+          Upgrade Constraint Policy:  Enforce
+          Version:                    0.6.0
+        Source Type:                  Catalog
+      Status:
+        Conditions:
+          Last Transition Time:  2024-09-06T13:38:38Z
+          Message:               
+          Observed Generation:   5
+          Reason:                Deprecated
+          Status:                False
+          Type:                  Deprecated
+          Last Transition Time:  2024-09-06T13:38:38Z
+          Message:               
+          Observed Generation:   5
+          Reason:                Deprecated
+          Status:                False
+          Type:                  PackageDeprecated
+          Last Transition Time:  2024-09-06T13:38:38Z
+          Message:               
+          Observed Generation:   5
+          Reason:                Deprecated
+          Status:                False
+          Type:                  ChannelDeprecated
+          Last Transition Time:  2024-09-06T13:38:38Z
+          Message:               
+          Observed Generation:   5
+          Reason:                Deprecated
+          Status:                False
+          Type:                  BundleDeprecated
+          Last Transition Time:  2024-09-06T13:40:14Z
+          Message:               resolved to "quay.io/operatorhubio/argocd-operator@sha256:d538c45a813b38ef0e44f40d279dc2653f97ca901fb660da5d7fe499d51ad3b3"
+          Observed Generation:   5
+          Reason:                Success
+          Status:                True
+          Type:                  Resolved
+          Last Transition Time:  2024-09-06T13:38:38Z
+          Message:               unpack successful:
+          Observed Generation:   5
+          Reason:                UnpackSuccess
+          Status:                True
+          Type:                  Unpacked
+          Last Transition Time:  2024-09-06T13:40:31Z
+          Message:               Installed bundle quay.io/operatorhubio/argocd-operator@sha256:d538c45a813b38ef0e44f40d279dc2653f97ca901fb660da5d7fe499d51ad3b3 successfully
+          Observed Generation:   5
+          Reason:                Success
+          Status:                True
+          Type:                  Installed
+      Install:
+        Bundle:
+          Name:     argocd-operator.v0.6.0
+          Version:  0.6.0
+      Resolution:
+        Bundle:
+          Name:     argocd-operator.v0.6.0
+          Version:  0.6.0
+      ```
diff --git a/docs/drafts/refs/olmv1-limitations.md b/docs/drafts/refs/olmv1-limitations.md
new file mode 100644
index 000000000..1c351f9e9
--- /dev/null
+++ b/docs/drafts/refs/olmv1-limitations.md
@@ -0,0 +1,3 @@
+# Current OLM v1 Limitations
+
+Placeholder. We need to document this.
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 4ac56f7f1..2c71be2a6 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -13,9 +13,9 @@ nav:
   - Components: 'components.md'
   - Tasks:
     - Adding a catalog of extensions: 'Tasks/adding-a-catalog.md'
-    - Finding extensions to install: 'Tasks/explore-available-packages.md'
+    - Finding extensions to install: 'Tasks/exploring-available-packages.md'
     - Installing an extension: 'Tasks/installing-an-extension.md'
-    - Deleting an extension: 'Tasks/uninstall-an-extension.md'
+    - Deleting an extension: 'Tasks/uninstalling-an-extension.md'
   - References:
     - Catalog queries: 'refs/catalog-queries.md'
     - CRD Upgrade Safety: 'refs/crd-upgrade-safety.md'