Skip to content
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.

Sign up for GitHub

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

Jump to bottom

📖 Update docs for Installing and deleting extensions #700

Merged
merged 5 commits into from
Mar 19, 2024
Merged

📖 Update docs for Installing and deleting extensions #700

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3903574
[Docs] Update "Installing an extension"
michaelryanpeter Mar 14, 2024
39994fe
Update "Deleting an extension"
michaelryanpeter Mar 14, 2024
2fce1d8
Apply review feedback
michaelryanpeter Mar 15, 2024
92e68aa
Fix stray `\` from asciidoctor conversion
michaelryanpeter Mar 15, 2024
1feb79a
Apply review feedback round 2
michaelryanpeter Mar 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 116 additions & 62 deletions docs/Tasks/installing-an-extension.md
View file
Open in desktop
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.

Copy link
Contributor

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

Copy link
Contributor Author

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.

2. Apply the CR the cluster:

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be Apply the CR to the cluster?

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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"
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is there ??? ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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
```
58 changes: 44 additions & 14 deletions docs/Tasks/uninstall-an-extension.md
View file
Open in desktop
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
```
Loading