📖 Update docs for Installing and deleting extensions (#700)

* [Docs] Update "Installing an extension" * Update "Deleting an extension" * Apply review feedback * Fix stray `\` from asciidoctor conversion * Apply review feedback round 2
operator-framework · Mar 19, 2024 · 9f6e7df · 9f6e7df
1 parent eefa546
commit 9f6e7df
Show file tree

Hide file tree

Showing 3 changed files with 141 additions and 77 deletions.
diff --git a/docs/Tasks/installing-an-extension.md b/docs/Tasks/installing-an-extension.md
@@ -1,62 +1,106 @@
-Creating a ClusterExtension CR installs the extension on cluster:  
-
-```bash
-$ kubectl get packages | grep argocd 
-operatorhubio-argocd-operator                            5m19s
-operatorhubio-argocd-operator-helm                       5m19s
-
-$ kubectl apply -f - <<EOF
-apiVersion: olm.operatorframework.io/v1alpha1
-kind: ClusterExtension
-metadata:
-  name: argocd-operator
-spec:
-  packageName: operatorhubio-argocd-operator
-EOF
-
-$ kubectl get clusterextensions
-NAME                          AGE
-operatorhubio-argocd-operator   53s
-
-$  kubectl get clusterextension argocd-operator -o yaml 
-apiVersion: olm.operatorframework.io/v1alpha1
-kind: ClusterExtension
-metadata:
-  annotations:
-    kubectl.kubernetes.io/last-applied-configuration: |
-      {"apiVersion":"olm.operatorframework.io/v1alpha1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"argocd-operator"},"spec":{"packageName":"argocd-operator"}}
-  creationTimestamp: "2023-06-21T14:57:50Z"
-  generation: 1
-  name: argocd-operator
-  resourceVersion: "10690"
-  uid: 6e0c67a5-eb9c-41c6-a455-140b28714d34
-spec:
-  packageName: operatorhubio-argocd-operator
-status:
-  conditions:
-  - lastTransitionTime: "2023-06-21T14:57:51Z"
-    message: resolved to "quay.io/operatorhubio/argocd-operator@sha256:1a9b3c8072f2d7f4d6528fa32905634d97b7b4c239ef9887e3fb821ff033fef6"
-    observedGeneration: 1
-    reason: Success
-    status: "True"
-    type: Resolved
-  - lastTransitionTime: "2023-06-21T14:57:57Z"
-    message: installed from "quay.io/operatorhubio/argocd-operator@sha256:1a9b3c8072f2d7f4d6528fa32905634d97b7b4c239ef9887e3fb821ff033fef6"
-    observedGeneration: 1
-    reason: Success
-    status: "True"
-    type: Installed
-  installedBundleResource: quay.io/operatorhubio/argocd-operator@sha256:1a9b3c8072f2d7f4d6528fa32905634d97b7b4c239ef9887e3fb821ff033fef6
-  resolvedBundleResource: quay.io/operatorhubio/argocd-operator@sha256:1a9b3c8072f2d7f4d6528fa32905634d97b7b4c239ef9887e3fb821ff033fef6
-```
-
-The status condition type `Installed`:`true` indicates that the extension was installed successfully. We can confirm this by looking at the workloads that were created as a result of this extension installation: 
-
-```bash 
-$ kubectl get namespaces | grep argocd 
-argocd-operator-system       Active   4m17s
-
-$ kubectl get pods -n argocd-operator-system 
-NAME                                                 READY   STATUS    RESTARTS   AGE
-argocd-operator-controller-manager-bb496c545-ljbbr   2/2     Running   0          4m32s
-```
+# Installing an extension from a catalog
+
+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.
+
+## Procedure
+
+1. Create a CR for the Kubernetes extension you want to install:
+
+    ``` yaml title="Example CR"
+    apiVersion: olm.operatorframework.io/v1alpha1
+    kind: ClusterExtension
+    metadata:
+      name: <extension_name>
+    spec:
+      packageName: <package_name>
+      channel: <channel>
+      version: "<version>"
+    ```
+
+     `extension_name`
+     : Specifies a custom name for the Kubernetes extension you want to install, such as `my-camel-k`.
+
+     `package_name`
+     : Specifies the name of the package you want to install, such as `camel-k`.
+
+     `channel`
+     : Optional: Specifies the extension's channel, such as `stable` or `candidate`.
+
+     `version`
+     : Optional: Specifies the version or version range you want installed, such as `1.3.1` or `"<2"`.
+     If you use a comparison string to define a version range, the string must be surrounded by double quotes (`"`).
+
+    !!! warning
+        Currently, the following limitations affect the installation of extensions:
+
+        * If mulitple catalogs are added to a cluster, you cannot specify a catalog when you install an extension.
+        * OLM 1.0 requires that all of the extensions have unique bundle and package names for dependency resolution.
+
+        As a result, if two catalogs have an extension with the same name, the installation might fail or lead to an unintended outcome.
+        For example, the first extension that matches might install successfully and finish without searching for a match in the second catalog.
+
+2. Apply the CR to the cluster:
+
+    ``` terminal
+    $ kubectl apply -f <cr_name>.yaml
+    ```
+
+    ??? success
+        ``` text title="Example output"
+        clusterextension.olm.operatorframework.io/camel-k created
+        ```
+
+### Verification
+
+* Describe the installed extension:
+
+    ``` terminal
+    $ kubectl describe clusterextensions
+    ```
+
+    ??? success
+        ``` text title="Example output"
+        Name:         my-camel-k
+        Namespace:
+        Labels:       <none>
+        Annotations:  <none>
+        API Version:  olm.operatorframework.io/v1alpha1
+        Kind:         ClusterExtension
+        Metadata:
+          Creation Timestamp:  2024-03-15T15:03:47Z
+          Generation:          1
+          Resource Version:    7691
+          UID:                 d756879f-217d-4ebe-85b1-8427bbb2f1df
+        Spec:
+          Package Name:               camel-k
+          Upgrade Constraint Policy:  Enforce
+        Status:
+          Conditions:
+            Last Transition Time:     2024-03-15T15:03:50Z
+            Message:                  resolved to "quay.io/operatorhubio/camel-k@sha256:d2b74c43ec8f9294450c9dcf2057be328d0998bb924ad036db489af79d1b39c3"
+            Observed Generation:      1
+            Reason:                   Success
+            Status:                   True
+            Type:                     Resolved
+            Last Transition Time:     2024-03-15T15:04:13Z
+            Message:                  installed from "quay.io/operatorhubio/camel-k@sha256:d2b74c43ec8f9294450c9dcf2057be328d0998bb924ad036db489af79d1b39c3"
+            Observed Generation:      1
+            Reason:                   Success
+            Status:                   True
+            Type:                     Installed
+          Installed Bundle Resource:  quay.io/operatorhubio/camel-k@sha256:d2b74c43ec8f9294450c9dcf2057be328d0998bb924ad036db489af79d1b39c3
+          Resolved Bundle Resource:   quay.io/operatorhubio/camel-k@sha256:d2b74c43ec8f9294450c9dcf2057be328d0998bb924ad036db489af79d1b39c3
+        Events:                       <none>
+        ```
diff --git a/docs/Tasks/uninstall-an-extension.md b/docs/Tasks/uninstall-an-extension.md
@@ -1,14 +1,34 @@
-Uninstalling an extension is as simple as deleting an existing ClusterExtension CR: 
-
-```bash
-$ kubectl get clusterextensions
-NAME                          AGE
-operatorhubio-argocd-operator   53s
-
-$ kubectl delete clusterextension argocd-operator 
-clusterextension.olm.operatorframework.io "argocd-operator" deleted
-$ kubectl get namespaces | grep argocd
-$
-$ kubectl get crds | grep argocd-operator 
-$
-```
+# Deleting an extension
+
+You can uninstall a Kubernetes extension and its associated custom resource definitions (CRD) by deleting the extension's custom resource (CR).
+
+## Prerequisites
+
+* You have an extension installed.
+
+## Procedure
+
+* Delete the extension's CR:
+
+    ``` terminal
+    $ kubectl delete clusterextensions <extension_name>
+    ```
+
+    `extension_name`
+    : Specifies the name defined in the `metadata.name` field of the extension's CR.
+
+    ``` text title="Example output"
+    clusterextension.olm.operatorframework.io "argocd-operator" deleted
+    ```
+
+### Verification
+
+* Verify that the Kubernetes extension is deleted:
+
+    ``` terminal
+    $ kubectl get clusterextension.olm.operatorframework.io
+    ```
+
+    ``` text title="Example output"
+    No resources found
+    ```
diff --git a/docs/refs/catalog-queries.md b/docs/refs/catalog-queries.md
@@ -24,7 +24,7 @@ Catalog blobs in a package
 ## Channel queries
 
 Channels in a package
-: `jq -s '.[] | select( .schema == "olm.channel" ) | select( .package == "<package_name>") \| .name'`
+: `jq -s '.[] | select( .schema == "olm.channel" ) | select( .package == "<package_name>") | .name'`
 
 Versions in a channel
 : `jq -s '.[] | select( .package == "<package_name>" ) | select( .schema == "olm.channel" ) | select( .name == "<channel_name>" ) | .entries | .[] | .name'`