From 414107623e1f7667dbac0e9bba9479255254cf12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bernhard=20Str=C3=A4hle?= Date: Tue, 14 May 2024 14:43:02 +0200 Subject: [PATCH] Add README for crd-generator maven plugin --- crd-generator/maven-plugin/README.md | 180 +++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 crd-generator/maven-plugin/README.md diff --git a/crd-generator/maven-plugin/README.md b/crd-generator/maven-plugin/README.md new file mode 100644 index 00000000000..f5283b3d30a --- /dev/null +++ b/crd-generator/maven-plugin/README.md @@ -0,0 +1,180 @@ +# CRD-Generator - Maven Plugin + +Maven plugin for the CRD-Generator: Generate CRDs from Java model during Maven builds. + +## Usage + +### Scan project for Custom Resource classes + +By default, the `target/` directory will be scanned for Custom Resource classes and the resulting CRDs will be emitted +below `target/META-INF/fabric8/`: + +```xml + + + io.fabric8 + crd-generator-maven-plugin + + + + generate + + + + +``` + +### Explicit Custom Resource classes + +The involved Custom Resource classes can also be configured explicitly. In this case, scanning is skipped and only the +provided classes are used. + +```xml + + + io.fabric8 + crd-generator-maven-plugin + + + + generate + + + + io.fabric8.crd.maven.example.v1.MyCustomResource + io.fabric8.crd.maven.example.v2.MyCustomResource + + + + + +``` + +### Scan a dependency for Custom Resource classes + +If CRDs for a Java model of an external project or another module should be generated, the dependency to be scanned must +be specified and added to the classpath. + +```xml + + + + io.fabric8.crd-generator.maven.example + custom-resources + + + + + io.fabric8 + crd-generator-maven-plugin + + + + generate + + + + + io.fabric8.crd-generator.maven.example + custom-resources + + + + + + + +``` + +### Restricting the classpath + +By default, the plugin considers all classes of the current project and all runtime dependencies of +the project. This can be changed by setting `classpath` to one of the following values: + +- `PROJECT_ONLY`: Only classes of the project +- `WITH_COMPILE_DEPENDENCIES`: Classes from the project and any compile time dependencies. +- `WITH_RUNTIME_DEPENDENCIES`: Classes from the project and any runtime dependencies. (default) +- `WITH_ALL_DEPENDENCIES`: Classes from the project, compile time and runtime dependencies. +- `WITH_ALL_DEPENDENCIES_AND_TESTS:`: Classes from the project (including tests), compile time, runtime and test + dependencies. + +### Filtering + +The Custom Resource classes which should be used by the CRD Generator can be filtered package. +Either by including or excluding: + +```xml + + + + io.fabric8.crd-generator.maven.example + custom-resources + + + + + io.fabric8 + crd-generator-maven-plugin + + + + generate + + + + + io.fabric8.crd.maven.example.api.v1 + + + + + io.fabric8.crd-generator.maven.example + custom-resources + + + + + + + +``` + +### More Configuration Parameters + +| Parameter | Description | +|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| +| `outputDirectory` | The output directory where the CRDs are emitted.
Default: `${project.build.outputDirectory}/META-INF/fabric8/` | +| `forceIndex` | If `true`, a Jandex index will be created even if the directory or JAR file contains an existing index.
Default: `false` | +| `forceScan` | If `true`, directories and JAR files are scanned even if Custom Resource classes are given.
Default: `false` | +| `implicitPreserveUnknownFields` | If `true`, `x-kubernetes-preserve-unknown-fields: true` will be added to objects which contain an any-setter or any-getter.
Default: `false` | +| `parallel` | If `true`, the CRDs will be generated in parallel.
Default: `true` | +| `skip` | If `true`, execution will be skipped.
Default: `false` | + +## Jandex + +The CRD-Generator Maven plugin uses [jandex](https://github.com/smallrye/jandex) under the hood to +find Custom Resource classes. + +With jandex, metadata of compiled Java classes can be collected in an index and this index can be used to +search for classes which implement an interface and/or are annotated by annotations. + +The CRD-Generator Maven plugin creates the necessary index automatically and searches for +Custom Resource classes in this index by using the following criteria: + +- The class must implement the interface `HasMetadata` +- The class must be annotated by `@Group` and `@Version` + +> [!NOTE] +> The abstract class `CustomResource` implements `HasMetadata`. As such a class which implements `CustomResource` will be found, too. + +> [!IMPORTANT] +> If your Custom Resource classes extend an own abstract class or own interface, so that `HasMetadata` is only implemented +> indirect, then ensure that this intermediate class is included in the scan scope. + +### Reusing existing indices + +If the project or the dependency to scan already contains a serialized Jandex index, +this pre-existing index will be used instead of generating an own index and will result in a small performance gain. +This behaviour can be overridden by setting `forceIndex` to `true`. + +