diff --git a/content/en/docs/developer-guides/addon.md b/content/en/docs/developer-guides/addon.md index 685a7c31..908640c4 100644 --- a/content/en/docs/developer-guides/addon.md +++ b/content/en/docs/developer-guides/addon.md @@ -859,86 +859,9 @@ This architecture graph shows how the coordination between add-on manager and ad 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. +to the `ClusterManagementAddOn` and `ManagedClusterAddOn` APIs. -1. Install strategy - -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. - -```yaml -apiVersion: addon.open-cluster-management.io/v1alpha1 -kind: ClusterManagementAddOn -metadata: - name: helloworld - annotations: - addon.open-cluster-management.io/lifecycle: "addon-manager" -spec: - addOnMeta: - displayName: helloworld - installStrategy: - type: Placements - placements: - - name: placement-aws - namespace: default -``` - -```yaml -apiVersion: cluster.open-cluster-management.io/v1beta1 -kind: Placement -metadata: - name: placement-aws - namespace: default -spec: - predicates: - - requiredClusterSelector: - claimSelector: - matchExpressions: - - key: platform.open-cluster-management.io - operator: In - values: - - aws -``` - -2. Rollout strategy - -With the rollout strategy defined in the `ClusterManagementAddOn` API, users can -control the upgrade behavior of the add-on when there are changes in the [supported configurations](#add-your-add-on-agent-supported-configurations). - -For example, if the add-on user updates the "deploy-config" and wants to apply -the change to the add-ons to a "canary" [decision group](https://open-cluster-management.io/concepts/placement/#decision-strategy) first. -If all the add-on upgrade successfully, then upgrade the rest of clusters progressively per cluster -at a rate of 25%. The rollout strategy can be defined as follows: - -```yaml -apiVersion: addon.open-cluster-management.io/v1alpha1 -kind: ClusterManagementAddOn -metadata: - name: helloworld - annotations: - addon.open-cluster-management.io/lifecycle: "addon-manager" -spec: - addOnMeta: - displayName: helloworld - installStrategy: - type: Placements - placements: - - name: placement-aws - namespace: default - configs: - - group: addon.open-cluster-management.io - resource: addondeploymentconfigs - name: deploy-config - namespace: open-cluster-management - rolloutStrategy: - type: Progressive - progressive: - mandatoryDecisionGroups: - - groupName: "canary" - maxConcurrency: 25% -``` +More detailed usage of add-on install strategy and rollout strategy refer to the [Add-on lifecycle management](https://open-cluster-management.io/docs/getting-started/installation/addon-management/#add-on-lifecycle-management). Add-on developers can use addon-framework v0.9.3 and the above versions to support the scenarios mentioned above. @@ -1505,3 +1428,7 @@ namespace, and mount the configmap to the addon agent deployments and daemonsets `CA_BUNDLE_FILE_PATH` to the file path of the mounted ca bundle. If the addon needs to support the `caBundle` for the `proxyConfig`, the **addon developer should get the ca bundle from the environment variable** `CA_BUNDLE_FILE_PATH` to make the agent work with the proxy. + +### Add-on template configurations + +[Add-on configurations](https://open-cluster-management.io/docs/getting-started/installation/addon-management/#add-on-configurations) provides examples of how to configure add-on templates for different use cases. diff --git a/content/en/docs/getting-started/installation/addon-management.md b/content/en/docs/getting-started/installation/addon-management.md index 9bd37390..44f90f33 100644 --- a/content/en/docs/getting-started/installation/addon-management.md +++ b/content/en/docs/getting-started/installation/addon-management.md @@ -182,7 +182,7 @@ the default add-on configuration. In scenarios where all add-ons have the same configuration. Only one configuration of the same group and resource can be specified in the `defaultConfig`. -In the example below, add-ons on all the clusters will use "default-deploy-config" and "default-example-config". +In the example below, add-ons on all the clusters will use "default-deploy-config" and "default-addon-template". ```yaml apiVersion: addon.open-cluster-management.io/v1alpha1 @@ -201,10 +201,10 @@ spec: group: addon.open-cluster-management.io resource: addondeploymentconfigs - defaultConfig: - name: default-example-config + name: default-addon-template namespace: open-cluster-management - group: example.open-cluster-management.io - resource: exampleconfigs + group: addon.open-cluster-management.io + resource: addontemplates ``` ### Configurations per install strategy @@ -212,12 +212,12 @@ spec: In `ClusterManagementAddOn`, `spec.installStrategy.placements[].configs` lists the configuration of `ManagedClusterAddon` during installation for a group of clusters. For the need to use multiple configurations with the same group and resource can be defined -in this field since OCM v0.15.0. It will override the [Default configurations](#default-configurations) -on certain clusters by group and resource. +in this field since OCM v0.15.0. If [Default configurations](#default-configurations) is defined, +it will override the [Default configurations](#default-configurations) on certain clusters by group and resource. -In the example below, add-ons on clusters selected by `Placement` placement-aws will -use "deploy-config", "example-config-1" and "example-config-2", while all the other add-ons -will still use "default-deploy-config" and "default-example-config". +In the example below, add-ons on clusters selected by `Placement` will +use "override-deploy-config" and "override-addon-template", while all the other add-ons +will still use "default-deploy-config" and "default-addon-template". ```yaml apiVersion: addon.open-cluster-management.io/v1alpha1 @@ -235,26 +235,76 @@ spec: namespace: open-cluster-management group: addon.open-cluster-management.io resource: addondeploymentconfigs + - defaultConfig: + name: default-addon-template + namespace: open-cluster-management + group: addon.open-cluster-management.io + resource: addontemplates installStrategy: type: Placements placements: - - name: placement-aws - namespace: default + - name: + namespace: configs: - - group: addon.open-cluster-management.io - resource: addondeploymentconfigs - name: deploy-config - namespace: open-cluster-management - - group: example.open-cluster-management.io - resource: exampleconfigs - name: example-config-1 + - name: override-deploy-config namespace: open-cluster-management - - group: example.open-cluster-management.io - resource: exampleconfigs - name: example-config-2 + group: addon.open-cluster-management.io + resource: addondeploymentconfigs + - name: override-addon-template namespace: open-cluster-management + group: addon.open-cluster-management.io + resource: addontemplates +``` + +Below are some recommended `Placement` for the install strategy: + +- To apply the same configuration across all `ManagedCluster`, use [Default configurations](#default-configurations). + +- To apply the configuration to the hub cluster, it must have a specific identifying label or claim, such as local-cluster: "true", for example: + +```yaml +apiVersion: cluster.open-cluster-management.io/v1beta1 +kind: Placement +metadata: + name: + namespace: +spec: + predicates: + - requiredClusterSelector: + labelSelector: + matchLabels: + local-cluster: "true" +``` + +- To apply the configuration to the spoke clusters, use the following `Placement`: + +```yaml +apiVersion: cluster.open-cluster-management.io/v1beta1 +kind: Placement +metadata: + name: + namespace: +spec: + predicates: + - requiredClusterSelector: + labelSelector: + matchExpressions: + - key: local-cluster + operator: NotIn + values: + - "true" +# Uncomment the following to install even when clusters are unreachable or unavailable. +# tolerations: +# - key: cluster.open-cluster-management.io/unreachable +# operator: Equal +# - key: cluster.open-cluster-management.io/unavailable +# operator: Equal ``` +- To apply the configuration to a specific set of clusters, see [Placement](https://open-cluster-management.io/docs/concepts/content-placement/placement/) for more options. + +- To apply the configuration to a single specific cluster, see the next section [Configurations per cluster](#configurations-per-cluster). + ### Configurations per cluster In `ManagedClusterAddOn`, `spec.configs` is a list of add-on configurations. @@ -264,7 +314,7 @@ It will override the [Default configurations](#default-configurations) and [Configurations per install strategy](#configurations-per-install-strategy) defined in `ClusterManagementAddOn` by group and resource. -In the below example, add-on on cluster1 will use "cluster1-deploy-config" and "cluster1-example-config". +In the below example, add-on on cluster1 will use "cluster1-deploy-config" and "cluster1-addon-template". ```yaml apiVersion: addon.open-cluster-management.io/v1alpha1 @@ -274,14 +324,14 @@ metadata: namespace: cluster1 spec: configs: - - group: addon.open-cluster-management.io - resource: addondeploymentconfigs - name: cluster1-deploy-config + - name: cluster1-deploy-config namespace: open-cluster-management - - group: example.open-cluster-management.io - resource: exampleconfigs - name: cluster1-example-config + group: addon.open-cluster-management.io + resource: addondeploymentconfigs + - name: cluster1-addon-template namespace: open-cluster-management + group: addon.open-cluster-management.io + resource: addontemplates ``` ### Supported configurations @@ -302,8 +352,8 @@ status: supportedConfigs: - group: addon.open-cluster-management.io resource: addondeploymentconfigs - - group: example.open-cluster-management.io - resource: exampleconfigs + - group: addon.open-cluster-management.io + resource: addontemplates ``` ### Effective configurations @@ -329,15 +379,15 @@ status: ... configReferences: - desiredConfig: - name: cluster1-deploy-config + name: cluster1-addon-template namespace: open-cluster-management specHash: dcf88f5b11bd191ed2f886675f967684da8b5bcbe6902458f672277d469e2044 group: addon.open-cluster-management.io lastAppliedConfig: - name: cluster1-deploy-config + name: cluster1-addon-template namespace: open-cluster-management specHash: dcf88f5b11bd191ed2f886675f967684da8b5bcbe6902458f672277d469e2044 lastObservedGeneration: 1 - name: cluster1-deploy-config - resource: addondeploymentconfigs + name: cluster1-addon-template + resource: addontemplates ``` \ No newline at end of file