Skip to content

Commit

Permalink
Add docs for added Generators to Kubernetes Gradle Plugin
Browse files Browse the repository at this point in the history
+ Add documentation for Quarkus, OpenLiberty, Micronaut generators
+ Fix invalid references, they can be added later when their
  documentation is added

Signed-off-by: Rohan Kumar <rohaan@redhat.com>
  • Loading branch information
rohanKanojia authored and manusa committed Jan 31, 2022
1 parent be8514f commit fd859ce
Show file tree
Hide file tree
Showing 12 changed files with 72 additions and 12 deletions.
15 changes: 15 additions & 0 deletions gradle-plugin/doc/src/main/asciidoc/inc/_generator.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,28 @@ All default generators examine the build information for certain aspects and gen
| `spring-boot`
| Spring Boot specific generator

| <<generator-quarkus,Quarkus>>
| `Quarkus`
| Generator for Quarkus based applications

| <<generator-micronaut,Micronaut>>
| `micronaut`
| Generator for Micronaut based applications

| <<generator-vertx,Vert.x>>
| `vertx`
| Generator for Vert.x applications

| <<generator-openliberty,Open Liberty>>
| `openliberty`
| Generator for Open Liberty applications
|===

include::generator/_options_common.adoc[]

include::generator/_java_exec.adoc[]
include::generator/_spring_boot.adoc[]
include::generator/_quarkus.adoc[]
include::generator/_micronaut.adoc[]
include::generator/_vertx.adoc[]
include::generator/_openliberty.adoc[]
Original file line number Diff line number Diff line change
Expand Up @@ -278,9 +278,10 @@ protected registry which requires authentication.

endif::[]

| *profile*
| Profile to which contains enricher and generators configuration. See <<profiles,Profiles>> for details.
| `jkube.profile`
// TODO - Add when support is complete
//| *profile*
//| Profile to which contains enricher and generators configuration. See <<profiles,Profiles>> for details.
//| `jkube.profile`

ifeval::["{task-prefix}" == "oc"]
| *processTemplatesLocally*
Expand Down
3 changes: 2 additions & 1 deletion gradle-plugin/doc/src/main/asciidoc/inc/_profiles.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,8 @@ Profiles are defined in YAML. The following example shows a simple profiles whic
----
<1> Profile's name
<2> <<generators, Generators>> to use
<3> <<enrichers, Enrichers>> to use
// TODO - Add when support is complete
//<3> <<enrichers, Enrichers>> to use
<4> List of enricher to *include* in that given order
<5> List of enricher to *exclude*
<6> Configuration for services an enrichers
Expand Down
4 changes: 2 additions & 2 deletions gradle-plugin/doc/src/main/asciidoc/inc/build/_overview.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ so that the assembly files will end up in `/my/target/directory` within the cont
If this directory contains a `.jkube-dockerignore` (or alternatively, a `.jkube-dockerexclude` file), then it is used
for excluding files for the build. If the file doesn't exist, or it's empty, then there are no exclusions.

