-
Notifications
You must be signed in to change notification settings - Fork 53
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
📖 Update docs for Installing and deleting extensions #700
Changes from all commits
3903574
39994fe
2fce1d8
92e68aa
1feb79a
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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" | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Why is there There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This adds a toggle to hide the output results once the MD is rendered. You can see it here in the rendered preview, step 2: https://deploy-preview-700--olmv1.netlify.app/tasks/installing-an-extension/ |
||
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> | ||
``` |
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 | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it's okay to leave this as is, but IIRC (please correct me if I'm wrong!) the first one found is the one used. It might be worth adding some text about that
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added a sentence but still kept it sort of hand wavy.