From e9a2bb65142d3aa75a403c21e11faf437ab2537e Mon Sep 17 00:00:00 2001 From: Mikalai Radchuk Date: Mon, 11 Nov 2024 15:01:45 +0100 Subject: [PATCH] Fix docs There were several intentional breaking changes in the API which are now included in v0.18.0 release. This commit mostly focuses on updating the documentation to reflect API changes. This includes making sure that snippets and example outputs match the current state of the project. Relevant PRs: * https://github.com/operator-framework/operator-controller/pull/1439 * https://github.com/operator-framework/operator-controller/pull/1434 Signed-off-by: Mikalai Radchuk --- docs/concepts/crd-upgrade-safety.md | 8 +- docs/getting-started/olmv1_getting_started.md | 8 +- docs/tutorials/add-catalog.md | 61 ++++--- docs/tutorials/downgrade-extension.md | 47 +++--- docs/tutorials/install-extension.md | 71 ++++---- docs/tutorials/uninstall-extension.md | 4 +- docs/tutorials/upgrade-extension.md | 152 +++++++++--------- 7 files changed, 174 insertions(+), 177 deletions(-) diff --git a/docs/concepts/crd-upgrade-safety.md b/docs/concepts/crd-upgrade-safety.md index 339315472..339082d7d 100644 --- a/docs/concepts/crd-upgrade-safety.md +++ b/docs/concepts/crd-upgrade-safety.md @@ -61,18 +61,18 @@ kind: ClusterExtension metadata: name: clusterextension-sample spec: + namespace: default + serviceAccount: + name: argocd-installer source: sourceType: Catalog catalog: packageName: argocd-operator version: 0.6.0 install: - namespace: default - serviceAccount: - name: argocd-installer preflight: crdUpgradeSafety: - disabled: true + enforcement: "None" ``` You cannot disable individual field validators. If you disable the CRD Upgrade Safety preflight check, all field validators are disabled. diff --git a/docs/getting-started/olmv1_getting_started.md b/docs/getting-started/olmv1_getting_started.md index 0763f9263..b86a8ff5b 100644 --- a/docs/getting-started/olmv1_getting_started.md +++ b/docs/getting-started/olmv1_getting_started.md @@ -44,7 +44,7 @@ spec: type: Image image: ref: quay.io/operatorhubio/catalog:latest - pollInterval: 10m + pollIntervalMinutes: 10 EOF ``` @@ -78,7 +78,7 @@ and on the extension upgrade process [here](../tutorials/upgrade-extension.md). ```bash # Update to v0.11.0 -kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"content-management": {"version": "0.11.0"}}}}' +kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}' ``` @@ -106,10 +106,10 @@ kubectl delete namespace argocd ```bash # Delete installer service account cluster roles -kubectl delete clusterrole argocd-installer-clusterrole && kubectl delete clusterrole argocd-rbac-clusterrole +kubectl delete clusterrole argocd-installer-clusterrole && kubectl delete clusterrole argocd-installer-rbac-clusterrole ``` ```bash # Delete installer service account cluster role bindings -kuebctl delete clusterrolebinding argocd-installer-binding && kubectl delete clusterrolebinding argocd-rbac-binding +kubectl delete clusterrolebinding argocd-installer-binding && kubectl delete clusterrolebinding argocd-installer-rbac-binding ``` diff --git a/docs/tutorials/add-catalog.md b/docs/tutorials/add-catalog.md index ff8ffa558..e1791d643 100644 --- a/docs/tutorials/add-catalog.md +++ b/docs/tutorials/add-catalog.md @@ -29,35 +29,33 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https:// apiVersion: olm.operatorframework.io/v1 kind: ClusterCatalog metadata: - name: operatorhubio + name: spec: source: type: Image image: ref: - pollInterval: + pollIntervalMinutes: ``` `catalog_name` : Specifies the image reference for the catalog you want to install, such as `quay.io/operatorhubio/catalog:latest`. `poll_interval_duration` - : Specifies the interval for polling the remote registry for newer image digests. - The default value is `24h`. - Valid units include seconds (`s`), minutes (`m`), and hours (`h`). - To disable polling, set a zero value, such as `0s`. + : Specifies the number of minutes for polling the remote registry for newer image digests. + This field is optional. To disable polling, unset the field. ``` yaml title="Example `operatorhubio.yaml` CR" apiVersion: olm.operatorframework.io/v1 kind: ClusterCatalog metadata: - name: operatorhub + name: operatorhubio spec: source: type: Image image: ref: quay.io/operatorhubio/catalog:latest - pollInterval: 10m + pollIntervalMinutes: 10 ``` 2. Apply the ClusterCatalog CR: @@ -81,8 +79,8 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https:// ``` ``` terminal title="Example output" - NAME LASTUNPACKED AGE - operatorhubio 9m31s 9m55s + NAME LASTUNPACKED SERVING AGE + operatorhubio 18s True 27s ``` * Check the status of your catalog: @@ -99,40 +97,41 @@ This catalog is distributed as an image [quay.io/operatorhubio/catalog](https:// API Version: olm.operatorframework.io/v1 Kind: ClusterCatalog Metadata: - Creation Timestamp: 2024-10-02T19:51:24Z - Finalizers: + Creation Timestamp: 2024-11-11T13:19:12Z + Finalizers: olm.operatorframework.io/delete-server-cache - Generation: 1 - Resource Version: 33321 - UID: 52894532-0646-41a5-8285-c7f48bba49e4 + Generation: 1 + Resource Version: 2143 + UID: 2cebaf11-7a5c-4813-bef3-58ac2e373057 Spec: - Priority: 0 + Availability Mode: Available + Priority: 0 Source: Image: - Poll Interval: 10m0s - Ref: quay.io/operatorhubio/catalog:latest - Type: Image + Poll Interval Minutes: 10 + Ref: quay.io/operatorhubio/catalog:latest + Type: Image Status: Conditions: - Last Transition Time: 2024-03-12T19:35:34Z + Last Transition Time: 2024-11-11T13:19:21Z Message: Successfully unpacked and stored content from resolved source - Observed Generation: 2 + Observed Generation: 1 Reason: Succeeded - Status: False + Status: True Type: Progressing - Last Transition Time: 2024-03-12T19:35:34Z + Last Transition Time: 2024-11-11T13:19:21Z Message: Serving desired content from resolved source - Observed Generation: 2 + Observed Generation: 1 Reason: Available Status: True Type: Serving - URLs: - Base: https://catalogd-server.olmv1-system.svc/catalogs/operatorhubio - Last Unpacked: 2024-03-12T19:35:34Z + Last Unpacked: 2024-11-11T13:19:21Z Resolved Source: Image: - Last Successful Poll Attempt: 2024-03-12T19:35:26Z - Ref: quay.io/operatorhubio/catalog@sha256:dee29aaed76fd1c72b654b9bc8bebc4b48b34fd8d41ece880524dc0c3c1c55ec - Type: Image - Events: + Ref: quay.io/operatorhubio/catalog@sha256:025cb23665449d8974102dda042c2e25bd3cb9138791971748f48d57c90a21d8 + Type: Image + Urls: + Base: https://catalogd-service.olmv1-system.svc/catalogs/operatorhubio + Events: + ``` diff --git a/docs/tutorials/downgrade-extension.md b/docs/tutorials/downgrade-extension.md index ee25a5136..57035f989 100644 --- a/docs/tutorials/downgrade-extension.md +++ b/docs/tutorials/downgrade-extension.md @@ -26,7 +26,7 @@ Custom Resource Definitions (CRDs) ensure that the resources used by the `Cluste **Disable CRD Safety Check Configuration:** -Add the `crdUpgradeSafety` field and set its `policy` to `Disabled` in the `ClusterExtension` resource under the `preflight` section. +Add the `crdUpgradeSafety` field and set its `enforcement` to `None` in the `ClusterExtension` resource. This configuration disables CRD safety checks during the downgrade process. **Example:** @@ -36,19 +36,18 @@ kind: ClusterExtension metadata: name: example-extension spec: + namespace: argocd + serviceAccount: + name: argocd-installer install: preflight: crdUpgradeSafety: - policy: Disabled - namespace: argocd - serviceAccount: - name: argocd-installer + enforcement: None source: sourceType: Catalog catalog: packageName: argocd-operator version: 0.6.0 - upgradeConstraintPolicy: SelfCertified ``` **Command Example:** @@ -56,9 +55,8 @@ spec: If you prefer using the command line, you can use `kubectl` to modify the upgrade CRD safety check configuration. ```bash -kubectl patch clusterextension --patch '{"spec":{"install":{"preflight":{"crdUpgradeSafety":{"policy":"Disabled"}}}}}' --type=merge +kubectl patch clusterextension example-extension --patch '{"spec":{"install":{"preflight":{"crdUpgradeSafety":{"enforcement":"None"}}}}}' --type=merge ``` -Kubernetes will apply the updated configuration, disabling CRD safety checks during the downgrade process. ### 2. Ignoring Catalog Provided Upgrade Constraints @@ -76,16 +74,19 @@ kind: ClusterExtension metadata: name: example-extension spec: + namespace: argocd + serviceAccount: + name: argocd-installer + install: + preflight: + crdUpgradeSafety: + enforcement: None source: sourceType: Catalog catalog: packageName: argocd-operator version: 0.6.0 upgradeConstraintPolicy: SelfCertified - install: - namespace: argocd - serviceAccount: - name: argocd-installer ``` **Command Example:** @@ -93,7 +94,7 @@ spec: If you prefer using the command line, you can use `kubectl` to modify the upgrade constraint policy. ```bash -kubectl patch clusterextension --patch '{"spec":{"upgradeConstraintPolicy":"SelfCertified"}}' --type=merge +kubectl patch clusterextension example-extension --patch '{"spec":{"source": {"catalog":{"upgradeConstraintPolicy":"SelfCertified"}}}}' --type=merge ``` ### 3. Executing the Downgrade @@ -105,7 +106,7 @@ Once the CRD safety checks are disabled and upgrade constraints are set, you can Modify the `ClusterExtension` custom resource to specify the target version and adjust the upgrade constraints. ```bash - kubectl edit clusterextension + kubectl edit clusterextension example-extension ``` 2. **Update the Version:** @@ -116,17 +117,21 @@ Once the CRD safety checks are disabled and upgrade constraints are set, you can apiVersion: olm.operatorframework.io/v1 kind: ClusterExtension metadata: - name: + name: example-extension spec: + namespace: argocd + serviceAccount: + name: argocd-installer + install: + preflight: + crdUpgradeSafety: + enforcement: None source: sourceType: Catalog catalog: - packageName: + packageName: argocd-operator version: - install: - namespace: - serviceAccount: - name: + upgradeConstraintPolicy: SelfCertified ``` `target_version` @@ -145,7 +150,7 @@ After completing the downgrade, verify that the `ClusterExtension` is functionin 1. **Check the Status of the ClusterExtension:** ```bash - kubectl get clusterextension -o yaml + kubectl get clusterextension example-extension -o yaml ``` Ensure that the `status` reflects the target version and that there are no error messages. diff --git a/docs/tutorials/install-extension.md b/docs/tutorials/install-extension.md index 92b7aadeb..ce2eb27ff 100644 --- a/docs/tutorials/install-extension.md +++ b/docs/tutorials/install-extension.md @@ -39,16 +39,15 @@ For information on determining the ServiceAccount's permission, please see [Deri metadata: name: spec: + namespace: + serviceAccount: + name: source: sourceType: Catalog catalog: packageName: channel: version: "" - install: - namespace: - serviceAccount: - name: ``` `extension_name` @@ -63,10 +62,10 @@ For information on determining the ServiceAccount's permission, please see [Deri `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 (`"`). - + `namespace_name` - : Specifies a name for the namespace in which the bundle of content for the package referenced - in the packageName field will be applied. + : Specifies a name for the namespace in which the bundle of content for the package referenced + in the packageName field will be applied. `serviceAccount_name` : serviceAccount name is a required reference to a ServiceAccount that exists @@ -110,66 +109,64 @@ For information on determining the ServiceAccount's permission, please see [Deri API Version: olm.operatorframework.io/v1 Kind: ClusterExtension Metadata: - Creation Timestamp: 2024-10-03T16:02:40Z - Finalizers: + Creation Timestamp: 2024-11-11T13:41:23Z + Finalizers: olm.operatorframework.io/cleanup-unpack-cache olm.operatorframework.io/cleanup-contentmanager-cache - Generation: 2 - Resource Version: 1174 - UID: 0fcaf3f5-d142-4c7e-8d88-c88a549f7764 + Generation: 1 + Resource Version: 5426 + UID: bde55f03-abe2-48af-8c09-28d32df878ad Spec: - Install: - Namespace: argocd - Service Account: + Namespace: argocd + Service Account: Name: argocd-installer - Source: + Source: Catalog: - Package Name: argocd-operator - Selector: - Upgrade Constraint Policy: CatalogProvided - Version: 0.6.0 + Package Name: argocd-operator + Upgrade Constraint Policy: CatalogProvided + Version: 0.6.0 Source Type: Catalog Status: - Conditions: - Last Transition Time: 2024-10-03T16:02:41Z + Conditions: + Last Transition Time: 2024-11-11T13:41:23Z Message: - Observed Generation: 2 + Observed Generation: 1 Reason: Deprecated Status: False Type: Deprecated - Last Transition Time: 2024-10-03T16:02:41Z + Last Transition Time: 2024-11-11T13:41:23Z Message: - Observed Generation: 2 + Observed Generation: 1 Reason: Deprecated Status: False Type: PackageDeprecated - Last Transition Time: 2024-10-03T16:02:41Z + Last Transition Time: 2024-11-11T13:41:23Z Message: - Observed Generation: 2 + Observed Generation: 1 Reason: Deprecated Status: False Type: ChannelDeprecated - Last Transition Time: 2024-10-03T16:02:41Z + Last Transition Time: 2024-11-11T13:41:23Z Message: - Observed Generation: 2 + Observed Generation: 1 Reason: Deprecated Status: False Type: BundleDeprecated - Last Transition Time: 2024-10-03T16:02:43Z + Last Transition Time: 2024-11-11T13:41:31Z Message: Installed bundle quay.io/operatorhubio/argocd-operator@sha256:d538c45a813b38ef0e44f40d279dc2653f97ca901fb660da5d7fe499d51ad3b3 successfully - Observed Generation: 2 + Observed Generation: 1 Reason: Succeeded Status: True Type: Installed - Last Transition Time: 2024-10-03T16:02:43Z + Last Transition Time: 2024-11-11T13:41:32Z Message: desired state reached - Observed Generation: 2 + Observed Generation: 1 Reason: Succeeded - Status: False + Status: True Type: Progressing - Install: + Install: Bundle: - Name: argocd-operator.v0.6.0 - Version: 0.6.0 + Name: argocd-operator.v0.6.0 + Version: 0.6.0 Events: ``` diff --git a/docs/tutorials/uninstall-extension.md b/docs/tutorials/uninstall-extension.md index 3d20442a8..2345e0ede 100644 --- a/docs/tutorials/uninstall-extension.md +++ b/docs/tutorials/uninstall-extension.md @@ -23,7 +23,7 @@ You can uninstall a Kubernetes extension and its associated custom resource defi : 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 + clusterextension.olm.operatorframework.io "argocd" deleted ``` ### Verification @@ -37,7 +37,7 @@ You can uninstall a Kubernetes extension and its associated custom resource defi ``` text title="Example output" No resources found ``` - + ### Cleanup * Remove the extension namespace, and installer service account cluster-scoped RBAC resources (if applicable). diff --git a/docs/tutorials/upgrade-extension.md b/docs/tutorials/upgrade-extension.md index 86ecaeb75..5fa877a2e 100644 --- a/docs/tutorials/upgrade-extension.md +++ b/docs/tutorials/upgrade-extension.md @@ -28,41 +28,39 @@ kind: ClusterExtension metadata: name: argocd spec: + namespace: argocd + serviceAccount: + name: argocd-installer source: sourceType: Catalog catalog: packageName: argocd-operator version: 0.5.0 - install: - namespace: argocd - serviceAccount: - name: argocd-installer ``` * Update the version field in the ClusterExtension resource: ``` terminal - kubectl apply -f - < + kubectl get clusterextension.olm.operatorframework.io/ -o yaml ``` ??? success ``` text title="Example output" - apiVersion: olm.operatorframework.io/v1 - kind: ClusterExtension - metadata: + 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":{"install":{"namespace":"argocd","serviceAccount":{"name":"argocd-installer"}},"source":{"catalog":{"packageName":"argocd-operator","version":"0.6.0"},"sourceType":"Catalog"}}} - creationTimestamp: "2024-10-03T16:02:40Z" + 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: "1174" - uid: 0fcaf3f5-d142-4c7e-8d88-c88a549f7764 - spec: - install: - namespace: argocd - serviceAccount: - name: argocd-installer + resourceVersion: "3289" + uid: 20f12bf4-76eb-457d-bbac-d28416c18a30 + spec: + namespace: argocd + serviceAccount: + name: argocd-installer source: - catalog: + catalog: packageName: argocd-operator - selector: {} upgradeConstraintPolicy: CatalogProvided version: 0.6.0 - sourceType: Catalog - status: + sourceType: Catalog + status: conditions: - - lastTransitionTime: "2024-10-03T16:02:41Z" - message: "" - observedGeneration: 2 - reason: Deprecated - status: "False" - type: Deprecated - - lastTransitionTime: "2024-10-03T16:02:41Z" - message: "" - observedGeneration: 2 - reason: Deprecated - status: "False" - type: PackageDeprecated - - lastTransitionTime: "2024-10-03T16:02:41Z" - message: "" - observedGeneration: 2 - reason: Deprecated - status: "False" - type: ChannelDeprecated - - lastTransitionTime: "2024-10-03T16:02:41Z" - message: "" - observedGeneration: 2 - reason: Deprecated - status: "False" - type: BundleDeprecated - - lastTransitionTime: "2024-10-03T16:02:43Z" - message: Installed bundle quay.io/operatorhubio/argocd-operator@sha256:d538c45a813b38ef0e44f40d279dc2653f97ca901fb660da5d7fe499d51ad3b3 + - 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-10-03T16:02:43Z" - message: desired state reached - observedGeneration: 2 - reason: Succeeded - status: "False" - type: Progressing + 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: + bundle: name: argocd-operator.v0.6.0 version: 0.6.0 ```