Each line in this file is treated as an entry in the `excludes` assembly `fileSet` <<build-assembly-inline, configuration >>.
Each line in this file is treated as an entry in the `excludes` assembly `fileSet` <<build-assembly-layer, configuration >>.
Files can be referenced by using their relative path name.
Wildcards are also supported, patterns will be matched using
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)[
Expand All @@ -51,7 +51,7 @@ build/classes/** # <1>
If this directory contains a `.jkube-dockerinclude` file, then it is used for including only those files for the build.
If the file doesn't exist or it's empty, then everything is included.

Each line in this file is treated as an entry in the `includes` assembly `fileSet` <<build-assembly-inline, configuration >>.
Each line in this file is treated as an entry in the `includes` assembly `fileSet` <<build-assembly-layer, configuration >>.
Files can be referenced by using their relative path name.
Wildcards are also supported, patterns will be matched using
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/FileSystem.html#getPathMatcher(java.lang.String)[
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,8 @@ the following additional configuration options are recognized:
| `jkube.generator.java-exec.webPort`
|===

The exposed ports are typically later on use by <<enrichers, Enrichers>> to create default Kubernetes or OpenShift services.
// TODO - Add when enrichers are added to documentation
//The exposed ports are typically later on use by <<enrichers, Enrichers>> to create default Kubernetes or OpenShift services.

You can add additional files to the target image within `baseDir` by placing files into `src/main/jkube-includes`.
These will be added with mode `0644`, while everything in `src/main/jkube-includes/bin` will be added with `0755`.
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
[[generator-micronaut]]
=== Micronaut Generator

The Micronaut generator (named `micronaut`) detects a Micronaut project by analyzing the plugin
dependencies searching for `io.micronaut.application:io.micronaut.application.gradle.plugin`.

This generator is based on the <<generator-java-exec, Java Application>> Generator and inherits all
of its configuration values.
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
[[generator-openliberty]]
=== Open Liberty

The Open Liberty generator runs when the Open Liberty plugin is enabled in the gradle build. It can done via two ways as specified in https://github.com/OpenLiberty/ci.gradle#usage[OpenLiberty Gradle Plugin docs]:

- Within `apply plugin:` section as `liberty`
- Within `plugins` section as `io.openliberty.tools.gradle.Liberty`

The generator is similar to the <<generator-java-exec,java-exec generator>>. It supports the <<generator-options-common, common generator options>> and the <<generator-java-exec-options, `java-exec` options>>.

For Open Liberty, the default value of webPort is 9080.
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
The usual way to define Docker images is with the plugin configuration as explained in <<jkubeBuild>>. This can either be done completely within the `build.gradle` or by referring to an external Dockerfile.

However, this plugin provides an additional route for defining image configurations. This is done by so called _Generators_. A generator is a Java component providing an auto-detection mechanism for certain build types like a Spring Boot build or a plain Java build. As soon as a _Generator_ detects that it is applicable it will be called with the list of images configured in the `build.gradle`. Typically a generator only creates dynamically a new image configuration if this list is empty. But a generator is free to also add new images to an existing list or even change the current image list.
However, this plugin provides an additional route for defining image configurations. This is done by so called _Generators_. A generator is a Java component providing an auto-detection mechanism for certain build types like a Spring Boot build or a plain Java build. As soon as a _Generator_ detects that it is applicable it will be called with the list of images configured in the `build.gradle`.

You can easily create your own generator as explained in <<generators-api, Generator API>>. This section will focus on existing generators and how you can configure them.
// TODO - Add when support is complete
//You can easily create your own generator as explained in <<generators-api, Generator API>>. This section will focus on existing generators and how you can configure them.

The included _Generators_ are enabled by default, but you can easily disable them or only select a certain set of generators. Each generator has a _name_, which is unique for a generator.

Expand Down
20 changes: 20 additions & 0 deletions gradle-plugin/doc/src/main/asciidoc/inc/generator/_quarkus.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
[[generator-quarkus]]
=== Quarkus

The `Quarkus` generator detects Quarkus based projects looking at project `build.gradle`:

The base images chosen are:
[[generator-quarkus-from]]
.Webapp Base Images
[cols="1,4,4"]
|===
| | Docker Build | S2I Build

| *Native*
| `registry.access.redhat.com/ubi8/ubi-minimal:8.1`
| `quay.io/quarkus/ubi-quarkus-native-binary-s2i`

| *Normal Build*
| `quay.io/jkube/jkube-java`
| `quay.io/jkube/jkube-java`
|===
Original file line number Diff line number Diff line change
Expand Up @@ -43,4 +43,6 @@ Additionally, if you name your fragment using a name prefix followed by a dash a

No image is also referenced in this example because the plugin also fills in the image details based on the configured image you are building with (either from a generator or from a dedicated image plugin configuration, as seen before).

Enrichment of resource fragments can be fine-tuned by using profile sub-directories. For more details see <<profiles, Profiles>>.
Enrichment of resource fragments can be fine-tuned by using profile sub-directories.
// TODO - Add when support is complete
//For more details see <<profiles, Profiles>>.
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
[[jkubeLog]]
=== *{task-prefix}Log*

This task tails the log of the app that you deployed via the <<jkube:deploy, {task-prefix}Apply>> task
This task tails the log of the app that you deployed via the <<jkubeApply, {task-prefix}Apply>> task

[source,sh,subs="+attributes"]
----
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
[[jkubeUndeploy]]
=== *{task-prefix}Undeploy*

This task is for deleting the kubernetes resources that you deployed via the <<jkubeApply, {task-prefix}Apply>> or <<jkube:deploy, {task-prefix}Deploy>> tasks.
This task is for deleting the kubernetes resources that you deployed via the <<jkubeApply, {task-prefix}Apply>> task.

It iterates through all the resources generated by the <<jkubeResource, {task-prefix}Resource>> task and deletes them from your current {cluster} cluster.

Expand Down

0 comments on commit fd859ce

Please sign in to comment.