-
Notifications
You must be signed in to change notification settings - Fork 53
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
📖 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
- Loading branch information
1 parent
eefa546
commit 9f6e7df
Showing
3 changed files
with
141 additions
and
77 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters