create a proposal for addon dependency management by elgnay · Pull Request #157 · open-cluster-management-io/enhancements

elgnay · 2025-10-22T04:28:09Z

Related issue: #156

openshift-ci · 2025-10-22T04:28:13Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: elgnay
Once this PR has been reviewed and has the lgtm label, please assign qiujian16 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

qiujian16 · 2025-10-22T07:31:37Z

+    // The default is false (soft dependency).
+    // +optional
+    // +kubebuilder:default=false
+    Required bool `json:"required,omitempty"`


boolean needs to be avoided.

Replaced Required with Type, using explicit values "Optional" and "Required".

qiujian16 · 2025-10-22T07:33:13Z

+
+- **Soft dependencies (default, required=false)**: The addon can still function with reduced functionality when the dependency is missing. When a soft dependency is not satisfied, the addon-manager will set `Degraded=True` with reason `DependencyNotSatisfied`, but the klusterlet-agent will not modify the `Available` condition, allowing the addon to remain available if its health checks pass.
+
+- **Hard dependencies (required=true)**: The addon cannot function at all without the dependency. When a hard dependency is not satisfied, the addon-manager will set `Degraded=True` with reason `RequiredDependencyNotSatisfied`, and the klusterlet-agent will detect this specific reason and set `Available=False`.


I think the addon will not be deployed under this case, like we should have a status that condition are or met, then addon-framework will deploy the resource.

I think the addon will not be deployed under this case

Should this work on a fresh install only, or rollout as well?

If the addon is already installed and its dependent addon becomes unavailable, should the addon be uninstalled in that case?

I do not think so, but we should have a degrade condition with the message that some dependencies are missing. With the second thought, maybe we do not need to disable installation, a degraded status condition will be good.

zhujian7 · 2025-10-27T01:28:26Z

+    // An empty list means the add-on has no dependencies.
+    // The default is an empty list.
+    // +optional
+    Dependencies []AddonDependency `json:"dependencies,omitempty"`


I'm not sure if there is a case: for one addon, it has different dependencies on different type of managed clusters, for instance, on the OCP clusters it depends on the managed-serviceaccount addon, but on the eks clusters, it does not or even depends on other addons. I am asking because we have a similar case for the addon health checking recently.

At present, we don’t have such a requirement, and we aim to keep the initial design as simple as possible. The case you mentioned is very interesting. In the future, the current API could be extended by adding a new field in AddonDependency — for example, when — that allows specifying a CEL expression to determine whether an addon actually depends on another.

qiujian16 · 2025-11-05T08:46:55Z

/assign @jnpacker

jnpacker · 2025-11-05T21:10:21Z

+
+There are two types of dependencies:
+
+- **Optional dependencies (default, type=Optional)**: The addon can still function with reduced functionality when the dependency is missing. When an optional dependency is not satisfied, the addon-manager will set `Degraded=True` with reason `DependencyNotSatisfied`, but the klusterlet-agent will not modify the `Available` condition, allowing the addon to remain available if its health checks pass.


Do we have any examples of this?
Will you publish some type of warning message in this case?

Do we have any examples of this?

The work-manager is one of the MultiCluster Engine add-ons. Its pod log viewing feature depends on the managed-serviceaccount add-on. If that add-on is missing, other features—such as cluster view and cluster action—will still work.

Will you publish some type of warning message in this case?

Added an optional field, message, to capture this type of warning or informational message.

jnpacker · 2025-11-05T21:12:08Z

+    description: "An addon that optionally uses ManagedServiceAccount API"
+  dependencies:
+  - name: managed-serviceaccount
+    # type: Optional is the default, can be omitted


I was going to say that optional is default, but without any other type of cue, I would have expected it to be optional: false from just reading the keys. you have.

That makes sense. Changed the default from Optional to Required.

jnpacker · 2025-11-05T21:14:16Z

+    //   condition should be set to False when the dependency is not satisfied.
+    // +optional
+    // +kubebuilder:validation:Enum=Optional;Required
+    // +kubebuilder:default=Optional


I'm not sure I would have assumed it was optional by default.

Also do we need or want to consider any versioning semantics?

I'm not sure I would have assumed it was optional by default.

Changed the default from Optional to Required.

Also do we need or want to consider any versioning semantics?

Since the ClusterManagementAddOn itself does not include any add-on version information, it’s not possible to define dependencies based on specific versions.

Signed-off-by: Yang Le <yangle@redhat.com>

jnpacker · 2026-02-05T20:00:26Z

+    //   condition should be set to False when the dependency is not satisfied.
+    // - "Optional": The addon can work with reduced functionality without this dependency.
+    //   The Degraded condition will be set with reason DependencyNotSatisfied when the dependency is not satisfied,
+    //   but the Available condition may remain True if the addon is otherwise functional.


I think this use case has poor UX and that you should consider saying it is False Available, with DependencyNotSatisfied = Degraded... Just a thought. having available true, make it less likely that a problem is correctly identified.

jnpacker · 2026-02-05T20:03:28Z

