From 16e9339eee3cecc5201e7d491ca982fac7785871 Mon Sep 17 00:00:00 2001 From: Qing Hao Date: Thu, 28 Mar 2024 21:01:47 +0800 Subject: [PATCH] update addon develop guide (#410) * update addon develop guide Signed-off-by: haoqing0110 * focus on release versions Signed-off-by: haoqing0110 * Update content/en/developer-guides/addon.md Co-authored-by: Jian Qiu Signed-off-by: haoqing0110 --------- Signed-off-by: haoqing0110 Co-authored-by: Jian Qiu --- content/en/developer-guides/addon.md | 107 ++++++++++++--------------- content/zh/developer-guides/addon.md | 107 ++++++++++++--------------- 2 files changed, 92 insertions(+), 122 deletions(-) diff --git a/content/en/developer-guides/addon.md b/content/en/developer-guides/addon.md index 5f4b2a9f..1ed40322 100644 --- a/content/en/developer-guides/addon.md +++ b/content/en/developer-guides/addon.md @@ -11,6 +11,10 @@ This page is a developer guide about how to build an OCM add-on using addon-fram +## Supported version + +The OCM v0.13.0 supports addon-framework v0.8.0 and the above versions. We suggest using the latest release v0.9.0. + ## Overview Add-on is an extension which can work with multiple clusters based on the foundation components in open-cluster-management. @@ -361,7 +365,8 @@ We support 3 kinds of health prober types to monitor the healthiness of add-on a ### Automatic installation -NOTE: This is deprecated since v0.12.0. Please use the `InstallStrategy` in +NOTE: +- NOTE: This is deprecated since v0.12.0 and will be removed in the future. Please use the `InstallStrategy` in [Managing the add-on agent lifecycle by addon-manager](#managing-the-add-on-agent-lifecycle-by-addon-manager) section instead. @@ -394,6 +399,34 @@ agentAddon, err := addonfactory.NewAgentAddonFactory(addonName, FS, "manifests") BuildTemplateAgentAddon() ``` +Addtionally, if you are using addon-framework v0.8.1 or higher, need to grant a `patch` permission on `ClusterManagementAddon` to your addon manager. + +```yaml +kind: ClusterRole + apiVersion: rbac.authorization.k8s.io/v1 + metadata: + name: helloworld-addon + rules: +... + - apiGroups: ["addon.open-cluster-management.io"] + resources: ["clustermanagementaddons"] + verbs: ["get", "list", "watch", "patch"] +``` + +The below annotation will be added automatically to claim the `ManagedClusterAddon` lifecycle is managed by the addon itself. + +```yaml +apiVersion: addon.open-cluster-management.io/v1alpha1 +kind: ClusterManagementAddOn +metadata: + annotations: + addon.open-cluster-management.io/lifecycle: "self" + name: helloworld +spec: + installStrategy: + type: Manual +``` + ### Register your add-on In most cases, the add-ons have requirements to access the hub cluster or other central service endpoint with TLS authentication. @@ -814,7 +847,7 @@ This architecture graph shows how the coordination between add-on manager and ad ## Managing the add-on agent lifecycle by addon-manager -The add-on agent lifecycle can now be managed by a new component called +The add-on agent lifecycle can now be managed by the general `addon-manager` starting from OCM v0.11.0. This is achieved through enhancements to the `ClusterManagementAddOn` and `ManagedClusterAddOn` APIs. @@ -823,8 +856,7 @@ to the `ClusterManagementAddOn` and `ManagedClusterAddOn` APIs. With the install strategy defined in the `ClusterManagementAddOn` API, users can configure which clusters the related `ManagedClusterAddon` should be enabled by referencing the `Placement`. For example, enabling the `helloworld` add-on on -clusters labeled with aws. (Before OCM v0.11.0, the [automatic installation strategy](#automatic-installation) -is hardcoded in the code.) +clusters labeled with aws. ```yaml apiVersion: addon.open-cluster-management.io/v1alpha1 @@ -898,89 +930,42 @@ spec: maxConcurrency: 25% ``` -The latest addon-framework already implements the installStrategy and rolloutStrategy. -Add-on developers only need to upgrade to the latest addon-framework and API in -the `go.mod` file with a minor code change to support the scenarios mentioned above. +Add-on developers can use addon-framework v0.8.0 and the above versions +to support the scenarios mentioned above. 1. Modify the `go.mod` file to use the latest addon-framework and API versions. ``` -open-cluster-management.io/addon-framework v0.8.0 -open-cluster-management.io/api v0.12.0 +open-cluster-management.io/addon-framework v0.9.0 +open-cluster-management.io/api v0.13.0 ``` 2. Remove the `WithInstallStrategy()` function described in the [automatic installation](#automatic-installation) section since it conflicts with the install strategy defined in the `ClusterManagementAddOn` API level. -With the above changes, you can now enable the "AddonManagement" feature gates -in `ClusterManager` and let the new component `addon-manager` manage the add-ons. - -3. Enable the "AddonManagement" feature gates in `ClusterManager` as shown below. - -Skip this step for OCM v0.12.0 and later version. - -```yaml -apiVersion: operator.open-cluster-management.io/v1 -kind: ClusterManager -metadata: - name: cluster-manager -spec: -... - addOnManagerConfiguration: - featureGates: - - feature: AddonManagement - mode: Enable - addOnManagerImagePullSpec: quay.io/open-cluster-management/addon-manager:latest -``` - -Once enabled, a new deployment `cluster-manager-addon-manager-controller` will be running. - -```bash -# oc get deploy -n open-cluster-management-hub cluster-manager-addon-manager-controller -NAME READY UP-TO-DATE AVAILABLE AGE -cluster-manager-addon-manager-controller 1/1 1 1 19m -``` - -4. Claim that the addon is managed by `addon-manager` by adding the annotation +3. Claim that the addon is managed by the general `addon-manager` by adding the annotation `addon.open-cluster-management.io/lifecycle: "addon-manager"` explicitly in the - `ClusterManagementAddOn`. + `ClusterManagementAddOn`. -```yaml -apiVersion: addon.open-cluster-management.io/v1alpha1 -kind: ClusterManagementAddOn -metadata: - name: helloworld - annotations: - addon.open-cluster-management.io/lifecycle: "addon-manager" -... -``` - -5. Define the `installStrategy` and `rolloutStrategy` in the `ClusterManagementAddOn` +4. Define the `installStrategy` and `rolloutStrategy` in the `ClusterManagementAddOn` as shown in the example above. Note that the rollout strategy is triggered by changes in configurations, so if the addon does not have [supported cofingurations](#add-your-add-on-agent-supported-configurations), the rollout strategy will not take effect. -For addons that upgrade the addon-framework to the latest version but want to -keep the current installation and upgrade behavior, the installStrategy type -should be set to "Manual". Do not add the annotation -`addon.open-cluster-management.io/lifecycle` or set it to "self". +5. If you do not want the automatic addon installation, set the install strategy type to `Manual`. ```yaml apiVersion: addon.open-cluster-management.io/v1alpha1 kind: ClusterManagementAddOn metadata: annotations: - addon.open-cluster-management.io/lifecycle: "self" - name: managed-serviceaccount + addon.open-cluster-management.io/lifecycle: "addon-manager" + name: helloworld spec: installStrategy: type: Manual ``` -For addons using addon-framework version v0.6.1 and earlier, the addon will -maintain its current installation and upgrade behavior, and the new component -`addon-manager` will have no impact on it. - ## Build an addon with addon template Using the addon-framework to develop an addon requires developers to implement the interface defined in the diff --git a/content/zh/developer-guides/addon.md b/content/zh/developer-guides/addon.md index 5f4b2a9f..1ed40322 100644 --- a/content/zh/developer-guides/addon.md +++ b/content/zh/developer-guides/addon.md @@ -11,6 +11,10 @@ This page is a developer guide about how to build an OCM add-on using addon-fram +## Supported version + +The OCM v0.13.0 supports addon-framework v0.8.0 and the above versions. We suggest using the latest release v0.9.0. + ## Overview Add-on is an extension which can work with multiple clusters based on the foundation components in open-cluster-management. @@ -361,7 +365,8 @@ We support 3 kinds of health prober types to monitor the healthiness of add-on a ### Automatic installation -NOTE: This is deprecated since v0.12.0. Please use the `InstallStrategy` in +NOTE: +- NOTE: This is deprecated since v0.12.0 and will be removed in the future. Please use the `InstallStrategy` in [Managing the add-on agent lifecycle by addon-manager](#managing-the-add-on-agent-lifecycle-by-addon-manager) section instead. @@ -394,6 +399,34 @@ agentAddon, err := addonfactory.NewAgentAddonFactory(addonName, FS, "manifests") BuildTemplateAgentAddon() ``` +Addtionally, if you are using addon-framework v0.8.1 or higher, need to grant a `patch` permission on `ClusterManagementAddon` to your addon manager. + +```yaml +kind: ClusterRole + apiVersion: rbac.authorization.k8s.io/v1 + metadata: + name: helloworld-addon + rules: +... + - apiGroups: ["addon.open-cluster-management.io"] + resources: ["clustermanagementaddons"] + verbs: ["get", "list", "watch", "patch"] +``` + +The below annotation will be added automatically to claim the `ManagedClusterAddon` lifecycle is managed by the addon itself. + +```yaml +apiVersion: addon.open-cluster-management.io/v1alpha1 +kind: ClusterManagementAddOn +metadata: + annotations: + addon.open-cluster-management.io/lifecycle: "self" + name: helloworld +spec: + installStrategy: + type: Manual +``` + ### Register your add-on In most cases, the add-ons have requirements to access the hub cluster or other central service endpoint with TLS authentication. @@ -814,7 +847,7 @@ This architecture graph shows how the coordination between add-on manager and ad ## Managing the add-on agent lifecycle by addon-manager -The add-on agent lifecycle can now be managed by a new component called +The add-on agent lifecycle can now be managed by the general `addon-manager` starting from OCM v0.11.0. This is achieved through enhancements to the `ClusterManagementAddOn` and `ManagedClusterAddOn` APIs. @@ -823,8 +856,7 @@ to the `ClusterManagementAddOn` and `ManagedClusterAddOn` APIs. With the install strategy defined in the `ClusterManagementAddOn` API, users can configure which clusters the related `ManagedClusterAddon` should be enabled by referencing the `Placement`. For example, enabling the `helloworld` add-on on -clusters labeled with aws. (Before OCM v0.11.0, the [automatic installation strategy](#automatic-installation) -is hardcoded in the code.) +clusters labeled with aws. ```yaml apiVersion: addon.open-cluster-management.io/v1alpha1 @@ -898,89 +930,42 @@ spec: maxConcurrency: 25% ``` -The latest addon-framework already implements the installStrategy and rolloutStrategy. -Add-on developers only need to upgrade to the latest addon-framework and API in -the `go.mod` file with a minor code change to support the scenarios mentioned above. +Add-on developers can use addon-framework v0.8.0 and the above versions +to support the scenarios mentioned above. 1. Modify the `go.mod` file to use the latest addon-framework and API versions. ``` -open-cluster-management.io/addon-framework v0.8.0 -open-cluster-management.io/api v0.12.0 +open-cluster-management.io/addon-framework v0.9.0 +open-cluster-management.io/api v0.13.0 ``` 2. Remove the `WithInstallStrategy()` function described in the [automatic installation](#automatic-installation) section since it conflicts with the install strategy defined in the `ClusterManagementAddOn` API level. -With the above changes, you can now enable the "AddonManagement" feature gates -in `ClusterManager` and let the new component `addon-manager` manage the add-ons. - -3. Enable the "AddonManagement" feature gates in `ClusterManager` as shown below. - -Skip this step for OCM v0.12.0 and later version. - -```yaml -apiVersion: operator.open-cluster-management.io/v1 -kind: ClusterManager -metadata: - name: cluster-manager -spec: -... - addOnManagerConfiguration: - featureGates: - - feature: AddonManagement - mode: Enable - addOnManagerImagePullSpec: quay.io/open-cluster-management/addon-manager:latest -``` - -Once enabled, a new deployment `cluster-manager-addon-manager-controller` will be running. - -```bash -# oc get deploy -n open-cluster-management-hub cluster-manager-addon-manager-controller -NAME READY UP-TO-DATE AVAILABLE AGE -cluster-manager-addon-manager-controller 1/1 1 1 19m -``` - -4. Claim that the addon is managed by `addon-manager` by adding the annotation +3. Claim that the addon is managed by the general `addon-manager` by adding the annotation `addon.open-cluster-management.io/lifecycle: "addon-manager"` explicitly in the - `ClusterManagementAddOn`. + `ClusterManagementAddOn`. -```yaml -apiVersion: addon.open-cluster-management.io/v1alpha1 -kind: ClusterManagementAddOn -metadata: - name: helloworld - annotations: - addon.open-cluster-management.io/lifecycle: "addon-manager" -... -``` - -5. Define the `installStrategy` and `rolloutStrategy` in the `ClusterManagementAddOn` +4. Define the `installStrategy` and `rolloutStrategy` in the `ClusterManagementAddOn` as shown in the example above. Note that the rollout strategy is triggered by changes in configurations, so if the addon does not have [supported cofingurations](#add-your-add-on-agent-supported-configurations), the rollout strategy will not take effect. -For addons that upgrade the addon-framework to the latest version but want to -keep the current installation and upgrade behavior, the installStrategy type -should be set to "Manual". Do not add the annotation -`addon.open-cluster-management.io/lifecycle` or set it to "self". +5. If you do not want the automatic addon installation, set the install strategy type to `Manual`. ```yaml apiVersion: addon.open-cluster-management.io/v1alpha1 kind: ClusterManagementAddOn metadata: annotations: - addon.open-cluster-management.io/lifecycle: "self" - name: managed-serviceaccount + addon.open-cluster-management.io/lifecycle: "addon-manager" + name: helloworld spec: installStrategy: type: Manual ``` -For addons using addon-framework version v0.6.1 and earlier, the addon will -maintain its current installation and upgrade behavior, and the new component -`addon-manager` will have no impact on it. - ## Build an addon with addon template Using the addon-framework to develop an addon requires developers to implement the interface defined in the