docs: add bundle metadata details, improve tests

Signed-off-by: Chris Laprun <[email protected]>

Author: metacosm

annotations/src/main/java/io/quarkiverse/operatorsdk/annotations/CSVMetadata.java

@@ -5,12 +5,28 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Provides more information to generate more detailed OLM bundle manifests, in particular in the ClusterServiceVersion
+ * resource. This can be used to provide information that cannot be inferred automatically or override what is generated by
+ * default. Many of these fields map to CSV fields. See the OLM documentation on
+ * <a href="https://olm.operatorframework.io/docs/tasks/creating-operator-manifests/#basic-metadata-optional">operator
+ * manifests</a> for more details.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.TYPE })
 @SuppressWarnings("unused")
 public @interface CSVMetadata {
+    /**
+     * The name which should be used for the generated bundle. If not provided, the name is derived from the project's (maven or
+     * gradle) name. This name can be used to assign reconcilers to the same bundle by creating a {@link SharedCSVMetadata}
+     * implementation bearing a {@link CSVMetadata} annotation specifying the CSV metadata to be shared among reconcilers
+     * assigned to that named bundle.
+     */
     String name() default "";
 
+    /**
+     * Extra annotations that should be added to the CSV metadata.
+     */
     Annotations annotations() default @Annotations;
 
     String description() default "";

annotations/src/main/java/io/quarkiverse/operatorsdk/annotations/SharedCSVMetadata.java

@@ -1,4 +1,8 @@
 package io.quarkiverse.operatorsdk.annotations;
 
+/**
+ * A marker interface used to identify classes bearing {@link CSVMetadata} that needs to be shared across reconcilers using the
+ * same {@link CSVMetadata#name()} attribute. Note that sharing metadata without using {@link SharedCSVMetadata} is not allowed.
+ */
 public interface SharedCSVMetadata {
 }

bundle-generator/deployment/src/test/java/io/quarkiverse/operatorsdk/bundle/MultipleReconcilerWithSharedMetadataBundleTest.java

@@ -1,6 +1,8 @@
 package io.quarkiverse.operatorsdk.bundle;
 
 import static io.quarkiverse.operatorsdk.bundle.Utils.checkBundleFor;
+import static io.quarkiverse.operatorsdk.bundle.Utils.getCSVFor;
+import static org.junit.jupiter.api.Assertions.assertEquals;
 
 import java.io.IOException;
 
@@ -29,8 +31,11 @@ public class MultipleReconcilerWithSharedMetadataBundleTest {
     @Test
     public void shouldWriteBundleForTheOperators() throws IOException {
         final var bundle = prodModeTestResults.getBuildDir().resolve(Utils.BUNDLE);
-        checkBundleFor(bundle, "shared", null);
+        checkBundleFor(bundle, AReconciler.SHARED, null);
         // reconcilers with no csv metadata should use the application name
         checkBundleFor(bundle, APPLICATION_NAME, null);
+
+        final var csv = getCSVFor(bundle, AReconciler.SHARED);
+        assertEquals(AReconciler.SHARED_VERSION, csv.getSpec().getVersion());
     }
 }

bundle-generator/deployment/src/test/java/io/quarkiverse/operatorsdk/bundle/sources/AReconciler.java

@@ -7,12 +7,14 @@
 import io.quarkiverse.operatorsdk.annotations.CSVMetadata;
 import io.quarkiverse.operatorsdk.annotations.SharedCSVMetadata;
 
-@CSVMetadata(name = "shared", version = "0.0.1")
+@CSVMetadata(name = AReconciler.SHARED, version = AReconciler.SHARED_VERSION)
 public class AReconciler implements Reconciler<ConfigMap>, SharedCSVMetadata {
 
+    public static final String SHARED_VERSION = "0.0.1";
+    public static final String SHARED = "shared";
+
     @Override
-    public UpdateControl<ConfigMap> reconcile(ConfigMap configMap, Context<ConfigMap> context)
-            throws Exception {
+    public UpdateControl<ConfigMap> reconcile(ConfigMap configMap, Context<ConfigMap> context) {
         return null;
     }
 }

bundle-generator/deployment/src/test/java/io/quarkiverse/operatorsdk/bundle/sources/BReconciler.java

@@ -6,12 +6,11 @@
 import io.javaoperatorsdk.operator.api.reconciler.UpdateControl;
 import io.quarkiverse.operatorsdk.annotations.CSVMetadata;
 
-@CSVMetadata(name = "shared", version = "0.0.2")
+@CSVMetadata(name = AReconciler.SHARED, version = "0.0.2")
 public class BReconciler implements Reconciler<Service> {
 
     @Override
-    public UpdateControl<Service> reconcile(Service service, Context<Service> context)
-            throws Exception {
+    public UpdateControl<Service> reconcile(Service service, Context<Service> context) {
         return null;
     }
 }

docs/modules/ROOT/pages/deploy-with-olm.adoc

@@ -63,13 +63,23 @@ If, for some reason, you need that label to be added to the selectors, just set
 
 While the extension attempts to infer a lot of the required information from your project itself and it is possible to generate valid bundles without providing extra information, it might still be useful or needed to specify additional metadata to help the generation process or provide data that cannot be inferred.
 
-The way this is accomplished is using the `CSVMetadata` and its associated annotations.
+This is accomplished is using the `io.quarkiverse.operatorsdk.annotations.CSVMetadata` and its associated annotations from the `quarkus-operator-sdk-annotations` module. `CSVMetadata` is meant to annotate your reconciler instances.
 
------ TODO: add more details on CSVMetadata ------
+By default, manifests for all reconcilers in a given operator will be generated as part of the same bundle, using a name automatically inferred from the project's name.
+It is, however, possible to split the reconcilers among several bundles by assigning reconcilers to different bundle names.
+One bundle will be created per specified bundle name.
+To associate a reconciler with a bundle name, you need to put the shared metadata (in the form of `CSVMetadata` annotation) on a class implementing the `io.quarkiverse.operatorsdk.annotations.SharedCSVMetadata` marker interface, specifying the desired bundle name on the associated `CSVMetadata` annotation.
+All reconcilers annotated with `CSVMetadata` using the same name as one of the `SharedCSVMetadata` classes will be assigned to the same bundle and share the associated metadata. Any value specified on `CSVMetadata` annotations that designate a reconciler as sharing metadata coming from a `SharedCSVMetadata` source will be **ignored**.
+
+You can see this behavior in action in the tests of the `quarkus-operator-sdk-bundle-generator-deployment` module.
+
+Note:
+If you provide a `SharedCSVMetadata` implementation without specifying a bundle name, then the specified metadata will be shared among all reconcilers that don't specify an explicit bundle name.
 
 === Validating the generated bundle
 
-It is recommended that you validate your bundle before proceeding further. The recommended way to do so is to run the following command:
+It is recommended that you validate your bundle before proceeding further.
+The recommended way to do so is to run the following command:
 
 [source,shell script]
 ----

samples/exposedapp/src/main/java/io/halkyon/ExposedAppReconciler.java

@@ -20,8 +20,7 @@
         @Dependent(name = "service", type = ServiceDependent.class),
         @Dependent(type = IngressDependent.class, readyPostcondition = IngressDependent.class)
 })
-@CSVMetadata(displayName = "ExposedApp operator", description = "A sample operator that shows how to use JOSDK's main features with the Quarkus extension",
-        provider = @CSVMetadata.Provider(name = "Christophe Laprun", url = "https://github.com/metacosm"))
+@CSVMetadata(displayName = "ExposedApp operator", description = "A sample operator that shows how to use JOSDK's main features with the Quarkus extension", provider = @CSVMetadata.Provider(name = "Christophe Laprun", url = "https://github.com/metacosm"))
 public class ExposedAppReconciler implements Reconciler<ExposedApp>,
         ContextInitializer<ExposedApp> {