📖[Docs] Update quickstart documentation (#1225)

Signed-off-by: Per Goncalves da Silva <[email protected]>
Co-authored-by: Per Goncalves da Silva <[email protected]>

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

docs/Tasks/explore-available-packages.md → 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.
 

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
 

docs/Tasks/uninstall-an-extension.md → 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).

docs/drafts/Tasks/create-installer-service-account.md

@@ -0,0 +1,3 @@
+# Create Installer Service Account
+
+Placeholder. We need to document this.

docs/drafts/Tasks/downgrading-an-extension.md

@@ -0,0 +1,3 @@
+# Downgrade an Extension
+
+Placeholder. This topic is under development.