From 39035741877635144fb473acb631ad8c24719123 Mon Sep 17 00:00:00 2001 From: Michael Ryan Peter Date: Thu, 14 Mar 2024 16:54:17 -0400 Subject: [PATCH 1/5] [Docs] Update "Installing an extension" --- docs/Tasks/installing-an-extension.md | 185 +++++++++++++++++--------- 1 file changed, 123 insertions(+), 62 deletions(-) diff --git a/docs/Tasks/installing-an-extension.md b/docs/Tasks/installing-an-extension.md index 10202ad07..189bafbbb 100644 --- a/docs/Tasks/installing-an-extension.md +++ b/docs/Tasks/installing-an-extension.md @@ -1,62 +1,123 @@ -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 - < + spec: + packageName: + channel: + version: "" + ``` + + `extension_name` + : Specifies a custom name for the Kubernetes extension you want to install, such as `my-argocd`. + + `package_name` + : Specifies the name of the package you want to install, such as `argocd-operator`. + + `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. + +2. Apply the CR the cluster: + + ``` terminal + $ kubectl apply -f .yaml + ``` + + ??? success + ``` text title="Example output" + clusterextension.olm.operatorframework.io/argocd-operator created + ``` + +### Verification + +* Get information about your bundle deployment: + + ``` terminal + $ kubectl get bundledeployment + ``` + + ??? success + ``` text title="Example output" + NAME ACTIVE BUNDLE INSTALL STATE AGE + argocd-operator 111s + ``` + +* Describe the installed extension: + + ``` terminal + $ kubectl describe clusterextensions + ``` + + ??? success + ``` text title="Example output" + Name: argocd-operator + Namespace: + Labels: + Annotations: + API Version: olm.operatorframework.io/v1alpha1 + Kind: ClusterExtension + Metadata: + Creation Timestamp: 2024-03-14T19:42:43Z + Generation: 2 + Resource Version: 371915 + UID: 6f37c260-327f-4aa3-9ba1-fa1d9bc20621 + Spec: + Package Name: argocd-operator + Upgrade Constraint Policy: Enforce + Status: + Conditions: + Last Transition Time: 2024-03-14T19:42:47Z + Message: bundledeployment status is unknown + Observed Generation: 2 + Reason: InstallationStatusUnknown + Status: Unknown + Type: Installed + Last Transition Time: 2024-03-14T19:49:52Z + Message: resolved to "quay.io/operatorhubio/argocd-operator@sha256:046a9764dadcbef0b9ce67e367393fb1c8e3b1d24e361341f33ac5fb93cf32a1" + Observed Generation: 2 + Reason: Success + Status: True + Type: Resolved + Resolved Bundle Resource: quay.io/operatorhubio/argocd-operator@sha256:046a9764dadcbef0b9ce67e367393fb1c8e3b1d24e361341f33ac5fb93cf32a1 + Events: + ``` + +### Additional resources + +* References > Catalog queries +* Concepts > Version resolution +* Concepts > Version ranges +* References > Version comparison operators From 39994fec5488bbf220ba8cabacc24c689da97a29 Mon Sep 17 00:00:00 2001 From: Michael Ryan Peter Date: Thu, 14 Mar 2024 16:55:11 -0400 Subject: [PATCH 2/5] Update "Deleting an extension" --- docs/Tasks/installing-an-extension.md | 7 ---- docs/Tasks/uninstall-an-extension.md | 58 ++++++++++++++++++++------- 2 files changed, 44 insertions(+), 21 deletions(-) diff --git a/docs/Tasks/installing-an-extension.md b/docs/Tasks/installing-an-extension.md index 189bafbbb..f3a71f476 100644 --- a/docs/Tasks/installing-an-extension.md +++ b/docs/Tasks/installing-an-extension.md @@ -114,10 +114,3 @@ After you add a catalog to your cluster, you can install an extension by creatin Resolved Bundle Resource: quay.io/operatorhubio/argocd-operator@sha256:046a9764dadcbef0b9ce67e367393fb1c8e3b1d24e361341f33ac5fb93cf32a1 Events: ``` - -### Additional resources - -* References > Catalog queries -* Concepts > Version resolution -* Concepts > Version ranges -* References > Version comparison operators diff --git a/docs/Tasks/uninstall-an-extension.md b/docs/Tasks/uninstall-an-extension.md index 4ebd24a37..9611b05f7 100644 --- a/docs/Tasks/uninstall-an-extension.md +++ b/docs/Tasks/uninstall-an-extension.md @@ -1,14 +1,44 @@ -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` + : 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 + +1. Verify that the Kubernetes extension is deleted: + + ``` terminal + $ kubectl get clusterextension.olm.operatorframework.io + ``` + + ``` text title="Example output" + No resources found + ``` + +2. Verify that the extension's system namespace is deleted: + + ``` terminal + $ kubectl get ns -system + ``` + + ``` text title="Example output" + Error from server (NotFound): namespaces "argo-operator-system" not found + ``` From 2fce1d859a7241f679c103b311324d2cc18c70cb Mon Sep 17 00:00:00 2001 From: Michael Ryan Peter Date: Fri, 15 Mar 2024 11:39:30 -0400 Subject: [PATCH 3/5] Apply review feedback --- docs/Tasks/installing-an-extension.md | 62 +++++++++++---------------- docs/Tasks/uninstall-an-extension.md | 12 +----- 2 files changed, 27 insertions(+), 47 deletions(-) diff --git a/docs/Tasks/installing-an-extension.md b/docs/Tasks/installing-an-extension.md index f3a71f476..18b08ed0f 100644 --- a/docs/Tasks/installing-an-extension.md +++ b/docs/Tasks/installing-an-extension.md @@ -19,7 +19,7 @@ After you add a catalog to your cluster, you can install an extension by creatin 1. Create a CR for the Kubernetes extension you want to install: ``` yaml title="Example CR" - apiVersion: clusterextension.operatorframework.io/v1alpha1 + apiVersion: olm.operatorframework.io/v1alpha1 kind: ClusterExtension metadata: name: @@ -30,10 +30,10 @@ After you add a catalog to your cluster, you can install an extension by creatin ``` `extension_name` - : Specifies a custom name for the Kubernetes extension you want to install, such as `my-argocd`. + : 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 `argocd-operator`. + : 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`. @@ -49,6 +49,7 @@ After you add a catalog to your cluster, you can install an extension by creatin * 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 the cluster: @@ -58,23 +59,11 @@ After you add a catalog to your cluster, you can install an extension by creatin ??? success ``` text title="Example output" - clusterextension.olm.operatorframework.io/argocd-operator created + clusterextension.olm.operatorframework.io/camel-k created ``` ### Verification -* Get information about your bundle deployment: - - ``` terminal - $ kubectl get bundledeployment - ``` - - ??? success - ``` text title="Example output" - NAME ACTIVE BUNDLE INSTALL STATE AGE - argocd-operator 111s - ``` - * Describe the installed extension: ``` terminal @@ -83,34 +72,35 @@ After you add a catalog to your cluster, you can install an extension by creatin ??? success ``` text title="Example output" - Name: argocd-operator + Name: my-camel-k Namespace: Labels: Annotations: API Version: olm.operatorframework.io/v1alpha1 Kind: ClusterExtension Metadata: - Creation Timestamp: 2024-03-14T19:42:43Z - Generation: 2 - Resource Version: 371915 - UID: 6f37c260-327f-4aa3-9ba1-fa1d9bc20621 + Creation Timestamp: 2024-03-15T15:03:47Z + Generation: 1 + Resource Version: 7691 + UID: d756879f-217d-4ebe-85b1-8427bbb2f1df Spec: - Package Name: argocd-operator + Package Name: camel-k Upgrade Constraint Policy: Enforce Status: Conditions: - Last Transition Time: 2024-03-14T19:42:47Z - Message: bundledeployment status is unknown - Observed Generation: 2 - Reason: InstallationStatusUnknown - Status: Unknown - Type: Installed - Last Transition Time: 2024-03-14T19:49:52Z - Message: resolved to "quay.io/operatorhubio/argocd-operator@sha256:046a9764dadcbef0b9ce67e367393fb1c8e3b1d24e361341f33ac5fb93cf32a1" - Observed Generation: 2 - Reason: Success - Status: True - Type: Resolved - Resolved Bundle Resource: quay.io/operatorhubio/argocd-operator@sha256:046a9764dadcbef0b9ce67e367393fb1c8e3b1d24e361341f33ac5fb93cf32a1 - Events: + 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: ``` diff --git a/docs/Tasks/uninstall-an-extension.md b/docs/Tasks/uninstall-an-extension.md index 9611b05f7..048a8cca5 100644 --- a/docs/Tasks/uninstall-an-extension.md +++ b/docs/Tasks/uninstall-an-extension.md @@ -23,7 +23,7 @@ You can uninstall a Kubernetes extension and its associated custom resource defi ### Verification -1. Verify that the Kubernetes extension is deleted: +* Verify that the Kubernetes extension is deleted: ``` terminal $ kubectl get clusterextension.olm.operatorframework.io @@ -32,13 +32,3 @@ You can uninstall a Kubernetes extension and its associated custom resource defi ``` text title="Example output" No resources found ``` - -2. Verify that the extension's system namespace is deleted: - - ``` terminal - $ kubectl get ns -system - ``` - - ``` text title="Example output" - Error from server (NotFound): namespaces "argo-operator-system" not found - ``` From 92e68aa3786006cac5234825810bf5d1f6a4bdb2 Mon Sep 17 00:00:00 2001 From: Michael Ryan Peter Date: Fri, 15 Mar 2024 11:39:51 -0400 Subject: [PATCH 4/5] Fix stray `\` from asciidoctor conversion --- docs/refs/catalog-queries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/refs/catalog-queries.md b/docs/refs/catalog-queries.md index 4acdc48b6..199a9fb86 100644 --- 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 == "") \| .name'` +: `jq -s '.[] | select( .schema == "olm.channel" ) | select( .package == "") | .name'` Versions in a channel : `jq -s '.[] | select( .package == "" ) | select( .schema == "olm.channel" ) | select( .name == "" ) | .entries | .[] | .name'` From 1feb79aab2eb00d08810ceba0430956899359c45 Mon Sep 17 00:00:00 2001 From: Michael Ryan Peter Date: Tue, 19 Mar 2024 11:23:08 -0400 Subject: [PATCH 5/5] Apply review feedback round 2 --- docs/Tasks/installing-an-extension.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Tasks/installing-an-extension.md b/docs/Tasks/installing-an-extension.md index 18b08ed0f..a82645aab 100644 --- a/docs/Tasks/installing-an-extension.md +++ b/docs/Tasks/installing-an-extension.md @@ -51,7 +51,7 @@ After you add a catalog to your cluster, you can install an extension by creatin 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 the cluster: +2. Apply the CR to the cluster: ``` terminal $ kubectl apply -f .yaml