-
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 2 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,116 @@ | ||
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: clusterextension.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-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: | ||
|
||
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. Should be 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. Thank you! Fixed in 1feb79a |
||
``` 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/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: | ||
michaelryanpeter marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
``` terminal | ||
$ kubectl describe clusterextensions | ||
``` | ||
|
||
??? success | ||
``` text title="Example output" | ||
Name: argocd-operator | ||
Namespace: | ||
Labels: <none> | ||
Annotations: <none> | ||
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: <none> | ||
michaelryanpeter marked this conversation as resolved.
Show resolved
Hide resolved
|
||
``` |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> | ||
``` | ||
|
||
`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 <extension_name>-system | ||
``` | ||
|
||
``` text title="Example output" | ||
Error from server (NotFound): namespaces "argo-operator-system" not 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.