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

📖 Update extension upgrade tutorial doc #1469

Merged
merged 2 commits into from
Nov 19, 2024
Merged

📖 Update extension upgrade tutorial doc #1469

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f70dafd
Update extension upgrade tutorial doc
trgeiger Nov 14, 2024
9e49f8a
Add example manifest for ArgoCD v0.2.0
trgeiger Nov 18, 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
5 changes: 2 additions & 3 deletions docs/getting-started/olmv1_getting_started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,12 +73,11 @@ kubectl apply -f https://raw.githubusercontent.com/operator-framework/operator-c
To upgrade the installed extension, update the version field in the ClusterExtension resource. Note that
there must be CRD compatibility between the versions being upgraded, and the target version must be
compatible with OLM v1. More information on CRD upgrade safety can be found [here](../concepts/crd-upgrade-safety.md),
compatible with OLM v1. More information on CRD upgrade safety can be found [here](../concepts/crd-upgrade-safety.md),
and on the extension upgrade process [here](../tutorials/upgrade-extension.md).
and more information on the extension upgrade process can be found [here](../tutorials/upgrade-extension.md).

```bash
# Update to v0.11.0
kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}'
kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.2.1"}}}}'
Copy link
Member

Choose a reason for hiding this comment

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

Will this work?

I believe https://raw.githubusercontent.com/operator-framework/operator-controller/main/config/samples/olm_v1_clusterextension.yaml is currently installing 0.6.0.

So if as a previous step we install 0.6.0 then here we effectively are trying to downgrade to 0.2.1.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yeah, that's why I have my comment/question above about if we should change the sample manifest. The existing example of using 0.11.0 doesn't work either because it's attempting to upgrade a minor version within a zero major version which we don't support.

This specific line in 'olmv1_getting_started.md' technically isn't part of any tutorial or anything, but rather a one-off example of what an upgrade command might look like. So I think we could get away with whatever we want here, although having it be functional and not show an example of non-functional minor version upgrade attempts would probably be best. I could rewrite it to not have any actual version in the command, maybe, but rather some placeholder?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@m1kola @everettraven so given we are adding a 0.2.0 manifest to the upgrade tutorial, should we just leave this line in olmv1_getting_started the same at 0.11.0 or maybe some other change?

Copy link
Member

Choose a reason for hiding this comment

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

I don't like that we have duplication of content. Maybe we should consolidate the tutorial and getting started somehow?

```

