Improve provisioning documentation with optional dependencies and capabilities by sergehuber · Pull Request #2135 · apache/karaf

sergehuber · 2025-10-27T15:21:10Z

This PR enhances the provisioning documentation with comprehensive coverage of:

Optional feature dependencies and how they work
Capabilities and requirements system
Conditional bundles and features
Detailed database service resolution example
Bundle refresh handling mechanisms
Fixed minor typo (Sometime → Sometimes)

These additions provide users with better understanding of advanced Karaf provisioning features.

…abilities - Added documentation for optional feature dependencies - Added capabilities and requirements explanation - Added conditional bundles and features section - Added comprehensive database service example - Added bundle refresh handling details - Fixed minor typo (Sometime → Sometimes)

rovarga · 2025-10-27T21:30:45Z

manual/src/main/asciidoc/user-guide/provisioning.adoc

+**How optional dependencies work:**
+
+* **Default behavior** (without `dependency="true"`): The feature dependency is always installed
+* **Optional behavior** (with `dependency="true"`): The feature dependency is only installed if the required capabilities are not already provided by the system


I think we want to provide examples of interoperability when version ranges are concerned.
Consider a feature with dependency=true and version=[1, 2) and another feature doing dependency=false version=1.0.1 .. and similar.

We really want to highlight how dependency=true makes interop with others easier.

I kind of agree, but I think the proposed change is good enough.

rovarga · 2025-10-27T21:31:53Z

manual/src/main/asciidoc/user-guide/provisioning.adoc

+* **Conflict avoidance**: Prevents multiple implementations of the same service from being installed simultaneously
+* **Flexible deployment**: Features can work with different providers without modification
+
+**Note**: While the `dependency="true"` attribute is supported for feature dependencies, the current Karaf standard features primarily use this pattern for bundle dependencies. Feature-level optional dependencies are more commonly used in custom feature definitions where alternative implementations need to be selected at deployment time.


hmm... I think it is also supported for <bundle>, right?

Correct, it also works for bundle.

It can be addressed in another PR though.

rovarga · 2025-10-27T21:33:21Z

manual/src/main/asciidoc/user-guide/provisioning.adoc

+</feature>
+----
+
+The requirement syntax can include OSGi filter expressions:


can we include a link to https://docs.osgi.org/specification/osgi.core/8.0.0/framework.module.html#framework.module.filtersyntax ?

rovarga · 2025-10-27T21:34:02Z

manual/src/main/asciidoc/user-guide/provisioning.adoc

+**How the resolver works:**
+
+1. When a feature with requirements is installed, the resolver checks if the required capabilities are already available
+2. If capabilities are missing, it looks for features that provide them


"any required capability is missing"

rovarga · 2025-10-27T21:34:52Z

manual/src/main/asciidoc/user-guide/provisioning.adoc

+
+1. When a feature with requirements is installed, the resolver checks if the required capabilities are already available
+2. If capabilities are missing, it looks for features that provide them
+3. If multiple features provide the same capability, it chooses one (typically the first available)


"typically"? @jbonofre can we make firm statement it is the first (in what sense)?

Yes, the resolver will take the first feature. I would be "clearer" here.

rovarga · 2025-10-27T21:39:20Z

manual/src/main/asciidoc/user-guide/provisioning.adoc

+
+**Requirement-based conditions**
+
+Install content only when specific OSGi requirements are satisfied:


related to above filter specification, we want to highlight this is a highly-dynamic mechanism, which can be dependent on runtime details, for example, when installing OS- or CPU-specific features as done in https://github.com/opendaylight/odlparent/blob/be317b379a316d5f298b2fb3e932247a2bc0de84/features/odl-netty-4/src/main/feature/template.xml#L15-L27

Yes, and it's very important. That's actually a concern from some users: the runtime can have different behaviors depending of what is installed, so it's basically not predictable.
That's one of the main reason of the "simple/flat resolver" that will be provided (optionally) in Karaf 4.5.0.

rovarga · 2025-10-27T21:42:56Z

manual/src/main/asciidoc/user-guide/provisioning.adoc

+
+During feature resolution and deployment, Karaf automatically detects bundles that need to be refreshed to ensure proper wiring and package resolution. This refresh mechanism is crucial for maintaining a consistent OSGi environment.
+
+**When bundles are refreshed:**


I very much like this section, but in my experience users are flabbergasted by the various causes.
Can we perhaps include example messages logged in karaf.log when these happen? Perhaps in a 'Diagnosing causes of bundle refresh' section?

jbonofre

If its' great improvements, I would do a couple of clarification.

@sergehuber do you mind to do the couple of changes for clarity ?

jbonofre · 2026-02-04T09:45:02Z

manual/src/main/asciidoc/user-guide/provisioning.adoc

+**How optional dependencies work:**
+
+* **Default behavior** (without `dependency="true"`): The feature dependency is always installed
+* **Optional behavior** (with `dependency="true"`): The feature dependency is only installed if the required capabilities are not already provided by the system


I kind of agree, but I think the proposed change is good enough.

jbonofre · 2026-02-04T09:45:19Z

manual/src/main/asciidoc/user-guide/provisioning.adoc

+* **Conflict avoidance**: Prevents multiple implementations of the same service from being installed simultaneously
+* **Flexible deployment**: Features can work with different providers without modification
+
+**Note**: While the `dependency="true"` attribute is supported for feature dependencies, the current Karaf standard features primarily use this pattern for bundle dependencies. Feature-level optional dependencies are more commonly used in custom feature definitions where alternative implementations need to be selected at deployment time.


Correct, it also works for bundle.

jbonofre · 2026-02-04T09:45:39Z

manual/src/main/asciidoc/user-guide/provisioning.adoc

+* **Conflict avoidance**: Prevents multiple implementations of the same service from being installed simultaneously
+* **Flexible deployment**: Features can work with different providers without modification
+
+**Note**: While the `dependency="true"` attribute is supported for feature dependencies, the current Karaf standard features primarily use this pattern for bundle dependencies. Feature-level optional dependencies are more commonly used in custom feature definitions where alternative implementations need to be selected at deployment time.


It can be addressed in another PR though.

jbonofre · 2026-02-04T09:46:40Z

manual/src/main/asciidoc/user-guide/provisioning.adoc

+
+1. When a feature with requirements is installed, the resolver checks if the required capabilities are already available
+2. If capabilities are missing, it looks for features that provide them
+3. If multiple features provide the same capability, it chooses one (typically the first available)


Yes, the resolver will take the first feature. I would be "clearer" here.

jbonofre · 2026-02-04T09:48:36Z

manual/src/main/asciidoc/user-guide/provisioning.adoc

+
+**Requirement-based conditions**
+
+Install content only when specific OSGi requirements are satisfied:


Yes, and it's very important. That's actually a concern from some users: the runtime can have different behaviors depending of what is installed, so it's basically not predictable.
That's one of the main reason of the "simple/flat resolver" that will be provided (optionally) in Karaf 4.5.0.

rovarga reviewed Oct 27, 2025

View reviewed changes

jbonofre requested changes Feb 4, 2026

View reviewed changes


		Requirement-based conditions

		Install content only when specific OSGi requirements are satisfied:


		During feature resolution and deployment, Karaf automatically detects bundles that need to be refreshed to ensure proper wiring and package resolution. This refresh mechanism is crucial for maintaining a consistent OSGi environment.

		When bundles are refreshed:

Conversation

sergehuber commented Oct 27, 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!

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!

rovarga Oct 27, 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!

jbonofre left a comment

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rovarga Oct 27, 2025 •

edited

Loading