From d9a614dc67e6ac84f2bcef55d5ccf85dab64822b Mon Sep 17 00:00:00 2001 From: Mikalai Radchuk Date: Thu, 14 Nov 2024 17:55:42 +0100 Subject: [PATCH] Fix docs: "Conceptual Guides" section 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 --- .../concepts/controlling-catalog-selection.md | 118 +++++++++++------- docs/concepts/crd-upgrade-safety.md | 28 ++--- docs/concepts/upgrade-support.md | 28 +++-- docs/concepts/version-ranges.md | 2 +- 4 files changed, 104 insertions(+), 72 deletions(-) diff --git a/docs/concepts/controlling-catalog-selection.md b/docs/concepts/controlling-catalog-selection.md index dc2f90ab8..384b7faf3 100644 --- a/docs/concepts/controlling-catalog-selection.md +++ b/docs/concepts/controlling-catalog-selection.md @@ -21,16 +21,21 @@ To select a specific catalog by name, you can use the `matchLabels` field in you apiVersion: olm.operatorframework.io/v1 kind: ClusterExtension metadata: - name: my-extension + name: argocd spec: - packageName: my-package - catalog: - selector: - matchLabels: - olm.operatorframework.io/metadata.name: my-content-management + namespace: argocd + serviceAccount: + name: argocd-installer + source: + sourceType: Catalog + catalog: + packageName: argocd-operator + selector: + matchLabels: + olm.operatorframework.io/metadata.name: operatorhubio ``` -In this example, only the catalog named `my-catalog` will be considered when resolving `my-package`. +In this example, only the catalog named `operatorhubio` will be considered when resolving `argocd-operator`. ### Selecting Catalogs by Labels @@ -42,13 +47,18 @@ If you have catalogs labeled with specific metadata, you can select them using ` apiVersion: olm.operatorframework.io/v1 kind: ClusterExtension metadata: - name: my-extension + name: argocd spec: - packageName: my-package - catalog: - selector: - matchLabels: - example.com/support: "true" + namespace: argocd + serviceAccount: + name: argocd-installer + source: + sourceType: Catalog + catalog: + packageName: argocd-operator + selector: + matchLabels: + example.com/support: "true" ``` This selects catalogs labeled with `example.com/support: "true"`. @@ -59,17 +69,22 @@ This selects catalogs labeled with `example.com/support: "true"`. apiVersion: olm.operatorframework.io/v1 kind: ClusterExtension metadata: - name: my-extension + name: argocd spec: - packageName: my-package - catalog: - selector: - matchExpressions: - - key: example.com/support - operator: In - values: - - "gold" - - "platinum" + namespace: argocd + serviceAccount: + name: argocd-installer + source: + sourceType: Catalog + catalog: + packageName: argocd-operator + selector: + matchExpressions: + - key: example.com/support + operator: In + values: + - "gold" + - "platinum" ``` This selects catalogs where the label `example.com/support` has the value `gold` or `platinum`. @@ -84,16 +99,21 @@ You can exclude catalogs by using the `NotIn` or `DoesNotExist` operators in `ma apiVersion: olm.operatorframework.io/v1 kind: ClusterExtension metadata: - name: my-extension + name: argocd spec: - packageName: my-package - catalog: - selector: - matchExpressions: - - key: olm.operatorframework.io/metadata.name - operator: NotIn - values: - - unwanted-content-management + namespace: argocd + serviceAccount: + name: argocd-installer + source: + sourceType: Catalog + catalog: + packageName: argocd-operator + selector: + matchExpressions: + - key: olm.operatorframework.io/metadata.name + operator: NotIn + values: + - unwanted-catalog ``` This excludes the catalog named `unwanted-catalog` from consideration. @@ -104,14 +124,19 @@ This excludes the catalog named `unwanted-catalog` from consideration. apiVersion: olm.operatorframework.io/v1 kind: ClusterExtension metadata: - name: my-extension + name: argocd spec: - packageName: my-package - catalog: - selector: - matchExpressions: - - key: example.com/support - operator: DoesNotExist + namespace: argocd + serviceAccount: + name: argocd-installer + source: + sourceType: Catalog + catalog: + packageName: argocd-operator + selector: + matchExpressions: + - key: example.com/support + operator: DoesNotExist ``` This selects catalogs that do not have the `example.com/support` label. @@ -200,11 +225,16 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera metadata: name: install-my-operator spec: - packageName: my-operator - catalog: - selector: - matchLabels: - example.com/support: "true" + namespace: my-operator-ns + serviceAccount: + name: my-operator-installer + source: + sourceType: Catalog + catalog: + packageName: my-operator + selector: + matchLabels: + example.com/support: "true" ``` 3. **Apply the Resources** diff --git a/docs/concepts/crd-upgrade-safety.md b/docs/concepts/crd-upgrade-safety.md index 339315472..53aef8f69 100644 --- a/docs/concepts/crd-upgrade-safety.md +++ b/docs/concepts/crd-upgrade-safety.md @@ -53,26 +53,26 @@ not cause the CRD Upgrade Safety preflight check to halt the upgrade: ## Disabling CRD Upgrade Safety The CRD Upgrade Safety preflight check can be entirely disabled by adding the -`preflight.crdUpgradeSafety.disabled` field with a value of "true" to the ClusterExtension of the CRD. +`.spec.install.preflight.crdUpgradeSafety.enforcement` field with a value of `None` to the `ClusterExtension` of the CRD. ```yaml apiVersion: olm.operatorframework.io/v1 kind: ClusterExtension metadata: - name: clusterextension-sample + name: argocd spec: - source: - sourceType: Catalog - catalog: - packageName: argocd-operator - version: 0.6.0 - install: - namespace: default - serviceAccount: - name: argocd-installer - preflight: - crdUpgradeSafety: - disabled: true + namespace: argocd + serviceAccount: + name: argocd-installer + source: + sourceType: Catalog + catalog: + packageName: argocd-operator + version: 0.6.0 + install: + preflight: + crdUpgradeSafety: + 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/concepts/upgrade-support.md b/docs/concepts/upgrade-support.md index 8287ff2b3..8ad7d589a 100644 --- a/docs/concepts/upgrade-support.md +++ b/docs/concepts/upgrade-support.md @@ -15,7 +15,7 @@ It also introduces an API to enable independently verified upgrades and downgrad When determining upgrade edges, also known as upgrade paths or upgrade constraints, for an installed cluster extension, Operator Lifecycle Manager (OLM) v1 supports [legacy OLM semantics](https://olm.operatorframework.io/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/) by default. This support follows the behavior from legacy OLM, including `replaces`, `skips`, and `skipRange` directives, with a few noted differences. -By supporting legacy OLM semantics, OLM v1 now honors the upgrade graph from catalogs accurately. +By supporting legacy OLM semantics, OLM v1 honors the upgrade graph from catalogs accurately. If there are multiple possible successors, OLM v1 behavior differs in the following ways: @@ -29,7 +29,7 @@ Consider the following set of file-based catalog (FBC) channel entries: - name: example.v3.0.0 skips: ["example.v2.0.0"] - name: example.v2.0.0 - skipRange: >=1.0.0 <2.0.0 + skipRange: ">=1.0.0 <2.0.0" ``` If `1.0.0` is installed, OLM v1 behavior differs in the following ways: @@ -39,18 +39,21 @@ If `1.0.0` is installed, OLM v1 behavior differs in the following ways: You can change the default behavior of the upgrade constraints by setting the `upgradeConstraintPolicy` parameter in your cluster extension's custom resource (CR). -``` yaml hl_lines="10" +``` yaml hl_lines="14" apiVersion: olm.operatorframework.io/v1 kind: ClusterExtension metadata: name: spec: - installNamespace: - packageName: + namespace: serviceAccount: name: - upgradeConstraintPolicy: SelfCertified - version: "" + source: + sourceType: Catalog + catalog: + packageName: + version: "" + upgradeConstraintPolicy: SelfCertified ``` Setting the `upgradeConstraintPolicy` to: @@ -82,11 +85,11 @@ You must verify and perform upgrades manually in cases where automatic upgrades !!! warning If you want to force an upgrade manually, you must thoroughly verify the outcome before applying any changes to production workloads. Failure to test and verify the upgrade might lead to catastrophic consequences such as data loss. -As a package admin, if you must upgrade or downgrade to version that might be incompatible with the currently installed version, you can set the `.spec.upgradeConstraintPolicy` field to `SelfCertified` on the relevant `ClusterExtension` resource. +As a package admin, if you must upgrade or downgrade to version that might be incompatible with the currently installed version, you can set the `.spec.source.catalog.upgradeConstraintPolicy` field to `SelfCertified` on the relevant `ClusterExtension` resource. If you set the field to `SelfCertified`, no upgrade constraints are set on the package. As a result, you can change the version to any version available in the catalogs for a given package. -Example `ClusterExtension` with `.spec.upgradeConstraintPolicy` field set to `SelfCertified`: +Example `ClusterExtension` with `.spec.source.catalog.upgradeConstraintPolicy` field set to `SelfCertified`: ```yaml apiVersion: olm.operatorframework.io/v1 @@ -94,14 +97,13 @@ kind: ClusterExtension metadata: name: extension-sample spec: + namespace: argocd + serviceAccount: + name: argocd-installer source: sourceType: Catalog catalog: packageName: argocd-operator version: 0.6.0 upgradeConstraintPolicy: SelfCertified - install: - namespace: argocd - serviceAccout: - name: argocd-installer ``` diff --git a/docs/concepts/version-ranges.md b/docs/concepts/version-ranges.md index 457a3eb20..97412deb2 100644 --- a/docs/concepts/version-ranges.md +++ b/docs/concepts/version-ranges.md @@ -31,7 +31,7 @@ You define a version range by adding a comparison string to the `spec.version` f To specify a version range, use a range comparison similar to the following example: ```yaml -version: >=3.0, <3.6 +version: ">=3.0, <3.6" ``` #### Wildcards in comparisons