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 addon develop guide #410

Merged
merged 3 commits into from
Mar 28, 2024
Merged

update addon develop guide #410

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c97b679
update addon develop guide
haoqing0110 Mar 26, 2024
580b422
focus on release versions
haoqing0110 Mar 28, 2024
eab12d7
Update content/en/developer-guides/addon.md
haoqing0110 Mar 28, 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
107 changes: 46 additions & 61 deletions content/en/developer-guides/addon.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ This page is a developer guide about how to build an OCM add-on using addon-fram

<!-- spellchecker-enable -->

## 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.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
107 changes: 46 additions & 61 deletions content/zh/developer-guides/addon.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ This page is a developer guide about how to build an OCM add-on using addon-fram

<!-- spellchecker-enable -->

## 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.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading