From 930774e25cd4cd7afc02571388b78a1382f8affd Mon Sep 17 00:00:00 2001 From: Rohan Kumar Date: Wed, 16 Nov 2022 17:09:18 +0530 Subject: [PATCH] doc (jkube-kit/doc) : Move Route generation documentation to JKube Kit + Fix path error related to kitdoc-path in Maven Plugin docs + Add documentation for Route Generation to JKube Kit Signed-off-by: Rohan Kumar --- .../main/asciidoc/inc/examples/_groovy.adoc | 5 + .../route-generation/_route_generation.adoc | 96 ++++++++++++++ .../gradle/_generate_route_false.adoc | 13 ++ .../gradle/_route_edge_insecure.adoc | 15 +++ .../maven/_generate_route_false.adoc | 18 +++ .../maven/_route_edge_insecure.adoc | 20 +++ .../inc/goals/build/_jkube-resource.adoc | 117 +----------------- .../asciidoc/inc/goals/develop/_goals.adoc | 4 +- 8 files changed, 171 insertions(+), 117 deletions(-) create mode 100644 jkube-kit/doc/src/main/asciidoc/inc/route-generation/_route_generation.adoc create mode 100644 jkube-kit/doc/src/main/asciidoc/inc/route-generation/gradle/_generate_route_false.adoc create mode 100644 jkube-kit/doc/src/main/asciidoc/inc/route-generation/gradle/_route_edge_insecure.adoc create mode 100644 jkube-kit/doc/src/main/asciidoc/inc/route-generation/maven/_generate_route_false.adoc create mode 100644 jkube-kit/doc/src/main/asciidoc/inc/route-generation/maven/_route_edge_insecure.adoc diff --git a/gradle-plugin/doc/src/main/asciidoc/inc/examples/_groovy.adoc b/gradle-plugin/doc/src/main/asciidoc/inc/examples/_groovy.adoc index 42afde59df..d9cbdb8723 100644 --- a/gradle-plugin/doc/src/main/asciidoc/inc/examples/_groovy.adoc +++ b/gradle-plugin/doc/src/main/asciidoc/inc/examples/_groovy.adoc @@ -1,5 +1,6 @@ [[groovy-scenario]] == Using Groovy Configuration +:examplejkubekitdoc-path: ../../../../../../../jkube-kit/doc/src/main/asciidoc If the <> mode doesn't fit your use case, and you want more flexibility, you can also use {plugin} Groovy configuration to configure @@ -389,3 +390,7 @@ kind: ServiceAccount metadata: name: build-robot ---- + +ifeval::["{task-prefix}" == "oc"] +include::{examplejkubekitdoc-path}/inc/route-generation/_route_generation.adoc[] +endif::[] diff --git a/jkube-kit/doc/src/main/asciidoc/inc/route-generation/_route_generation.adoc b/jkube-kit/doc/src/main/asciidoc/inc/route-generation/_route_generation.adoc new file mode 100644 index 0000000000..db0d74ea17 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/route-generation/_route_generation.adoc @@ -0,0 +1,96 @@ +[[resource-route-generation]] +=== Route Generation + +ifeval::["{plugin-type}" == "maven"] +When the `{goal-prefix}:resource` goal is run, +endif::[] +ifeval::["{plugin-type}" == "gradle"] +When the `{task-prefix}Resource` goal is run, +endif::[] + +an {cluster} +https://docs.openshift.org/latest/architecture/networking/routes.html[Route] descriptor (`route.yml`) will also be +generated along the service if an {cluster} cluster is targeted. +If you do not want to generate a Route descriptor, you can set the `jkube.openshift.generateRoute` property to `false`. + +*Note:* +Routes will be automatically generated for Services with recognized web ports (`80`, `443`, `8080`, `8443`, `9080`, , `9090`, `9443`). + +If your service exposes any other port and you still want to generate a Route, you can do any of the following: + +* Force the route creation by setting the `jkube.createExternalUrls` property to `true`. +* Force the route creation by using the `expose: true` label in the `Service`: +** Add the `expose: true` label in a `Service` fragment. +** Add the `expose: true` label by leveraging the <> (`jkube.enricher.jkube-service.expose`). + +.Route Generation Configuration +[cols="1,6,1"] +|=== +| Element | Description | Property + +| *generateRoute* +| If value is set to `false` then no Route descriptor will be generated. +By default it is set to `true`, which will create a `route.yml` descriptor and also add Route resource to `openshift.yml`. +| `jkube.openshift.generateRoute` + + `jkube.enricher.jkube-openshift-route.generateRoute` + +| *tlsTermination* +a| tlsTermination indicates termination type. The following values are supported: + +* edge (default) +* passthrough +* reencrypt + +See https://docs.openshift.com/container-platform/3.11/architecture/networking/routes.html#secured-routes or https://docs.openshift.com/container-platform/latest/networking/routes/secured-routes.html +| `jkube.enricher.jkube-openshift-route.tlsTermination` + +| *tlsInsecureEdgeTerminationPolicy* +a| tlsInsecureEdgeTerminationPolicy indicates the desired behavior for insecure connections to a route. +While each router may make its own decisions on which ports to expose, this is normally port 80. + +* Allow - traffic is sent to the server on the insecure port (default) +* Disable - no traffic is allowed on the insecure port. +* Redirect - clients are redirected to the secure port. + +See https://docs.openshift.com/container-platform/latest/rest_api/network_apis/route-route-openshift-io-v1.html +| `jkube.enricher.jkube-openshift-route.tlsInsecureEdgeTerminationPolicy` +|=== + +Below is an example of generating a Route with "edge" termination and "Allow" insecureEdgeTerminationPolicy: + +ifeval::["{plugin-type}" == "maven"] +include::maven/_route_edge_insecure.adoc[] +endif::[] +ifeval::["{plugin-type}" == "gradle"] +include::gradle/_route_edge_insecure.adoc[] +endif::[] + + +Adding certificates for routes is not directly supported in the pom, but can be added via a yaml fragment. + +If you do not want to generate a Route descriptor, you can also specify so in the plugin configuration in your POM as seen below. + +ifeval::["{plugin-type}" == "maven"] +include::maven/_generate_route_false.adoc[] +endif::[] +ifeval::["{plugin-type}" == "gradle"] +include::gradle/_generate_route_false.adoc[] +endif::[] + + +If you are using resource fragments, then also you can configure it in your Service resource fragment (e.g. `service.yml`). +You need to add an `expose` label to the `metadata` section of your service and set it to `false`. + +.Example for not generating route resource by configuring it in resource fragments + +[source, yaml] +---- +metadata: + annotations: + api.service.kubernetes.io/path: /hello + labels: + expose: "false" +spec: + type: LoadBalancer +---- diff --git a/jkube-kit/doc/src/main/asciidoc/inc/route-generation/gradle/_generate_route_false.adoc b/jkube-kit/doc/src/main/asciidoc/inc/route-generation/gradle/_generate_route_false.adoc new file mode 100644 index 0000000000..ec55fefb77 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/route-generation/gradle/_generate_route_false.adoc @@ -0,0 +1,13 @@ +.Example for not generating route resource by configuring it in `build.gradle` +[source,groovy,indent=0,subs="verbatim,quotes,attributes"] +---- +{pluginExtension} { + enricher { + config { + 'jkube-openshift-route' { + generateRoute = false + } + } + } +} +---- \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/route-generation/gradle/_route_edge_insecure.adoc b/jkube-kit/doc/src/main/asciidoc/inc/route-generation/gradle/_route_edge_insecure.adoc new file mode 100644 index 0000000000..bd748eb811 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/route-generation/gradle/_route_edge_insecure.adoc @@ -0,0 +1,15 @@ +.Example for generating route resource by configuring it in `build.gradle` +[source,groovy,indent=0,subs="verbatim,quotes,attributes"] +---- +{pluginExtension} { + enricher { + config { + 'jkube-openshift-route' { + generateRoute = true + tlsInsecureEdgeTerminationPolicy = 'Allow' + tlsTermination = 'Edge' + } + } + } +} +---- \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/route-generation/maven/_generate_route_false.adoc b/jkube-kit/doc/src/main/asciidoc/inc/route-generation/maven/_generate_route_false.adoc new file mode 100644 index 0000000000..d1d4953939 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/route-generation/maven/_generate_route_false.adoc @@ -0,0 +1,18 @@ +.Example for not generating route resource by configuring it in `pom.xml` +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + org.eclipse.jkube + {plugin} + {version} + + + + + false + + + + + +---- diff --git a/jkube-kit/doc/src/main/asciidoc/inc/route-generation/maven/_route_edge_insecure.adoc b/jkube-kit/doc/src/main/asciidoc/inc/route-generation/maven/_route_edge_insecure.adoc new file mode 100644 index 0000000000..09becb3b51 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/route-generation/maven/_route_edge_insecure.adoc @@ -0,0 +1,20 @@ +.Example for generating route resource by configuring it in `pom.xml` +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + org.eclipse.jkube + {plugin} + {version} + + + + + true + Allow + edge + + + + + +---- \ No newline at end of file diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-resource.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-resource.adoc index 9bfc7f8645..d7373618e6 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-resource.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-resource.adoc @@ -1,5 +1,6 @@ [[jkube:resource]] == *{goal-prefix}:resource* +:kitdoc-path: ../../../../../../../../jkube-kit/doc/src/main/asciidoc This goal generates {cluster} resources based on your project. It can either be opinionated defaults or based on the configuration provided in XML config or resource fragments in `src/main/jkube`. @@ -753,121 +754,7 @@ Resource goal also validates the generated resource descriptors using API specif |=== ifeval::["{goal-prefix}" == "oc"] -[[resource-route-generation]] -=== Route Generation - -When the `{goal-prefix}:resource` goal is run, an {cluster} -https://docs.openshift.org/latest/architecture/networking/routes.html[Route] descriptor (`route.yml`) will also be -generated along the service if an {cluster} cluster is targeted. -If you do not want to generate a Route descriptor, you can set the `jkube.openshift.generateRoute` property to `false`. - -*Note:* -Routes will be automatically generated for Services with recognized web ports (`80`, `443`, `8080`, `9080`, , `9090`, `9443`). - -If your service exposes any other port and you still want to generate a Route, you can do any of the following: - -* Force the route creation by setting the `jkube.createExternalUrls` property to `true`. -* Force the route creation by using the `expose: true` label in the `Service`: -** Add the `expose: true` label in a `Service` fragment. -** Add the `expose: true` label by leveraging the <> (`jkube.enricher.jkube-service.expose`). - -.Route Generation Configuration -[cols="1,6,1"] -|=== -| Element | Description | Property - -| *generateRoute* -| If value is set to `false` then no Route descriptor will be generated. - By default it is set to `true`, which will create a `route.yml` descriptor and also add Route resource to `openshift.yml`. -| `jkube.openshift.generateRoute` - - `jkube.enricher.jkube-openshift-route.generateRoute` - -| *tlsTermination* -a| tlsTermination indicates termination type. The following values are supported: - -* edge (default) -* passthrough -* reencrypt - -See https://docs.openshift.com/container-platform/3.11/architecture/networking/routes.html#secured-routes or https://docs.openshift.com/container-platform/latest/networking/routes/secured-routes.html -| `jkube.enricher.jkube-openshift-route.tlsTermination` - -| *tlsInsecureEdgeTerminationPolicy* -a| tlsInsecureEdgeTerminationPolicy indicates the desired behavior for insecure connections to a route. -While each router may make its own decisions on which ports to expose, this is normally port 80. - -* Allow - traffic is sent to the server on the insecure port (default) -* Disable - no traffic is allowed on the insecure port. -* Redirect - clients are redirected to the secure port. - -See https://docs.openshift.com/container-platform/latest/rest_api/network_apis/route-route-openshift-io-v1.html -| `jkube.enricher.jkube-openshift-route.tlsInsecureEdgeTerminationPolicy` -|=== - -Below is an example of generating a Route with "edge" termination and "Allow" insecureEdgeTerminationPolicy: -.Example for generating route resource by configuring it in `pom.xml` - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - org.eclipse.jkube - {plugin} - {version} - - - - - true - Allow - edge - - - - - ----- - -Adding certificates for routes is not directly supported in the pom, but can be added via a yaml fragment. - -If you do not want to generate a Route descriptor, you can also specify so in the plugin configuration in your POM as seen below. - -.Example for not generating route resource by configuring it in `pom.xml` - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - org.eclipse.jkube - {plugin} - {version} - - - - - false - - - - - ----- - -If you are using resource fragments, then also you can configure it in your Service resource fragment (e.g. `service.yml`). -You need to add an `expose` label to the `metadata` section of your service and set it to `false`. - -.Example for not generating route resource by configuring it in resource fragments - -[source, yaml] ----- -metadata: - annotations: - api.service.kubernetes.io/path: /hello - labels: - expose: "false" -spec: - type: LoadBalancer ----- - +include::{kitdoc-path}/inc/route-generation/_route_generation.adoc[] endif::[] [[Supported-Properties-Resource]] diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_goals.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_goals.adoc index 4e075e6144..0ad4d665f1 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_goals.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_goals.adoc @@ -1,10 +1,10 @@ [[goals-overview-develop]] # Development Goals -:kitdoc-path: ../../../../../../../../jkube-kit/doc/src/main/asciidoc +:developjkubekitdoc-path: ../../../../../../../../jkube-kit/doc/src/main/asciidoc include::_jkube-deploy.adoc[] include::_jkube-undeploy.adoc[] include::_jkube-log.adoc[] include::_jkube-debug.adoc[] -include::{kitdoc-path}/inc/remote-dev/_index.adoc[] +include::{developjkubekitdoc-path}/inc/remote-dev/_index.adoc[] include::_jkube-watch.adoc[]