From d30a0e71fb5bb86642a9cb3fec54d928768a1046 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bernhard=20Str=C3=A4hle?= Date: Mon, 16 Dec 2024 11:17:44 +0100 Subject: [PATCH] doc(crd-generator): add usage description for Gradle users (6722) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Bernhard Strähle --- crd-generator/README.md | 39 +++++++++++++++++ crd-generator/gradle/README.md | 77 ++++++++++++++++++++++++++++++++++ doc/CRD-generator.md | 5 ++- 3 files changed, 119 insertions(+), 2 deletions(-) create mode 100644 crd-generator/README.md create mode 100644 crd-generator/gradle/README.md diff --git a/crd-generator/README.md b/crd-generator/README.md new file mode 100644 index 0000000000..01621e7022 --- /dev/null +++ b/crd-generator/README.md @@ -0,0 +1,39 @@ +# CRD Generator + +## Modules + +### CRD Generator v1 (deprecated since 7.0.0) + +- **CRD Generator API v1** - `io.fabric8:crd-generator-api` + _Core implementation of the old generator, based on [sundrio](https://github.com/sundrio/sundrio)._ +- **CRD Generator annotation processing tool (APT)** - `io.fabric8:crd-generator-apt` + _Annotation processor which hooks into the build process to generate CRDs._ + +### CRD Generator v2 +- **CRD Generator API v2** - `io.fabric8:crd-generator-api-v2` + _Core implementation of the new generator, based on [Jackson/jsonSchema](https://github.com/FasterXML/jackson-module-jsonSchema)._ +- **CRD Generator Collector** - `io.fabric8:crd-generator-collector` + _Shared component to find and load compiled Custom Resource classes in directories and Jar files._ +- **CRD Generator Maven Plugin** - `io.fabric8:crd-generator-maven-plugin` + _Maven plugin that generates CRDs during the build process._ +- **CRD Generator CLI** - `io.fabric8:crd-generator-cli` + _CLI tool that generates CRDs when executed._ + +### Utility Modules +_(not published)_ + +- **test-apt** - `io.fabric8:crd-generator-test-apt` + _Integration tests for CRD Generator API v1 and the annotation processor tool_ +- **test** - `io.fabric8:crd-generator-test` + _Approval tests for CRD Generator API v1 and v2_ + +## Usage + +- [Introduction and Annotation usage](../doc/CRD-generator.md) +- [CRD Generator Maven Plugin](maven-plugin/README.md) +- [CRD Generator CLI tool](cli/README.md) +- [CRD Generator usage with Gradle in build script](gradle/README.md) + +### Deprecated Tools + +- [CRD Generator annotation processing tool (APT)](apt/README.md) diff --git a/crd-generator/gradle/README.md b/crd-generator/gradle/README.md new file mode 100644 index 0000000000..d402dbec7e --- /dev/null +++ b/crd-generator/gradle/README.md @@ -0,0 +1,77 @@ +# CRD Generator - Usage with Gradle in build script + +The CRD Generator v2 can be used in a [build script](https://docs.gradle.org/current/userguide/writing_build_scripts.html) without an additional plugin: + +## Kotlin DSL (`build.gradle.kts`) + +```kotlin +import io.fabric8.crdv2.generator.CRDGenerationInfo +import io.fabric8.crdv2.generator.CRDGenerator +import io.fabric8.crd.generator.collector.CustomResourceCollector +import java.nio.file.Files + +plugins { + id("java") +} + +group = "io.fabric8.crd-generator.gradle" +version = "0.0.1-SNAPSHOT" + +repositories { + mavenCentral() +} + +dependencies { + compileOnly("io.fabric8:kubernetes-client-api:7.0.0") +} + +buildscript { + repositories { + mavenCentral() + } + dependencies { + classpath("io.fabric8:crd-generator-api-v2:7.0.0") + classpath("io.fabric8:crd-generator-collector:7.0.0") + } +} + +tasks.register("generateCrds") { + description = "Generate CRDs from compiled custom resource classes" + group = "crd" + + val sourceSet = project.sourceSets["main"] + + val compileClasspathElements = sourceSet.compileClasspath.map { e -> e.absolutePath } + + val outputClassesDirs = sourceSet.output.classesDirs + val outputClasspathElements = outputClassesDirs.map { d -> d.absolutePath } + + val classpathElements = listOf(outputClasspathElements, compileClasspathElements).flatten() + val filesToScan = listOf(outputClassesDirs).flatten() + val outputDir = sourceSet.output.resourcesDir + + doLast { + Files.createDirectories(outputDir!!.toPath()) + + val collector = CustomResourceCollector() + .withParentClassLoader(Thread.currentThread().contextClassLoader) + .withClasspathElements(classpathElements) + .withFilesToScan(filesToScan) + + val crdGenerator = CRDGenerator() + .customResourceClasses(collector.findCustomResourceClasses()) + .inOutputDir(outputDir) + + val crdGenerationInfo: CRDGenerationInfo = crdGenerator.detailedGenerate() + + crdGenerationInfo.crdDetailsPerNameAndVersion.forEach { (crdName, versionToInfo) -> + println("Generated CRD $crdName:") + versionToInfo.forEach { (version, info) -> println(" $version -> ${info.filePath}") } + } + } +} + +tasks.named(JvmConstants.CLASSES_TASK_NAME) { + finalizedBy("generateCrds") +} +``` diff --git a/doc/CRD-generator.md b/doc/CRD-generator.md index 31af8d78ea..51c4de089b 100644 --- a/doc/CRD-generator.md +++ b/doc/CRD-generator.md @@ -1,4 +1,4 @@ -# CRD generation +# CRD Generator The [CRD Generator annotation processing tool (APT)](../crd-generator/apt/README.md) (`io.fabric8:crd-generator-apt`) and its API (`io.fabric8:crd-generator-api`) are being deprecated and will eventually be removed once we offer a complete replacement for all users. @@ -38,7 +38,8 @@ with Maven: with Gradle: > [!NOTE] -> The Gradle plugin is not available yet. Please use the Maven plugin or the CLI tool. +> The Gradle plugin is not available yet. +> Meanwhile, Gradle users can use the [CRD Generator in a build script](../crd-generator/gradle/README.md). Now you can define a `class` that extends `io.fabric8.kubernetes.client.CustomResource` and the corresponding CRD is generated in the folder: `target/classes/META-INF/fabric8`