diff --git a/docs/getting-started/olmv1_getting_started.md b/docs/getting-started/olmv1_getting_started.md index fc8e2c544..de6f35f14 100644 --- a/docs/getting-started/olmv1_getting_started.md +++ b/docs/getting-started/olmv1_getting_started.md @@ -73,8 +73,7 @@ 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 diff --git a/docs/tutorials/upgrade-extension.md b/docs/tutorials/upgrade-extension.md index f9eb22355..b8b2aa5aa 100644 --- a/docs/tutorials/upgrade-extension.md +++ b/docs/tutorials/upgrade-extension.md @@ -11,36 +11,316 @@ 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`: - -``` yaml title="Example CR" -apiVersion: olm.operatorframework.io/v1 -kind: ClusterExtension -metadata: - name: argocd -spec: - namespace: argocd - serviceAccount: - name: argocd-installer - source: - sourceType: Catalog - catalog: - packageName: argocd-operator - version: 0.5.0 +For this example, we will be using v0.2.0 of the ArgoCD operator. If you would like to follow along +with this tutorial, you can apply the following manifest to your cluster by, for example, +saving it to a local file and then running `kubectl apply -f FILENAME`: + +??? info "ArgoCD v0.2.0 manifests" + ```yaml + --- + apiVersion: v1 + kind: Namespace + metadata: + name: argocd + --- + apiVersion: v1 + kind: ServiceAccount + metadata: + name: argocd-installer + namespace: argocd + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRoleBinding + metadata: + name: argocd-installer-binding + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: argocd-installer-clusterrole + subjects: + - kind: ServiceAccount + name: argocd-installer + namespace: argocd + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: argocd-installer-clusterrole + rules: + # Allow ClusterExtension to set blockOwnerDeletion ownerReferences + - apiGroups: [olm.operatorframework.io] + resources: [clusterextensions/finalizers] + verbs: [update] + resourceNames: [argocd] + # Manage ArgoCD CRDs + - apiGroups: [apiextensions.k8s.io] + resources: [customresourcedefinitions] + verbs: [create, list, watch] + - apiGroups: [apiextensions.k8s.io] + resources: [customresourcedefinitions] + verbs: [get, update, patch, delete] + resourceNames: + - appprojects.argoproj.io + - argocds.argoproj.io + - applications.argoproj.io + - argocdexports.argoproj.io + - applicationsets.argoproj.io + # Manage ArgoCD ClusterRoles and ClusterRoleBindings + - apiGroups: [rbac.authorization.k8s.io] + resources: [clusterroles] + verbs: [create, list, watch] + - apiGroups: [rbac.authorization.k8s.io] + resources: [clusterroles] + verbs: [get, update, patch, delete] + resourceNames: + - argocd-operator.v0-1dhiybrldl1gyksid1dk2dqjsc72psdybc7iyvse5gpx + - argocd-operator-metrics-reader + - argocd-operator.v0-22gmilmgp91wu25is5i2ec598hni8owq3l71bbkl7iz3 + - apiGroups: [rbac.authorization.k8s.io] + resources: [clusterrolebindings] + verbs: [create, list, watch] + - apiGroups: [rbac.authorization.k8s.io] + resources: [clusterrolebindings] + verbs: [get, update, patch, delete] + resourceNames: + - argocd-operator.v0-1dhiybrldl1gyksid1dk2dqjsc72psdybc7iyvse5gpx + - argocd-operator.v0-22gmilmgp91wu25is5i2ec598hni8owq3l71bbkl7iz3 + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRoleBinding + metadata: + name: argocd-installer-rbac-binding + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: argocd-installer-rbac-clusterrole + subjects: + - kind: ServiceAccount + name: argocd-installer + namespace: argocd + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: argocd-installer-rbac-clusterrole + rules: + - apiGroups: [""] + resources: [configmaps] + verbs: ['*'] + - apiGroups: [""] + resources: [endpoints] + verbs: ['*'] + - apiGroups: [""] + resources: [events] + verbs: ['*'] + - apiGroups: [""] + resources: [namespaces] + verbs: ['*'] + - apiGroups: [""] + resources: [persistentvolumeclaims] + verbs: ['*'] + - apiGroups: [""] + resources: [pods] + verbs: ['*', get] + - apiGroups: [""] + resources: [pods/log] + verbs: [get] + - apiGroups: [""] + resources: [secrets] + verbs: ['*'] + - apiGroups: [""] + resources: [serviceaccounts] + verbs: ['*'] + - apiGroups: [""] + resources: [services] + verbs: ['*'] + - apiGroups: [""] + resources: [services/finalizers] + verbs: ['*'] + - apiGroups: [apps] + resources: [daemonsets] + verbs: ['*'] + - apiGroups: [apps] + resources: [deployments] + verbs: ['*'] + - apiGroups: [apps] + resources: [deployments/finalizers] + resourceNames: [argocd-operator] + verbs: [update] + - apiGroups: [apps] + resources: [replicasets] + verbs: ['*'] + - apiGroups: [apps] + resources: [statefulsets] + verbs: ['*'] + - apiGroups: [apps.openshift.io] + resources: [deploymentconfigs] + verbs: ['*'] + - apiGroups: [argoproj.io] + resources: [applications] + verbs: ['*'] + - apiGroups: [argoproj.io] + resources: [appprojects] + verbs: ['*'] + - apiGroups: [argoproj.io] + resources: [argocdexports] + verbs: ['*'] + - apiGroups: [argoproj.io] + resources: [argocdexports/finalizers] + verbs: ['*'] + - apiGroups: [argoproj.io] + resources: [argocdexports/status] + verbs: ['*'] + - apiGroups: [argoproj.io] + resources: [argocds] + verbs: ['*'] + - apiGroups: [argoproj.io] + resources: [argocds/finalizers] + verbs: ['*'] + - apiGroups: [argoproj.io] + resources: [argocds/status] + verbs: ['*'] + - apiGroups: [authentication.k8s.io] + resources: [tokenreviews] + verbs: [create] + - apiGroups: [authorization.k8s.io] + resources: [subjectaccessreviews] + verbs: [create] + - apiGroups: [autoscaling] + resources: [horizontalpodautoscalers] + verbs: ['*'] + - apiGroups: [batch] + resources: [cronjobs] + verbs: ['*'] + - apiGroups: [batch] + resources: [jobs] + verbs: ['*'] + - apiGroups: [config.openshift.io] + resources: [clusterversions] + verbs: [get, list, watch] + - apiGroups: [monitoring.coreos.com] + resources: [prometheuses] + verbs: ['*'] + - apiGroups: [monitoring.coreos.com] + resources: [servicemonitors] + verbs: ['*'] + - apiGroups: [networking.k8s.io] + resources: [ingresses] + verbs: ['*'] + - apiGroups: [rbac.authorization.k8s.io] + resources: ['*'] + verbs: ['*'] + - apiGroups: [rbac.authorization.k8s.io] + resources: [clusterrolebindings] + verbs: ['*'] + - apiGroups: [rbac.authorization.k8s.io] + resources: [clusterroles] + verbs: ['*'] + - apiGroups: [route.openshift.io] + resources: [routes] + verbs: ['*'] + - apiGroups: [route.openshift.io] + resources: [routes/custom-host] + verbs: ['*'] + - apiGroups: ["coordination.k8s.io"] + resources: ["leases"] + verbs: ["get", "list", "watch", "create", "update", "patch", "delete"] + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: Role + metadata: + name: argocd-installer-role + namespace: argocd + rules: + - apiGroups: [""] + resources: [serviceaccounts] + verbs: [create, list, watch] + - apiGroups: [""] + resources: [serviceaccounts] + verbs: [get, update, patch, delete] + resourceNames: [argocd-operator-controller-manager] + - apiGroups: [""] + resources: [configmaps] + verbs: [create, list, watch] + - apiGroups: [""] + resources: [configmaps] + verbs: [get, update, patch, delete] + resourceNames: [argocd-operator-manager-config] + - apiGroups: [""] + resources: [services] + verbs: [create, list, watch] + - apiGroups: [""] + resources: [services] + verbs: [get, update, patch, delete] + resourceNames: [argocd-operator-controller-manager-metrics-service] + - apiGroups: [apps] + resources: [deployments] + verbs: [create, list, watch] + - apiGroups: [apps] + resources: [deployments] + verbs: [get, update, patch, delete] + resourceNames: [argocd-operator-controller-manager] + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: RoleBinding + metadata: + name: argocd-installer-binding + namespace: argocd + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: argocd-installer-role + subjects: + - kind: ServiceAccount + name: argocd-installer + namespace: argocd + --- + apiVersion: olm.operatorframework.io/v1 + kind: ClusterExtension + metadata: + name: argocd + spec: + namespace: argocd + serviceAccount: + name: argocd-installer + source: + sourceType: Catalog + catalog: + packageName: argocd-operator + version: 0.2.0 + ``` + +If we view the current state of our ClusterExtension we should see that we have installed version 0.2.0: + +```terminal +kubectl get clusterextension argocd -o jsonpath-as-json="{.status.install}" ``` -* Update the version field in the ClusterExtension resource: +!!! success "Command output" + ``` json + [ + { + "bundle": { + "name": "argocd-operator.v0.2.0", + "version": "0.2.0" + } + } + ] + ``` + +* To initiate our upgrade, let's update the version field in the ClusterExtension resource: - ``` terminal + ``` terminal title="Method 1: apply a new ClusterExtension manifest" kubectl apply -f - < --type='merge' -p '{"spec": {"source": {"catalog": {"version": ""}}}}' + ``` terminal title="Method 2: run patch command" + kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.2.1"}}}}' ``` - `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"}}}}' - ``` - - !!! success - ``` text title="Example output" + !!! success "Method 2 output" + ``` text clusterextension.olm.operatorframework.io/argocd patched ``` -### Verification +* We can now verify that the ClusterExtension is updated to the new version: -* Verify that the Kubernetes extension is updated: - - ``` terminal - kubectl get clusterextension argocd -o yaml + ``` terminal title="Get the current ClusterExtension version" + kubectl get clusterextension argocd -o jsonpath-as-json="{.status.install}" ``` - ??? success - ``` text title="Example output" - apiVersion: olm.operatorframework.io/v1 - kind: ClusterExtension - 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" - 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 - spec: - namespace: argocd - serviceAccount: - name: argocd-installer - source: - catalog: - packageName: argocd-operator - upgradeConstraintPolicy: CatalogProvided - version: 0.6.0 - sourceType: Catalog - status: - conditions: - - lastTransitionTime: "2024-11-11T14:13:12Z" - message: "" - observedGeneration: 2 - reason: Deprecated - status: "False" - type: Deprecated - - lastTransitionTime: "2024-11-11T14:13:12Z" - message: "" - observedGeneration: 2 - reason: Deprecated - status: "False" - type: PackageDeprecated - - lastTransitionTime: "2024-11-11T14:13:12Z" - message: "" - observedGeneration: 2 - reason: Deprecated - status: "False" - type: ChannelDeprecated - - lastTransitionTime: "2024-11-11T14:13:12Z" - 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 - successfully - observedGeneration: 2 - reason: Succeeded - status: "True" - type: Installed - - lastTransitionTime: "2024-11-11T14:13:19Z" - message: desired state reached - observedGeneration: 2 - reason: Succeeded - status: "True" - type: Progressing - install: - bundle: - name: argocd-operator.v0.6.0 - version: 0.6.0 + !!! success "Updated ClusterExtension version" + ``` json + [ + { + "bundle": { + "name": "argocd-operator.v0.2.1", + "version": "0.2.1" + } + } + ] ``` + +!!! note "Note on the `kubectl.kubernetes.io/last-applied-configuration` annotation" + After your upgrade, the contents of the `kubectl.kubernetes.io/last-applied-configuration` annotation field will + differ depending on your method of upgrade. If you apply a new ClusterExtension manifest as in the first method shown, + the last applied configuration will show the new version since we replaced the existing manifest. If you use the patch + method or `kubectl edit clusterextension`, then the last applied configuration will show the old version. \ No newline at end of file