+
+- **Required dependencies (default, type=Required)**: The addon cannot function at all without the dependency. When a required dependency is not satisfied, the addon-manager will set `Degraded=True` with reason `RequiredDependencyNotSatisfied`, and the klusterlet-agent will detect this specific reason and set `Available=False`.
+
+- **Optional dependencies (type=Optional)**: The addon can still function with reduced functionality when the dependency is missing. When an optional dependency is not satisfied, the addon-manager will set `Degraded=True` with reason `DependencyNotSatisfied`, but the klusterlet-agent will not modify the `Available` condition, allowing the addon to remain available if its health checks pass.


If something is truly optional, then the addon my NOT be degraded, it might just have been a nice to have.

jnpacker · 2026-02-05T20:05:49Z

+
+2. **Check each dependency**: For each dependency in the list:
+   - Check if a `ManagedClusterAddOn` with the same name exists in the same namespace (managed cluster namespace)
+   - Check if the dependent addon's `Available` condition is `True`


Does this imply that I can have a dependent addon (child) and it has some optional dependents that are missing and so the Dependent is Available=True, but it's actually degraded?

jnpacker · 2026-02-05T20:06:49Z

+
+3. **Set Degraded condition based on dependency type**:
+   - **If all dependencies are satisfied**:
+     - Ensure the `Degraded` condition is not set with reason `DependencyNotSatisfied` or `RequiredDependencyNotSatisfied`


I see here is the Dependency Degraded check... So the Available check above is technically separate.

jnpacker · 2026-02-05T20:07:33Z

+   - **If any optional dependency is not satisfied** (type=Optional):
+     - Set the `Degraded` condition to `True` with:
+       - Reason: `DependencyNotSatisfied`
+       - Message: Clear description of which dependencies are missing, including the custom message if provided (e.g., "Optional addon 'managed-serviceaccount' is not installed or not available. Token-based access to managed clusters is unavailable.")


Not just missing but degraded as well.

jnpacker · 2026-02-05T20:11:57Z

+- Test complete workflow:
+  1. Install addon A with dependency on addon B (B not installed) - verify Degraded condition
+  2. Install addon B - verify addon A becomes Available
+  3. Delete addon B - verify addon A becomes Degraded


Degraded works for Option, I'm not sure it makes sense for Required. At this point it is failed.

jnpacker

Looking to discuss or maybe a table with degrade, failed and Availability matrixed out based on the types of dependencies, and then I'm good.

openshift-ci Bot requested review from deads2k and qiujian16 October 22, 2025 04:28

qiujian16 reviewed Oct 22, 2025

View reviewed changes

elgnay force-pushed the addon-dependency branch from 03d652c to 8954e74 Compare October 22, 2025 08:34

zhujian7 reviewed Oct 27, 2025

View reviewed changes

openshift-ci Bot assigned jnpacker Nov 5, 2025

jnpacker reviewed Nov 5, 2025

View reviewed changes

Comment thread enhancements/sig-architecture/156-addon-dependency/README.md

jnpacker reviewed Nov 5, 2025

View reviewed changes

create a proposal for addon dependency management

4624636

Signed-off-by: Yang Le <yangle@redhat.com>

elgnay force-pushed the addon-dependency branch from 8954e74 to 4624636 Compare November 6, 2025 15:36

jnpacker reviewed Feb 5, 2026

View reviewed changes


		- Soft dependencies (default, required=false): The addon can still function with reduced functionality when the dependency is missing. When a soft dependency is not satisfied, the addon-manager will set `Degraded=True` with reason `DependencyNotSatisfied`, but the klusterlet-agent will not modify the `Available` condition, allowing the addon to remain available if its health checks pass.

		- Hard dependencies (required=true): The addon cannot function at all without the dependency. When a hard dependency is not satisfied, the addon-manager will set `Degraded=True` with reason `RequiredDependencyNotSatisfied`, and the klusterlet-agent will detect this specific reason and set `Available=False`.


		There are two types of dependencies:

		- Optional dependencies (default, type=Optional): The addon can still function with reduced functionality when the dependency is missing. When an optional dependency is not satisfied, the addon-manager will set `Degraded=True` with reason `DependencyNotSatisfied`, but the klusterlet-agent will not modify the `Available` condition, allowing the addon to remain available if its health checks pass.


		- Required dependencies (default, type=Required): The addon cannot function at all without the dependency. When a required dependency is not satisfied, the addon-manager will set `Degraded=True` with reason `RequiredDependencyNotSatisfied`, and the klusterlet-agent will detect this specific reason and set `Available=False`.

		- Optional dependencies (type=Optional): The addon can still function with reduced functionality when the dependency is missing. When an optional dependency is not satisfied, the addon-manager will set `Degraded=True` with reason `DependencyNotSatisfied`, but the klusterlet-agent will not modify the `Available` condition, allowing the addon to remain available if its health checks pass.

Uh oh!

Conversation

elgnay commented Oct 22, 2025

Uh oh!

openshift-ci Bot commented Oct 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qiujian16 Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qiujian16 commented Nov 5, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elgnay Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elgnay Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jnpacker left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

qiujian16 Oct 29, 2025 •

edited

Loading

elgnay Nov 6, 2025 •

edited

Loading

elgnay Nov 6, 2025 •

edited

Loading