For information on the downgrade process, see [here](../tutorials/downgrade-extension.md).
Expand Down
56 changes: 22 additions & 34 deletions docs/tutorials/upgrade-extension.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,17 @@ For information on downgrading an extension, see [Downgrade an Extension](downgr

## Prerequisites

* You have an extension installed
* You have a ClusterExtension installed
* The target version is compatible with OLM v1 (see [OLM v1 limitations](../project/olmv1_limitations.md))
* CRD compatibility between the versions being upgraded or downgraded (see [CRD upgrade safety](../concepts/crd-upgrade-safety.md))
* The installer service account's RBAC permissions are adequate for the target version (see [Minimal RBAC for Installer Service Account](../howto/derive-service-account.md))
* Any changes to the CustomResourceDefinition in the new version meet compatibility requirements (see [CRD upgrade safety](../concepts/crd-upgrade-safety.md))
* The installer ServiceAccount's RBAC permissions are adequate for the target version (see [Minimal RBAC for Installer Service Account](../howto/derive-service-account.md))
* You are not attempting to upgrade between minor versions with a major version of zero (see [Upgrades within the major version zero](../concepts/upgrade-support.md#upgrades-within-the-major-version-zero))

For more detailed information see [Upgrade Support](../concepts/upgrade-support.md).

## Procedure

Suppose we have successfully created and installed v0.5.0 of the ArgoCD operator with the following `ClusterExtension`:
Suppose we have successfully created and installed v0.2.0 of the ArgoCD operator with the following `ClusterExtension`:

``` yaml title="Example CR"
apiVersion: olm.operatorframework.io/v1
Expand All @@ -35,7 +36,7 @@ spec:
sourceType: Catalog
catalog:
packageName: argocd-operator
version: 0.5.0
version: 0.2.0
```

* Update the version field in the ClusterExtension resource:
Expand All @@ -54,7 +55,7 @@ spec:
sourceType: Catalog
catalog:
packageName: argocd-operator
version: 0.6.0 # Update to version 0.6.0
version: 0.2.1 # Update to version 0.2.1
EOF
```

Expand All @@ -66,27 +67,14 @@ spec:
Alternatively, you can use `kubectl patch` to update the version field:

``` terminal
kubectl patch clusterextension <extension_name> --type='merge' -p '{"spec": {"source": {"catalog": {"version": "<target_version>"}}}}'
```

`extension_name`
: Specifies the name defined in the `metadata.name` field of the extension's CR.

`target_version`
: Specifies the version to upgrade or downgrade to.

For example:
``` terminal
kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.6.0"}}}}'
kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.2.1"}}}}'
```

!!! success
``` text title="Example output"
clusterextension.olm.operatorframework.io/argocd patched
```

### Verification

* Verify that the Kubernetes extension is updated:

``` terminal
Expand All @@ -100,15 +88,15 @@ spec:
metadata:
annotations:
kubectl.kubernetes.io/last-applied-configuration: |
{"apiVersion":"olm.operatorframework.io/v1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"argocd"},"spec":{"namespace":"argocd","serviceAccount":{"name":"argocd-installer"},"source":{"catalog":{"packageName":"argocd-operator","version":"0.5.0"},"sourceType":"Catalog"}}}
creationTimestamp: "2024-11-11T14:13:12Z"
{"apiVersion":"olm.operatorframework.io/v1","kind":"ClusterExtension","metadata":{"annotations":{},"name":"argocd"},"spec":{"namespace":"argocd","serviceAccount":{"name":"argocd-installer"},"source":{"catalog":{"packageName":"argocd-operator","version":"0.2.1"},"sourceType":"Catalog"}}}
m1kola marked this conversation as resolved.
Show resolved Hide resolved
creationTimestamp: "2024-11-15T19:29:34Z"
finalizers:
- olm.operatorframework.io/cleanup-unpack-cache
- olm.operatorframework.io/cleanup-contentmanager-cache
generation: 2
name: argocd
resourceVersion: "3289"
uid: 20f12bf4-76eb-457d-bbac-d28416c18a30
resourceVersion: "7274"
uid: 9af8e5f8-ae3d-4231-b15c-e63c62619db7
spec:
namespace: argocd
serviceAccount:
Expand All @@ -117,49 +105,49 @@ spec:
catalog:
packageName: argocd-operator
upgradeConstraintPolicy: CatalogProvided
version: 0.6.0
version: 0.2.1
sourceType: Catalog
status:
conditions:
- lastTransitionTime: "2024-11-11T14:13:12Z"
- lastTransitionTime: "2024-11-15T19:29:34Z"
message: ""
observedGeneration: 2
reason: Deprecated
status: "False"
type: Deprecated
- lastTransitionTime: "2024-11-11T14:13:12Z"
- lastTransitionTime: "2024-11-15T19:29:34Z"
message: ""
observedGeneration: 2
reason: Deprecated
status: "False"
type: PackageDeprecated
- lastTransitionTime: "2024-11-11T14:13:12Z"
- lastTransitionTime: "2024-11-15T19:29:34Z"
message: ""
observedGeneration: 2
reason: Deprecated
status: "False"
type: ChannelDeprecated
- lastTransitionTime: "2024-11-11T14:13:12Z"
- lastTransitionTime: "2024-11-15T19:29:34Z"
message: ""
observedGeneration: 2
reason: Deprecated
status: "False"
type: BundleDeprecated
- lastTransitionTime: "2024-11-11T14:13:18Z"
message: Installed bundle quay.io/operatorhubio/argocd-operator@sha256:d538c45a813b38ef0e44f40d279dc2653f97ca901fb660da5d7fe499d51ad3b3
- lastTransitionTime: "2024-11-15T19:29:37Z"
message: Installed bundle quay.io/operatorhubio/argocd-operator@sha256:e1cfacacf891fb243ded2bcd449a4f5c76f3230bf96a4de32734a87303e087c8
successfully
observedGeneration: 2
reason: Succeeded
status: "True"
type: Installed
- lastTransitionTime: "2024-11-11T14:13:19Z"
- lastTransitionTime: "2024-11-15T19:29:37Z"
message: desired state reached
observedGeneration: 2
reason: Succeeded
status: "True"
type: Progressing
install:
bundle:
name: argocd-operator.v0.6.0
version: 0.6.0
name: argocd-operator.v0.2.1
version: 0.2.1
```