diff --git a/CHANGELOG.md b/CHANGELOG.md index ab865967dd..ec695102d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,7 +24,8 @@ Usage: * Fix #167: Add CMD for wildfly based applications * Added Webapp Wildfly maven quickstart * Fix #171: OpenShift pull secret not picked up without registry auth configuration -* Fix #171: Customized Quarkus application quick start +* Fix #171: Customized Quarkus application quick start +* Fix #101: Removed Openshift specific functionality from Kubernetes Maven Plugin ### 1.0.0-alpha-2 (2020-04-24) * Fix #130: Updated HelmMojo documentation diff --git a/kubernetes-maven-plugin/doc/pom.xml b/kubernetes-maven-plugin/doc/pom.xml index c23a3031c0..cec0cf9df8 100644 --- a/kubernetes-maven-plugin/doc/pom.xml +++ b/kubernetes-maven-plugin/doc/pom.xml @@ -32,7 +32,9 @@ 1.6.0 2.1.0 - 1.5.0-alpha.18 + kubernetes-maven-plugin + k8s + Kubernetes @@ -148,6 +150,10 @@ left false + ${plugin} + ${goal-prefix} + ${cluster} + ${project.version} @@ -157,43 +163,6 @@ true - - - - - pdf - - - - org.asciidoctor - asciidoctor-maven-plugin - - - output-pdf - package - - process-asciidoc - - - pdf - rouge - - - - - - - - - org.asciidoctor - asciidoctorj-pdf - ${asciidoctorj-pdf.version} - - - - - - diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_access.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_access.adoc index 9a9d77acee..f8fcd7f6fd 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_access.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_access.adoc @@ -6,7 +6,7 @@ WARNING: This section is work-in-progress and not yet finished -For Kubernetes builds the kubernetes-maven-plugin uses the Docker remote API so the URL of your Docker Daemon must be specified. The URL can be specified by the dockerHost or machine configuration, or by the `DOCKER_HOST` environment variable. If not given +For {cluster} builds the {plugin} uses the Docker remote API so the URL of your Docker Daemon must be specified. The URL can be specified by the dockerHost or machine configuration, or by the `DOCKER_HOST` environment variable. If not given The Docker remote API supports communication via SSL and authentication with certificates. The path to the certificates can @@ -18,4 +18,3 @@ be specified by the certPath or machine configuration, or by the Plugin reads your `kubeconfig` file to read your Kubernetes/OpenShift configuration. By default, `kubeconfig` file is assumed to be either in `~/.kube/config` or using the environment variable `KUBECONFIG`. - diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_appendix.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_appendix.adoc index 1cf9d18aba..efaeef4136 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_appendix.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_appendix.adoc @@ -16,11 +16,11 @@ By default if no environment variable nor system property is set, scan for a fil * By embedding in MOJO configuration the mapping: -[source, xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_authentication.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_authentication.adoc index cd092b02b3..383de7c833 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_authentication.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_authentication.adoc @@ -2,7 +2,7 @@ [[authentication]] = Authentication -When pulling (via the `autoPull` mode of `{plugin}:start`) or pushing image, it +When pulling (via the `autoPull` mode of `{goal-prefix}:start`) or pushing image, it might be necessary to authenticate against a Docker registry. There are five different locations searched for credentials. In order, these are: @@ -17,7 +17,7 @@ Using the username and password directly in the `pom.xml` is not recommended since this is widely visible. This is the easiest and transparent way, though. Using an `` is straight forward: -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- @@ -38,13 +38,13 @@ the outside: .Example [source, sh, subs="+attributes"] ---- -mvn -Ddocker.username=jolokia -Ddocker.password=s!cr!t {plugin}:push +mvn -Ddocker.username=jolokia -Ddocker.password=s!cr!t {goal-prefix}:push ---- The most _mavenish_ way is to add a server to the Maven settings file `~/.m2/settings.xml`: .Example -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- @@ -84,7 +84,7 @@ can be added. In the example below the credentials provider are only used for image push operations: .Example -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- @@ -158,7 +158,7 @@ that you have setup a _master password_ in passwords: .Example -[source,bash] +[source, bash, subs="+attributes"] ---- $ mvn --encrypt-password Password: diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_compatibility.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_compatibility.adoc index 21f8a90d95..e98e217402 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_compatibility.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_compatibility.adoc @@ -1,3 +1,4 @@ +ifeval::["{goal-prefix}" == "k8s"] [[compatibility-with-Kubernetes]] = Compatibility with Kubernetes @@ -20,3 +21,31 @@ | KMP 0.1.0 | x | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |=== + +endif::[] + +ifeval::["{goal-prefix}" == "oc"] + +[[compatibility-with-OpenShift]] += Compatibility with OpenShift + +[[openshift-compatibility]] +== OpenShift Compatibility + +.OpenShift Compatibility +|=== +| OMP | OpenShift 4.2.0 | OpenShift 3.11.0 | OpenShift 3.10.0 | OpenShift 3.9.0 | OpenShift 3.7.0 | OpenShift 3.6.0 | OpenShift 3.5.0 | OpenShift 1.4.1 + +| OMP 1.0.0-alpha-2 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | x | x + +| OMP 1.0.0-alpha-1 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | x | x + +| OMP 0.2.0 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | x | x + +| OMP 0.1.1 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | x | x + +| OMP 0.1.0 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | x | x + +|=== + +endif::[] diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_enricher.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_enricher.adoc index 89e2f57aad..436ce9e8de 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_enricher.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_enricher.adoc @@ -1,9 +1,8 @@ - [[enrichers]] = Enrichers -Enriching is the complementary concept to <>. Whereas Generators are used to create and customize Docker images, Enrichers are use to create and customize Kubernetes resource objects. +Enriching is the complementary concept to <>. Whereas Generators are used to create and customize Docker images, Enrichers are use to create and customize {cluster} resource objects. There are a lot of similarities to Generators: @@ -33,7 +32,7 @@ This plugin comes with a set of default enrichers. In addition custom enrichers [[enrichers-default]] == Default Enrichers -kubernetes-maven-plugin comes with a set of enrichers which are enabled by default. There are two categories of default enrichers: +{plugin} comes with a set of enrichers which are enabled by default. There are two categories of default enrichers: * *Generic Enrichers* are used to add default resource object when they are missing or add common metadata extracted from the given build information * *Specific Enrichers* are enrichers which are focused on a certain tech stack that they detect. @@ -83,7 +82,7 @@ kubernetes-maven-plugin comes with a set of enrichers which are enabled by defau | Add revision history limit (https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#revision-history-limit[Kubernetes doc]) as a deployment spec property to the Kubernetes/OpenShift resources. | <> -| Add ImageStreamTag change triggers on Kubernetes resources such as StatefulSets, ReplicaSets and DaemonSets using the `image.openshift.io/triggers` annotation. +| Add ImageStreamTag change triggers on {cluster} resources such as StatefulSets, ReplicaSets and DaemonSets using the `image.openshift.io/triggers` annotation. | <> | Add ConfigMap elements defined as XML or as annotation. @@ -166,13 +165,13 @@ Enricher which adds appropriate annotations and volumes to enable OpenShift's au This enricher adds an init container to convert the service serving certificates from PEM (the format that OpenShift generates them in) to a JKS-format Java keystore ready for consumption in Java services. -This enricher is disabled by default. In order to use it, you must configure the Kubernetes Maven plugin to use this enricher: +This enricher is disabled by default. In order to use it, you must configure the {plugin} to use this enricher: -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} {version} @@ -243,8 +242,9 @@ The auto-TLS enricher supports the following configuration options: | `server` |=== -[[enrichers-jkube] +[[enrichers-jkube]] === JKube Enrichers + JKube enrichers are used for providing the connection to other components of the jkube.Microservices platform. They are useful to add icons to application or links to documentation sites. [[jkube-healthcheck-karaf]] @@ -300,22 +300,22 @@ The enricher will use the following settings by default: If `path` attribute is not set (default value) then this enricher is disabled. -These values can be configured by the enricher in the `kubernetes-maven-plugin` configuration as shown below: +These values can be configured by the enricher in the `{plugin}` configuration as shown below: -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} {version} - kmp - - resource - helm - build - + jkube + + resource + helm + build + @@ -337,11 +337,13 @@ These values can be configured by the enricher in the `kubernetes-maven-plugin` This enricher adds kubernetes readiness and liveness probes with Spring Boot. This requires the following dependency has been enabled in Spring Boot -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- org.springframework.boot spring-boot-starter-actuator +---- The enricher will try to discover the settings from the `application.properties` / `application.yaml` Spring Boot configuration file. @@ -358,15 +360,16 @@ The enricher will use the following settings by default: * `failureThreshold`: `3` * `successThreshold`: `1` -These values can be configured by the enricher in the `kubernetes-maven-plugin` configuration as shown below: -[source,xml] +These values can be configured by the enricher in the `{plugin}` configuration as shown below: +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} {version} - kmp + jkube resource helm @@ -387,7 +390,7 @@ These values can be configured by the enricher in the `kubernetes-maven-plugin` - +---- [[jkube-healthcheck-wildfly-swarm]] @@ -396,11 +399,13 @@ These values can be configured by the enricher in the `kubernetes-maven-plugin` This enricher adds kubernetes readiness and liveness probes with WildFly Swarm. This requires the following fraction has been enabled in WildFly Swarm -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- org.wildfly.swarm microprofile-health +---- The enricher will use the following settings by default: @@ -410,15 +415,16 @@ The enricher will use the following settings by default: - failureThreshold = `3` - successThreshold = `1` -These values can be configured by the enricher in the `kubernetes-maven-plugin` configuration as shown below: -[source,xml] +These values can be configured by the enricher in the `{plugin}` configuration as shown below: +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} {version} - kmp + jkube resource helm @@ -440,6 +446,7 @@ These values can be configured by the enricher in the `kubernetes-maven-plugin` +---- [[jkube-healthcheck-thorntail-v2]] @@ -448,11 +455,13 @@ These values can be configured by the enricher in the `kubernetes-maven-plugin` This enricher adds kubernetes readiness and liveness probes with Thorntail v2. This requires the following fraction has been enabled in Thorntail -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- io.thorntail microprofile-health +---- The enricher will use the following settings by default: @@ -462,15 +471,16 @@ The enricher will use the following settings by default: - failureThreshold = `3` - successThreshold = `1` -These values can be configured by the enricher in the `kubernetes-maven-plugin` configuration as shown below: -[source,xml] +These values can be configured by the enricher in the `{plugin}` configuration as shown below: +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} {version} - kmp + jkube resource helm @@ -492,6 +502,7 @@ These values can be configured by the enricher in the `kubernetes-maven-plugin` +---- [[jkube-healthcheck-vertx]] ==== jkube-healthcheck-vertx @@ -517,11 +528,11 @@ The minimal configuration to add health checks is the following: ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} {version} - kmp + jkube resource helm @@ -564,11 +575,11 @@ You can provide two different configuration for the readiness and liveness check ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} {version} - kmp + jkube resource helm @@ -609,11 +620,11 @@ Shared (generic) configuration can be set outside of the specific configuration. ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} {version} - kmp + jkube resource helm @@ -896,7 +907,7 @@ Lets say you have a maven pom.xml with the following scm information, ---- -This infomation will be enriched as annotations in the generated manifest like, +This information will be enriched as annotations in the generated manifest like, [source,yaml] ---- diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_extensions.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_extensions.adoc index 29c68e1fd7..8375c0c7a3 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_extensions.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_extensions.adoc @@ -6,7 +6,7 @@ This plugin provides two major extensions hook how the creation of images and re * *Generators* are used to auto create or customize image configuration when creating Docker images. They are a bit like http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#using-boot-generator-poms[Spring Boot Generator POMs] as they can be enabled or disabled by declaring a Maven dependency. Generators are able to examine the build and to _detect_ certain feature like whether Spring boot application is build or a plain war file. Depending on the collected information a base image or the exposed ports are selected automatically for creating a image build configuration. -* *Enrichers* are a similar concept but for creating the Kubernetes resource descriptors. Enricher can add build meta data as labels, automatically create `ReplicaSet` or `Service` based on the image performed. Again, enrichers can be selectively switched on and off via declaring Maven dependencies or via the XML configuration. kubernetes-maven-plugin already comes with a rich set of enrichers. Whereas *Generators* are only useful in the _Zero-Config_ case, *Enrichers* make sense for any configuration variant. +* *Enrichers* are a similar concept but for creating the Kubernetes resource descriptors. Enricher can add build meta data as labels, automatically create `ReplicaSet` or `Service` based on the image performed. Again, enrichers can be selectively switched on and off via declaring Maven dependencies or via the XML configuration. {plugin} already comes with a rich set of enrichers. Whereas *Generators* are only useful in the _Zero-Config_ case, *Enrichers* make sense for any configuration variant. The following sections described which Generators and Enrichers are available and how own customizations can be hooked in. diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_generator.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_generator.adoc index 16bd24ee6a..038e06140e 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_generator.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_generator.adoc @@ -46,7 +46,6 @@ All default generators examine the build information for certain aspects and gen | `Quarkus` | Generator for Quarkus based applications - | <> | `webapps` | Generator for Open Liberty applications diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_global_configuration.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_global_configuration.adoc index 760f90f631..cc169c2206 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_global_configuration.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_global_configuration.adoc @@ -6,5 +6,6 @@ Global plugin configuration properties are typically apply to all Maven plugin g | Property | Description | `jkube.skip` -| Skips over executing the goal. Typically used to disable the JKube Kubernetes maven plugin when it's configured in a project. +| Skips over executing the goal. Typically used to disable the {plugin} when it's configured in a project. +|=== diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_installation.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_installation.adoc index 4de8c60c0e..cec3f1b6f0 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_installation.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_installation.adoc @@ -26,7 +26,7 @@ By default, Maven will only search for plugins in the `org.apache.maven.plugins` ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} {version} @@ -43,7 +43,7 @@ By default, Maven will only search for plugins in the `org.apache.maven.plugins` - + jkube diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_integrations.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_integrations.adoc index c252fa0ef3..250a1bf6c8 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_integrations.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_integrations.adoc @@ -5,13 +5,13 @@ [[integrations.dekorate]] == Dekorate -*kubernetes-maven-plugin* provides a Zero Configuration approach to delegate deployment manifests +*{plugin}* provides a Zero Configuration approach to delegate deployment manifests generation to https://github.com/dekorateio/dekorate[Dekorate]. Just by adding a dependency to Dekorate library in the `pom.xml` file, all manifest generation will be delegated to Dekorate. -[source, xml, indent=2] +[source,xml,indent=2,subs="verbatim,quotes,attributes"] ---- @@ -41,6 +41,6 @@ generation will be delegated to Dekorate. A full example of the integration can be found in the directory https://github.com/eclipse/jkube/tree/master/quickstarts/maven/spring-boot-dekorate[quickstarts/maven/spring-boot-dekorate]. -An *experimental* feature is also provided to merge resources generated both by *kubernetes-maven-plugin* +An *experimental* feature is also provided to merge resources generated both by *{plugin}* and Dekorate. You can activate this feature by using the following flag `-Djkube.mergeWithDekorate` in the command-line, or setting it up as a property (`true`). diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_introduction.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_introduction.adoc index 6e0bc60060..bbe5d0ef16 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_introduction.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_introduction.adoc @@ -2,7 +2,13 @@ [[introduction]] = Introduction -The *kubernetes-maven-plugin* (k-m-p) brings your Java applications on to http://kubernetes.io/[Kubernetes]. +The *{plugin}* brings your Java applications on to +ifeval::["{goal-prefix}" == "k8s"] +http://kubernetes.io/[Kubernetes]. +endif::[] +ifeval::["{goal-prefix}" == "oc"] +https://www.openshift.com/[OpenShift]. +endif::[] It provides a tight integration into http://maven.apache.org[Maven] and benefits from the build configuration already provided. This plugin focus on two tasks: _Building Docker images_ and _creating Kubernetes resource descriptors_. It can be configured very flexibly and supports multiple configuration models for creating: A _Zero-Config_ setup allows for a quick ramp-up with some opinionated defaults. @@ -12,22 +18,22 @@ For the full power, in order to tune all facets of the creation, external _resou [[building-images]] == Building Images -The <> goal is for creating Docker images containing the actual application. These then can be deployed later on Kubernetes or OpenShift. +The <> goal is for creating Docker images containing the actual application. These then can be deployed later on Kubernetes or OpenShift. It is easy to include build artifacts and their dependencies into these images. This plugin uses the assembly descriptor format from the http://maven.apache.org/plugins/maven-assembly-plugin/[maven-assembly-plugin] to specify the content which will be added to the image. -That images can then be pushed to public or private Docker registries with <>. +That images can then be pushed to public or private Docker registries with <>. Depending on the operational mode, for building the actual image either a Docker daemon is used directly or an https://docs.openshift.com/enterprise/3.0/architecture/core_concepts/builds_and_image_streams.html#docker-build[OpenShift Docker Build] is performed. -A special <> goal allows for reacting to code changes to automatically recreate images or copy new artifacts into running containers. +A special <> goal allows for reacting to code changes to automatically recreate images or copy new artifacts into running containers. These image related features are inherited from the https://github.com/jkubeio/docker-maven-plugin[jkubeio/docker-maven-plugin] which is part of this plugin. [[resource-descriptors]] -== Kubernetes Resources +== {cluster} Resources -Kubernetes resource descriptors can be created or generated from <>. -These files are packaged within the Maven artifacts and can be deployed to a running orchestration platform with <>. +{cluster} resource descriptors can be created or generated from <>. +These files are packaged within the Maven artifacts and can be deployed to a running orchestration platform with <>. Typically you only specify a small part of the real resource descriptors which will be enriched by this plugin with various extra information taken from the `pom.xml`. This drastically reduces boilerplate code for common scenarios. @@ -56,11 +62,11 @@ The following table gives an overview of the different models | Default <> will create a default _Service_ and _Deployment_ (_DeploymentConfig_ for OpenShift) when no other resource objects are provided. Depending on the image they can detect which port to expose in the service. As with Generators, Enrichers support a limited set of configuration options. | *XML configuration* -| k-m-p inherits the XML based configuration for building images from the https://jkubeio.github.io/docker-maven-plugin/#docker:build[docker-maven-plugin] and provides the same functionality. It supports an http://maven.apache.org/components/plugins/maven-assembly-plugin/assembly.html[assembly descriptor] for specifying the content of the Docker image. +| {plugin} inherits the XML based configuration for building images from the https://jkubeio.github.io/docker-maven-plugin/#docker:build[docker-maven-plugin] and provides the same functionality. It supports an http://maven.apache.org/components/plugins/maven-assembly-plugin/assembly.html[assembly descriptor] for specifying the content of the Docker image. | A subset of possible resource objects can be configured with a dedicated XML syntax. With a decent IDE you get autocompletion on most object and inline documentation for the available configuration elements. The provided configuration can be still enhanced by Enhancers which is useful for adding e.g. labels and annotations containing build or other information. | *Resource Fragments* and *Dockerfiles* -| Similarly to the docker-maven-plugin, k-m-p supports <> too, which are referenced from the plugin configuration. +| Similarly to the docker-maven-plugin, {plugin} supports <> too, which are referenced from the plugin configuration. | Resource descriptors can be provided as external YAML files which specify a skeleton. This skeleton is then filled by Enrichers which add labels and more. Maven properties within these files are resolved to thier values. With this model you can use every Kubernetes / OpenShift resource object with all their flexibility, but still get the benefit of adding build information. |=== @@ -106,7 +112,7 @@ This minimal but full working example `pom.xml` shows how a simple spring boot a org.eclipse.jkube - kubernetes-maven-plugin + {plugin} {version} @@ -116,11 +122,11 @@ This minimal but full working example `pom.xml` shows how a simple spring boot a <1> This minimalistic spring boot application uses the spring-boot parent POM for setting up dependencies and plugins <2> The Spring Boot web starter dependency enables a simple embedded Tomcat for serving Spring MVC apps <3> The `spring-boot-maven-plugin` is responsible for repackaging the application into a fat jar, including all dependencies and the embedded Tomcat -<4> The `kubernetes-maven-plugin` enables the automatic generation of a Docker image and Kubernetes / OpenShift descriptors including this Spring application. +<4> The `{plugin}` enables the automatic generation of a Docker image and Kubernetes / OpenShift descriptors including this Spring application. This setup make some opinionated decisions for you: -* As base image https://github.com/jkubeio-images/java/tree/master/images/jboss/openjdk8/jdk[jkube.java-jboss-openjdk8-jdk] is chosen which enables https://www.jolokia.org[Jolokia] and https://github.com/prometheus/jmx_exporter[jmx_exporter]. It also comes with a sophisticated https://github.com/jkubeio-images/run-java-sh[startup script]. +* As base image https://github.com/fabric8io-images/java/tree/master/images/jboss/openjdk8/jdk[jkube/java-jboss-openjdk8-jdk] is chosen which enables https://www.jolokia.org[Jolokia] and https://github.com/prometheus/jmx_exporter[jmx_exporter]. It also comes with a sophisticated https://github.com/jkubeio-images/run-java-sh[startup script]. * It will create a Kubernetes http://kubernetes.io/docs/user-guide/deployments/[Deployment] and a http://kubernetes.io/docs/user-guide/services/[Service] as resource objects * It exports port 8080 as the application service port (and 8778 and 9779 for Jolokia and jmx_exporter access, respectively) @@ -128,30 +134,30 @@ These choices can be influenced by configuration options as described in <> explicitly), then a Docker build will be performed on OpenShift which at the end creates an https://docs.openshift.com/enterprise/3.1/architecture/core_concepts/builds_and_image_streams.html[ImageStream]. To deploy the resources to the cluster call -[source,bash] +[source, bash, subs="+attributes"] ---- -mvn k8s:resource k8s:deploy +mvn {goal-prefix}:resource {goal-prefix}:deploy ---- -By default a _Service_ and a _Deployment_ object pointing to the created Docker image is created. When running in OpenShift mode, a _Service_ and _DeploymentConfig_ which refers the _ImageStream_ created with `k8s:build` will be installed. +By default a _Service_ and a _Deployment_ object pointing to the created Docker image is created. When running in OpenShift mode, a _Service_ and _DeploymentConfig_ which refers the _ImageStream_ created with `{goal-prefix}:build` will be installed. -Of course you can bind all those jkube.goals to execution phases as well, so that they are called along with standard lifecycle goals like `install`. For example, to bind the building of the Kubernetes resource files and the Docker images, add the following goals to the execution of the k-m-p: +Of course you can bind all those jkube.goals to execution phases as well, so that they are called along with standard lifecycle goals like `install`. For example, to bind the building of the Kubernetes resource files and the Docker images, add the following goals to the execution of the {plugin}: .Example for lifecycle bindings -[source, xml, indent=0] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} @@ -169,11 +175,11 @@ Of course you can bind all those jkube.goals to execution phases as well, so tha If you'd also like to automatically deploy to Kubernetes each time you do a `mvn install` you can add the `deploy` goal: .Example for lifecycle bindings with automatic deploys for mvn install -[source, xml, indent=0] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} @@ -204,7 +210,7 @@ The plugin configuration can be roughly divided into the following sections: * `` configures <> which are responsible for creating images. Generators are used as an alternative to a dedicated `` section. * `` configures various aspects of <> for creating or enhancing resource descriptors. -A working example can be found in the https://github.com/eclipse/jkube/tree/master/kubernetes-maven-plugin/tree/master/quickstarts/maven/xml-config[quickstarts/maven/xml-config] directory. An extract of the plugin configuration is shown below: +A working example can be found in the https://github.com/eclipse/jkube/tree/master/quickstarts/maven/xml-config[samples/xml-config] directory. An extract of the plugin configuration is shown below: .Example for an XML configuration [source,xml,indent=0,subs="verbatim,quotes,attributes"] @@ -299,8 +305,8 @@ Let's have a look at an example from https://github.com/eclipse/jkube/tree/maste serviceAccount: ribbon ---- -As you can see, there is no `metadata` section as would be expected for Kubernetes resources because it will be automatically added by the `kubernetes-maven-plugin`. The object's `Kind`, if not given, is automatically derived from the -filename. In this case, the `kubernetes-maven-plugin` will create a `Deployment` because the file is called `deployment.yml`. Similar mappings between file names and resource type exist for each supported resource kind, the +As you can see, there is no `metadata` section as would be expected for Kubernetes resources because it will be automatically added by the `{plugin}`. The object's `Kind`, if not given, is automatically derived from the +filename. In this case, the `{plugin}` will create a `Deployment` because the file is called `deployment.yml`. Similar mappings between file names and resource type exist for each supported resource kind, the complete list of which (along with associated abbreviations) can be found in the <>. @@ -316,7 +322,7 @@ No image is also referenced in this example because the plugin also fills in the -NOTE: For building images there is also an alternative mode using external Dockerfiles, in addition to the XML based configuration. Refer to <> for details. +NOTE: For building images there is also an alternative mode using external Dockerfiles, in addition to the XML based configuration. Refer to <> for details. ''' diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_profiles.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_profiles.adoc index f287b8ec93..15b12d094c 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_profiles.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_profiles.adoc @@ -133,11 +133,11 @@ Profiles can be selected by defining them in the plugin configuration, by giving Here is an example how the profile can be used in a plugin configuration: -[source, xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} my-spring-boot-apps ..... @@ -150,9 +150,9 @@ Here is an example how the profile can be used in a plugin configuration: Alternatively a profile can be also specified on the command line when calling Maven: -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn -Djkube.profile=my-spring-boot-apps k8s:build k8s:deploy +mvn -Djkube.profile=my-spring-boot-apps {goal-prefix}:build {goal-prefix}:deploy ---- If a configuration for enrichers and generators are provided as part of the plugin's `` then this takes precedence over any profile specified. @@ -164,9 +164,9 @@ Profiles are also very useful when used together with resource fragments in `src For example, consider the following directory layout: -[source] +[source, subs="+attributes"] ---- -src/main/k8s: +src/main/{goal-prefix}: app-rc.yml app-svc.yml raw/ --> diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_registry.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_registry.adoc index b4643f827e..4a82ebd6b1 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_registry.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_registry.adoc @@ -34,9 +34,9 @@ evaluated which can be also provided as system property via detecting a registry. This registry is used for pulling (i.e. for autopull the base image -when doing a `{plugin}:build`) and pushing with `{plugin}:push`. However, +when doing a `{goal-prefix}:build`) and pushing with `{goal-prefix}:push`. However, when these two goals are combined on the command line like in `mvn --Ddocker.registry=myregistry:5000 package {plugin}:build {plugin}:push` +-Ddocker.registry=myregistry:5000 package {goal-prefix}:build {goal-prefix}:push` the same registry is used for both operation. For a more fine grained control, separate registries for _pull_ and _push_ can be specified. @@ -46,7 +46,7 @@ control, separate registries for _pull_ and _push_ can be specified. `docker.push.registry`, respectively. .Example -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- docker.jolokia.org:443 @@ -57,7 +57,7 @@ control, separate registries for _pull_ and _push_ can be specified. docker.ro14nd.de .... - + postgresql diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/build/_overview.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/build/_overview.adoc index 1ce65886f5..4e1df4fafa 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/build/_overview.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/build/_overview.adoc @@ -13,7 +13,7 @@ Alternatively an external Dockerfile template or Docker archive can be used. Thi * *contextDir* specifies docker build context if an external dockerfile is located outside of Docker build context. If not specified, Dockerfile's parent directory is used as build context. * *dockerFile* specifies a specific Dockerfile path. The Docker build context directory is set to `contextDir` if given. If not the directory by default is the directory in which the Dockerfile is stored. -* *dockerArchive* specifies a previously saved image archive to load directly. Such a tar archive can be created with `docker save` or the <<{plugin}:save>> goal. If a `dockerArchive` is provided, no `dockerFile` or `dockerFileDir` must be given. +* *dockerArchive* specifies a previously saved image archive to load directly. Such a tar archive can be created with `docker save` or the <> goal. If a `dockerArchive` is provided, no `dockerFile` or `dockerFileDir` must be given. * *dockerFileDir* (_deprecated_, use *contextDir*) specifies a directory containing a Dockerfile that will be used to create the image. The name of the Dockerfile is `Dockerfile` by default but can be also set with the option `dockerFile` (see below). All paths can be either absolute or relative paths (except when both `dockerFileDir` and `dockerFile` are provided in which case `dockerFile` must not be absolute). A relative path is looked up in `${project.basedir}/src/main/docker` by default. You can make it easily an absolute path by using `${project.basedir}` in your configuration. @@ -76,7 +76,7 @@ If you want to add some `` configuration to this image for starting it with [[build-filtering]] .Filtering -kubernetes-maven-plugin filters given Dockerfile with Maven properties, much like the `maven-resource-plugin` does. Filtering is enabled by default and can be switched off with a build config `false`. Properties which we want to replace are specified with the `${..}` syntax. +{plugin} filters given Dockerfile with Maven properties, much like the `maven-resource-plugin` does. Filtering is enabled by default and can be switched off with a build config `false`. Properties which we want to replace are specified with the `${..}` syntax. Replacement includes Maven project properties such as `${project.artifactId}`, properties set in the build, command-line properties, and system properties. Unresolved properties remain untouched. This partial replacement means that you can easily mix it with Docker build arguments and environment variable reference, but you need to be careful. @@ -94,7 +94,7 @@ For replacing other data in other files targeted for the Docker image, please us .Example The following example uses a Dockerfile in the directory `src/main/docker/demo` and replaces all properties in the format `@property@` within the Dockerfile. -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- @@ -118,11 +118,11 @@ The following example uses a Dockerfile in the directory This plugin supports so call *dmp-plugins* which are used during the build phase. dmp-plugins are enabled by just declaring a dependency in the plugin declaration: -[source, xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/enricher/_jkube_service.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/enricher/_jkube_service.adoc index 2d66f5184a..80e6864ab1 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/enricher/_jkube_service.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/enricher/_jkube_service.adoc @@ -134,11 +134,11 @@ Assuming that the image exposes ports `8080` and `8778` (either directly or via This example shows also the mapping rules: -* Port specification in `port` always override the port meta data of the contained Docker images (i.e. the ports exposed) +* Port specification in `port` always override the port metadata of the contained Docker images (i.e. the ports exposed) * You can always provide a complete mapping with `port` on your own * The ports exposed by the images serve as _default values_ which are used if not specified by this configuration option. * You can map ports which are _not_ exposed by the images by specifying them as target ports. -Multiple ports are **only** mapped when _multiPort_ mode is enabled (which is switched off by default). If _multiPort_ mode is disabled, only the first port from the list of mapped ports as calculated like above is taken. +Multiple ports are **only** mapped when _multiPort_ mode is enabled (which is switched off by default). If _multiPort_ mode is disabled, only the first port from the list of mapped ports calculated as above is taken. When you set `legacyPortMapping` to true than ports 8080 to 9090 are mapped to port 80 automatically if not explicitly mapped via `_port_`. I.e. when an image exposes port 8080 with a legacy mapping this mapped to a service port 80, not 8080. You _should not_ switch this on for any good reason. In fact it might be that this option can vanish anytime. diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/generator/_options_common.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/generator/_options_common.adoc index 3ea8524321..14c2c14a12 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/generator/_options_common.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/generator/_options_common.adoc @@ -7,7 +7,7 @@ There are some configuration options which are shared by all generators: | Element | Description | Property | *add* -| When this set to `true`, then the generator _adds_ to an existing image configuration. By default this is disabled, so that a generator only kicks in when there are no other image configurations in the build, which are either configured directly for a `k8s:build` or already added by a generator which has been run previously. +| When this set to `true`, then the generator _adds_ to an existing image configuration. By default this is disabled, so that a generator only kicks in when there are no other image configurations in the build, which are either configured directly for a `{goal-prefix}:build` or already added by a generator which has been run previously. | | *alias* diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/generator/_overview.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/generator/_overview.adoc index a8408b8f6f..e95edbee51 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/generator/_overview.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/generator/_overview.adoc @@ -1,4 +1,4 @@ -The usual way to define Docker images is with the plugin configuration as explained in <>. This can either be done completely within the `pom.xml` or by referring to an external Dockerfile. Since kubernetes-maven-plugin includes https://github.com/jkubeio/docker-maven-plugin[docker-maven-plugin] the way by which images are built is identical. +The usual way to define Docker images is with the plugin configuration as explained in <>. This can either be done completely within the `pom.xml` or by referring to an external Dockerfile. Since {plugin} includes https://github.com/jkubeio/docker-maven-plugin[docker-maven-plugin] the way by which images are built is identical. 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 `pom.xml`. 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. @@ -54,7 +54,7 @@ The following sub-elements are supported: Beside specifying generator configuration in the plugin's configuration it can be set directly with properties, too: .Example generator property config -[source, sh] +[source, sh, subs="+attributes"] ---- mvn -Djkube.generator.spring-boot.alias="myapp" ---- @@ -67,17 +67,17 @@ In addition to the provided default _Generators_ described in the next section < You can declare the generator holding jars as dependency to this plugin as shown in this example -[source, xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- - kubernetes-maven-plugin + {plugin} .... io.acme mygenerator 1.0 - + ---- diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/generator/_spring_boot.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/generator/_spring_boot.adoc index 691ca2869b..402df77dae 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/generator/_spring_boot.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/generator/_spring_boot.adoc @@ -20,12 +20,12 @@ Beside the <> and the <>* +| *<>* | Build images -| *<>* +| *<>* | Push images to a registry -| *<>* +| *<>* | Create Kubernetes or OpenShift resource descriptors -| *<>* +| *<>* | Apply resources to a running cluster |=== @@ -33,19 +33,19 @@ This plugin supports a rich set for providing a smooth Java developer experience |=== | Goal | Description -| *<>* -| Deploy resources descriptors to a cluster after creating them and building the app. Same as <> except that it runs in the backgorund. +| *<>* +| Deploy resources descriptors to a cluster after creating them and building the app. Same as <> except that it runs in the background. -| *<>* +| *<>* | Undeploy and remove resources descriptors from a cluster. -| *<>* +| *<>* | Watch for file changes and perform rebuilds and redeployments -| *<>* +| *<>* | Show the logs of the running application -| *<>* +| *<>* | Enable remote debugging |=== @@ -57,12 +57,12 @@ Depending on whether the OpenShift or Kubernetes operational mode is used, the w | Use Case | Kubernetes | OpenShift | Build -a| `k8s:build` `k8s:push` +a| `{goal-prefix}:build` `{goal-prefix}:push` * Creates an image against an exposed Docker daemon (with a `docker.tar`) * Pushes the image to a registry which is then referenced from the configuration -a| `k8s:build` +a| `{goal-prefix}:build` * Creates or uses a `BuildConfig` * Creates or uses an `ImageStream` which can be referenced by the deployment descriptors in a `DeploymenConfig` @@ -70,11 +70,11 @@ a| `k8s:build` | Deploy -a| `k8s:deploy` +a| `{goal-prefix}:deploy` * Applies a Kubernetes resource descriptor to cluster -a| `k8s:deploy` +a| `{goal-prefix}:deploy` * Applies an OpenShift resource descriptor to a cluster diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-apply.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-apply.adoc index 7cbf952275..f75f0137c4 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-apply.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-apply.adoc @@ -1,12 +1,12 @@ -[[k8s:apply]] -== *k8s:apply* +[[jkube:apply]] +== *{goal-prefix}:apply* -This goal applies the resources created with <> to a connected Kubernetes cluster. It's similar to <> but does not the full deployment cycle of creating the resource, creating the application image and sending the resource descriptors to the clusters. This goal can be easily bound to `` within the plugin's configuration and binds by default to the `install` lifecycle phase. +This goal applies the resources created with <> to a connected Kubernetes cluster. It's similar to <> but does not the full deployment cycle of creating the resource, creating the application image and sending the resource descriptors to the clusters. This goal can be easily bound to `` within the plugin's configuration and binds by default to the `install` lifecycle phase. -[source,sh,subs="attributes"] +[source, sh, subs="+attributes"] ---- -mvn k8s:apply +mvn {goal-prefix}:apply ---- [[Supported-Properties-Apply]] @@ -25,9 +25,17 @@ mvn k8s:apply | Should we update resources by deleting them first and then creating them again, by default `false` | `jkube.recreate` +ifeval::["{goal-prefix}" == "k8s"] | *kubernetesManifest* -| The generated kubernetes YAML file, defaults to `${basedir}/target/classes/META-INF/jkube/kubernetes.yml` +| The generated kubernetes YAML file. Defaults to `${basedir}/target/classes/META-INF/jkube/kubernetes.yml` | `jkube.kubernetesManifest` +endif::[] + +ifeval::["{goal-prefix}" == "oc"] +| *openshiftManifest* +| The generated kubernetes YAML file. Defaults to `${basedir}/target/classes/META-INF/jkube/openshift.yml` +| `jkube.openshiftManifest` +endif::[] | *create* | Should we create new resources, defaults to `true` @@ -84,6 +92,5 @@ mvn k8s:apply | *skipApply* | Skip applying the resources, defaults to `false` | `jkube.skip.apply` -|=== -[[Supported-Properties]] +|=== diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-build.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-build.adoc index b805139441..4576928739 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-build.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-build.adoc @@ -1,6 +1,6 @@ -[[k8s:build]] -== *k8s:build* +[[jkube:build]] +== *{goal-prefix}:build* This goal is for building Docker images. Images can be built in two different ways depending on the `mode` configuration (controlled by the `jkube.mode` property). By default the mode is set to `auto`. In this case the plugin tries to detect which kind of build should be performed by contacting the API server. If this fails or if no cluster access is configured e.g. with `oc login` then the mode is set to `kubernetes` in which case a standard Docker build is performed. It can also be forced to `openshift` to perform an OpenShift build. @@ -10,7 +10,7 @@ By default the mode is set to `auto`. In this case the plugin tries to detect wh If the mode is set to `kubernetes` then a normal Docker build is performed. The connection configuration to access the Docker daemon is described in <>. -In order to make the generated images available to the Kubernetes cluster the generated images need to be pushed to a registry with the goal <>. This is not necessary for single node clusters, though as there is no need to distribute images. +In order to make the generated images available to the Kubernetes cluster the generated images need to be pushed to a registry with the goal <>. This is not necessary for single node clusters, though as there is no need to distribute images. [[build-openshift]] === OpenShift Build @@ -33,9 +33,9 @@ There are two kind of binary builds supported by this plugin, which can be selec Both build strategies update an https://docs.openshift.com/enterprise/latest/architecture/core_concepts/builds_and_image_streams.html#image-streams[Image Stream] after the image creation. -The https://docs.openshift.com/enterprise/latest/dev_guide/builds.html#defining-a-buildconfig[Build Config] and https://docs.openshift.com/enterprise/latest/architecture/core_concepts/builds_and_image_streams.html#image-streams[Image streams] can be managed by this plugin. If they do not exist, they will be automatically created by `k8s:build`. If they do already exist, they are reused, except when the `buildRecreate` configuration option (property `jkube.build.recreate`) is set to a value as described in <>. Also if the provided build strategy is different than the one defined in the existing build configuration, the Build Config is edited to reflect the new type (which in turn removes all build associated with the previous build). +The https://docs.openshift.com/enterprise/latest/dev_guide/builds.html#defining-a-buildconfig[Build Config] and https://docs.openshift.com/enterprise/latest/architecture/core_concepts/builds_and_image_streams.html#image-streams[Image streams] can be managed by this plugin. If they do not exist, they will be automatically created by `{goal-prefix}:build`. If they do already exist, they are reused, except when the `buildRecreate` configuration option (property `jkube.build.recreate`) is set to a value as described in <>. Also if the provided build strategy is different than the one defined in the existing build configuration, the Build Config is edited to reflect the new type (which in turn removes all build associated with the previous build). -This image stream created can then be directly referenced from https://docs.openshift.com/enterprise/latest/architecture/core_concepts/deployments.html#deployments-and-deployment-configurations[Deployment Configuration] objects created by <>. +This image stream created can then be directly referenced from https://docs.openshift.com/enterprise/latest/architecture/core_concepts/deployments.html#deployments-and-deployment-configurations[Deployment Configuration] objects created by <>. By default, image streams are created with a local lookup policy, so that they can be used also by other resources such as Deployments or StatefulSets. This behavior can be turned off by setting the `jkube.s2i.imageStreamLookupPolicyLocal` property to `false` when building the project. @@ -162,7 +162,7 @@ a| The build mode which can be | | *outputDirectory* -| Default output directory to be used by this plugin. The default value is `target/docker` and is only used for the goal `{plugin}:build`. +| Default output directory to be used by this plugin. The default value is `target/docker` and is only used for the goal `{goal-prefix}:build`. | `docker.target.dir` | *portPropertyFile* @@ -188,7 +188,7 @@ a| The build mode which can be | `jkube.resourceDir` | *environment* -| Environment name where resources are placed. For example, if you set this property to dev and resourceDir is the default one, JKube will look at src/main/jkube/dev. If not set then root `resourceDir` directory is used. +| Environment name where resources are placed. For example, if you set this property to dev and resourceDir is the default one, JKube will look at src/main/jkube/dev. If not set then root `resourceDir` directory is used. | `jkube.environment` | *skip* @@ -196,7 +196,7 @@ a| The build mode which can be | `docker.skip` | *skipBuild* -| If set not images will be build (which implies also _skip.tag_) with `{plugin}:build` +| If set not images will be build (which implies also _skip.tag_) with `{goal-prefix}:build` | `docker.skip.build` | *skipBuildPom* @@ -204,7 +204,7 @@ a| The build mode which can be | `jkube.skip.build.pom` | *skipTag* -| If set to `true` this plugin won't add any tags to images that have been built with `{plugin}:build` +| If set to `true` this plugin won't add any tags to images that have been built with `{goal-prefix}:build` | `docker.skip.tag` | *skipMachine* @@ -212,7 +212,7 @@ a| The build mode which can be | `docker.skip.machine` | *sourceDirectory* -| Default directory that contains the assembly descriptor(s) used by the plugin. The default value is `src/main/docker`. This option is only relevant for the `{plugin}:build` goal. +| Default directory that contains the assembly descriptor(s) used by the plugin. The default value is `src/main/docker`. This option is only relevant for the `{goal-prefix}:build` goal. | `docker.source.dir` | *verbose* @@ -224,7 +224,7 @@ a| The build mode which can be You can configure parameters to define how plugin is going to connect to Kubernetes cluster instead of relying on default parameters. -[source, xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- @@ -320,7 +320,7 @@ include::../../image/_configuration.adoc[] The `` section is mandatory and is explained in <>. .Example for -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- .... diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-helm.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-helm.adoc index 5693301c81..093a6d4916 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-helm.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-helm.adoc @@ -1,26 +1,26 @@ -[[k8s:helm]] -== *k8s:helm* +[[jkube:helm]] +== *{goal-prefix}:helm* This goal is for creating https://helm.sh/docs/topics/charts[Helm charts] for your Maven project so that you can install, update or delete your app in Kubernetes using https://github.com/helm/helm[Helm]. -For creating a Helm chart you simply call `k8s:helm` goal on the command line: +For creating a Helm chart you simply call `{goal-prefix}:helm` goal on the command line: -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn k8s:resource k8s:helm +mvn {goal-prefix}:resource {goal-prefix}:helm ---- -The `k8s:resource` goal is required to create the resource descriptors which are included in the Helm chart. +The `{goal-prefix}:resource` goal is required to create the resource descriptors which are included in the Helm chart. If you have already built the resource then you can omit this goal. The configuration is defined in a `` section within the plugin's configuration: .Example Helm configuration -[source, xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- @@ -90,8 +90,8 @@ This configuration section knows the following sub-elements in order to configur | `jkube.helm.type` | *sourceDir* -| Where to find the resource descriptors generated with `k8s:resource`. - By default this is `${basedir}/target/classes/META-INF/jkube., which is also the output directory used by `k8s:resource`. +| Where to find the resource descriptors generated with `{goal-prefix}:resource`. + By default this is `${basedir}/target/classes/META-INF/jkube., which is also the output directory used by `{goal-prefix}:resource`. | `jkube.helm.sourceDir` | *outputDir* @@ -112,7 +112,7 @@ This configuration section knows the following sub-elements in order to configur In a next step you can install this via the https://github.com/helm/helm/releases[helm command line tool] as follows: -[source, sh] +[source, sh, subs="+attributes"] ---- helm install nameForChartInRepository target/jkube/helm/${chartName}/kubernetes ---- @@ -122,14 +122,14 @@ helm install target/jkube/helm/${chartName}/kubernetes --generate-name ---- To add the `helm` goal to your project so that it is automatically executed just add the `helm` goal to the `executions` -section of the `kubernetes-maven-plugin` section of your `pom.xml`. +section of the `{plugin}` section of your `pom.xml`. .Add helm goal -[source, xml, indent=0] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-push.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-push.adoc index 6f8d469f60..2767d16737 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-push.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-push.adoc @@ -1,5 +1,5 @@ -[[k8s:push]] -== *k8s:push* +[[jkube:push]] +== *{goal-prefix}:push* WARNING: Section needs review and rearrangements 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 d28b3a4bac..d538aa3393 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,9 +1,14 @@ -[[k8s:resource]] -== *k8s:resource* - -This goal generates kubernetes 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`. Generated -resources are in `target/classes/META-INF/jkube/kubernetes` directory. +[[jkube:resource]] +== *{goal-prefix}:resource* + +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`. +ifeval::["{goal-prefix}" == "k8s"] +Generated resources are in `target/classes/META-INF/jkube/kubernetes` directory. +endif::[] +ifeval::["{goal-prefix}" == "oc"] +Generated resources are in `target/classes/META-INF/jkube/openshift` directory. +endif::[] [[resource-labels-annotations]] === Labels and Annotations @@ -62,7 +67,7 @@ Labels and annotations can be easily added to any resource object. This is best <3> `` labels are used to label services <4> `` labels are for replica set and replication controller <5> `` holds labels for pod specifications in replication controller, replica sets and deployments -<6> `` is for labels on deployments (kubernetes) +<6> `` is for labels on deployments (kubernetes) and deployment configs (openshift) <7> The subelements are also available for specifying annotations. <8> `` you can set location of fragments as `URL`. @@ -77,9 +82,15 @@ The following subelements are possible for `` and `` : | *all* | All entries specified in the `` sections are applied to all resource objects created. +ifeval::["{goal-prefix}" == "oc"] + This also implies build object like image stream and build configs which are created implicitly for an <>. +endif::[] | *deployment* -| Labels and annotations applied to `Deployment` (for Kubernetes) +| Labels and annotations applied to `Deployment` (for Kubernetes). +ifeval::["{goal-prefix}" == "oc"] + And `DeploymentConfig` (for OpenShift) objects. +endif::[] | *pod* @@ -133,7 +144,10 @@ This is best explained by an example. docker.io -... +---- + +[source,xml] +---- @@ -183,7 +197,28 @@ Resource goal also validates the generated resource descriptors using API specif | *jkube.failOnValidationError* | If value is set to `true` then any validation error will block the plugin execution. A warning will be printed otherwise. | `false` + +|=== + +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`. + +.Route Generation Configuration +[cols="1.6.1"] |=== +| Configuration | Description | Default + +| *jkube.openshift.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`. +| `true` +|=== +endif::[] 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. @@ -193,7 +228,7 @@ If you do not want to generate a Route descriptor, you can also specify so in th ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} {version} false @@ -226,6 +261,28 @@ In case both the label and the property have been set with conflicting values, p |=== | Element | Description | Property(System property or maven property) +ifeval::["{goal-prefix}" == "oc"] +| *enableAutomaticTrigger* +| If the value is set to `false` then automatic deployments would be disabled. Defaults to `true` +| `jkube.openshift.enableAutomaticTrigger` + +| *deployTimeoutSeconds* +| The OpenShift deploy timeout in seconds. Defaults to `3600` +| `jkube.openshift.deployTimeoutSeconds` + +| *imageChangeTrigger* +| Add ImageChange triggers to DeploymentConfigs when on openshift. Defaults to `true` +| `jkube.openshift.imageChangeTrigger` + +| *trimImageInContainerSpec* +| If set to true it would set the container image reference to "", this is done to handle weird behavior of Openshift 3.7 in which subsequent rollouts lead to ImagePullErr. Defaults to `false` +| `jkube.openshift.trimImageInContainerSpec` + +| *enrichAllWithImageChangeTrigger* +| Adds ImageChangeTriggers with respect to all containers specified inside DeploymentConfig. Defaults to `false` +| `jkube.openshift.enrichAllWithImageChangeTrigger` +endif::[] + | *profile* | Profile to use. A profile contains the enrichers and generators to use as well as their configuration. Profiles are looked up in the classpath and can be provided as yaml files. Defaults to `default` | `jkube.profile` @@ -269,6 +326,5 @@ In case both the label and the property have been set with conflicting values, p | *skipResource* | Skip resource generation. Defaults to `false` | `jkube.skip.resource` -|=== -[[Other-flags]] +|=== diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-debug.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-debug.adoc index 5c4834bb7c..3d73e41584 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-debug.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-debug.adoc @@ -1,21 +1,21 @@ -[[k8s:debug]] -== *k8s:debug* +[[jkube:debug]] +== *{goal-prefix}:debug* This goal enables debugging in your Java app and then port forwards from localhost to the latest running pod of your app so that you can easily debug your app from your Java IDE. -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn k8s:debug +mvn {goal-prefix}:debug ---- Then follow the on screen instructions. The default debug port is `5005`. If you wish to change the local port to use for debugging then pass in the `jkube.debug.port` parameter: -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn k8s:debug -Djkube.debug.port=8000 +mvn {goal-prefix}:debug -Djkube.debug.port=8000 ---- Then in your IDE you start a Remote debug execution using this remote port using localhost and you should be able to set breakpoints and step through your code. @@ -26,20 +26,20 @@ Debug is enabled via the `JAVA_ENABLE_DEBUG` environment variable being set to ` ### Speeding up debugging -By default the `k8s:debug` goal has to edit your Deployment to enable debugging then wait for a pod to start. It might be in development you frequently want to debug things and want to speed things up a bit. +By default the `{goal-prefix}:debug` goal has to edit your Deployment to enable debugging then wait for a pod to start. It might be in development you frequently want to debug things and want to speed things up a bit. If so you can enable debug mode for each build via the `jkube.debug.enabled` property. e.g. you can pass this property on the command line: -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn k8s:deploy -Djkube.debug.enabled=true +mvn {goal-prefix}:deploy -Djkube.debug.enabled=true ---- Or you can add something like this to your `~/.m2/settings.xml` file so that you enable debug mode for all maven builds on your laptop by using a profile : -[source, xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- @@ -53,23 +53,25 @@ Or you can add something like this to your `~/.m2/settings.xml` file so that you true + + ---- -Then whenever you type the `k8s:debug` goal there is no need for the maven goal to edit the `Deployment` and wait for a pod to restart; we can immediately start debugging when you type: +Then whenever you type the `{goal-prefix}:debug` goal there is no need for the maven goal to edit the `Deployment` and wait for a pod to restart; we can immediately start debugging when you type: -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn k8s:debug +mvn {goal-prefix}:debug ---- -### Debugging with suspension +=== Debugging with suspension -The `k8s:debug` goal allows to attach a remote debugger to a running container, but the application is free to execute when the debugger is not attached. +The `{goal-prefix}:debug` goal allows to attach a remote debugger to a running container, but the application is free to execute when the debugger is not attached. In some cases, you may want to have complete control on the execution, e.g. to investigate the application behavior at startup. This can be done using the `jkube.debug.suspend` flag: -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn k8s:debug -Djkube.debug.suspend +mvn {goal-prefix}:debug -Djkube.debug.suspend ---- The suspend flag will set the `JAVA_DEBUG_SUSPEND` environment variable to `true` and `JAVA_DEBUG_SESSION` to a random number in your deployment. @@ -96,6 +98,3 @@ WARNING: The `jkube.debug.suspend` flag will disable readiness probes in the Kub | Disables readiness probes in Kubernetes Deployment in order to start port forwarding during early phases of application startup. Defaults to `false` | `jkube.debug.suspend` |=== - -[[Supported-Properties]] - diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-deploy.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-deploy.adoc index 9bcaade7ee..435596c27e 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-deploy.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-deploy.adoc @@ -1,24 +1,24 @@ -[[k8s:deploy]] -== *k8s:deploy* +[[jkube:deploy]] +== *{goal-prefix}:deploy* This is the main goal for building your docker image, generating the kubernetes resources and deploying them into the cluster (insofar your pom.xml is set up correct; keep reading :)). -[source,sh,subs="attributes"] +[source, sh, subs="+attributes"] ---- -mvn k8s:deploy +mvn {goal-prefix}:deploy ---- -This goal is designed to run <> and <> before the deploy **iff* you have the goals bound in your pom.xml: +This goal is designed to run <> and <> before the deploy *if* you have the goals bound in your pom.xml: [source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} {version} - + jkube @@ -35,8 +35,8 @@ This goal is designed to run <> and <> before the deplo Effectively this builds your project then invokes these goals: -* <> -* <> +* <> +* <> By default the behaviour of resource goal is it generates `route.yml` for a service if you have not done any configuration changes. Sometimes there may be case when you want to generate route.yml but do not want to create route resource on OpenShift Cluster. This can be achieved by the following configuration. @@ -46,7 +46,7 @@ By default the behaviour of resource goal is it generates `route.yml` for a serv ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} {version} diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-log.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-log.adoc index cf3e601373..4b2c22453d 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-log.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-log.adoc @@ -1,42 +1,42 @@ -[[k8s:log]] -== *k8s:log* +[[jkube:log]] +== *{goal-prefix}:log* -This goal tails the log of the app that you deployed via the <> goal +This goal tails the log of the app that you deployed via the <> goal -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn k8s:log +mvn {goal-prefix}:log ---- You can then terminate the output by hitting `Ctrl+C` If you wish to get the log of the app and then terminate immediately then try: -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn k8s:log -Djkube.log.follow=false +mvn {goal-prefix}:log -Djkube.log.follow=false ---- This lets you pipe the output into grep or some other tool -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn k8s:log -Djkube.log.follow=false | grep Exception +mvn {goal-prefix}:log -Djkube.log.follow=false | grep Exception ---- If your app is running in multiple pods you can configure the pod name to log via the `jkube.log.pod` property, otherwise it defaults to the latest pod: -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn k8s:log -Djkube.log.pod=foo +mvn {goal-prefix}:log -Djkube.log.pod=foo ---- If your pod has multiple containers you can configure the container name to log via the `jkube.log.container` property, otherwise it defaults to the first container: -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn k8s:log -Djkube.log.container=foo +mvn {goal-prefix}:log -Djkube.log.container=foo ---- [[Supported-Properties-Log]] diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-undeploy.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-undeploy.adoc index cb33a45d76..fce331bc90 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-undeploy.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-undeploy.adoc @@ -1,13 +1,13 @@ -[[k8s:undeploy]] -== *k8s:undeploy* +[[jkube:undeploy]] +== *{goal-prefix}:undeploy* -This goal is for deleting the kubernetes resources that you deployed via the <> or <> goals +This goal is for deleting the kubernetes resources that you deployed via the <> or <> goals -It iterates through all the resources generated by the <> goal and deletes them from your current kubernetes cluster. +It iterates through all the resources generated by the <> goal and deletes them from your current kubernetes cluster. -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn k8s:undeploy +mvn {goal-prefix}:undeploy ---- diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-watch.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-watch.adoc index 858fcf1ef8..bd492b556f 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-watch.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-watch.adoc @@ -1,11 +1,11 @@ -[[k8s:watch]] -== *k8s:watch* +[[jkube:watch]] +== *{goal-prefix}:watch* This goal is used to monitor the project workspace for changes and automatically trigger a redeploy of the application running on Kubernetes. -In order to use k8s:watch for spring-boot, you need to make sure that `devtools` is included in the repacked +In order to use {goal-prefix}:watch for spring-boot, you need to make sure that `devtools` is included in the repacked archive, as shown in the following listing: ---- @@ -28,12 +28,12 @@ Before entering the watch mode, this goal must generate the docker image and the and deploy the app on Kubernetes. Lifecycle bindings should be configured as follows to allow the generation of such resources. -.Lifecycle bindings for k8s:watch -[source, xml, indent=0] +.Lifecycle bindings for {goal-prefix}:watch +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- org.eclipse.jkube - kubernetes-maven-plugin + {plugin} @@ -51,9 +51,9 @@ the generation of such resources. For any application having `resource` and `build` goals bound to the lifecycle, the following command can be used to run the watch task. -[source, bash] +[source, bash, subs="+attributes"] ---- -mvn k8s:watch +mvn {goal-prefix}:watch ---- This plugin supports different watcher providers, enabled automatically if the project satisfies certain conditions. @@ -71,21 +71,21 @@ This watcher is enabled by default for all Spring Boot projects. It performs the You can try it on any spring boot application via: -[source, sh] +[source, sh, subs="+attributes"] ---- -mvn k8s:watch +mvn {goal-prefix}:watch ---- Once the goal starts up the spring boot RemoteSpringApplication it will watch for local development changes. e.g. if you edit the java code of your app and then build it via something like this: -[source, sh] +[source, sh, subs="+attributes"] ---- mvn package ---- -You should see your app reload on the fly in the shell running the <> goal! +You should see your app reload on the fly in the shell running the <> goal! There is also support for LiveReload as well. @@ -98,7 +98,7 @@ This is a generic watcher that can be used in Kubernetes mode only. Once activat The watcher can be activated e.g. by running this command in another shell: -[source, sh] +[source, sh, subs="+attributes"] ---- mvn package ---- diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_configuration.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_configuration.adoc index b70db0efaf..42a2b38418 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_configuration.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_configuration.adoc @@ -18,12 +18,12 @@ linking images together or for specifying it with the global *image* configurati | Registry to use for this image. If the `name` already contains a registry this takes precedence. See <> for more details. | <> -| Element which contains all the configuration aspects when doing a <<{plugin}:build>>. This element can be omitted if the image is only pulled from a registry e.g. as support for integration tests like database images. +| Element which contains all the configuration aspects when doing a <>. This element can be omitted if the image is only pulled from a registry e.g. as support for integration tests like database images. -ifeval::["{plugin}" == "docker"] +ifeval::["{goal-prefix}" == "k8s"] | <> | Element which describe how containers should be -created and run when <<{plugin}:start>> is called. If this image is only used a _data container_ (i.e. is supposed only to be mounted as a volume) for exporting artifacts via volumes this section can be missing. +created and run when <> is called. If this image is only used a _data container_ (i.e. is supposed only to be mounted as a volume) for exporting artifacts via volumes this section can be missing. | <> | Specification of external configuration as an alternative to this XML based configuration with `` and ``. It contains a `` element specifying the handler for getting the configuration. See <> for details. diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_example.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_example.adoc index 2e11299cc3..2567617ed3 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_example.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_example.adoc @@ -1,9 +1,9 @@ .Example -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- - .... + %g/docker-demo:0.1 diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_naming.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_naming.adoc index bd08f2b55c..913e6fc83a 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_naming.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_naming.adoc @@ -1,5 +1,5 @@ [[image-name]] -## Image Names +== Image Names When specifying the image name in the configuration with the `` field you can use several placeholders which are replaced during runtime by this plugin. In addition you can use regular Maven properties which are resolved by Maven itself. [cols="1,5"] @@ -22,9 +22,9 @@ When specifying the image name in the configuration with the `` field you | If the project version ends with `-SNAPSHOT` this placeholder resolves to `snapshot-` where timestamp has the date format `yyMMdd-HHmmss-SSSS` (eg `snapshot-`). This feature is especially useful during development in oder to avoid conflicts when images are to be updated which are still in use. You need to take care yourself of cleaning up old images afterwards, though. |=== -ifeval::["{plugin}" == "docker"] +ifeval::["{goal-prefix}" == "k8s"] [[container-name]] -## Container Names +== Container Names Similar to image name placeholders, for starting and stopping containers and alternate set of placeholders can be configured in order to the name the containers to create. @@ -55,6 +55,7 @@ When specifying the container name pattern the following placeholders can be use You can combine the placeholders in any combination and will be resolved during `docker:start`, `docker:stop` and `docker:watch`. The following example is using a container name pattern of `%n-%i` which is also the default. +Given an image `fabric8io/dmp-sample-jolokia:latest`, then during `mvn docker:start` a container with the name `dmp-sample-jolokia-1` is first tried. If there is already a container with this name, then `dmp-sample-jolokia-2` is the second attempt. This goes on until a "free" name is found. diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_env.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_env.adoc index ae12088467..2aeedb95c8 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_env.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_env.adoc @@ -3,7 +3,7 @@ When creating a container one or more environment variables can be set via configuration with the `env` parameter .Example -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- /opt/jdk8 @@ -18,7 +18,7 @@ It is also possible to set the environment variables from the outside of the plu Labels can be set inline the same way as environment variables: .Example -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- foo diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_startup.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_startup.adoc index 6d05398933..b55f80df94 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_startup.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_startup.adoc @@ -27,7 +27,7 @@ An entry point or command can be specified in two alternative formats: Either shell or params should be specified. .Example -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- @@ -38,7 +38,7 @@ Either shell or params should be specified. or .Example -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- @@ -53,7 +53,7 @@ or This can be formulated also more dense with: .Example -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- java -jar $HOME/server.jar @@ -62,7 +62,7 @@ This can be formulated also more dense with: or .Example -[source,xml] +[source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/index.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/index.adoc index 66a2f378af..031585232f 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/index.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/index.adoc @@ -1,13 +1,15 @@ -= org.eclipse.jkube/kubernetes-maven-plugin += org.eclipse.jkube/{plugin} Roland Huß, James Strachan; +:plugin: kubernetes-maven-plugin +:goal-prefix: k8s +:cluster: Kubernetes :revnumber: {version} :revdate: {localdate} :toc: macro :toclevels: 3 -:toc-title: kubernetes-maven-plugin +:toc-title: {plugin} :doctype: book :icons: font -:plugin: jkube :plugindir: ../../../../../plugin ifndef::ebook-format[:leveloffset: 1] @@ -41,4 +43,3 @@ include::inc/_faq.adoc[] include::inc/_appendix.adoc[] -// include::classpath:/META-INF/doc/dmp/inc/_docker-build.adoc[] diff --git a/kubernetes-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/build/AbstractDockerMojo.java b/kubernetes-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/build/AbstractDockerMojo.java index bcbae58cac..aa2a58e7ce 100644 --- a/kubernetes-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/build/AbstractDockerMojo.java +++ b/kubernetes-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/build/AbstractDockerMojo.java @@ -273,13 +273,6 @@ public abstract class AbstractDockerMojo extends AbstractMojo @Parameter(property = "jkube.skip", defaultValue = "false") protected boolean skip; - /** - * Whether to perform a Kubernetes build (i.e. against a vanilla Docker daemon) or - * an OpenShift build (with a Docker build against the OpenShift API server. - */ - @Parameter(property = "jkube.mode") - protected RuntimeMode mode = RuntimeMode.DEFAULT; - @Parameter(property = "jkube.skip.build.pom") protected Boolean skipBuildPom; @@ -290,13 +283,6 @@ public abstract class AbstractDockerMojo extends AbstractMojo @Parameter protected ProcessorConfig generator; - /** - * Allow the ImageStream used in the S2I binary build to be used in standard - * Kubernetes resources such as Deployment or StatefulSet. - */ - @Parameter(property = "jkube.s2i.imageStreamLookupPolicyLocal", defaultValue = "true") - protected boolean s2iImageStreamLookupPolicyLocal = true; - /** * While creating a BuildConfig, By default, if the builder image specified in the * build configuration is available locally on the node, that image will be used. @@ -402,12 +388,16 @@ public KitLogger getKitLogger() { return log; } + public RuntimeMode getConfiguredRuntimeMode() { + return RuntimeMode.kubernetes; + } + protected void init() { log = new AnsiLogger(getLog(), useColorForLogging(), verbose, !settings.getInteractiveMode(), getLogPrefix()); authConfigFactory = new AuthConfigFactory(log); imageConfigResolver.setLog(log); clusterAccess = new ClusterAccess(initClusterConfiguration()); - runtimeMode = clusterAccess.resolveRuntimeMode(mode, log); + runtimeMode = clusterAccess.resolveRuntimeMode(getConfiguredRuntimeMode(), log); } protected boolean canExecute() { @@ -432,7 +422,7 @@ public final void execute() throws MojoExecutionException, MojoFailureException .log(log) .configuration(initJKubeConfiguration()) .clusterAccess(clusterAccess) - .platformMode(mode) + .platformMode(getConfiguredRuntimeMode()) .dockerServiceHub(serviceHubFactory.createServiceHub(access, log, logSpecFactory)) .buildServiceConfig(buildServiceConfigBuilder().build()) .build(); @@ -691,7 +681,6 @@ private void buildAndTag(ImageConfiguration imageConfig) protected BuildServiceConfig.BuildServiceConfigBuilder buildServiceConfigBuilder() { return BuildServiceConfig.builder() .buildRecreateMode(BuildRecreateMode.fromParameter(buildRecreate)) - .s2iImageStreamLookupPolicyLocal(s2iImageStreamLookupPolicyLocal) .forcePull(forcePull) .imagePullManager(getImagePullManager(imagePullPolicy, autoPull)) .buildDirectory(project.getBuild().getDirectory()) diff --git a/kubernetes-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/WatchMojo.java b/kubernetes-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/WatchMojo.java index 4d41146f78..afde6f4896 100644 --- a/kubernetes-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/WatchMojo.java +++ b/kubernetes-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/WatchMojo.java @@ -117,7 +117,7 @@ private WatcherContext getWatcherContext() throws MojoExecutionException { .logger(log) .newPodLogger(createLogger("[[C]][NEW][[C]] ")) .oldPodLogger(createLogger("[[R]][OLD][[R]] ")) - .mode(mode) + .mode(getConfiguredRuntimeMode()) .project(MavenUtil.convertMavenProjectToJKubeProject(project, session)) .useProjectClasspath(useProjectClasspath) .clusterConfiguration(initClusterConfiguration()) @@ -137,7 +137,7 @@ protected GeneratorContext.GeneratorContextBuilder generatorContextBuilder() thr .config(extractGeneratorConfig()) .project(MavenUtil.convertMavenProjectToJKubeProject(project, session)) .logger(log) - .runtimeMode(mode) + .runtimeMode(getConfiguredRuntimeMode()) .useProjectClasspath(useProjectClasspath) .artifactResolver(jkubeServiceHub.getArtifactResolverService()) .generatorMode(GeneratorMode.WATCH); diff --git a/openshift-maven-plugin/doc/ci-docs.sh b/openshift-maven-plugin/doc/ci-docs.sh deleted file mode 100755 index 3e134e2041..0000000000 --- a/openshift-maven-plugin/doc/ci-docs.sh +++ /dev/null @@ -1,34 +0,0 @@ -# -# Copyright (c) 2019 Red Hat, Inc. -# This program and the accompanying materials are made -# available under the terms of the Eclipse Public License 2.0 -# which is available at: -# -# https://www.eclipse.org/legal/epl-2.0/ -# -# SPDX-License-Identifier: EPL-2.0 -# -# Contributors: -# Red Hat, Inc. - initial API and implementation -# - -set -e - -echo ============================================ -echo Deploying openshift-maven-plugin documentation -echo ============================================ - -export MAVEN_OPTS="-Xmx3000m" - -mvn -B install -DskipTests=true -cd doc -mvn -B -Phtml,pdf package -git clone -b gh-pages https://fabric8cd:$GH_TOKEN@github.com/jkubeio/openshift-maven-plugin gh-pages -cp -rv target/generated-docs/* gh-pages/ -cd gh-pages -mv index.pdf openshift-maven-plugin.pdf -git add --ignore-errors * -git commit -m "generated documentation" -git push origin gh-pages -cd .. -rm -rf gh-pages target diff --git a/openshift-maven-plugin/doc/pom.xml b/openshift-maven-plugin/doc/pom.xml deleted file mode 100644 index 091c2466f9..0000000000 --- a/openshift-maven-plugin/doc/pom.xml +++ /dev/null @@ -1,199 +0,0 @@ - - - - 4.0.0 - - org.eclipse.jkube - openshift-maven-plugin-parent - 1.0.0-SNAPSHOT - ../pom.xml - - - openshift-maven-plugin-doc - jar - - Openshift Maven Plugin :: Documentation - - - 1.6.0 - 2.1.0 - 1.5.0-alpha.18 - - - - - - - - org.asciidoctor - asciidoctorj - ${asciidoctorj.version} - - - - - - - - - - org.apache.maven.plugins - maven-enforcer-plugin - - - dependency-convergence - - enforce - - - - true - - - - - - maven-resources-plugin - ${version.maven-resources-plugin} - - - copy-asciidoc - process-resources - - copy-resources - - - ${project.build.outputDirectory}/META-INF/doc/fmp - - - src/main/asciidoc - false - - - - - - - - - - - - org.asciidoctor - asciidoctor-maven-plugin - ${asciidoctor-maven-plugin.version} - - src/main/asciidoc - - font - - ${project.version} - - - - true - - - - DEBUG - - - - - - org.eclipse.jkube - openshift-maven-plugin-doc - ${project.version} - - - - - - - - - - - html - - - - org.asciidoctor - asciidoctor-maven-plugin - - - output-html - package - - process-asciidoc - - - coderay - html - coderay - - left - false - - - - - - - - true - - - - - - pdf - - - - org.asciidoctor - asciidoctor-maven-plugin - - - output-pdf - package - - process-asciidoc - - - pdf - rouge - - - - - - - - - org.asciidoctor - asciidoctorj-pdf - ${asciidoctorj-pdf.version} - - - - - - - - - diff --git a/openshift-maven-plugin/doc/sample-demo.gif b/openshift-maven-plugin/doc/sample-demo.gif deleted file mode 100644 index 695cfde16b..0000000000 Binary files a/openshift-maven-plugin/doc/sample-demo.gif and /dev/null differ diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_access.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_access.adoc deleted file mode 100644 index 7f69cb24fc..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_access.adoc +++ /dev/null @@ -1,20 +0,0 @@ -[[access-configuration]] - -= Access configuration - -== Docker Access - -WARNING: This section is work-in-progress and not yet finished - -For kubernetes builds the openshift-maven-plugin uses the Docker remote API so the URL of your Docker Daemon must be specified. The URL can be specified by the dockerHost or machine configuration, or by the `DOCKER_HOST` environment variable. If not given - -The Docker remote API supports communication via SSL and -authentication with certificates. The path to the certificates can -be specified by the certPath or machine configuration, or by the -`DOCKER_CERT_PATH` environment variable. - - -== OpenShift and Kubernetes Access - -Plugin reads your `kubeconfig` file to read your Kubernetes/OpenShift configuration. By default, `kubeconfig` file is assumed to be either -in `~/.kube/config` or using the environment variable `KUBECONFIG`. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_appendix.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_appendix.adoc deleted file mode 100644 index 2afaa319b5..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_appendix.adoc +++ /dev/null @@ -1,33 +0,0 @@ -[[appendix]] -= Appendix - -== Kind/Filename Type Mapping - -[[appendix-kind-mapping]] -include::{plugindir}/src/main/resources/META-INF/jkube/kind-filename-type-mapping-default.adoc[] - -== Custom Kind/Filename Mapping - -You can add your custom `Kind/Filename` mappings. -To do it you have two approaches: - -* Setting an environment variable or system property called `jkube.mapping` pointing out to a `.properties` files with pairs `=>filename1>, ` -By default if no environment variable nor system property is set, scan for a file located at classpath `/META-INF/jkube.kind-filename-type-mapping-default.properties`. - -* By embedding in MOJO configuration the mapping: - -[source, xml] ----- - - org.eclipse.jkube - openshift-maven-plugin - - - - Var - foo, bar - - - - ----- \ No newline at end of file diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_authentication.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_authentication.adoc deleted file mode 100644 index cd092b02b3..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_authentication.adoc +++ /dev/null @@ -1,192 +0,0 @@ - -[[authentication]] -= Authentication - -When pulling (via the `autoPull` mode of `{plugin}:start`) or pushing image, it -might be necessary to authenticate against a Docker registry. - -There are five different locations searched for credentials. In order, these are: - -* Providing system properties `docker.username` and `docker.password` from the outside. -* Using a `` section in the plugin configuration with `` and `` elements. -* Using OpenShift configuration in `~/.config/kube` -* Using a `` configuration in `~/.m2/settings.xml` -* Login into a registry with `docker login` (credentials in a credential helper or in `~/.docker/config.json`) - -Using the username and password directly in the `pom.xml` is not -recommended since this is widely visible. This is the easiest and -transparent way, though. Using an `` is straight forward: - -[source,xml] ----- - - - consol/tomcat-7.0 - ... - - jolokia - s!cr!t - - - ----- - -The system property provided credentials are a good compromise when -using CI servers like Jenkins. You simply provide the credentials from -the outside: - -.Example -[source, sh, subs="+attributes"] ----- -mvn -Ddocker.username=jolokia -Ddocker.password=s!cr!t {plugin}:push ----- - -The most _mavenish_ way is to add a server to the Maven settings file `~/.m2/settings.xml`: - -.Example -[source,xml] ----- - - - docker.io - jolokia - s!cr!t - - .... - ----- - -The server id must specify the registry to push to/pull from, which by -default is central index `docker.io` (or `index.docker.io` / `registry.hub.docker.com` as fallbacks). -Here you should add your docker.io account for your repositories. If you have multiple accounts -for the same registry, the second user can be specified as part of the ID. In the example above, if you -have a second account 'jkubeio' then use an `docker.org.eclipse.jkubeio` for this second entry. I.e. add the -username with a slash to the id name. The default without username is only taken if no server entry with -a username appended id is chosen. - -The most _secure_ way is to rely on docker's credential store or credential helper and read confidential information -from an external credentials store, such as the native keychain of the operating system. Follow the instruction on -https://docs.docker.com/engine/reference/commandline/login/#credentials-store[the docker login documentation]. - -As a final fallback, this plugin consults `$DOCKER_CONFIG/config.json` if `DOCKER_CONFIG` is set, or `~/.docker/config.json` if not, and reads credentials stored directly within this -file. This unsafe behavior happened when connecting to a registry with the command `docker login` from the command line -with older versions of docker (pre 1.13.0) or when docker is not configured to use a -https://docs.docker.com/engine/reference/commandline/login/#credentials-store[credential store]. - -== Pull vs. Push Authentication - -The credentials lookup described above is valid for both push and -pull operations. In order to narrow things down, credentials can be -provided for pull or push operations alone: - -In an `` section a sub-section `` and/or `` -can be added. In the example below the credentials provider are only -used for image push operations: - -.Example -[source,xml] ----- - - - consol/tomcat-7.0 - ... - - - jolokia - s!cr!t - - - - ----- - -When the credentials are given on the command line as system -properties, then the properties `docker.pull.username` / -`docker.pull.password` and `docker.push.username` / -`docker.push.password` are used for pull and push operations, -respectively (when given). Either way, the standard lookup algorithm -as described in the previous section is used as fallback. - -== OpenShift Authentication - -When working with the default registry in OpenShift, the credentials -to authenticate are the OpenShift username and access token. So, a -typical interaction with the OpenShift registry from the outside is: - ----- -oc login -... -mvn -Ddocker.registry=docker-registry.domain.com:80/default/myimage \ - -Ddocker.username=$(oc whoami) \ - -Ddocker.password=$(oc whoami -t) ----- - -(note, that the image's username part ("default" here") must -correspond to an OpenShift project with the same name to which you -currently connected account has access). - -This can be simplified by using the system property -`docker.useOpenShiftAuth` in which case the plugin does the -lookup. The equivalent to the example above is - ----- -oc login -... -mvn -Ddocker.registry=docker-registry.domain.com:80/default/myimage \ - -Ddocker.useOpenShiftAuth ----- - -Alternatively the configuration option `` can be -added to the `` section. - -For dedicated _pull_ and _push_ configuration the system properties -`docker.pull.useOpenShiftAuth` and `docker.push.useOpenShiftAuth` are -available as well as the configuration option `` in -an `` or `` section within the `` -configuration. - -If `useOpenShiftAuth` is enabled then the OpenShift Konfiguration will be looked up in `$KUBECONFIG` or, if this environment variable is not set, in `~/.kube/config`. - -[[password-encryption]] -== Password encryption - -Regardless of which mode you choose you can encrypt password as described -in the -http://maven.apache.org/guides/mini/guide-encryption.html[Maven documentation]. Assuming -that you have setup a _master password_ in -`~/.m2/security-settings.xml` you can create easily encrypt -passwords: - -.Example -[source,bash] ----- -$ mvn --encrypt-password -Password: -{QJ6wvuEfacMHklqsmrtrn1/ClOLqLm8hB7yUL23KOKo=} ----- - -This password then can be used in `authConfig`, `docker.password` -and/or the `` setting configuration. However, putting an -encrypted password into `authConfig` in the `pom.xml` doesn't make -much sense, since this password is encrypted with an individual master -password. - -[[extended-authentication]] -== Extended Authentication - -Some docker registries require additional steps to authenticate. -link:https://docs.aws.amazon.com/AmazonECR/latest/userguide/ECR_GetStarted.html[Amazon ECR] requires using an IAM access key to obtain temporary docker login credentials. -The `docker:push` and `docker:pull` goals automatically execute this exchange for any registry of the form __ *.dkr.ecr.* __ *.amazonaws.com*, unless the `skipExtendedAuth` configuration (`docker.skip.extendedAuth` property) is set true. - -Note that for an ECR repository with URI `123456789012.dkr.ecr.eu-west-1.amazonaws.com/example/image` the d-m-p's `docker.registry` should be set to `123456789012.dkr.ecr.eu-west-1.amazonaws.com` and `example/image` is the `` of the image. - -You can use any IAM access key with the necessary permissions in any of the locations mentioned above except `~/.docker/config.json`. -Use the IAM *Access key ID* as the username and the *Secret access key* as the password. -In case you're using temporary security credentials provided by the AWS Security Token Service (AWS STS), you have to provide the *security token* as well. -To do so, either specify the `docker.authToken` system property or provide an `` element alongside username & password in the `authConfig`. - -In case you are running on an EC2 instance that has an appropriate IAM role assigned -(e.g. a role that grants the AWS built-in policy _AmazonEC2ContainerRegistryPowerUser_) -authentication information doesn't need to be provided at all. Instead the instance -meta-data service is queried for temporary access credentials supplied by the -assigned role. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_compatibility.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_compatibility.adoc deleted file mode 100644 index b313900ec4..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_compatibility.adoc +++ /dev/null @@ -1,23 +0,0 @@ - -[[compatibility-with-Openshift]] -= Compatibility with Openshift - -[[openshift-compatibility]] -== OpenShift Compatibility - -.OpenShift Compatibility -|=== -| OMP | OpenShift 4.2.0 | OpenShift 3.11.0 | OpenShift 3.10.0 | OpenShift 3.9.0 | OpenShift 3.7.0 | OpenShift 3.6.0 | OpenShift 3.5.0 | OpenShift 1.4.1 - -| OMP 1.0.0-alpha-2 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | x | x - -| OMP 1.0.0-alpha-1 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | x | x - -| OMP 0.2.0 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | x | x - -| OMP 0.1.1 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | x | x - -| OMP 0.1.0 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | x | x - -|=== - diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_enricher.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_enricher.adoc deleted file mode 100644 index 0103c1e253..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_enricher.adoc +++ /dev/null @@ -1,1105 +0,0 @@ - -[[enrichers]] -= Enrichers - -Enriching is the complementary concept to <>. Whereas Generators are used to create and customize Docker images, Enrichers are use to create and customize Kubernetes/OpenShift resource objects. - -There are a lot of similarities to Generators: - -* Each Enricher has a unique name. -* Enrichers are looked up automatically from the plugin dependencies and there is a set of default enrichers delivered with this plugin. -* Enrichers are configured the same ways as generators - -The <> is a good blueprint, simply replace `` with ``. The configuration is structural identical: - -.Enricher configuration -[cols="2,6"] -|=== -| Element | Description - -| `` -| Contains one ore more `` elements with enricher names which should be included. If given, only this list of enrichers are included in this order. The enrichers from every active profile are included, too. However the enrichers listed here are moved to the front of the list, so that they are called first. Use the profile `raw` if you want to explicitly set the complete list of enrichers. - -| `` -| Holds one or more `` elements with enricher names to exclude. This means all the detected enrichers are used except the ones mentioned in this section. - -| `` -| Configuration for all enrichers. Each enricher supports a specific set of configuration values as described in its documentation. The subelements of this section are enricher names. E.g. for enricher `jkube-service`, the sub-element is called ``. This element then holds the specific enricher configuration like `` for the service name. Configuration coming from profiles are merged into this config, but not overriding the configuration specified here. -|=== - -This plugin comes with a set of default enrichers. In addition custom enrichers can be easily added by providing implementation of the <> and adding these as a dependency to the build. - -[[enrichers-default]] -== Default Enrichers - -kubernetes-maven-plugin comes with a set of enrichers which are enabled by default. There are two categories of default enrichers: - -* *Generic Enrichers* are used to add default resource object when they are missing or add common metadata extracted from the given build information -* *Specific Enrichers* are enrichers which are focused on a certain tech stack that they detect. - -. Default Enrichers Overview -[cols="2,7"] -|=== -| Enricher | Description - -| <> -| Add Prometheus annotations. - -| <> -| Add Maven SCM information as annotations to the kubernetes/openshift resources - -| <> -| Create default controller (replication controller, replica set or deployment) if missing. - -| <> -| Examine build dependencies for `kubernetes.yml` and add the objects found therein. - -| <> -| Check local `.git` directory and add build information as annotations. - -| <> -| Add the image name into a `PodSpec` of replication controller, replication sets and deployments, if missing. - -| <> -| Add a default name to every object which misses a name. - -| <> -| Copy over annotations from a `Deployment` to a `Pod` - -| <> -| Add a default portname for commonly known service. - -| <> -| Add Maven coordinates as labels to all objects. - -| <> -| Create a default service if missing and extrac ports from the Docker image configuration. - -| <> -| Add Maven Issue Management information as annotations to the kubernetes/openshift resources - -| <> -| Add revision history limit (https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#revision-history-limit[Kubernetes doc]) as a deployment spec property to the Kubernetes/OpenShift resources. - -| <> -| Add ImageStreamTag change triggers on resources such as StatefulSets, ReplicaSets and DaemonSets using the `image.openshift.io/triggers` annotation. - -| <> -| Add ConfigMap elements defined as XML or as annotation. - -| <> -| Add Secret elements defined as annotation. - -| <> -| Add a ServiceAccount defined as XML or mentioned in resource fragement. -|=== - -[[enrichers-standard]] -=== Standard Enrichers - -Default enrichers are used for adding missing resources or adding metadata to given resource objects. The following default enhancers are available out of the box - -[[jkube-controller]] -==== jkube-controller - -include::enricher/_jkube_service.adoc[] - -[[jkube-image]] -==== jkube-image - -[[jkube-name]] -==== jkube-name - -[[jkube-portname]] -==== jkube-portname - -[[jkube-pod-annotation]] -==== jkube-pod-annotation - -[[jkube-project-label]] -==== jkube-project-label - -Enricher that adds standard labels and selectors to generated resources (e.g. `app`, `group`, `provider`, `version`). - -The `jkube-project-label` enricher supports the following configuration options: - -[cols="2,6,3"] -|=== -| Option | Description | Default - -| `useProjectLabel` -| Enable this flag to turn on the generation of the old `project` label in Kubernetes resources. The `project` label has been replaced by the `app` label in newer versions of the plugin. -| `false` -|=== - -The project labels which are already specified in the input fragments are not overridden by the enricher. - -[[jkube-git]] -==== jkube-git - -Enricher that adds info from .git directory as annotations. - -The git branch & latest commit on the branch are annotated as jkube.git-branch & jkube.git-commit. -fabrci8/git-url is annotated as the url of your configured remote. - -[cols="2,6,3"] -|=== -| Option | Description | Default - -| `gitRemote` -| Configures the git remote name, whose url you want to annotate as 'git-url'. -| `origin` -|=== - -[[jkube-dependency]] -==== jkube-dependency - -[[jkube-volume-permission]] -==== jkube-volume-permission - -Enricher which fixes the permission of persistent volume mount with the help of an init container. - -[[jkube-autotls]] -==== jkube-openshift-autotls - -Enricher which adds appropriate annotations and volumes to enable OpenShift's automatic https://docs.openshift.org/latest/dev_guide/secrets.html#service-serving-certificate-secrets[Service Serving Certificate Secrets]. -This enricher adds an init container to convert the service serving certificates from PEM (the format that OpenShift generates them in) to -a JKS-format Java keystore ready for consumption in Java services. - -This enricher is disabled by default. In order to use it, you must configure the Openshift Maven plugin to use this enricher: - -[source,xml] ----- - - org.eclipse.jkube - openshift-maven-plugin - {version} - - - - resource - - - - - - - jkube-openshift-autotls - - - - ... - - - - - ----- - -The auto-TLS enricher supports the following configuration options: - -[cols="2,6,3"] -|=== -| Option | Description | Default - -| `tlsSecretName` -| The name of the secret to be used to store the generated service serving certs. -| `-tls` - -| `tlsSecretVolumeMountPoint` -| Where the service serving secret should be mounted to in the pod. -| `/var/run/secrets/jkube.io/tls-pem` - -| `tlsSecretVolumeName` -| The name of the secret volume. -| `tls-pem` - -| `jksVolumeMountPoint` -| Where the generated keystore volume should be mounted to in the pod. -| `/var/run/secrets/jkube.io/tls-jks` - -| `jksVolumeName` -| The name of the keystore volume. -| `tls-jks` - -| `pemToJKSInitContainerImage` -| The name of the image used as an init container to convert PEM certificate/key to Java keystore. -| `jimmidyson/pemtokeystore:v0.1.0` - -| `pemToJKSInitContainerName` -| the name of the init container to convert PEM certificate/key to Java keystore. -| `tls-jks-converter` - -| `keystoreFileName` -| The name of the generated keystore file. -| `keystore.jks` - -| `keystorePassword` -| The password to use for the generated keystore. -| `changeit` - -| `keystoreCertAlias` -| The alias in the keystore used for the imported service serving certificate. -| `server` -|=== - -[[enrichers-jkube.] -=== JKube Enrichers - -JKube enrichers are used for providing the connection to other components of the jkube.Microservices platform. They are useful to add icons to application or links to documentation sites. - -[[jkube-healthcheck-karaf]] -==== jkube-healthcheck-karaf - -This enricher adds kubernetes readiness and liveness probes with Apache Karaf. This requires that - `jkube.karaf-checks` has been enabled in the Karaf startup features. - -The enricher will use the following settings by default: - -- port = `8181` -- scheme = `HTTP` -- failureThreshold = `3` -- successThreshold = `1` - -and use paths `/readiness-check` for readiness check and `/health-check` for liveness check. - -These options cannot be configured. - -[[jkube-prometheus]] -==== jkube-prometheus - -This enricher adds Prometheus annotation like: - -[source,yaml] ----- -apiVersion: v1 -kind: List -items: -- apiVersion: v1 - kind: Service - metadata: - annotations: - prometheus.io/scrape: "true" - prometheus.io/port: 9779 ----- - -By default the enricher inspects the images' BuildConfiguration and add the annotations if the port 9779 is listed. -You can force the plugin to add annotations by setting enricher's config ```prometheusPort``` - -[[jkube-healthcheck-webapp]] -==== jkube-healthcheck-webapp - -This enricher adds kubernetes readiness and liveness probes with WebApp. This requires that you have `maven-war-plugin` set. - -The enricher will use the following settings by default: - -- port = `8080` -- scheme = `HTTP` -- path = `` -- initialReadinessDelay = 10 -- initialLivenessDelay = 180 - -If `path` attribute is not set (default value) then this enricher is disabled. - -These values can be configured by the enricher in the `kubernetes-maven-plugin` configuration as shown below: - -[source,xml] ----- - - org.eclipse.jkube - openshift-maven-plugin - {version} - - - kmp - - resource - helm - build - - - - - - - - / - - - - - ... - ----- - -[[jkube-healthcheck-spring-boot]] -==== jkube-healthcheck-spring-boot - -This enricher adds kubernetes readiness and liveness probes with Spring Boot. This requires the following dependency - has been enabled in Spring Boot - -[source,xml] - - org.springframework.boot - spring-boot-starter-actuator - - -The enricher will try to discover the settings from the `application.properties` / `application.yaml` Spring Boot configuration file. - -The port number is read from the `management.port` option, and will use the default value of `8080` -The scheme will use HTTPS if `server.ssl.key-store` option is in use, and fallback to use `HTTP` otherwise. - -The enricher will use the following settings by default: - -* `readinessProbeInitialDelaySeconds` : `10` -* `readinessProbePeriodSeconds` : __ -* `livenessProbeInitialDelaySeconds` : `180` -* `livenessProbePeriodSeconds` : __ -* `timeoutSeconds` : __ -* `failureThreshold`: `3` -* `successThreshold`: `1` - -These values can be configured by the enricher in the `kubernetes-maven-plugin` configuration as shown below: -[source,xml] - - org.eclipse.jkube - openshift-maven-plugin - {version} - - - kmp - - resource - helm - build - - - - - - - - 5 - 30 - 3 - 1 - - - - - - - - -[[jkube-healthcheck-wildfly-swarm]] -==== jkube-jkube-healthcheck-wildfly-swarm - -This enricher adds kubernetes readiness and liveness probes with WildFly Swarm. This requires the following fraction - has been enabled in WildFly Swarm - -[source,xml] - - org.wildfly.swarm - microprofile-health - - -The enricher will use the following settings by default: - -- port = `8080` -- scheme = `HTTP` -- path = `/health` -- failureThreshold = `3` -- successThreshold = `1` - -These values can be configured by the enricher in the `kubernetes-maven-plugin` configuration as shown below: -[source,xml] - - org.eclipse.jkube - openshift-maven-plugin - {version} - - - kmp - - resource - helm - build - - - - - - - - 4444 - HTTPS - health/myapp - 3 - 1 - - - - - - - -[[jkube-healthcheck-thorntail-v2]] -==== jkube-healthcheck-thorntail-v2 - -This enricher adds kubernetes readiness and liveness probes with Thorntail v2. This requires the following fraction - has been enabled in Thorntail - -[source,xml] - - io.thorntail - microprofile-health - - -The enricher will use the following settings by default: - -- port = `8080` -- scheme = `HTTP` -- path = `/health` -- failureThreshold = `3` -- successThreshold = `1` - -These values can be configured by the enricher in the `kubernetes-maven-plugin` configuration as shown below: -[source,xml] - - org.eclipse.jkube - openshift-maven-plugin - {version} - - - kmp - - resource - helm - build - - - - - - - - 4444 - HTTPS - health/myapp - 3 - 1 - - - - - - -[[jkube-healthcheck-vertx]] -==== jkube-healthcheck-vertx - -This enricher adds kubernetes readiness and liveness probes with Eclipse Vert.x applications. The readiness probe lets Kubernetes -detects when the application is ready, while the liveness probe allows Kubernetes to verify that the application is -still alive. - -This enricher allows configuring the readiness and liveness probes. Are supported: `http` (emit HTTP requests), `tcp` (open a socket), `exec` (execute a command). - -By default, this enricher uses the same configuration for liveness and readiness probes. But specific configurations can be provided. The configurations can be overridden using project's properties. - -===== Using the jkube-healthcheck-vertx enricher - -The enricher is automatically executed if your project uses the `vertx-maven-plugin` or depends on `io.vertx:vertx-core`. -However, by default, no health check will be added to your deployment. - -===== Minimal configuration - -The minimal configuration to add health checks is the following: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - org.eclipse.jkube - openshift-maven-plugin - {version} - - - kmp - - resource - helm - build - - - - - - - - /health - - - - - ----- - -It configures the readiness and liveness health checks using HTTP requests on the port `8080` (default port) and on the path `/health`. The defaults are: - -* port = `8080` (for HTTP) -* scheme = `HTTP` -* path = _none_ (disabled) - -the previous configuration can also be given use project's properties: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - /health - ----- - -===== Configuring differently the readiness and liveness health checks - -You can provide two different configuration for the readiness and liveness checks: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - org.eclipse.jkube - openshift-maven-plugin - {version} - - - kmp - - resource - helm - build - - - - - - - - - /ready - - - /health - - - - - - ----- - -You can also use the `readiness` and `liveness` chunks in user properties: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - /ready - /ready - ----- - -Shared (generic) configuration can be set outside of the specific configuration. For instance, to use the port 8081: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - org.eclipse.jkube - openshift-maven-plugin - {version} - - - kmp - - resource - helm - build - - - - - - - - 8081 - - /ready - - - /health - - - - - - ----- - -Or: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - 8081 - /ready - /ready - ----- - -===== Configuration Structure - -The configuration is structured as follows - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - /both - - - ping - - - - ready - - - ----- - -The same structured is used in project's properties: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - /both - - ping - - ready ----- - -**Important**: Project's properties override the configuration provided in the plugin configuration. The overriding rules are: -_specific properties_ > _generic properties_ > _specific configuration_ > _generic configuration_. - -===== Probe configuration - -You can configure the different aspect of the probes. These attributes can be configured for both the readiness and liveness probes or be specific to one. - - -.Probe configuration -|=== -|Name |Description - -|`type` -|The probe type among `http` (default), `tcp` and `exec`. - -|`initial-delay` -|Number of seconds after the container has started before probes are initiated. - -|`period` -|How often (in seconds) to perform the probe. - -|`timeout` -|Number of seconds after which the probe times out. - -|`success-threshold` -|Minimum consecutive successes for the probe to be considered successful after having failed. - -|`failure-threshold` -|Minimum consecutive failures for the probe to be considered failed after having succeeded. - -|=== - - -More details about probes are available on https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/. - -===== HTTP probe configuration - -When using HTTP `GET` requests to determine readiness or liveness, several aspects can be configured. HTTP probes are used by default. To be more specific set the `type` attribute to `http`. - -.HTTP probes configuration -|=== -|Name |Description |Default - -|`scheme` -|Scheme to use for connecting to the host. -|`HTTP` - -|`path` -|Path to access on the HTTP server. An empty path disable the check -| - -|`headers` -|Custom headers to set in the request. HTTP allows repeated headers. It cannot be configured using project's properties. An example is available below. -| - -|`port` -|Number of the port to access on the container. A 0 or negative number disable the check. -|8080 - -|`port-name` -|Name of the port to access on the container. If neither the `port` or the `port-name` is set, the check is disabled. If both are set the configuration is considered invalid. -| - -|=== - -Here is an example of HTTP probe configuration: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - 3 - 3 - - 8081 - /ping - HTTPS - - Awesome - - - - - -1 - - - ----- - -===== TCP probe configuration - -You can also configure the probes to just open a socket on a specific port. The `type` attribute must be set to `tcp`. - -.TCP probes configuration -|=== -|Name |Description - -|`port` -|Number of the port to access on the container. A 0 or negative number disable the check. - -|`port-name` -|Name of the port to access on the container. If neither the `port` or the `port-name` is set, the check is disabled. If both are set the configuration is considered invalid. - -|=== - -For example: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - 3 - 3 - - tcp - 8081 - - - <-- use HTTP Get probe --> - /ping - 8080 - - - ----- - -===== Exec probe configuration - -You can also configure the probes to execute a command. If the command succeeds, it returns 0, and Kubernetes consider the pod to be alive and healthy. If the command returns a non-zero value, Kubernetes kills the pod and restarts it. To use a command, you must set the `type` attribute to `exec`: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - 3 - 3 - - exec - - cat - /tmp/healthy - - - - <-- use HTTP Get probe --> - /ping - 8080 - - - ----- - -As you can see in the snippet above the command is passed using the `command` attribute. This attribute cannot be configured using project's properties. An empty command disables the check. - -===== Disabling health checks - -You can disables the checks by setting: - -* the `port` to 0 or to a negative number for `http` and `tcp` probes -* the `command` to an empty list for `exec` - -In the first case, you can use project's properties to disable them: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - -1 ----- - -For `http` probes, an empty or not set `path` also disable the probe. - -[[jkube-maven-scm-enricher]] -==== jkube-maven-scm-enricher - -This enricher adds additional https://maven.apache.org/pom.html#SCM[SCM] related metadata to all objects supporting annotations. -These metadata will be added only if https://maven.apache.org/pom.html#SCM[SCM] information is present in the maven `pom.xml` of the project. - -The following annotations will be added to the objects that supports annotations, - -.Maven SCM Enrichers Annotation Mapping -[cols="2,2,3"] -|=== -| Maven SCM Info | Annotation | Description - -| scm/connection -| jkube.io/scm-con-url -| The SCM connection that will be used to connect to the project's SCM - -| scm/developerConnection -| jkube.io/scm-devcon-url -| The SCM Developer Connection that will be used to connect to the project's developer SCM - -| scm/tag -| jkube.io/scm-tag -| The SCM tag that will be used to checkout the sources, like HEAD dev-branch etc., - -| scm/url -| jkube.io/scm-url -| The SCM web url that can be used to browse the SCM over web browser - -|=== - -Lets say you have a maven pom.xml with the following scm information, -[source,xml] ----- - - scm:git:git://github.com/jkubeio/kubernetes-maven-plugin.git - scm:git:git://github.com/jkubeio/kubernetes-maven-plugin.git - git://github.com/jkubeio/kubernetes-maven-plugin.git - - ----- -This infomation will be enriched as annotations in the generated manifest like, - -[source,yaml] ----- -... - kind: Service - metadata: - annotations - jkube.io/scm-con-url: "scm:git:git://github.com/jkubeio/kubernetes-maven-plugin.git" - jkube.io/scm-devcon-url: "scm:git:git://github.com/jkubeio/kubernetes-maven-plugin.git" - jkube.io/scm-tag: "HEAD" - jkube.io/scm-url: "git://github.com/jkubeio/kubernetes-maven-plugin.git" -... ----- - -[[jkube-maven-issue-mgmt-enricher]] -==== jkube-maven-issue-mgmt - -This enricher adds additional https://maven.apache.org/pom.html#Issue_Management[Issue Management] related metadata to all objects supporting annotations. -These metadata will be added only if the https://maven.apache.org/pom.html#Issue_Management[Issue Management] information in available in maven `pom.xml` of the project. - -The following annotations will be added to the objects that supports annotations, - -.Maven Issue Tracker Enrichers Annotation Mapping -[cols="2,2,3"] -|=== -| Maven Issue Tracker Info | Annotation | Description - -| issueManagement/system -| jkube.io/issue-system -| The Issue Management system like Bugzilla, JIRA, GitHub etc., - -| issueManagement/url -| jkube.io/issue-tracker-url -| The Issue Management url e.g. GitHub Issues Url - -|=== - -Lets say you have a maven pom.xml with the following issue management information, - -[source,xml] ----- - - GitHub - https://github.com/reactiverse/vertx-maven-plugin/issues/ - ----- - -This information will be enriched as annotations in the generated manifest like, - -[source,yaml] ----- -... - kind: Service - metadata: - annotations: - jkube.io/issue-system: "GitHub" - jkube.io/issue-tracker-url: "https://github.com/reactiverse/vertx-maven-plugin/issues/" -... ----- - -[[jkube-revision-history-enricher]] -==== jkube-revision-history - -This enricher adds `spec.revisionHistoryLimit` property to deployment spec of Kubernetes/OpenShift resources. -A deployment’s revision history is stored in the replica sets, that specifies the number of old ReplicaSets to retain in order to allow rollback. -For more information read https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#revision-history-limit[Kubernetes documentation]. - -The following configuration parameters can be used to influence the behaviour of this enricher: - -.Default revision history enricher -[cols="2,2,3"] -|=== -| Element | Description | Default - -| limit -| Number of revision histories to retain -| 2 -|=== - -Just as any other enricher you can specify required properties with in the enricher's configuration as below, - -[source,xml] ----- -... - - - - 8 - - - -... ----- - -This information will be enriched as spec property in the generated manifest like, - -[source,yaml] ----- -... -kind: Deployment -spec: - revisionHistoryLimit: 8 -... ----- - -[[jkube-triggers-annotation]] -==== jkube-triggers-annotation - -This enricher adds ImageStreamTag change triggers on Kubernetes resources that support the `image.openshift.io/triggers` annotation, such as StatefulSets, ReplicaSets and DaemonSets. - -The trigger is added to all containers that apply, but can be restricted to a limited set of containers using the following configuration: - -[source,xml] ----- -... - - - - container-name-1,c2 - - - -... ----- - -[[jkube-configmap-file]] -==== jkube-configmap-file - -This enricher adds ConfigMap defined as `resources` in plugin configuration and/or resolves file content from an annotation. - -As XML you can define: - -[source, xml] -.pom.xml ----- - - - - myconfigmap - - - A - B - - - - - ----- - -This creates a ConfigMap data with key `A` and value `B`. - -You can also use `file` tag to refer to the content of a file. - -[source, xml] ----- - - - - configmap-test - - - src/test/resources/test-application.properties - - - - - ----- - -This creates a ConfigMap with key `test-application.properties` and value the content of the `src/test/resources/test-application.properties` file. -If you set `name` tag then this is used as key instead of the filename. - -If you are defining a custom `ConfigMap` file, you can use an annotation to define a file name as key and its content as the value: - -[source, yaml] ----- -metadata: - name: ${project.artifactId} - annotations: - maven.jkube.io/cm/application.properties: src/test/resources/test-application.properties ----- - -This creates a `ConfigMap` data with key `application.properties` (part defined after `cm`) and value the content of `src/test/resources/test-application.properties` file. - -[[jkube-secret-file]] -==== jkube-secret-file - -This enricher adds Secret defined as file content from an annotation. - -If you are defining a custom `Secret` file, you can use an annotation to define a file name as key and its content as the value: - -[source, yaml] ----- -metadata: - name: ${project.artifactId} - annotations: - maven.jkube.io/secret/application.properties: src/test/resources/test-application.properties ----- - -This creates a `Secret` data with the key `application.properties` (part defined after `secret`) and value content of `src/test/resources/test-application.properties` file (base64 encoded). - -== Enricher API - -_how to write your own enricher and install them_ diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_extensions.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_extensions.adoc deleted file mode 100644 index 29c68e1fd7..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_extensions.adoc +++ /dev/null @@ -1,15 +0,0 @@ - -[[extensions]] -= Extensions - -This plugin provides two major extensions hook how the creation of images and resources descriptors can be customized: - -* *Generators* are used to auto create or customize image configuration when creating Docker images. They are a bit like http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#using-boot-generator-poms[Spring Boot Generator POMs] as they can be enabled or disabled by declaring a Maven dependency. Generators are able to examine the build and to _detect_ certain feature like whether Spring boot application is build or a plain war file. Depending on the collected information a base image or the exposed ports are selected automatically for creating a image build configuration. - -* *Enrichers* are a similar concept but for creating the Kubernetes resource descriptors. Enricher can add build meta data as labels, automatically create `ReplicaSet` or `Service` based on the image performed. Again, enrichers can be selectively switched on and off via declaring Maven dependencies or via the XML configuration. kubernetes-maven-plugin already comes with a rich set of enrichers. Whereas *Generators* are only useful in the _Zero-Config_ case, *Enrichers* make sense for any configuration variant. - -The following sections described which Generators and Enrichers are available and how own customizations can be hooked in. - -include::extensions/_generator.adoc[] - -include::extensions/_enricher.adoc[] diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_faq.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_faq.adoc deleted file mode 100644 index 84fdb58d7d..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_faq.adoc +++ /dev/null @@ -1,120 +0,0 @@ -[[faq]] -= FAQ - -== General questions - -=== How do I define an environment variable? - -The easiest way is to add a `src/main/jkube/deployment.yml` file to your project containing something like: - -[source, yaml] ----- -spec: - template: - spec: - containers: - -env: - - name: FOO - value: bar ----- - -The above will generate an environment variable `$FOO` of value `bar` - -For a full list of the environments used in java base images, https://hub.docker.com/r/jkube.java-jboss-openjdk8-jdk[see this list] - -=== How do I define a system property? - -The simplest way is to add system properties to the `JAVA_OPTIONS` environment variable. - -For a full list of the environments used in java base images, https://hub.docker.com/r/jkube.java-jboss-openjdk8-jdk[see this list] - -e.g. add a `src/main/jkube/deployment.yml` file to your project containing something like: - -[source, yaml] ----- -spec: - template: - spec: - containers: - - env: - - name: JAVA_OPTIONS - value: "-Dfoo=bar -Dxyz=abc" ----- - -The above will define the system properties `foo=bar` and `xyz=abc` - -=== How do I mount a config file from a ConfigMap? - -First you need to create your `ConfigMap` resource via a file `src/main/jkube/configmap.yml` - -[source, yaml] ----- -data: - application.properties: | - # spring application properties file - welcome = Hello from Kubernetes ConfigMap!!! - dummy = some value ----- - -Then mount the entry in the `ConfigMap` into your `Deployment` via a file `src/main/jkube/deployment.yml` - -[source, yaml] ----- -metadata: - annotations: - configmap.jkube.io/update-on-change: ${project.artifactId} -spec: - replicas: 1 - template: - spec: - volumes: - - name: config - configMap: - name: ${project.artifactId} - items: - - key: application.properties - path: application.properties - containers: - - volumeMounts: - - name: config - mountPath: /deployments/config ----- - -Here is https://github.com/jkube.quickstarts/spring-boot-webmvc/tree/master/src/main/jkube[an example quickstart doing this] - -Note that the annotation `configmap.jkube.io/update-on-change` is optional; its used if your application is not capable of watching for changes in the `/deployments/config/application.properties` file. In this case if you are also running the https://github.com/jkubeio/configmapcontroller[configmapcontroller] then this will cause a rolling upgrade of your application to use the new `ConfigMap` contents as you change it. - -=== How do I use a Persistent Volume? - -First you need to create your `PersistentVolumeClaim` resource via a file `src/main/jkube/foo-pvc.yml` where `foo` is the name of the `PersistentVolumeClaim`. It might be your app requires multiple vpersistent volumes so you will need multiple `PersistentVolumeClaim` resources. - - -[source, yaml] ----- -spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 100Mi ----- - -Then to mount the `PersistentVolumeClaim` into your `Deployment` create a file `src/main/jkube/deployment.yml` - -[source, yaml] ----- -spec: - template: - spec: - volumes: - - name: foo - persistentVolumeClaim: - claimName: foo - containers: - - volumeMounts: - - mountPath: /whatnot - name: foo ----- - -Where the above defines the `PersistentVolumeClaim` called `foo` which is then mounted into the container at `/whatnot` - diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_generator.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_generator.adoc deleted file mode 100644 index 038e06140e..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_generator.adoc +++ /dev/null @@ -1,66 +0,0 @@ - -[[generators]] -= Generators - -include::generator/_overview.adoc[] - -[[generators-default]] -== Default Generators - -All default generators examine the build information for certain aspects and generate a Docker build configuration on the fly. They can be configured to a certain degree, where the configuration is generator specific. - -.Default Generators -[cols="1,1,4"] -|=== -| Generator | Name | Description - -| <> -| `java-exec` -| Generic generator for flat classpath and fat-jar Java applications - -| <> -| `spring-boot` -| Spring Boot specific generator - -| <> -| `wildfly-swarm` -| Generator for Wildfly Swarm apps - -| <> -| `thorntail-v2` -| Generator for Thorntail v2 apps - -| <> -| `vertx` -| Generator for Vert.x applications - -| <> -| `karaf` -| Generator for Karaf based apps - -| <> -| `webapps` -| Generator for WAR based applications supporting Tomcat, Jetty and Wildfly base images - -| <> -| `Quarkus` -| Generator for Quarkus based applications - -| <> -| `webapps` -| Generator for Open Liberty applications -|=== - -include::generator/_options_common.adoc[] - -include::generator/_java_exec.adoc[] -include::generator/_spring_boot.adoc[] -include::generator/_wildfly_swarm.adoc[] -include::generator/_thorntail_v2.adoc[] -include::generator/_vertx.adoc[] -include::generator/_karaf.adoc[] -include::generator/_webapp.adoc[] -include::generator/_quarkus.adoc[] -include::generator/_openliberty.adoc[] - -include::generator/_api.adoc[] diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_global_configuration.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_global_configuration.adoc deleted file mode 100644 index 30ddd4e570..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_global_configuration.adoc +++ /dev/null @@ -1,10 +0,0 @@ -Global plugin configuration properties are typically apply to all Maven plugin goals. - -.Global plugin configuration -[cols="1,5"] -|=== -| Property | Description - -| `jkube.skip` -| Skips over executing the goal. Typically used to disable the Openshift maven plugin when it's configured in a project. - diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_installation.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_installation.adoc deleted file mode 100644 index 4899f79045..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_installation.adoc +++ /dev/null @@ -1,58 +0,0 @@ - -[[installation]] -= Installation - -This plugin is available from Maven central and can be connected to -pre- and post-integration phase as seen below. The configuration and -available goals are described below. - -By default, Maven will only search for plugins in the `org.apache.maven.plugins` and `org.codehaus.mojo` packages. In order to resolve the provider for the JKube plugin goals, you need to edit `~/.m2/settings.xml` and add the `org.eclipse.jkube` namespace so the `` configuration. - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - ... - - - org.eclipse.jkube - - - ... - ----- - - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - org.eclipse.jkube - openshift-maven-plugin - {version} - - - .... - - - - ... - - .... - - - .... - - - - - - - jkube - - resource - build - helm - - - - ----- diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_integrations.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_integrations.adoc deleted file mode 100644 index 685f9c8b61..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_integrations.adoc +++ /dev/null @@ -1,46 +0,0 @@ - -[[integrations]] -= Integrations - -[[integrations.dekorate]] -== Dekorate - -*openshift-maven-plugin* provides a Zero Configuration approach to delegate deployment manifests -generation to https://github.com/dekorateio/dekorate[Dekorate]. - -Just by adding a dependency to Dekorate library in the `pom.xml` file, all manifest -generation will be delegated to Dekorate. - -[source, xml, indent=2] ----- - - - - io.dekorate - option-annotations - ${dekorate.version} - - - io.dekorate - openshift-annotations - ${dekorate.version} - - - io.dekorate - kubernetes-annotations - ${dekorate.version} - - - io.dekorate - dekorate-spring-boot - ${dekorate.version} - - ----- - -A full example of the integration can be found in the directory -https://github.com/eclipse/jkube/tree/master/quickstarts/maven/spring-boot-dekorate[quickstarts/maven/spring-boot-dekorate]. - -An *experimental* feature is also provided to merge resources generated both by *openshift-maven-plugin* -and Dekorate. You can activate this feature by using the following flag `-Djkube.mergeWithDekorate` -in the command-line, or setting it up as a property (`true`). diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_introduction.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_introduction.adoc deleted file mode 100644 index 314cc68cea..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_introduction.adoc +++ /dev/null @@ -1,325 +0,0 @@ - -[[introduction]] -= Introduction - -The *openshift-maven-plugin* (omp) brings your Java applications on to https://www.openshift.com/[Openshift]. -It provides a tight integration into http://maven.apache.org[Maven] and benefits from the build configuration already provided. -This plugin focus on two tasks: _Building Docker images_ and _creating Kubernetes resource descriptors_. -It can be configured very flexibly and supports multiple configuration models for creating: A _Zero-Config_ setup allows for a quick ramp-up with some opinionated defaults. -For more advanced requirements, an _XML configuration_ provides additional configuration options which can be added to the `pom.xml`. -For the full power, in order to tune all facets of the creation, external _resource fragments_ and _Dockerfiles_ can be used. - -[[building-images]] -== Building Images - -The <> goal is for creating Docker images containing the actual application. These then can be deployed later on Kubernetes or OpenShift. -It is easy to include build artifacts and their dependencies into these images. -This plugin uses the assembly descriptor format from the http://maven.apache.org/plugins/maven-assembly-plugin/[maven-assembly-plugin] to specify the content which will be added to the image. -That images can then be pushed to public or private Docker registries with <>. - -Depending on the operational mode, for building the actual image either a Docker daemon is used directly or an https://docs.openshift.com/enterprise/3.0/architecture/core_concepts/builds_and_image_streams.html#docker-build[OpenShift Docker Build] is performed. - -A special <> goal allows for reacting to code changes to automatically recreate images or copy new artifacts into running containers. - -These image related features are inherited from the https://github.com/jkubeio/docker-maven-plugin[jkubeio/docker-maven-plugin] which is part of this plugin. - -[[resource-descriptors]] -== Openshift Resources - -Openshift resource descriptors can be created or generated from <>. -These files are packaged within the Maven artifacts and can be deployed to a running orchestration platform with <>. - -Typically you only specify a small part of the real resource descriptors which will be enriched by this plugin with various extra information taken from the `pom.xml`. -This drastically reduces boilerplate code for common scenarios. - -== Configuration - -As mentioned already there are three levels of configuration: - -* *Zero-Config* mode makes some very opinionated decisions based on what is present in the pom.xml like what base image to use or which ports to expose. -This is great for starting up things and for keeping quickstart applications small and tidy. - -* *XML plugin configuration* mode is similar to what https://jkubeio.github.io/docker-maven-plugin/#example[docker-maven-plugin] provides. -This allows for type-safe configuration with IDE support, but only a subset of possible resource descriptor features is provided. - -* *Kubernetes & OpenShift resource fragments* are user provided YAML files that can be _enriched_ by the plugin. This allows expert users to use a plain configuration file with all their capabilities, but also to add project specific build information and avoid boilerplate code. - -The following table gives an overview of the different models - -.Configuration Models -[cols="1,4,3"] -|=== -| Model | Docker Images | Resource Descriptors - -| *Zero-Config* -| <> are used to create Docker image configurations. Generators can detect certain aspects of the build (e.g. whether Spring Boot is used) and then choose some default like the base image, which ports to expose and the startup command. They can be configured, but offer only a few options. -| Default <> will create a default _Service_ and _Deployment_ (_DeploymentConfig_ for OpenShift) when no other resource objects are provided. Depending on the image they can detect which port to expose in the service. As with Generators, Enrichers support a limited set of configuration options. - -| *XML configuration* -| omp inherits the XML based configuration for building images from the https://jkubeio.github.io/docker-maven-plugin/#docker:build[docker-maven-plugin] and provides the same functionality. It supports an http://maven.apache.org/components/plugins/maven-assembly-plugin/assembly.html[assembly descriptor] for specifying the content of the Docker image. -| A subset of possible resource objects can be configured with a dedicated XML syntax. With a decent IDE you get autocompletion on most object and inline documentation for the available configuration elements. The provided configuration can be still enhanced by Enhancers which is useful for adding e.g. labels and annotations containing build or other information. - -| *Resource Fragments* and *Dockerfiles* -| Similarly to the docker-maven-plugin, omp supports <> too, which are referenced from the plugin configuration. -| Resource descriptors can be provided as external YAML files which specify a skeleton. This skeleton is then filled by Enrichers which add labels and more. Maven properties within these files are resolved to thier values. With this model you can use every Kubernetes / OpenShift resource object with all their flexibility, but still get the benefit of adding build information. -|=== - - -== Examples - -Let's have a look at some code. The following examples will demonstrate all three configurations variants: - -[[zero-config]] -=== Zero-Config - -This minimal but full working example `pom.xml` shows how a simple spring boot application can be dockerized and prepared for Kubernetes. The full example can be found in directory https://github.com/jkubeio/kubernetes-maven-plugin/tree/master/samples/zero-config[samples/zero-config]. - -.Example -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - 4.0.0 - - org.eclipse.jkube - jkube-maven-sample-zero-config - {version} - jar - - - org.springframework.boot - spring-boot-starter-parent - 1.5.5.RELEASE - - - - - org.springframework.boot - spring-boot-starter-web - - - - - - - org.springframework.boot - spring-boot-maven-plugin - - - org.eclipse.jkube - openshift-maven-plugin - {version} - - - - ----- -<1> This minimalistic spring boot application uses the spring-boot parent POM for setting up dependencies and plugins -<2> The Spring Boot web starter dependency enables a simple embedded Tomcat for serving Spring MVC apps -<3> The `spring-boot-maven-plugin` is responsible for repackaging the application into a fat jar, including all dependencies and the embedded Tomcat -<4> The `kubernetes-maven-plugin` enables the automatic generation of a Docker image and Kubernetes / OpenShift descriptors including this Spring application. - -This setup make some opinionated decisions for you: - -* As base image https://github.com/fabric8io-images/java/tree/master/images/jboss/openjdk8/jdk[jkube/java-jboss-openjdk8-jdk] is chosen which enables https://www.jolokia.org[Jolokia] and https://github.com/prometheus/jmx_exporter[jmx_exporter]. It also comes with a sophisticated https://github.com/jkubeio-images/run-java-sh[startup script]. -* It will create a Kubernetes http://kubernetes.io/docs/user-guide/deployments/[Deployment] and a http://kubernetes.io/docs/user-guide/services/[Service] as resource objects -* It exports port 8080 as the application service port (and 8778 and 9779 for Jolokia and jmx_exporter access, respectively) - -These choices can be influenced by configuration options as described in <>. - -To start the Docker image build, you simply run - -[source,bash] ----- -mvn package oc:build ----- - -This will create the Docker image against a running Docker daemon (which must be accessible either via Unix Socket or with the URL set in `DOCKER_HOST`). Alternatively, when connected to an OpenShift cluster (or using the `openshift` <> explicitly), then a Docker build will be performed on OpenShift which at the end creates an https://docs.openshift.com/enterprise/3.1/architecture/core_concepts/builds_and_image_streams.html[ImageStream]. - -To deploy the resources to the cluster call - -[source,bash] ----- -mvn oc:resource oc:deploy ----- - -By default a _Service_ and a _Deployment_ object pointing to the created Docker image is created. When running in OpenShift mode, a _Service_ and _DeploymentConfig_ which refers the _ImageStream_ created with `oc:build` will be installed. - -Of course you can bind all those jkube.goals to execution phases as well, so that they are called along with standard lifecycle goals like `install`. For example, to bind the building of the Kubernetes resource files and the Docker images, add the following goals to the execution of the omp: - -.Example for lifecycle bindings -[source, xml, indent=0] ----- - - org.eclipse.jkube - openshift-maven-plugin - - - - - - - resource - build - - - - ----- - -If you'd also like to automatically deploy to Kubernetes each time you do a `mvn install` you can add the `deploy` goal: - -.Example for lifecycle bindings with automatic deploys for mvn install -[source, xml, indent=0] ----- - - org.eclipse.jkube - openshift-maven-plugin - - - - - - - resource - build - deploy - - - - ----- - -=== XML Configuration - -WARNING: XML based configuration is only partially implemented and is not recommended for use right now. - -Although the Zero-config mode and its generators can be tweaked with options up to a certain degree, many cases require more flexibility. For such instances, an XML-based plugin configuration can be used, in a way similar to the -https://jkubeio.github.io/docker-maven-plugin/#configuration[XML configuration] used by `docker-maven-plugin`. - -The plugin configuration can be roughly divided into the following sections: - -* Global configuration options are responsible for tuning the behaviour of plugin goals -* `` defines which Docker <> are used and configured. This section is similar to the https://jkubeio.github.io/docker-maven-plugin/#image-configuration[image configuration] of the `docker-maven-plugin`, except that `` and `` sub-elements are ignored) -* `` defines the resource descriptors for deploying on an OpenShift or Kuberneres cluster. -* `` configures <> which are responsible for creating images. Generators are used as an alternative to a dedicated `` section. -* `` configures various aspects of <> for creating or enhancing resource descriptors. - -A working example can be found in the https://github.com/eclipse/jkube/tree/master/quickstarts/maven/xml-config[samples/xml-config] directory. An extract of the plugin configuration is shown below: - -.Example for an XML configuration -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - test-ns - - - xml-config-demo:1.0.0 - - camel-app - - fabric8/java-centos-openjdk8-jre - - - /deployments - - - - /deployments - org.apache.camel.cdi.Main - - - - - - - - - quickstarts - - - - 2 - ${project.artifactId} - - - - camel-service - true - - - - - - build-robot - - - - ----- -<1> Standard docker-maven-plugin configuration for building one single Docker image -<2> Kubernetes / OpenShift resources to create -<3> Labels which should be applied globally to all resource objects -<4> Number of replicas desired -<5> Name of controller created by plugin -<6> One or more http://kubernetes.io/docs/user-guide/services/[Service] definitions. - -The XML resource configuration is based on plain Kubernetes resource objects. When targeting OpenShift, Kubernetes resource descriptors will be automatically converted to their OpenShift counterparts, e.g. a Kubernetes http://kubernetes.io/docs/user-guide/deployments/[Deployment] will be converted to an OpenShift https://docs.openshift.org/latest/architecture/core_concepts/deployments.html#deployments-and-deployment-configurations[DeploymentConfig]. - -=== Resource Fragments - -The third configuration option is to use an external configuration in form of YAML resource descriptors which are located in the `src/main/jkube` directory. Each resource gets its own file, which contains a skeleton of a resource descriptor. The plugin will pick up the resource, enrich it and then combine all to a single `kubernetes.yml` and `openshift.yml` file. Within these descriptor files you are can freely use any Kubernetes feature. - -Note: In order to support simultaneously both OpenShift and Kubernetes, there is currently no way to specify OpenShift-only features this way, though this might change in future releases. - -Let's have a look at an example from https://github.com/eclipse/jkube/tree/master/quickstarts/maven/external-resources[quickstarts/maven/external-resources]. This is a plain Spring Boot application, whose images are auto generated like in the <> case. The resource fragments are in `src/main/jkube`. - -.Example fragment "deployment.yml" -[source,yaml,indent=0,subs="verbatim,quotes,attributes"] ----- - spec: - replicas: 1 - template: - spec: - volumes: - - name: config - gitRepo: - repository: 'https://github.com/jstrachan/sample-springboot-config.git' - revision: 667ee4db6bc842b127825351e5c9bae5a4fb2147 - directory: . - containers: - - volumeMounts: - - name: config - mountPath: /app/config - env: - - name: KUBERNETES_NAMESPACE - valueFrom: - fieldRef: - apiVersion: v1 - fieldPath: metadata.namespace - serviceAccount: ribbon ----- - -As you can see, there is no `metadata` section as would be expected for Kubernetes resources because it will be automatically added by the `kubernetes-maven-plugin`. The object's `Kind`, if not given, is automatically derived from the -filename. In this case, the `kubernetes-maven-plugin` will create a `Deployment` because the file is called `deployment.yml`. Similar mappings between file names and resource type exist for each supported resource kind, the -complete list of which (along with associated abbreviations) can be found in the <>. - - - -NOTE: Now that sidecar containers are supported in this plugin, be careful whenever you're supplying container name in the resource fragment. If container specified in resource fragment doesn't have a name or it's name is equal to default fmp generated application's container name; it would not be treated as sidecar and it would be merged into main container. However, You can override plugin's default name for main container via `jkube.generator.alias` property. - -''' - -Additionally, if you name your fragment using a name prefix followed by a dash and the mapped file name, the plugin will automatically use that name for your resource. So, for example, if you name your deployment fragment -`myapp-deployment.yml`, the plugin will name your resource `myapp`. In the absence of such provided name for your resource, a name will be automatically derived from your project's metadata (in particular, its `artifactId` as specified in your POM). - -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). - - - -NOTE: For building images there is also an alternative mode using external Dockerfiles, in addition to the XML based configuration. Refer to <> for details. - -''' - -Enrichment of resource fragments can be fine-tuned by using profile sub-directories. For more details see <>. - -Now that we have seen some examples of the various ways how this plugin can be used, the following sections will describe the plugin goals and extension points in detail. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_profiles.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_profiles.adoc deleted file mode 100644 index f8b4cea669..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_profiles.adoc +++ /dev/null @@ -1,242 +0,0 @@ - -[[profiles]] -= Profiles - -Profiles can be used to combine a set of enrichers and generators and to give this combination a referable name. - -Profiles are defined in YAML. The following example shows a simple profiles which uses only the <> and some enrichers adding for adding default resources: - -.Profile Definition -[source, yaml] ----- -- name: my-spring-boot-apps # <1> - generator: # <2> - includes: - - spring-boot - enricher: # <3> - includes: # <4> - # Default Deployment object - - jkube-controller - # Add a default service - - jkube-service - excludes: # <5> - - jkube-icon - config: # <6> - jkube-service: - # Expose service as NodePort - type: NodePort - order: 10 # <7> -- name: another-profile - .... ----- -<1> Profile's name -<2> <> to use -<3> <> to use -<4> List of enricher to *include* in that given order -<5> List of enricher to *exclude* -<6> Configuration for services an enrichers -<7> An order which influences the way how profiles with the same name are merged - -Each `profiles.yml` has a list of profiles which are defined with these elements: - -.Profile elements -[cols="1,6"] -|=== -| Element | Description - -| *name* -| Profile name. This plugin comes with a set of <>. Those profiles can be extended by defining a custom profile with the same name of the profile to extend. - -| *generator* -| List of generator definitions. See <> for the format of these definitions. - -| *enricher* -| List of enrichers definitions. See <> for the format of these definitions. - -| *order* -| The order of the profile which is used when profiles of the same name are merged. -|=== - -[[generator-enricher-definition]] -## Generator and Enricher definitions - -The definition of generators and enrichers in the profile follows the same format: - -.Generator and Enericher definition -[cols="1,6"] -|=== -| Element | Description - -| *includes* -| List of generators or enrichers to include. The order in the list determines the order in which the processors are applied. - -| *excludes* -| List of generators or enrichers. These have precedences over _includes_ and will exclude a processor even when referenced in an _includes_ sections - -| *config* -| Configuration for generators or enrichers. This is a map where the keys are the name of the processor to configure and the value is again a map with configuration keys and values specific to the processor. See the documentation of the respective generator or enricher for the available configuration keys. -|=== - -[[profiles-lookup-order]] -## Lookup order - -Profiles can be defined externally either directly as a build resource in `src/main/jkube/profiles.yml` or provided as part of a plugin's dependency where it is supposed to be included as `META-INF/jkube/profiles.yml`. Multiple profiles can be include in these `profiles.yml` descriptors as a list: - -If a profile is <> then it is looked up from various places in the following order: - -* From the compile and plugin classpath from `META-INF/jkube/profiles-default.yml`. These files are reserved for profiles defined by this plugin -* From the compile and plugin classpath from `META-INF/jkube/profiles.yml`. Use this location for defining your custom profiles which you want to include via dependencies. -* From the project in `src/main/jkube/profiles.yml`. The directory can be tuned with the plugin option `resourceDir` (property: `jkube.resourceDir`) - -When multiple profiles of the same name are found, then these profiles are merged. If profile have an order number, then the _higher_ order takes precedences when merging profiles. - -For _includes_ of the same processors, the processor is moved to the earliest position. E.g consider the following two profiles with the name `my-profile` - -.Profile A -[source, yaml] ----- -name: my-profile -enricher: - includes: [ e1, e2 ] ----- - -.Profile B -[source, yaml] ----- -name: my-profile -enricher: - includes: [ e3, e1 ] -order: 10 ----- - -then when merged results in the following profile (when no order is given, it defaults to 0): - -.Profile merged -[source, yaml] ----- -name: my-profile -enricher: - includes: [ e1, e2, e3 ] -order: 10 ----- - -Profile with the same order number are merged according to the lookup order described above, where the latter profile is supposed to have a higher order. - -The configuration for enrichers and generators are merged, too, where higher order profiles override configuration values with the same key of lower order profile configuration. - -[[profiles-using]] -## Using Profiles - -Profiles can be selected by defining them in the plugin configuration, by giving a system property or by using <> in the directory holding the resource fragments. - -.Profile used in plugin configuration - -Here is an example how the profile can be used in a plugin configuration: - -[source, xml] ----- - - org.eclipse.jkube - openshift-maven-plugin - - my-spring-boot-apps - ..... - - ----- -<1> Name which select the profile from the `profiles.yml` - -.Profile as system property - -Alternatively a profile can be also specified on the command line when calling Maven: - -[source, sh] ----- -mvn -Djkube.profile=my-spring-boot-apps oc:build oc:deploy ----- - -If a configuration for enrichers and generators are provided as part of the plugin's `` then this takes precedence over any profile specified. - -[[profiles-resource-fragments]] -.Profiles for resource fragments - -Profiles are also very useful when used together with resource fragments in `src/main/jkube`. By default the resource objects defined here are enriched with the configured profile (if any). A different profile can be selected easily by using a sub directory within `src/main/jkube`. The name of each sub directory is interpreted as a profile name and all resource definition files found in this sub directory are enhanced with the enhancers defined in this profile. - -For example, consider the following directory layout: - -[source] ----- -src/main/oc: - app-rc.yml - app-svc.yml - raw/ --> - couchbase-rc.yml - couchbase-svc.yml ----- - -Here, the resource descriptors `app-rc.yml` and `app-svc.yml` are enhanced with the enrichers defined in the main configuration. The files two files `couchbase-rc.yml` and `couchbase-svc.yml` in the sub directory `raw/` instead are enriched with the profile **raw**. This is a predefined profile which includes no enricher at all, so the couchbase resource objects are not enriched and taken over literally. This is an easy way how you can fine tune enrichment for different object set. - -[[profiles-predefined]] -## Predefined Profiles - -This plugin comes with a list of the following predefined profiles: - -.Predefined Profiles -[cols="1,6"] -|=== -| Profile | Description - -| *default* -| The default profile which is active if no profile is specified. It consists of a curated set of generator and enrichers. See <> for the current definition. - -| *minimal* -| This profile contains no generators and only enrichers for adding default objects (controller and services). No other enrichment is included. - -| *explicit* -| Like default but without adding default objects like controllers and services. - -| *aggregate* -| Includes no generators and only the <> enricher for picking up and combining resources from the compile time dependencies. - -| *internal-microservice* -| Do not expose a port for the service to generate. Otherwise the same as the _default_ profile. - -| *osio* -| Includes everything in the _default_ profile, plus additional enrichers and generators relevant only to https://openshift.io[OpenShift.io]. -|=== - -[[profiles-extended]] -## Extending Profiles - -A profile can also extend another profile to avoid repetition e.g of generators if the profile is only about including certain enrichers. For example, for a profile like: - -[source, yaml] ----- -- name: minimal - extends: default - enricher: - includes: - - jkube-name - - jkube-controller - - jkube-service - - jkube-image - - jkube-project-label - - jkube-debug - - jkube-namespace - - jkube-metadata - - jkube-controller-from-configuration - - jkube-openshift-deploymentconfig - - jkube-openshift-project - - jkube-openshift-service-expose - - jkube-openshift-route - ----- -one then would not need to repeat all generators as they are inherited from the `default` profile. - -[[profiles-default]] -.Default Profile - -[source, yaml] ----- -include::{plugindir}/src/main/resources/META-INF/jkube/profiles-default.yml[tags=default] ----- diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_registry.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_registry.adoc deleted file mode 100644 index b4643f827e..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_registry.adoc +++ /dev/null @@ -1,84 +0,0 @@ - -[[registry]] -= Registry handling - -Docker uses registries to store images. The registry is typically -specified as part of the name. I.e. if the first part (everything -before the first `/`) contains a dot (`.`) or colon (`:`) this part is -interpreted as an address (with an optionally port) of a remote -registry. This registry (or the default `docker.io` if no -registry is given) is used during push and pull operations. This -plugin follows the same semantics, so if an image name is specified -with a registry part, this registry is contacted. Authentication is -explained in the next <<_authentication,section>>. - -There are some situations however where you want to have more -flexibility for specifying a remote registry. This might be because -you do not want to hard code a registry into `pom.xml` but -provide it from the outside with an environment variable or a system -property. - -This plugin supports various ways of specifying a registry: - -* If the image name contains a registry part, this registry is used -unconditionally and can not be overwritten from the outside. -* If an image name doesn't contain a registry, then by default the -default Docker registry `docker.io` is used for push and pull -operations. But this can be overwritten through various means: -** If the `` configuration contains a `` subelement -this registry is used. -** Otherwise, a global configuration element `` is -evaluated which can be also provided as system property via -`-Ddocker.registry`. -** Finally an environment variable `DOCKER_REGISTRY` is looked up for -detecting a registry. - -This registry is used for pulling (i.e. for autopull the base image -when doing a `{plugin}:build`) and pushing with `{plugin}:push`. However, -when these two goals are combined on the command line like in `mvn --Ddocker.registry=myregistry:5000 package {plugin}:build {plugin}:push` -the same registry is used for both operation. For a more fine grained -control, separate registries for _pull_ and _push_ can be specified. - -* In the plugin's configuration with the parameters `` and -``, respectively. -* With the system properties `docker.pull.registry` and -`docker.push.registry`, respectively. - -.Example -[source,xml] ----- - - docker.jolokia.org:443 - - - - jolokia/jolokia-java - - docker.ro14nd.de - .... - - - postgresql - - .... - - - - docker.example.com:5000/another/server - - - ----- - -There is some special behaviour when using an externally provided -registry like described above: - -* When _pulling_, the image pulled will be also tagged with a repository -name *without* registry. The reasoning behind this is that this -image then can be referenced also by the configuration when the -registry is not specified anymore explicitly. -* When _pushing_ a local image, temporarily a tag including the -registry is added and removed after the push. This is required -because Docker can only push registry-named images. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_volumes.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/_volumes.adoc deleted file mode 100644 index ce1ef379d7..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/_volumes.adoc +++ /dev/null @@ -1,55 +0,0 @@ -[[volume-configuration]] - -= Volume Configuration - -OpenShift maven plugin supports volume configuration in XML format in pom.xml. These are the volume types which are supported: - -.Supported Volume Types -[cols="1,22"] -|=== -| Volume Type | Description - -| hostPath | Mounts a file or directory from the host node's filesystem into your pod - -| emptyDir | Containers in the Pod can all read and write the same files in the emptyDir volume, though that volume can be mounted at the same or different paths in each Container. When a Pod is removed from a node for any reason, the data in the emptyDir is deleted forever. - -| gitRepo | It mounts an empty directory and clones a git repository into it for your Pod to use. - -| secret | It is used to pass sensitive information, such as passwords, to Pods. - -| nfsPath | Allows an existing NFS(Network File System) share to be mounted into your Pod. - -| gcePdName | Mounts a Google Compute Engine(GCE) into your Pod. You must create PD using `gcloud` or GCE API or UI before you can use it. - -| glusterFsPath | Allows a Glusterfs (an open source networked filesystem) volume to be mounted into your Pod. - -| persistentVolumeClaim | Used to mount a PersistentVolume into a Pod. - -| awsElasticBlockStore | Mounts an Amazon Web Services(AWS) EBS Volume into your Pod. - -| azureDisk | Mounts a Microsoft Azure Data Disk into a Pod - -| azureFile | Mounts a Microsoft Azure File Volume(SMB 2.1 and 3.0 into a Pod. - -| cephfs | Allows an existing CephFS volume to be mounted into your Pod. You must have your own Ceph server running with the share exported before you can use it. - -| fc | Allows existing fibre channel volume to be mounted in a Pod. You must configure FC SAN Zoning to allocate and mask those LUNs (volumes) to the target WWNs beforehand so that Kubernetes hosts can access them. - -| flocker | Flocker is an open source clustered Container data volume manager. A `flocker` volume allows a Flocker dataset to be mounted into a Pod. You must have your own Flocker installation running before you can use it. - -| iscsi | Allows an existing ISCSI(SCSI over IP) volume to be mounted into your Pod. - -| portworxVolume | A portworxVolume is an elastic block storage layer that runs hyperconverged with Kubernetes. - -| quobyte | Allows existing `Quobyte` volume to be mounted into your Pod. You must have your own Quobyte setup running the volumes created. - -| rbd | Allows a Rados Block Device volume to be mounted into your Pod. - -| scaleIO | ScaleIO is a software-based storage platform that can use existing hardware to create clusters of scalable shared block networked storage. The scaleIO volume plugin allows deployed Pods to access existing ScaleIO volumes. - -| storageOS | A storageos volume allows an existing StorageOS volume to be mounted into your Pod. You must run the StorageOS container on each node that wants to access StorageOS volumes - -| vsphereVolume | Used to mount a vSphere VMDK volume into your Pod. - -| downwardAPI | A downwardAPI volume is used to make downward API data available to applications. It mounts a directory and writes the requested data in plain text files. -|=== \ No newline at end of file diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_assembly.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_assembly.adoc deleted file mode 100644 index 4192125622..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_assembly.adoc +++ /dev/null @@ -1,203 +0,0 @@ - -The `` element within `` is has an XML struture and defines how build artifacts and other files can enter the Docker image. - -[[config-image-build-assembly]] -.Assembly Configuration (< >> : < >>) -[cols="1,5"] -|=== -| Element | Description - -| *name* -| Assembly name, which is `maven` by default. This name is used for the archives and directories created during the build. This directory holds the files specified by the assembly. If an <> is used than this name is also the relative directory which contains the assembly files. - -| *targetDir* -| Directory under which the files and artifacts contained in the assembly will be copied within the container. The default value for this is `/`, so `/maven` if *name* is not set to a different value. This option has no meaning when an <> is used. - -| <> -| Inlined assembly descriptor as described in <> below. - -| <> -| Path to an assembly descriptor file, whose format is described <> below. - -| <> -| Alias to a predefined assembly descriptor. The available aliases are also described in <> below. - -| *dockerFileDir* -| Directory containing an external Dockerfile. _This option is deprecated, please use directly in the section_. - -| *exportTargetDir* -| Specification whether the `targetDir` should be exported as a volume. This value is `true` by default except in the case the `targetDir` is set to the container root (`/`). It is also `false` by default when a base image is used with `from` since exporting makes no sense in this case and will waste disk space unnecessarily. - -| *ignorePermissions* -| Specification if existing file permissions should be ignored -when creating the assembly archive with a mode `dir`. This value is `false` by default. _This property is deprecated, use a `permissions` of `ignore` instead._ - -| *mode* -a| Mode how the how the assembled files should be collected: - -* `dir` : Files are simply copied (default), -* `tar` : Transfer via tar archive -* `tgz` : Transfer via compressed tar archive -* `zip` : Transfer via ZIP archive - -The archive formats have the advantage that file permission can be preserved better (since the copying is independent from the underlying files systems), but might triggers internal bugs from the Maven assembler (as it has been reported in https://github.com/fabric8io/docker-maven-plugin/issues/171[#171]) - -| *permissions* -a| Permission of the files to add: - -* `ignore` to use the permission as found on files regardless on any -assembly configuration -* `keep` to respect the assembly provided permissions, `exec` for setting the executable bit on all files (required for Windows when using an assembly mode `dir`) -* `auto` to let the plugin select `exec` on Windows and `keep` on others. - -`keep` is the default value. - -| *tarLongFileMode* -| Sets the TarArchiver behaviour on file paths with more than 100 characters length. Valid values are: "warn"(default), "fail", "truncate", "gnu", "posix", "posix_warn" or "omit" - -| [[config-image-build-assembly-user]] *user* -| User and/or group under which the files should be added. The user must already exist in the base image. - -It has the general format `user[:group[:run-user]]`. The user and group can be given either as numeric user- and group-id or as names. The group id is optional. - -If a third part is given, then the build changes to user `root` before changing the ownerships, changes the ownerships and then change to user `run-user` which is then used for the final command to execute. This feature might be needed, if the base image already changed the user (e.g. to 'jboss') so that a `chown` from root to this user would fail. - -For example, the image `jboss/wildfly` use a "jboss" user under which all commands are executed. Adding files in Docker always happens under the UID root. These files can only be changed to "jboss" is the `chown` command is executed as root. For the following commands to be run again as "jboss" (like the final `standalone.sh`), the plugin switches back to user `jboss` (this is this "run-user") after changing the file ownership. For this example a specification of -`jboss:jboss:jboss` would be required. -|=== - -In the event you do not need to include any artifacts with the image, you may safely omit this element from the configuration. - -[[build-assembly-descriptor]] -==== Assembly Descriptor - -With using the `inline`, `descriptor` or `descriptorRef` option -it is possible to bring local files, artifacts and dependencies into -the running Docker container. A `descriptor` points to a file -describing the data to put into an image to build. It has the same -http://maven.apache.org/plugins/maven-assembly-plugin/assembly.html[format] as for creating assemblies with the -http://maven.apache.org/plugins/maven-assembly-plugin[maven-assembly-plugin] with following exceptions: - -* `` are ignored, the assembly will allways use a directory -when preparing the data container (i.e. the format is fixed to -`dir`) -* The `` is ignored since only a single assembly descriptor is -used (no need to distinguish multiple descriptors) - -Also you can inline the assembly description with a `inline` description -directly into the pom file. Adding the proper namespace even allows for -IDE autocompletion. As an example, refer to the profile `inline` in -the `data-jolokia-demo` 's pom.xml. - -Alternatively `descriptorRef` can be used with the name of a -predefined assembly descriptor. The following symbolic names can be -used for `descriptorRef`: - -[[build-assembly-descriptor-refs]] -.Predefined Assembly Descriptors -[cols="1,3"] -|=== -| Assembly Reference | Description - -| *artifact-with-dependencies* -| Attaches project's artifact and all its dependencies. Also, when a `classpath` file exists in the target directory, this will be added to. - -| *artifact* -| Attaches only the project's artifact but no dependencies. - -| *project* -| Attaches the whole Maven project but with out the `target/` directory. - -| *rootWar* -| Copies the artifact as `ROOT.war` to the exposed directory. I.e. Tomcat will then deploy the war under the root context. -|=== - -.Example -[source,xml] ----- - - - - - artifact-with-dependencies - ..... ----- - -will add the created artifact with the name `${project.build.finalName}.${artifact.extension}` and all jar dependencies in the the `targetDir` (which is `/maven` by default). - -All declared files end up in the configured `targetDir` (or `/maven` by default) in the created image. - -.Maven peculiarities when including the artifact -If the assembly references the artifact to build with this pom, it is required that the `package` phase is included in the run. Otherwise the artifact file, can't be found by `docker:build`. This is an old https://issues.apache.org/jira/browse/MASSEMBLY-94[outstanding issue] of the assembly plugin which probably can't be fixed because of the way how Maven works. We tried hard to workaround this issue and in 90% of all cases, you won't experience any problem. However, when the following warning happens which might lead to the given error: - -[source] ----- -[WARNING] Cannot include project artifact: io.fabric8:helloworld:jar:0.20.0; it doesn't have an associated file or directory. -[WARNING] The following patterns were never triggered in this artifact inclusion filter: -o 'io.fabric8:helloworld' - -[ERROR] DOCKER> Failed to create assembly for docker image (with mode 'dir'): Error creating assembly archive docker: You must set at least one file. ----- - -then you have two options to fix this: - -* Call `mvn package {plugin}:build` to explicitly run "package" and "docker:build" in a chain. -* Bind `build` to an to an execution phase in the plugin's definition. By default `{plugin}:build` will bind to the `install` phase is set in an execution. Then you can use a plain `mvn install` for building the artifact and creating the image. - -[source,xml] ----- - - - docker-build - - build - - - ----- - -.Example - -In the following example a dependency from the pom.xml is included and -mapped to the name `jolokia.war`. With this configuration you will end -up with an image, based on `busybox` which has a directory `/maven` -containing a single file `jolokia.war`. This volume is also exported -automatically. - -[source,xml] ----- - - - - - - org.jolokia:jolokia-war - - . - jolokia.war - - - - ----- - -Another container can now connect to the volume an 'mount' the -`/maven` directory. A container from `consol/tomcat-7.0` will look -into `/maven` and copy over everything to `/opt/tomcat/webapps` before -starting Tomcat. - -If you are using the `artifact` or `artifact-with-dependencies` descriptor, it is -possible to change the name of the final build artifact with the following: - -.Example -[source,xml] ----- - - your-desired-final-name - ... - ----- - -Please note, based on the following documentation listed http://maven.apache.org/pom.html#BaseBuild_Element[here], there is no guarantee the plugin creating your artifact will honor it in which case you will need to use a custom descriptor like above to achieve the desired naming. - -Currently the `jar` and `war` plugins properly honor the usage of `finalName`. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_buildargs.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_buildargs.adoc deleted file mode 100644 index 5c29d36038..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_buildargs.adoc +++ /dev/null @@ -1,15 +0,0 @@ -[[property-buildargs]] -As described in section <> for external Dockerfiles https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables-build-arg[Docker build arg] can be used. In addition to the -configuration within the plugin configuration you can also use properties to specify them: - -* Set a system property when running Maven, eg.: `-Ddocker.buildArg.http_proxy=http://proxy:8001`. This is especially -useful when using predefined Docker arguments for setting proxies transparently. -* Set a project property within the `pom.xml`, eg.: - -.Example -[source,xml] ----- - myValue ----- - -Please note that the system property setting will always override the project property. Also note that for all properties which are not Docker https://docs.docker.com/engine/reference/builder/#arg[predefined] properties, the external Dockerfile must contain an `ARGS` instruction. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_configuration.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_configuration.adoc deleted file mode 100644 index db97370859..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_configuration.adoc +++ /dev/null @@ -1,187 +0,0 @@ - -All build relevant configuration is contained in the `` section -of an image configuration. The following configuration options are supported: - -[[config-image-build]] -.Build configuration (< >>) -[cols="1,5"] -|=== -| Element | Description - -| <> -| specifies the assembly configuration as described in <> - -| <> -| Map specifying the value of https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables-build-arg[Docker build args] -which should be used when building the image with an external Dockerfile which uses build arguments. The key-value syntax is the same as when defining Maven properties (or `labels` or `env`). -This argument is ignored when no external Dockerfile is used. Build args can also be specified as properties as -described in <> - -| *buildOptions* -| Map specifying the build options to provide to the docker daemon when building the image. These options map to the ones listed as query parameters in the -https://docs.docker.com/engine/reference/api/docker_remote_api_v1.24/#build-image-from-a-dockerfile[Docker Remote API] and are restricted to simple options -(e.g.: memory, shmsize). If you use the respective configuration options for build options natively supported by the build configuration (i.e. `noCache`, `cleanup=remove` for buildoption `forcerm=1` and `args` for build args) then these will override any corresponding options given here. The key-value syntax is the same as when defining environment variables or labels as described in <>. - -| *cleanup* -| Cleanup dangling (untagged) images after each build (including any containers created from them). Default is `try` which tries to remove the old image, but doesn't fail the build if this is not possible because e.g. the image is still used by a running container. Use `remove` if you want to fail the build and `none` if no cleanup is requested. - -| [[context-dir]]*contextDir* -| Path to a directory used for the build's context. You can specify the `Dockerfile` to use with *dockerFile*, which by default is the Dockerfile found in the `contextDir`. The Dockerfile can be also located outside of the `contextDir`, if provided with an absolute file path. See <> for details. - -| <> -| A command to execute by default (i.e. if no command is provided when a container for this image is started). See <> for details. - -| *compression* -| The compression mode how the build archive is transmitted to the docker daemon (`{plugin}:build`) and how docker build archives are attached to this build as sources (`{plugin}:source`). The value can be `none` (default), `gzip` or `bzip2`. - -| *dockerFile* -| Path to a `Dockerfile` which also triggers _Dockerfile mode_. See <> for details. - -| *dockerFileDir* (_deprecated_ in favor of *<>*) -| Path to a directory holding a `Dockerfile` and switch on _Dockerfile mode_. See <> for details. _This option is deprecated in favor of _contextDir_ and will be removed for the next major release_. - -| *dockerArchive* -| Path to a saved image archive which is then imported. See <> for details. - -| <> -| An entrypoint allows you to configure a container that will run as an executable. See <> for details. - -| <> -| The environments as described in <>. - -| *filter* -| Enable and set the delimiters for property replacements. By default properties in the format `${..}` are replaced with Maven properties. You can switch off property replacement by setting this property to `false`. When using a single char like `@` then this is used as a delimiter (e.g `@...@`). See <> for more details. - -| [[build-config-from]]*from* -| The base image which should be used for this image. If not given this default to `busybox:latest` and is suitable for a pure data image. -ifeval::["{plugin}" == "jkube"] -In case of an <> this parameter specifies the S2I Builder Image to use, which by default is `fabric8/s2i-java:latest`. See also <> how to add additional properties for the base image. - -endif::[] - -| [[build-config-from-ext]]**fromExt** -a| Extended definition for a base image. This field holds a map of defined in `value` format. The known keys are: - -* `` : Name of the base image -ifeval::["{plugin}" == "jkube"] -* `` : Kind of the reference to the builder image when in S2I build mode. By default its `ImageStreamTag` but can be also `ImageStream`. An alternative would be `DockerImage` -* `` : Namespace where this builder image lives. - -endif::[] - -A provided `` takes precedence over the name given here. This tag is useful for extensions of this plugin. - -| <> -| Definition of a health check as described in <> - -| *imagePullPolicy* -| Specific pull policy for the base image. This overwrites any global pull policy. See the globale configuration option <> for the possible values and the default. - -| *loadNamePattern* -a| Scan the images in the archive specified in `dockerArchive` and match the associated repository and tag information against this pattern. When a matching repository and tag is found, create a tag linking the `name` for this image to the repository and tag that matched the pattern. - -The wildcards are: - -* `?` matches a single character -* `*` matches within one component, where components are separated by slashes, or the final colon that separates the repository from the tag -* `**` matches multiple components, stopping at the final colon -* `**/` matches multiple components, but must stop at a slash, or the final colon - -When matching multiple components, `$$**/$$` is likely to be more useful than `$$**$$`. The pattern `$$**image-name:*$$` will match `my-group/my-image-name:some-tag`, whereas `$$**/image-name:*$$` will not, because the wildcard has to stop at a slash. Note that `$$**/image-name:*$$` will also match 'image-name:some-tag', since the `$$**/$$` wildcard can be empty. - -| <> -| Labels as described in <>. - -| *maintainer* -| The author (`MAINTAINER`) field for the generated image - -| *noCache* -| Don't use Docker's build cache. This can be overwritten by setting a system property `docker.noCache` when running Maven. - -| *cacheFrom* -| A list of `` elements specifying image names to use as cache sources. - -| *optimise* -| if set to true then it will compress all the `runCmds` into a single `RUN` directive so that only one image layer is created. - -| *ports* -| The exposed ports which is a list of `` elements, one for each port to expose. Whitespace is trimmed from each element and empty elements are ignored. The format can be either pure numerical ("8080") or with the protocol attached ("8080/tcp"). - -| *shell* -| Shell to be used for the *runCmds*. It contains *arg* elements which are defining the executable and its params. - -| *runCmds* -| Commands to be run during the build process. It contains *run* elements which are passed to the shell. Whitespace is trimmed from each element and empty elements are ignored. The run commands are inserted right after the assembly and after *workdir* into the Dockerfile. This tag is not to be confused with the `` section for this image which specifies the runtime behaviour when starting containers. - -| *skip* -| if set to true disables building of the image. This config option is best used together with a maven property - -| *skipTag* -| If set to `true` this plugin won't add any tags to images. Property: `docker.skip.tag` - -| *tags* -| List of additional `tag` elements with which an image is to be tagged after the build. Whitespace is trimmed from each element and empty elements are ignored. - -| *user* -| User to which the Dockerfile should switch to the end (corresponds to the `USER` Dockerfile directive). - -| *volumes* -| List of `volume` elements to create a container volume. Whitespace is trimmed from each element and empty elements are ignored. - -| *workdir* -| Directory to change to when starting the container. -|=== - -From this configuration this Plugin creates an in-memory Dockerfile, -copies over the assembled files and calls the Docker daemon via its -remote API. - -.Example -[source,xml] ----- - - java:8u40 - john.doe@example.com - - latest - ${project.version} - - - 8080 - - - /path/to/expose - - - 2147483648 - - - - - /bin/sh - -c - - - - groupadd -r appUser - useradd -r -g appUser appUser - - - - - - java - -jar - /opt/demo/server.jar - - - - - dir - /opt/demo - assembly.xml - - ----- - -In order to see the individual build steps you can switch on `verbose` mode either by setting the property `docker.verbose` or by using `true` in the <> diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_healthcheck.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_healthcheck.adoc deleted file mode 100644 index bd2cadb680..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_healthcheck.adoc +++ /dev/null @@ -1,48 +0,0 @@ - -Healthchecks has been introduced since Docker 1.12 and are a way to tell Docker how to test a container to check that it's still working. With a health check you specify a command which is periodically executed and checked for its return value. If the healtcheck return with an exit 0 the container is considered to be healthy, if it returns with 1 then the container is not working correctly. - -The healtcheck configuration can have the following options - -.Healthcheck Configuration -[cols="1,5"] -|=== -| Element | Description - - -| *cmd* -| Command to execute, which can be given in an shell or exec format as described in <>. - -| *interval* -| Interval for how often to run the healthcheck. The time is specified in seconds, but a time unit can be appended to change this. - -| *mode* -| Mode of the healthcheck. This can be `cmd` which is the default and specifies that the health check should be executed. Or `none` to disable a health check from the base image. Only use this option with `none` for disabling some healthcheck from the base image. - -| *retries* -| How many retries should be performed before the container is to be considered unhealthy. - -| *startPeriod* -| Initialization time for containers that need time to bootstrap. Probe failure during that period will not be counted towards the maximum number of retries. However, if a health check succeeds during the start period, the container is considered started and all consecutive failures will be counted towards the maximum number of retries. Given in seconds, but another time unit can be appended. - -| *timeout* -| Timeout after which healthckeck should be stopped and considered to have failed. Given in seconds, but another time unit can be appended. -|=== - -The following example queries an URL every 10s as an healthcheck: - -.Example -[source,xml] ----- - - - 5m - - 3s - - 30m - - 3 - - curl -f http://localhost/ || exit 1 - ----- diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_overview.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_overview.adoc deleted file mode 100644 index cfbc639e67..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/build/_overview.adoc +++ /dev/null @@ -1,114 +0,0 @@ - -[[build-overview]] -There are two different modes how images can be built: - -.Inline plugin configuration -With an inline plugin configuration all information required to build the image is contained in the plugin configuration. By default its the standard XML based configuration for the plugin but can be switched to a property based configuration syntax as described in the section <>. The XML configuration syntax is recommended because of its more structured and typed nature. - -When using this mode, the Dockerfile is created on the fly with all instructions extracted from the configuration given. - -[[external-dockerfile]] -.External Dockerfile or Docker archive -Alternatively an external Dockerfile template or Docker archive can be used. This mode is switched on by using one of these three configuration options within - -* *contextDir* specifies docker build context if an external dockerfile is located outside of Docker build context. If not specified, Dockerfile's parent directory is used as build context. -* *dockerFile* specifies a specific Dockerfile path. The Docker build context directory is set to `contextDir` if given. If not the directory by default is the directory in which the Dockerfile is stored. -* *dockerArchive* specifies a previously saved image archive to load directly. Such a tar archive can be created with `docker save` or the <<{plugin}:save>> goal. If a `dockerArchive` is provided, no `dockerFile` or `dockerFileDir` must be given. -* *dockerFileDir* (_deprecated_, use *contextDir*) specifies a directory containing a Dockerfile that will be used to create the image. The name of the Dockerfile is `Dockerfile` by default but can be also set with the option `dockerFile` (see below). - -All paths can be either absolute or relative paths (except when both `dockerFileDir` and `dockerFile` are provided in which case `dockerFile` must not be absolute). A relative path is looked up in `${project.basedir}/src/main/docker` by default. You can make it easily an absolute path by using `${project.basedir}` in your configuration. - -.Adding assemblies in Dockerfile mode -Any additional files located in the `dockerFileDir` directory will also be added to the build context as well. -You can also use an assembly if specified in an <>. -However, you need to add the files on your own in the Dockerfile with an `ADD` or `COPY` command. -The files of the assembly are stored in a build context relative directory `maven/` but can be changed by changing the assembly name with the option `` in the assembly configuration. - -E.g. the files can be added with - -.Example -[source,dockerfile] ----- -COPY maven/ /my/target/directory ----- - -so that the assembly files will end up in `/my/target/directory` within the container. - -If this directory contains a `.maven-dockerignore` (or alternatively, a `.maven-dockerexclude` file), then it is used for excluding files for the build. Each line in this file is treated as a http://ant.apache.org/manual/Types/fileset.html[FileSet exclude pattern] as used by the http://maven.apache.org/plugins/maven-assembly-plugin[maven-assembly-plugin]. It is similar to `.dockerignore` when using Docker but has a slightly different syntax (hence the different name). -<> is an example which excludes all compiled Java classes. - -[[ex-build-dockerexclude]] -.Example `.maven-dockerexclude` or `.maven-dockerignore` -==== -[source] ----- -target/classes/** # <1> ----- -<1> Exclude all compiled classes -==== - - -If this directory contains a `.maven-dockerinclude` file, then it is used for including only those files for the build. Each line in this file is also treated as a http://ant.apache.org/manual/Types/fileset.html[FileSet exclude pattern] as used by the http://maven.apache.org/plugins/maven-assembly-plugin[maven-assembly-plugin]. <> shows how to include only jar file that have build to the Docker build context. - -[[ex-build-dockerinclude]] -.Example `.maven-dockerinclude` -==== -[source] ----- -target/*.jar # <1> ----- -<1> Only add jar file to you Docker build context. -==== - -Except for the <> all other configuration options are ignored for now. - -[[simple-dockerfile-build]] -.Simple Dockerfile build - -When only a single image should be built with a Dockerfile no XML configuration is needed at all. -All what need to be done is to place a `Dockerfile` into the top-level module directory, alongside to `pom.xml`. -You can still configure <> in the plugin configuration, but as soon as you add an `` in the XML configuration, you need to configure also the build explicitly. - -The image name is by default set from the Maven coordinates (`%g/%a:%l`, see <> for an explanation of the params which are essentially the Maven GAV) -This name can be set with the property `docker.name`. - -If you want to add some `` configuration to this image for starting it with `docker:run` then you can add an image configuration but without a `` section in which case the Dockerfile will be picked up, too. This works only for a single image, though. - -[[build-filtering]] -.Filtering -openshift-maven-plugin filters given Dockerfile with Maven properties, much like the `maven-resource-plugin` does. Filtering is enabled by default and can be switched off with a build config `false`. Properties which we want to replace are specified with the `${..}` syntax. -Replacement includes Maven project properties such as `${project.artifactId}`, properties set in the build, command-line properties, and system properties. Unresolved properties remain untouched. - -This partial replacement means that you can easily mix it with Docker build arguments and environment variable reference, but you need to be careful. -If you want to be more explicit about the property delimiter to clearly separate Docker properties and Maven properties you can redefine the delimiter. -In general, the `filter` option can be specified the same way as delimiters in the resource plugin. -In particular, if this configuration contains a * then the parts left, and right of the asterisks are used as delimiters. - -For example, the default `${*}` parse Maven properties in the format that we know. -If you specify a single character for `` then this delimiter is taken for both, the start and the end. -E.g a `@` triggers on parameters in the format `@...@`, much like in the `maven-invoker-plugin`. -Use something like this if you want to clearly separate from Docker builds args. -This form of property replacement works for Dockerfile only. -For replacing other data in other files targeted for the Docker image, please use the `maven-resource-plugin` or an <> with filtering to make them available in the docker build context. - -.Example -The following example uses a Dockerfile in the directory -`src/main/docker/demo` and replaces all properties in the format `@property@` within the Dockerfile. -[source,xml] ----- - - - - - user/demo - - demo - @ - - - - - ... - ----- - diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/enricher/_jkube_service.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/enricher/_jkube_service.adoc deleted file mode 100644 index 55515793ec..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/enricher/_jkube_service.adoc +++ /dev/null @@ -1,144 +0,0 @@ - -[[jkube-service]] -==== jkube-service - -This enricher is used to ensure that a service is present. -This can be either directly configured with fragments or with the XML configuration, but it can be also automatically inferred by looking at the ports exposed by an image configuration. -An explicit configuration always takes precedence over auto detection. For enriching an existing service this enricher actually works only on a configured service which matches with the configured (or inferred) service name. - -The following configuration parameters can be used to influence the behaviour of this enricher: - -[[enricher-jkube-service]] -.Default service enricher -[cols="1,6,1"] -|=== -| Element | Description | Default - -| *name* -| Service name to enrich by default. If not given here or configured elsewhere, the artifactId is used -| - -| *headless* -| whether a headless service without a port should be configured. A headless service has the `ClusterIP` set to `None` and will be only used if no ports are exposed by the image configuration or by the configuration `port`. - -| `false` - -| *expose* -| If set to true, a label `expose` with value `true` is added which can be picked up by the jkube.https://github.com/jkubeio/exposecontroller[expose-controller] to expose the service to the outside by various means. See the documentation of expose-controller for more details. -| `false` - -| *type* -| Kubernetes / OpenShift service type to set like _LoadBalancer_, _NodePort_ or _ClusterIP_. -| - -| *port* -| The service port to use. By default the same port as the ports exposed in the image configuration is used, but can be changed with this parameter. See <> for a detailed description of the format which can be put into this variable. -| - -| *multiPort* -| Set this to `true` if you want all ports to be exposed from an image configuration. Otherwise only the first port is used as a service port. -| `false` - -| *protocol* -| Default protocol to use for the services. Must be `tcp` or `udp` -| `tcp` - -| *normalizePort* -| Normalize the port numbering of the service to common and conventional port numbers. -| `false` -|=== - - -Following is the Port mapping that comes in effect, when normalizePort option is set true. - -[cols="1,1"] -|=== -| Original Port | Normalized Port -| 8080 | 80 -| 8081 | 80 -| 8181 | 80 -| 8180 | 80 -| 8443 | 443 -| 443 | 443 -|=== - -You specify the properties like for any enricher within the enrichers configuration like in - -.Example -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ------ - - .. - - - - my-service - NodePort - true - - - - ------ - -[[jkube-service-ports]] -.Port specification - -With the option `port` you can influence the mapping how ports are mapped from the pod to the service. -By default and if this option is not given the ports exposed are dictated by the ports exposed from the Docker images contained in the pods. -Remember, each image configured can be part of the pod. -However you can expose also completely different ports as the images meta data declare. - -The property `port` can contain a comma separated list of mappings of the following format: - -[source,text,subs="verbatim,quotes,attributes"] ------ -:/,:/,.... ------ - -where the `targetPort` and `` specification is optional. These ports are overlayed over the ports exposed by the images, in the given order. - -This is best explained by some examples. - -For example if you have a pod which exposes a Microservice on port 8080 and you want to expose it as a service on port 80 (so that it can be accessed with `http://myservice`) you can simply use the following enricher configuration: - -.Example -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ------ - - - - - myservice - 80:8080 - - - - ------ -<1> 80 is the service port, 8080 the port opened in from the pod's images - -If your pod _exposes_ their ports (which e.g. all generator do), then you can even omit the 8080 here (i.e. `80`). -In this case the _first_ port exposed will be mapped to port 80, all other exposed ports will be omitted. - -By default an automatically generated service only exposes the first port, even when more ports are exposed. -When you want to map multiple ports you need to set the config option `true`. -In this case you can also provide multiple mappings as a comma separated list in the `` specification where each element of the list are the mapping for the first, second, ... port. - -A more (and bit artificially constructed) specification could be `80,9779:9779/udp,443`. -Assuming that the image exposes ports `8080` and `8778` (either directly or via <>) and we have switched on multiport mode, then the following service port mappings will be performed for the automatically generated service: - -* Pod port 8080 is mapped to service port 80. -* Pod port 9779 is mapped to service port 9779 with protocol UDP. Note how this second entry overrides the pod exposed port 8778. -* Pod port 443 is mapped to service port 443. - -This example shows also the mapping rules: - -* Port specification in `port` always override the port metadata of the contained Docker images (i.e. the ports exposed) -* You can always provide a complete mapping with `port` on your own -* The ports exposed by the images serve as _default values_ which are used if not specified by this configuration option. -* You can map ports which are _not_ exposed by the images by specifying them as target ports. - -Multiple ports are **only** mapped when _multiPort_ mode is enabled (which is switched off by default). If _multiPort_ mode is disabled, only the first port from the list of mapped ports as calculated as above is taken. - -When you set `legacyPortMapping` to true than ports 8080 to 9090 are mapped to port 80 automatically if not explicitly mapped via `_port_`. I.e. when an image exposes port 8080 with a legacy mapping this mapped to a service port 80, not 8080. You _should not_ switch this on for any good reason. In fact it might be that this option can vanish anytime. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_api.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_api.adoc deleted file mode 100644 index 5418f20925..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_api.adoc +++ /dev/null @@ -1,4 +0,0 @@ -[[generators-api]] -== Generator API - -WARNING: The API is still a bit in flux and will be documented later. Please refer to the https://github.com/jkubeio/kubernetes-maven-plugin/blob/master/generator/api/src/main/java/org.eclipse.jkube/maven/generator/api/Generator.java[Generator] Interface in the meantime. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_java_exec.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_java_exec.adoc deleted file mode 100644 index 9771dffef3..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_java_exec.adoc +++ /dev/null @@ -1,73 +0,0 @@ -[[generator-java-exec]] -=== Java Applications - -One of the most generic _Generators_ is the `java-exec` generator. -It is responsible for starting up arbitrary Java application. -It knows how to deal with fat-jar applications where the application and all dependencies are included within a single jar and the `MANIFEST.MF` within the jar references a main class. -But also flat classpath applications, where the dependencies are separate jar files and a main class is given. - -If no main class is explicitly configured, the plugin first attempts to locate a fat jar. -If the Maven build creates a JAR file with a `META-INF/MANIFEST.MF` containing a `Main-Class` entry, then this is considered to be the fat jar to use. -If there are more than one of such files then the largest one is used. - -If a main class is configured (see below) then the image configuration will contain the application jar plus all dependency jars. -If no main class is configured as well as no fat jar being detected, then this _Generator_ tries to detect a single main class by searching for `public static void main(String args[])` among the application classes. If exactly one class is found this is considered to be the main class. If no or more than one is found the _Generator_ finally does nothing. - -It will use the following base image by default, but as explained <> and can be changed with the `from` configuration. - -[[generator-java-exec-from]] -.Java Base Images -[cols="1,4,4,4"] -|=== -| | Docker Build | S2I Build | ImageStream - -| *Community* -| `fabric8/java-jboss-openjdk8-jdk` -| `fabric8/s2i-java` -| `fabric8-java` - -| *Red Hat* -| `jboss-fuse-6/fis-java-openshift` -| `jboss-fuse-6/fis-java-openshift` -| `fis-java-openshift` -|=== - -These images always refer to the latest tag. The _Red Hat_ base images are selected, when the plugin itself is a Red Hat supported version (which is detected by the plugins version number). - -When a `fromMode` of `istag` is used to specify an `ImageStreamTag` and when no `from` is given, then as default the `ImageStreamTag` `fis-java-openshift` in the namespace `openshift` is chosen. If you are using a RedHat variation of this plugin (i.e. if the version is ending with `-redhat`), then a `fromMode` of `istag` is the default, otherwise its `fromMode = "docker"` which use the a plain Docker image reference for the S2I builder image. - -Beside the common configuration parameters described in the table <> the following additional configuration options are recognized: - -[[generator-java-exec-options]] -.Java Application configuration options -[cols="1,6,1"] -|=== -| Element | Description | Default - -| *assemblyRef* -| If a reference to an assembly is given, then this is used without trying to detect the artifacts to include. -| -| *targetDir* -| Directory within the generated image where to put the detected artefacts into. Change this only if the base image is changed, too. -| `/deployments` - -| *jolokiaPort* -| Port of the Jolokia agent exposed by the base image. Set this to 0 if you don't want to expose the Jolokia port. -| 8778 - -| *mainClass* -| Main class to call. If not given first a check is performed to detect a fat-jar (see above). Next a class is looked up by scanning `target/classes` for a single class with a main method. If no such class is found or if more than one is found, then this generator does nothing. -| - -| *prometheusPort* -| Port of the Prometheus jmx_exporter exposed by the base image. Set this to 0 if you don't want to expose the Prometheus port. -| 9779 - -| *webPort* -| Port to expose as service, which is supposed to be the port of a web application. Set this to 0 if you don't want to expose a port. -| 8080 -|=== - -The exposed ports are typically later on use by <> 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`. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_karaf.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_karaf.adoc deleted file mode 100644 index 05baa3c9f6..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_karaf.adoc +++ /dev/null @@ -1,49 +0,0 @@ -[[generator-karaf]] -=== Karaf - -This generator named `karaf` kicks in when the build uses a `karaf-maven-plugin`. By default the following base images are used: - -[[generator-karaf-from]] -.Karaf Base Images -[cols="1,4,4"] -|=== -| | Docker Build | S2I Build - -| *Community* -| `jkube.s2i-karaf` -| `jkube.s2i-karaf` - -| *Red Hat* -| `jboss-fuse-6/fis-karaf-openshift` -| `jboss-fuse-6/fis-karaf-openshift` -|=== - -When a `fromMode` of `istag` is used to specify an `ImageStreamTag` and when no `from` is given, then as default the `ImageStreamTag` `fis-karaf-openshift:2.0` in the namespace `openshift` is chosen. - -In addition to the <> this generator can be configured with the following options: - -.Karaf configuration options -[cols="1,6,1"] -|=== -| Element | Description | Default - -| *baseDir* -| Directory within the generated image where to put the detected artefacts into. Change this only if the base image is changed, too. -| `/deployments` - -| *jolokiaPort* -| Port of the Jolokia agent exposed by the base image. Set this to 0 if you don't want to expose the Jolokia port. -| 8778 - -| *mainClass* -| Main class to call. If not given first a check is performed to detect a fat-jar (see above). Next a class is tried to be found by scanning `target/classes` for a single class with a main method. If no if found or more than one is found, then this generator does nothing. -| - -| *user* -| User and/or group under which the files should be added. The syntax of this options is descriped in <>. -| `jboss:jboss:jboss` - -| *webPort* -| Port to expose as service, which is supposed to be the port of a web application. Set this to 0 if you don't want to expose a port. -| 8080 -|=== diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_openliberty.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_openliberty.adoc deleted file mode 100644 index 0e20004cc0..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_openliberty.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[[generator-openliberty]] -=== Open Liberty - -The Open Liberty generator runs when the Open Liberty plugin is enabled in the maven build. - -The generator is similar to the <>. It supports the <> and the <>. - -For Open Liberty, the default value of webPort is 9080. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_options_common.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_options_common.adoc deleted file mode 100644 index af5221cfc6..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_options_common.adoc +++ /dev/null @@ -1,34 +0,0 @@ -There are some configuration options which are shared by all generators: - -[[generator-options-common]] -.Common generator options -[cols="1,6,1"] -|=== -| Element | Description | Property - -| *add* -| When this set to `true`, then the generator _adds_ to an existing image configuration. By default this is disabled, so that a generator only kicks in when there are no other image configurations in the build, which are either configured directly for a `oc:build` or already added by a generator which has been run previously. -| - -| *alias* -| An alias name for referencing this image in various other parts of the configuration. This is also used in the log output. The default alias name is the name of the generator. -| `jkube.generator.alias` - -| *from* -| This is the base image from where to start when creating the images. By default the generators make an opinionated decision for the base image which are described in the respective generator section. -| `jkube.generator.from` - -| *fromMode* -| Whe using OpenShift S2I builds the base image can be either a plain docker image (mode: `docker`) or a reference to an https://docs.openshift.com/container-platform/3.3/architecture/core_concepts/builds_and_image_streams.html[ ImageStreamTag] (mode: `istag`). In the case of an ImageStreamTag, `from` has to be specified in the form `namespace/image-stream:tag`. The mode takes only effect when running in OpenShift mode. -| `jkube.generator.fromMode` - -| *name* -| The Docker image name used when doing Docker builds. For OpenShift S2I builds its the name of the image stream. This can be a pattern as descibed in <>. The default is `%g/%a:%l`. -| `jkube.generator.name` - -| *registry* -| A optional Docker registry used when doing Docker builds. It has no effect for OpenShift S2I builds. -| `jkube.generator.registry` -|=== - -When used as properties they can be directly referenced with the property names above. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_overview.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_overview.adoc deleted file mode 100644 index 84c2c54a9c..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_overview.adoc +++ /dev/null @@ -1,87 +0,0 @@ -The usual way to define Docker images is with the plugin configuration as explained in <>. This can either be done completely within the `pom.xml` or by referring to an external Dockerfile. Since kubernetes-maven-plugin includes https://github.com/jkubeio/docker-maven-plugin[docker-maven-plugin] the way by which images are built is identical. - -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 `pom.xml`. 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. - -You can easily create your own generator as explained in <>. 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. - -The generator configuration is embedded in a `` configuration section: - -[[generator-example]] -.Example for a generator configuration -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - .... - - .... - - - spring-boot - - - - ping - - - - - ----- -<1> Start of generators' configuration. -<2> Generators can be included and excluded. Includes have precedence, and the generators are called in the given order. -<3> Configuration for individual generators. -<4> The config is a map of supported config values. Each section is embedded in a tag named after the generator. - -The following sub-elements are supported: - -.Generator configuration -[cols="1,6"] -|=== -| Element | Description - -| `` -| Contains one ore more `` elements with generator names which should be included. If given only this list of generators are included in this given order. The order is important because by default only the first matching generator kicks in. The generators from every active profile are included, too. However the generators listed here are moved to the front of the list, so that they are called first. Use the profile `raw` if you want to explicitly set the complete list of generators. - -| `` -| Holds one or more `` elements with generator names to exclude. If set then all detected generators are used except the ones mentioned in this section. - -| `` -| Configuration for all generators. Each generator support a specific set of configuration values as described in the documentation. The subelements of this section are generator names to configure. E.g. for generator `spring-boot`, the sub-element is called ``. This element then holds the specific generator configuration like `` for specifying the final image name. See above for an example. Configuration coming from profiles are merged into this config, but not overriding the configuration specified here. -|=== - -Beside specifying generator configuration in the plugin's configuration it can be set directly with properties, too: - -.Example generator property config -[source, sh] ----- -mvn -Djkube.generator.spring-boot.alias="myapp" ----- - -The general scheme is a prefix `jkube.generator.` followed by the unique generator name and then the generator specific key. - -In addition to the provided default _Generators_ described in the next section <>, custom generators can be easily added. There are two ways to include generators: - -.Plugin dependency - -You can declare the generator holding jars as dependency to this plugin as shown in this example - -[source, xml] ----- - - openshift-maven-plugin - .... - - - io.acme - mygenerator - 1.0 - - - ----- - -.Compile time dependency - -Alternatively and if your application code comes with a custom generator you can set the global configuration option `useProjectClasspath` (property: `jkube.useProjectClasspath`) to true. In this case also the project artifact and its dependencies are looked up for _Generators_. See <> for details how to write your own generators. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_quarkus.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_quarkus.adoc deleted file mode 100644 index 84d1999feb..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_quarkus.adoc +++ /dev/null @@ -1,25 +0,0 @@ -[[generator-quarkus]] -=== Quarkus - -The `Quarkus` generator tried to detect quarkus based projects looking at project `pom.xml`: - -The base images chosen are: -[[generator-quarkus-from]] -.Webapp Base Images -[cols="1,4,4"] -|=== -| | Docker Build | S2I Build - -| *Native* -| `registry.fedoraproject.org/fedora-minimal` -| --- - -| *Normal Build* -| `openjdk:11` -| --- -|=== - -[IMPORTANT] -==== -S2I builds are currently not yet supported for the Quarkus generator. -==== diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_spring_boot.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_spring_boot.adoc deleted file mode 100644 index 8ada4dcda1..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_spring_boot.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[[generator-spring-boot]] -=== Spring Boot - -This generator is called `spring-boot` and gets activated when it finds a `spring-boot-maven-plugin` in the pom.xml. - -This generator is based on the <> Generator and inherits all of its configuration values. The generated container port is read from the `server.port` property `application.properties`, defaulting to `8080` if it is not found. It also uses the same default images as the <>. - -Beside the <> and the <> the following additional configuration is recognized: - -.Spring-Boot configuration options -[cols="1,6,1"] -|=== -| Element | Description | Default - -| *color* -| If seth force the use of color in the Spring Boot console output. -| -|=== - -The generator adds Kubernetes liveness and readiness probes pointing to either the management or server port as read from the `application.properties`. -If the `management.port` (for Spring Boot 1) or `management.server.port` (for Spring Boot 2) and `management.ssl.key-store` (for Spring Boot 1) or `management.server.ssl.key-store` (for Spring Boot 2) properties are set in `application.properties` otherwise or `server.ssl.key-store` property is set in `application.properties` then the probes are automatically set to use `https`. - -The generator works differently when called together with `oc:watch`. -In that case it enables support for http://docs.spring.io/spring-boot/docs/current/reference/html/using-boot-devtools.html[Spring Boot Developer Tools] which allows for hot reloading of the Spring Boot app. -In particular, the following steps are performed: - -* If a secret token is not provided within the Spring Boot application configuration `application.properties` or `application.yml` with the key `spring.devtools.remote.secret` then a custom secret token is created and added to `application.properties` -* Add `spring-boot-devtools.jar` as `BOOT-INF/lib/spring-devtools.jar` to the spring-boot fat jar. - -Since during `oc:watch` the application itself within the `target/` directory is modified for allowing easy reloading you must ensure that you do a `mvn clean` before building an artefact which should be put into production. -Since the released version are typically generated with a CI system which does a clean build anyway this should be only a theoretical problem. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_thorntail_v2.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_thorntail_v2.adoc deleted file mode 100644 index ab74e3125c..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_thorntail_v2.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[[generator-thorntail-v2]] -=== Thorntail v2 - -The Thorntail v2 generator detects a Thorntail v2 build and disables the Prometheus Java agent because of this https://issues.jboss.org/browse/THORN-1859[issue]. - -Otherwise this generator is identical to the <>. It supports the <> and the <>. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_vertx.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_vertx.adoc deleted file mode 100644 index b7d96cc41c..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_vertx.adoc +++ /dev/null @@ -1,31 +0,0 @@ -[[generator-vertx]] -=== Vert.x - -The Vert.x generator detects an application using Eclipse Vert.x. It generates the metadata to start the application as a fat jar. - -Currently, this generator is enabled if: - -* you are using the Vert.x Maven Plugin (https://github.com/reactiverse/vertx-maven-plugin) -* you are depending on `io.vertx:vertx-core` and uses the Maven Shader plugin - -Otherwise this generator is identical to the <>. It supports the <> and the <>. - -The generator automatically: - -* enable metrics and JMX publishing of the metrics when `io.vertx:vertx-dropwizard-metrics` is in the project's classpath / dependencies. -* enable clustering when a Vert.x cluster manager is available in the project's classpath / dependencies. this is done by appending `-cluster` to the command line. -* Force IPv4 stack when `vertx-infinispan` is used. -* Disable the async DNS resolver to fallback to the regular JVM DNS resolver. - -You can pass application parameter by setting the `JAVA_ARGS` env variable. You can pass system properties either using the same variable or using `JAVA_OPTIONS`. For instance, create `src/main/jkube/deployment.yml` with the following content to configure `JAVA_ARGS`: - -[source, yaml] ----- -spec: - template: - spec: - containers: - - env: - - name: JAVA_ARGS - value: "-Dfoo=bar -cluster -instances=2" ----- diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_webapp.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_webapp.adoc deleted file mode 100644 index affee99a6a..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_webapp.adoc +++ /dev/null @@ -1,66 +0,0 @@ -[[generator-webapp]] -=== Web Applications - -The `webapp` generator tries to detect WAR builds and selects a base servlet container image based on the configuration found in the `pom.xml`: - -* A **Tomcat** base image is selected when a `tomcat6-maven-plugin` or `tomcat7-maven-plugin` is present or when a `META-INF/context.xml` could be found in the classes directory. -* A **Jetty** base image is selected when a `jetty-maven-plugin` is present or one of the files `WEB-INF/jetty-web.xml` or `WEB-INF/jetty-logging.properties` is found. -* A **Wildfly** base image is chosen for a given `jboss-as-maven-plugin` or `wildfly-maven-plugin` or when a Wildfly specific deployment descriptor like `jboss-web.xml` is found. - -The base images chosen are: - -[[generator-webapp-from]] -.Webapp Base Images -[cols="1,4,4"] -|=== -| | Docker Build | S2I Build - -| *Tomcat* -| `jkube.tomcat-8` -| --- - -| *Jetty* -| `jkube.jetty-9` -| --- - -| *Wildfly* -| `jboss/wildfly` -| --- -|=== - -[IMPORTANT] -==== -S2I builds are currently not yet supported for the webapp generator. -==== - -In addition to the <> this generator can be configured with the following options: - -.Webapp configuration options -[cols="1,6,1"] -|=== -| Element | Description | Default - -| *server* -| Fix server to use in the base image. Can be either **tomcat**, **jetty** or **wildfly** -| - -| *targetDir* -| Where to put the war file into the target image. By default its selected by the base image chosen but can be overwritten with this option. -| - -| *user* -| User and/or group under which the files should be added. The syntax of this options is descriped in <>. -| - -| *path* -| Context path with which the application can be reached by default -| `/` (root context) - -| *cmd* -| Command to use to start the container. By default the base images startup command is used. -| - -| *ports* -| Comma separated list of ports to expose in the image and which eventually are translated later to Kubernertes services. The ports depend on the base image and are selecte automatically. But they can be overwritten here. -| -|=== diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_wildfly_swarm.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_wildfly_swarm.adoc deleted file mode 100644 index 895366a39d..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/generator/_wildfly_swarm.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[[generator-wildfly-swarm]] -=== Wildfly Swarm - -The WildFly Swarm generator detects a WildFly Swarm build and disables the Prometheus Java agent because of this https://issues.jboss.org/browse/THORN-1859[issue]. - -Otherwise this generator is identical to the <>. It supports the <> and the <>. diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/_goals.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/_goals.adoc deleted file mode 100644 index d758737a85..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/_goals.adoc +++ /dev/null @@ -1,84 +0,0 @@ -[[goals]] -= Goals Overview - -This plugin supports a rich set for providing a smooth Java developer experience. These goals can be categorized in multiple groups: - -* <> are all about creating and managing Kubernetes build artifacts like Docker images or S2I builds. - -* <> target help not only in deploying resource descriptors to the development cluster but also to manage the lifecycle of the development cluster as well. - -[[goals-build]] -.Build Goals -[cols="1,3"] -|=== -| Goal | Description - -| *<>* -| Build images - -| *<>* -| Push images to a registry - -| *<>* -| Create Kubernetes or OpenShift resource descriptors - -| *<>* -| Apply resources to a running cluster -|=== - -[[goals-develop]] -.Development Goals -[cols="1,3"] -|=== -| Goal | Description - -| *<>* -| Deploy resources descriptors to a cluster after creating them and building the app. Same as <> except that it runs in the backgorund. - -| *<>* -| Undeploy and remove resources descriptors from a cluster. - -| *<>* -| Watch for file changes and perform rebuilds and redeployments - -| *<>* -| Show the logs of the running application - -| *<>* -| Enable remote debugging -|=== - -Depending on whether the OpenShift or Kubernetes operational mode is used, the workflow and the performed actions differs : - -.Workflows -[cols="1,4,4"] -|=== -| Use Case | Kubernetes | OpenShift - -| Build -a| `oc:build` `oc:push` - -* Creates an image against an exposed Docker daemon (with a `docker.tar`) -* Pushes the image to a registry which is then referenced from the configuration - -a| `oc:build` - -* Creates or uses a `BuildConfig` -* Creates or uses an `ImageStream` which can be referenced by the deployment descriptors in a `DeploymenConfig` -* Starts an OpenShift build with a `docker.tar` as input - - -| Deploy -a| `oc:deploy` - -* Applies a Kubernetes resource descriptor to cluster - -a| `oc:deploy` - -* Applies an OpenShift resource descriptor to a cluster - -|=== - - -include::build/_goals.adoc[] -include::develop/_goals.adoc[] diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_goals.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_goals.adoc deleted file mode 100644 index e05d13176e..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_goals.adoc +++ /dev/null @@ -1,8 +0,0 @@ - -[[goals-overview-build]] -# Build Goals - -include::_jkube-resource.adoc[] -include::_jkube-build.adoc[] -include::_jkube-push.adoc[] -include::_jkube-apply.adoc[] diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-apply.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-apply.adoc deleted file mode 100644 index cd6b10ee2e..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-apply.adoc +++ /dev/null @@ -1,84 +0,0 @@ - -[[oc:apply]] -== *oc:apply* - -This goal applies the resources created with <> to a connected Kubernetes cluster. It's similar to <> but does not the full deployment cycle of creating the resource, creating the application image and sending the resource descriptors to the clusters. This goal can be easily bound to `` within the plugin's configuration and binds by default to the `install` lifecycle phase. - -[source,sh,subs="attributes"] ----- -mvn oc:apply ----- - -[[Supported-Properties-Apply]] -=== Supported Properties For Apply goal - -.Other options available with apply goal -[cols="1.6.3"] -|=== -| Element | Description | Property(System property or maven property) - -| *failOnError* -| Should we fail the build if an apply fails, by default `true` -| `jkube.deploy.failOnError` - -| *recreate* -| Should we update resources by deleting them first and then creating them again, by default `false` -| `jkube.recreate` - -| *openshiftManifest* -| The generated kubernetes YAML file. Defaults to `${basedir}/target/classes/META-INF/jkube/openshift.yml` -| `jkube.openshiftManifest` - -| *create* -| Should we create new resources, defaults to `true` -| `jkube.deploy.create` - -| *rolling* -| Should we use rolling updates to apply changes, defaults to `false` -| `jkube.rolling` - -| *servicesOnly* -| In services only mode we only process services so that those can be recursively created/updated first before creating/updating any pods and replication controllers, defaults to `false` -| `jkube.deploy.servicesOnly` - -| *ignoreServices* -| Do we want to ignore services. This is particularly useful when in recreate mode to let you easily recreate all the ReplicationControllers and Pods but leave any service definitions alone to avoid changing the portalIP addresses and breaking existing pods using the service. Defaults to `false` -| `jkube.deploy.ignoreServices` - -| *processTemplatesLocally* -| Process templates locally in Java so that we can apply OpenShift templates on any Kubernetes environment, defaults to `false` -| `jkube.deploy.processTemplatesLocally` - -| *deletePods* -| Should we delete all the pods if we update a Replication Controller, defaults to `true` -| `jkube.deploy.deletePods` - -| *ignoreRunningOAuthClients* -| Do we want to ignore OAuthClients which are already running?. OAuthClients are shared across namespaces so we should not try to update or create/delete global oauth clients, defaults to `true` -| `jkube.deploy.ignoreRunningOAuthClients` - -| *createExternalUrls* -| Should we create external Ingress for any LoadBalancer Services which don't already have them. Defaults to `false` -| `jkube.deploy.createExternalUrls` - -| *jsonLogDir* -| The folder we should store any temporary json files or results. Defaults to `${basedir}/target/jkube/applyJson` -| `jkube.deploy.jsonLogDir` - -| *waitSeconds* -| How many seconds to wait for a URL to be generated for a service , defaults to `5` -| `jkube.serviceUrl.waitSeconds` - -| *resourceDir* -| Folder where to find project specific files, defaults to `${basedir}/src/main/jkube` -| `jkube.resourceDir` - -| *environment* -| Environment name where resources are placed. For example, if you set this property to dev and resourceDir is the default one, jkube will look at `src/main/jkube/dev`. Defaults to `null` -| `jkube.environment` - -| *skipApply* -| Skip applying the resources, defaults to `false` -| `jkube.skip.apply` - -|=== \ No newline at end of file diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-build.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-build.adoc deleted file mode 100644 index ddcf28a4bb..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-build.adoc +++ /dev/null @@ -1,372 +0,0 @@ - -[[oc:build]] -== *oc:build* - -This goal is for building Docker images. Images can be built in two different ways depending on the `mode` configuration (controlled by the `jkube.mode` property). -By default the mode is set to `auto`. In this case the plugin tries to detect which kind of build should be performed by contacting the API server. If this fails or if no cluster access is configured e.g. with `oc login` then the mode is set to `kubernetes` in which case a standard Docker build is performed. It can also be forced to `openshift` to perform an OpenShift build. - -[[build-kubernetes]] -=== Kubernetes Build - -If the mode is set to `kubernetes` then a normal Docker build is performed. The connection configuration to access the Docker daemon is described in <>. - -In order to make the generated images available to the Kubernetes cluster the generated images need to be pushed to a registry with the goal <>. This is not necessary for single node clusters, though as there is no need to distribute images. - -[[build-openshift]] -=== OpenShift Build - -For the `openshift` mode, OpenShift specific https://docs.openshift.com/enterprise/latest/architecture/core_concepts/builds_and_image_streams.html[builds] will be performed. These are so called https://docs.openshift.com/enterprise/latest/architecture/core_concepts/builds_and_image_streams.html[Binary Source] builds ("binary builds" in short), where the data specified with the <> is sent directly to OpenShift as a binary archive. - -There are two kind of binary builds supported by this plugin, which can be selected with the `buildStrategy` configuration option (`jkube.build.strategy` property) - -.Build Strategies -[cols="1,6"] -|=== -| `buildStrategy` | Description - - | `s2i` -| The https://docs.openshift.com/enterprise/latest/architecture/core_concepts/builds_and_image_streams.html#source-build[Source-to-Image] (S2I) build strategy uses so called builder images for creating new application images from binary build data. The builder image to use is taken from the base image configuration specified with <> in the image build configuration. See below for a list of builder images which can be used with this plugin. - -| `docker` -| A https://docs.openshift.com/enterprise/latest/architecture/core_concepts/builds_and_image_streams.html#docker-build[Docker Build] is similar to a normal Docker build except that it is done by the OpenShift cluster and not by a Docker daemon. In addition this build pushes the generated image to the OpenShift internal registry so that it is accessbile in the whole cluster. -|=== - -Both build strategies update an https://docs.openshift.com/enterprise/latest/architecture/core_concepts/builds_and_image_streams.html#image-streams[Image Stream] after the image creation. - -The https://docs.openshift.com/enterprise/latest/dev_guide/builds.html#defining-a-buildconfig[Build Config] and https://docs.openshift.com/enterprise/latest/architecture/core_concepts/builds_and_image_streams.html#image-streams[Image streams] can be managed by this plugin. If they do not exist, they will be automatically created by `oc:build`. If they do already exist, they are reused, except when the `buildRecreate` configuration option (property `jkube.build.recreate`) is set to a value as described in <>. Also if the provided build strategy is different than the one defined in the existing build configuration, the Build Config is edited to reflect the new type (which in turn removes all build associated with the previous build). - -This image stream created can then be directly referenced from https://docs.openshift.com/enterprise/latest/architecture/core_concepts/deployments.html#deployments-and-deployment-configurations[Deployment Configuration] objects created by <>. -By default, image streams are created with a local lookup policy, so that they can be used also by other resources such as Deployments or StatefulSets. -This behavior can be turned off by setting the `jkube.s2i.imageStreamLookupPolicyLocal` property to `false` when building the project. - -In order to be able to create these OpenShift resource objects access to an OpenShift installation is required. The access parameters are described in <>. - -Regardless of which build mode is used, the images are configured in the same way. - -The configuration consists of two parts: -* a global section which defines the overall behaviour of this plugin -* and an `` section which defines how the images should be build - -Many of the options below are relevant for the <> or the <> with Docker builds as they influence how the Docker image is build. - -For an S2I binary build, on the other hand, the most relevant section is the <> one because the build depends on which buider/base image is used and how it interprets the content of the uploaded `docker.tar`. - -[[build-goal-configuration]] -=== Configuration - -The following sections describe the usual configuration, which is similar to the build configuration used in the https://dmp.jkube.io[docker-maven-plugin]. - -In addition a more automatic way for creating predefined build configuration can be performed with so called <>. Generators are very flexible and can be easily created. These are described in an extra <>. - -Global configuration parameters specify overall behavior common for all images to build. Some of the configuration options are shared with other goals. - -.Global configuration -[cols="1,5,1"] -|=== -| Element | Description | Property - -| *apiVersion* -| Use this variable if you are using an older version of docker not compatible with the current default use to communicate with the server. -| `docker.apiVersion` - - | *authConfig* -| Authentication information when pulling from or pushing to Docker registry. There is a dedicated section <> for how to do security. -| - -| *autoPull* -a| Decide how to pull missing base images or images to start: - - * `on` : Automatic download any missing images (default) - * `off` : Automatic pulling is switched off - * `always` : Pull images always even when they already exist locally - * `once` : For multi-module builds images are only checked once and pulled for the whole build. - -| `docker.autoPull` - -| *buildRecreate* -a| If the effective <> is `openshift` then this option decides how the OpenShift resource objects associated with the build should be treated when they already exist: - -* `buildConfig` or `bc` : Only the BuildConfig is recreated -* `imageStream` or `is` : Only the ImageStream is recreated -* `all` : Both, BuildConfig and ImageStream are recreated -* `none` : Neither BuildConfig nor ImageStream is recreated - -The default is `none`. If you provide the property without value then `all` is assumed, so everything gets recreated. -| `jkube.build.recreate` - -| *buildStrategy* -a| If the effective <> is `openshift` then this option sets the build strategy. This can be: - -* `s2i` for a https://docs.openshift.com/enterprise/latest/architecture/core_concepts/builds_and_image_streams.html#source-build[Source-to-Image build] with a binary source -* `docker` for a https://docs.openshift.com/enterprise/latest/architecture/core_concepts/builds_and_image_streams.html#docker-build[Docker build] with a binary source - -By default S2I is used. -| `jkube.build.strategy` - -|*forcePull* -| -Applicable only for OpenShift, S2I build strategy. - -While creating a BuildConfig, By default, if the builder image specified in the -build configuration is available locally on the node, that image will be used. - -Using forcePull will override the local image and refresh it from the registry the image stream points to. - -|`jkube.build.forcePull` - - -| *certPath* -| Path to SSL certificate when SSL is used for communicating with the Docker daemon. These certificates are normally stored in `~/.docker/`. With this configuration the path can be set explicitly. If not set, the fallback is first taken from the environment variable `DOCKER_CERT_PATH` and then as last resort `~/.docker/`. The keys in this are expected with it standard names `ca.pem`, `cert.pem` and `key.pem`. Please refer to the https://docs.docker.com/articles/https[Docker documentation] for more information about SSL security with Docker. -| `docker.certPath` - -| *dockerHost* -a| The URL of the Docker Daemon. If this configuration option is not given, then the optional `` configuration section is consulted. The scheme of the URL can be either given directly as `http` or `https` -depending on whether plain HTTP communication is enabled or SSL should -be used. Alternatively the scheme could be `tcp` in which case the -protocol is determined via the IANA assigned port: 2375 for `http` -and 2376 for `https`. Finally, Unix sockets are supported by using -the scheme `unix` together with the filesystem path to the unix socket. -The discovery sequence used by the docker-maven-plugin to determine -the URL is: - -. value of *dockerHost* (`docker.host`) -. the Docker host associated with the docker-machine named in ``, i.e. the `DOCKER_HOST` from `docker-machine env`. See <> for more information about Docker machine support. -. the value of the environment variable `DOCKER_HOST`. -. `unix:///var/run/docker.sock` if it is a readable socket. -| `docker.host` - -| *image* -| In order to temporarily restrict the operation of plugin goals this configuration option can be used. Typically this will be set via the system property `docker.image` when Maven is called. The value can be a single image name (either its alias or full name) or it can be a comma separated list with multiple image names. Any name which doesn't refer an image in the configuration will be ignored. -| `docker.image` - -| *machine* -| Docker machine configuration. See <> for possible values -| - -| [[build-mode]] *mode* -a| The build mode which can be - -* `kubernetes` : A Docker image will be created by calling a Docker daemon. See <> for details. -* `openshift` : An OpenShift Build will be triggered, which can be either a _Docker binary build_ or a _S2I binary build_, depending on the configuration `buildStrategy`. See <> for details. -* `auto` : The plugin tries to detect the mode by contacting the configured cluster. - -`auto` is the default. (_Because of technical reasons, "kubernetes" is currently the default, but will change to "auto" eventually_) -| `jkube.mode` - -| *maxConnections* -| Number of parallel connections are allowed to be opened to the Docker Host. For parsing log output, a connection needs to be kept open (as well for the wait features), so don't put that number to low. Default is 100 which should be suitable for most of the cases. -| `docker.maxConnections` - -| *access* -| Group of configuration parameters to connect to Kubernetes/OpenShift cluster -| - -| *outputDirectory* -| Default output directory to be used by this plugin. The default value is `target/docker` and is only used for the goal `{plugin}:build`. -| `docker.target.dir` - -| *portPropertyFile* -| Global property file into which the mapped properties should be written to. The format of this file and its purpose are also described in <>. -| - -| *profile* -| Profile to which contains enricher and generators configuration. See <> for details. -| `jkube.profile` - -| *pullSecret* -| The name to use for naming pullSecret to be created to pull the base image in case pulling from a private registry which requires authentication for Openshift. - - The default value for pull registry will be picked from "docker.pull.registry/docker.registry". -| `jkube.build.pullSecret` - -| *registry* -| Specify globally a registry to use for pulling and pushing images. See <> for details. -| `docker.registry` - -| *resourceDir* -| Directory where jkube.resources are stored. This is also the directory where a custom profile is looked up. Default is `src/main/jkube`. -| `jkube.resourceDir` - -| *environment* -| Environment name where resources are placed. For example, if you set this property to dev and resourceDir is the default one, JKube will look at src/main/jkube/dev. If not set then root `resourceDir` directory is used. -| `jkube.environment` - -| *skip* -| With this parameter the execution of this plugin can be skipped completely. -| `docker.skip` - -| *skipBuild* -| If set not images will be build (which implies also _skip.tag_) with `{plugin}:build` -| `docker.skip.build` - -| *skipBuildPom* -| If set the build step will be skipped for modules of type `pom`. If not set, then by default projects of type `pom` will be skipped if there are no image configurations contained. -| `jkube.skip.build.pom` - -| *skipTag* -| If set to `true` this plugin won't add any tags to images that have been built with `{plugin}:build` -| `docker.skip.tag` - -| *skipMachine* -| Skip using docker machine in any case -| `docker.skip.machine` - -| *sourceDirectory* -| Default directory that contains the assembly descriptor(s) used by the plugin. The default value is `src/main/docker`. This option is only relevant for the `{plugin}:build` goal. -| `docker.source.dir` - -| *verbose* -| Boolean attribute for switching on verbose output like the build steps when doing a Docker build. Default is `false` -| `docker.verbose` -|=== - -=== Kubernetes Access Configuration - -You can configure parameters to define how plugin is going to connect to Kubernetes cluster instead of relying on default parameters. - -[source, xml] ----- - - - - - - - - ----- - -[cols="1,5,1"] -|=== -| Element | Description | Property (System property or Maven property) - -| *username* -| Username on which to operate -| `jkube.username` - -| *password* -| Password on which to operate -| `jkube.password` - -| *namespace* -| Namespace on which to operate -| `jkube.namespace` - -| *masterUrl* -| Master URL on which to operate -| `jkube.masterUrl` - -| *apiVersion* -| Api version on which to operate -| `jkube.apiVersion` - -| *caCertFile* -| CaCert File on which to operate -| `jkube.caCertFile` - -| *caCertData* -| CaCert Data on which to operate -| `jkube.caCertData` - -| *clientCertFile* -| Client Cert File on which to operate -| `jkube.clientCertFile` - -| *clientCertData* -| Client Cert Data on which to operate -| `jkube.clientCertData` - -| *clientKeyFile* -| Client Key File on which to operate -| `jkube.clientKeyFile` - -| *clientKeyData* -| Client Key Data on which to operate -| `jkube.clientKeyData` - -| *clientKeyAlgo* -| Client Key Algorithm on which to operate -| `jkube.clientKeyAlgo` - -| *clientKeyPassphrase* -| Client Key Passphrase on which to operate -| `jkube.clientKeyPassphrase` - -| *trustStoreFile* -| Trust Store File on which to operate -| `jkube.trustStoreFile` - -| *trustStorePassphrase* -| Trust Store Passphrase on which to operate -| `jkube.trustStorePassphrase` - -| *keyStoreFile* -| Key Store File on which to operate -| `jkube.keyStoreFile` - -| *keyStorePassphrase* -| Key Store Passphrase on which to operate -| `jkube.keyStorePassphrase` -|=== - -=== Image Configuration - -The configuration how images should be created a defined in a dedicated `` sections. These are specified for each image within the `` element of the configuration with one `` element per image to use. - -The `` element can contain the following sub elements: - -include::../../image/_configuration.adoc[] - -The `` section is mandatory and is explained in <>. - -.Example for -[source,xml] ----- - - .... - - - %g/docker-demo:0.1 - service - .... - - - .... - - - ----- -<1> One or more ``` definitions -<2> The Docker image name used when creating the image. -<3> An alias which can be used in other parts of the plugin to reference to this image. This alias must be unique. -<4> A `` section as described in <> - - -[[build-configuration]] -=== Build Configuration - -include::../../build/_overview.adoc[] - -include::../../build/_configuration.adoc[] - -[[build-assembly]] -=== Assembly - -include::../../build/_assembly.adoc[] - -[[misc-env]] -=== Environment and Labels - -include::../../misc/_env.adoc[] - -[[misc-startup]] -=== Startup Arguments - -include::../../misc/_startup.adoc[] - -INFO:: Startup arguments are not used in S2I builds - -[[build-buildargs]] -=== Build Args - -include::../../build/_buildargs.adoc[] diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-push.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-push.adoc deleted file mode 100644 index 9f6da4e544..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-push.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[[oc:push]] -== *oc:push* - -WARNING: Section needs review and rearrangements - -include::../../push/_overview.adoc[] - -include::../../push/_configuration.adoc[] diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-resource.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-resource.adoc deleted file mode 100644 index 83e2e2ec6d..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-resource.adoc +++ /dev/null @@ -1,315 +0,0 @@ -[[oc:resource]] -== *oc:resource* - -This goal generates OpenShift 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`. Generated -resources are in `target/classes/META-INF/jkube/openshift` directory. - -[[resource-labels-annotations]] -=== Labels and Annotations - -Labels and annotations can be easily added to any resource object. This is best explained by an example. - - -.Example for label and annotations -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - ... - - ... - - - - - organisation - unesco - - - - - database - mysql - - - persistent - true - - - - ... - - - ... - - - ... - - - - - ... - - - https://gist.githubusercontent.com/lordofthejars/ac2823cec7831697d09444bbaa76cd50/raw/e4b43f1b6494766dfc635b5959af7730c1a58a93/deployment.yaml - - - - ----- -<1> `` section with `` contains labels which should be applied to objects of various kinds -<2> Within `` labels which should be applied to *every* object can be specified -<3> `` labels are used to label services -<4> `` labels are for replica set and replication controller -<5> `` holds labels for pod specifications in replication controller, replica sets and deployments -<6> `` is for labels on deployments (kubernetes) and deployment configs (openshift) -<7> The subelements are also available for specifying annotations. -<8> `` you can set location of fragments as `URL`. - -Labels and annotations can be specified in free form as a map. In this map the element name is the name of the label or annotation respectively, whereas the content is the value to set. - -The following subelements are possible for `` and `` : - -.Label and annotation configuration -[cols="1,6"] -|=== -| Element | Description - -| *all* -| All entries specified in the `` sections are applied to all resource objects created. This also implies build object like image stream and build configs which are created implicitely for an <>. - -| *deployment* -| Labels and annotations applied to `Deployment` (for Kubernetes) and `DeploymentConfig` (for OpenShift) objects - - -| *pod* -| Labels and annotations applied pod specification as used in `ReplicationController`, `ReplicaSets`, `Deployments` and `DeploymentConfigs` objects. - - -| *replicaSet* -| Labels and annotations applied to `ReplicaSet` and `ReplicationController` objects. - -| *service* -| Labels and annotations applied to `Service` objects. -|=== - -[[resource-secrets]] -=== Secrets - - -Once you've configured some docker registry credentials into `~/.m2/setting.xml`, as explained in the -<> section, you can create Kubernetes secrets from a server declaration. - -**XML configuration** - - -You can create a secret using xml configuration in the `pom.xml` file. It should contain the following fields: - -[cols="1,1,6"] -|=== -|key |required |description - -|**dockerServerId** -|`true` -|the server id which is configured in -`~/.m2/setting.xml` - -|**name** -|`true` -|this will be used as name of the kubernetes secret resource - -|**namespace** -|`false` -|the secret resource will be applied to the specific -namespace, if provided -|=== - -This is best explained by an example. - -.Example for XML configuration - -[source,xml] ----- - - docker.io - ----- - -[source,xml] ----- - - - - - ${docker.registry} - mydockerkey - - - - ----- - -**Yaml fragment with annotation** - - -You can create a secret using a yaml fragment. You can reference the docker server id with an annotation -`maven.jkube.io/dockerServerId`. The yaml fragment file should be put under -the `src/main/jkube/` folder. - -.Example - -[source,yaml] ----- -apiVersion: v1 -kind: Secret -metadata: - name: mydockerkey - namespace: default - annotations: - maven.jkube.io/dockerServerId: ${docker.registry} -type: kubernetes.io/dockercfg ----- - -[[resource-validation]] -=== Resource Validation -Resource goal also validates the generated resource descriptors using API specification of https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json[Kubernetes]. - -.Validation Configuration -[cols="1,6,1"] -|=== -| Configuration | Description | Default - -| *jkube.skipResourceValidation* -| If value is set to `true` then resource validation is skipped. This may be useful if resource validation is failing for some reason but you still want to continue the deployment. -| `false` - -| *jkube.failOnValidationError* -| If value is set to `true` then any validation error will block the plugin execution. A warning will be printed otherwise. -| `false` - -|=== - -[[resource-route-generation]] -=== Route Generation - -When the `oc:resource` goal is run, an OpenShift https://docs.openshift.org/latest/architecture/networking/routes.html[Route] descriptor (`route.yml`) will also be generated along the service if an OpenShift cluster is targeted. -If you do not want to generate a Route descriptor, you can set the `jkube.openshift.generateRoute` property to `false`. - -.Route Generation Configuration -[cols="1.6.1"] -|=== -| Configuration | Description | Default - -| *jkube.openshift.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`. -| `true` -|=== - -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 - openshift-maven-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 ----- - -In case both the label and the property have been set with conflicting values, precedence will be given to the property value, so if you set the label to `true` but set the property to `false` then no Route descriptor will be generated because precedence will be given to the property value. - -[[Supported-Properties-Resource]] -=== Supported Properties for Resource goal - -.Options available with resource goal -[cols="1.6.3"] -|=== -| Element | Description | Property(System property or maven property) - -| *enableAutomaticTrigger* -| If the value is set to `false` then automatic deployments would be disabled. Defaults to `true` -| `jkube.openshift.enableAutomaticTrigger` - -| *skipHealthCheck* -| Whether to skip health checks addition in generated resources or not. Defaults to `false` -| `jkube.skipHealthCheck` - -| *deployTimeoutSeconds* -| The OpenShift deploy timeout in seconds. Defaults to `3600` -| `jkube.openshift.deployTimeoutSeconds` - -| *imageChangeTrigger* -| Add ImageChange triggers to DeploymentConfigs when on openshift. Defaults to `true` -| `jkube.openshift.imageChangeTrigger` - -| *trimImageInContainerSpec* -| If set to true it would set the container image reference to "", this is done to handle weird behavior of Openshift 3.7 in which subsequent rollouts lead to ImagePullErr. Defaults to `false` -| `jkube.openshift.trimImageInContainerSpec` - -| *enrichAllWithImageChangeTrigger* -| Adds ImageChangeTriggers with respect to all containers specified inside DeploymentConfig. Defaults to `false` -| `jkube.openshift.enrichAllWithImageChangeTrigger` - -| *profile* -| Profile to use. A profile contains the enrichers and generators to use as well as their configuration. Profiles are looked up in the classpath and can be provided as yaml files. Defaults to `default` -| `jkube.profile` - -| *sidecar* -| Whether to enable sidecar behavior or not. By default pod specs are merged into main application container. Defaults to `false` -| `jkube.sidecar` - -| *workDir* -| The JKube working directory. Defaults to `${project.build.directory}/jkube` -| `jkube.workDir` - -| *environment* -| Environment name where resources are placed. For example, if you set this property to dev and resourceDir is the default one, plugin will look at `src/main/jkube/dev`. Defaults to `null` -| `jkube.environment` - -| *useProjectClassPath* -| Should we use the project's compile time classpath to scan for additional enrichers/generators. Defaults to `false` -| `jkube.useProjectClassPath` - -| *resourceDir* -| Folder where to find project specific files. Defaults to `${basedir}/src/main/jkube` -| `jkube.resourceDir` - -| *targetDir* -| The generated Kubernetes manifests. Defaults to `${project.build.outputDirectory}/META-INF/jkube` -| `jkube.targetDir` - -| *resourceType* -| The artifact type for attaching the generated resource file to the project. Can be either 'json' or 'yaml'. Defaults to `yaml` -| `jkube.resourceType` - -| *mergeWithDekorate* -| When resource generation is delegated to Dekorate, should JKube resources be merged with Dekorate's. Defaults to `false` -| `jkube.mergeWithDekorate` - -| *skipResource* -| Skip resource generation. Defaults to `false` -| `jkube.skip.resource` - -|=== - -[[Supported-Properties]] diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_goals.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_goals.adoc deleted file mode 100644 index d44ea00298..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_goals.adoc +++ /dev/null @@ -1,8 +0,0 @@ -[[goals-overview-develop]] -# Development Goals - -include::_jkube-deploy.adoc[] -include::_jkube-undeploy.adoc[] -include::_jkube-log.adoc[] -include::_jkube-debug.adoc[] -include::_jkube-watch.adoc[] diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-debug.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-debug.adoc deleted file mode 100644 index c9901aa48c..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-debug.adoc +++ /dev/null @@ -1,98 +0,0 @@ - -[[oc:debug]] -== *oc:debug* - -This goal enables debugging in your Java app and then port forwards from localhost to the latest running pod of your app so that you can easily debug your app from your Java IDE. - -[source, sh] ----- -mvn oc:debug ----- - -Then follow the on screen instructions. - -The default debug port is `5005`. If you wish to change the local port to use for debugging then pass in the `jkube.debug.port` parameter: - -[source, sh] ----- -mvn oc:debug -Djkube.debug.port=8000 ----- - -Then in your IDE you start a Remote debug execution using this remote port using localhost and you should be able to set breakpoints and step through your code. - -This lets you debug your apps while they are running inside a Kubernetes cluster - for example if you wish to debug a REST endpoint while another pod is invoking it. - -Debug is enabled via the `JAVA_ENABLE_DEBUG` environment variable being set to `true`. This environment variable is used for all the standard Java docker images used by Spring Boot, flat classpath and executable JAR projects and Wildfly Swarm. If you use your own custom docker base image you may wish to also respect this environment variable too to enable debugging. - -### Speeding up debugging - -By default the `oc:debug` goal has to edit your Deployment to enable debugging then wait for a pod to start. It might be in development you frequently want to debug things and want to speed things up a bit. - -If so you can enable debug mode for each build via the `jkube.debug.enabled` property. - -e.g. you can pass this property on the command line: - -[source, sh] ----- -mvn oc:deploy -Djkube.debug.enabled=true ----- - -Or you can add something like this to your `~/.m2/settings.xml` file so that you enable debug mode for all maven builds on your laptop by using a profile : - -[source, xml] ----- - - - - - enable-debug - - true - - - true - - ----- - -Then whenever you type the `oc:debug` goal there is no need for the maven goal to edit the `Deployment` and wait for a pod to restart; we can immediately start debugging when you type: - -[source, sh] ----- -mvn oc:debug ----- - -### Debugging with suspension - -The `oc:debug` goal allows to attach a remote debugger to a running container, but the application is free to execute when the debugger is not attached. -In some cases, you may want to have complete control on the execution, e.g. to investigate the application behavior at startup. This can be done using the `jkube.debug.suspend` flag: - -[source, sh] ----- -mvn oc:debug -Djkube.debug.suspend ----- - -The suspend flag will set the `JAVA_DEBUG_SUSPEND` environment variable to `true` and `JAVA_DEBUG_SESSION` to a random number in your deployment. -When the `JAVA_DEBUG_SUSPEND` environment variable is set, standard docker images will use `suspend=y` in the JVM startup options for debugging. - -The `JAVA_DEBUG_SESSION` environment variable is always set to a random number (each time you run the debug goal with the suspend flag) in order to tell Kubernetes to restart the pod. -The remote application will start only after a remote debugger is attached. You can use the remote debugging feature of your IDE to connect (on `localhost`, port `5005` by default). - -WARNING: The `jkube.debug.suspend` flag will disable readiness probes in the Kubernetes deployment in order to start port-forwarding during the early phases of application startup - -[[Supported-Properties-Debug]] -=== Supported Properties For Debug Goal - -.Options available with debug goal -[cols="1.6.3"] -|=== -| Element | Description | Property(System property or maven property) - -| *debugPort* -| Default port available for debugging your application inside Kubernetes. Defaults to `5005` -| `jkube.debug.port` - -| *debugSuspend* -| Disables readiness probes in Kubernetes Deployment in order to start port forwarding during early phases of application startup. Defaults to `false` -| `jkube.debug.suspend` -|=== diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-deploy.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-deploy.adoc deleted file mode 100644 index a01a879963..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-deploy.adoc +++ /dev/null @@ -1,59 +0,0 @@ - -[[oc:deploy]] -== *oc:deploy* - -This is the main goal for building your docker image, generating the kubernetes resources and deploying them into the cluster (insofar your pom.xml is set up correct; keep reading :)). - -[source,sh,subs="attributes"] ----- -mvn oc:deploy ----- - -This goal is designed to run <> and <> before the deploy **iff* you have the goals bound in your pom.xml: - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - org.eclipse.jkube - openshift-maven-plugin - {version} - - - - - jkube - - resource - build - helm - - - - ----- - - -Effectively this builds your project then invokes these goals: - -* <> -* <> - -By default the behaviour of resource goal is it generates `route.yml` for a service if you have not done any configuration changes. Sometimes there may be case when you want to generate route.yml but do not want to create route resource on OpenShift Cluster. This can be achieved by the following configuration. - -.Example for not generating route resource on your cluster - -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - org.eclipse.jkube - openshift-maven-plugin - {version} - - - - jkube-expose - - - - ----- diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-log.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-log.adoc deleted file mode 100644 index b09a43d741..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-log.adoc +++ /dev/null @@ -1,61 +0,0 @@ - -[[oc:log]] -== *oc:log* - -This goal tails the log of the app that you deployed via the <> goal - -[source, sh] ----- -mvn oc:log ----- - -You can then terminate the output by hitting `Ctrl+C` - -If you wish to get the log of the app and then terminate immediately then try: - -[source, sh] ----- -mvn oc:log -Djkube.log.follow=false ----- - -This lets you pipe the output into grep or some other tool - -[source, sh] ----- -mvn oc:log -Djkube.log.follow=false | grep Exception ----- - -If your app is running in multiple pods you can configure the pod name to log via the `jkube.log.pod` property, otherwise it defaults to the latest pod: - -[source, sh] ----- -mvn oc:log -Djkube.log.pod=foo ----- - -If your pod has multiple containers you can configure the container name to log via the `jkube.log.container` property, otherwise it defaults to the first container: - -[source, sh] ----- -mvn oc:log -Djkube.log.container=foo ----- - -[[Supported-Properties-Log]] -=== Supported Properties for Log goal - -.Options available with log goal -[cols="1.6.3"] -|=== -| Element | Description | Property(System property or Maven property) - -| *logFollow* -| Get follow logs for your application inside Kubernetes. Defaults to `true` -| `jkube.log.follow` - -| *logContainer* -| Get logs of some specific container inside your application Deployment. Defaults to `null` -| `jkube.log.container` - -| *logPod* -| Get logs of some specific pod inside your application Deployment. Defaults to `null` -| `jkube.log.pod` -|=== diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-undeploy.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-undeploy.adoc deleted file mode 100644 index 79c3de58b0..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-undeploy.adoc +++ /dev/null @@ -1,13 +0,0 @@ - -[[oc:undeploy]] -== *oc:undeploy* - -This goal is for deleting the kubernetes resources that you deployed via the <> or <> goals - -It iterates through all the resources generated by the <> goal and deletes them from your current kubernetes cluster. - -[source, sh] ----- -mvn oc:undeploy ----- - diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-watch.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-watch.adoc deleted file mode 100644 index 64013e1857..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/goals/develop/_jkube-watch.adoc +++ /dev/null @@ -1,123 +0,0 @@ - -[[oc:watch]] -== *oc:watch* - -This goal is used to monitor the project workspace for changes and automatically trigger a redeploy of the application -running on Kubernetes. - -In order to use oc:watch for spring-boot, you need to make sure that `devtools` is included in the repacked -archive, as shown in the following listing: ----- - - org.springframework.boot - spring-boot-maven-plugin - - false - - ----- - -Then you need to set a `spring.devtools.remote.secret` in application.properties, as shown in the following example: - ----- -spring.devtools.remote.secret=mysecret ----- - -Before entering the watch mode, this goal must generate the docker image and the Kubernetes resources -(optionally including some development libraries/configuration), -and deploy the app on Kubernetes. Lifecycle bindings should be configured as follows to allow -the generation of such resources. - -.Lifecycle bindings for oc:watch -[source, xml, indent=0] ----- - - org.eclipse.jkube - openshift-maven-plugin - - - - - - - resource - build - - - - ----- - -For any application having `resource` and `build` goals bound to the lifecycle, the following -command can be used to run the watch task. - -[source, bash] ----- -mvn oc:watch ----- - -This plugin supports different watcher providers, enabled automatically if the project satisfies certain conditions. - -Watcher providers can also be configured manually. The <> is a good blueprint, simply replace `` with ``. The configuration is structurally identical. - -[[watcher-spring-boot]] -=== Spring Boot - -This watcher is enabled by default for all Spring Boot projects. It performs the following actions: - -* deploys your application with Spring Boot DevTools enabled -* tails the log of the latest running pod for your application -* watches the local development build of your Spring Boot based application and then triggers a reload of the application when there are changes - -You can try it on any spring boot application via: - -[source, sh] ----- -mvn oc:watch ----- - -Once the goal starts up the spring boot RemoteSpringApplication it will watch for local development changes. - -e.g. if you edit the java code of your app and then build it via something like this: - -[source, sh] ----- -mvn package ----- - -You should see your app reload on the fly in the shell running the <> goal! - -There is also support for LiveReload as well. - - -[[watcher-docker-image]] -=== Docker Image - -This is a generic watcher that can be used in Kubernetes mode only. Once activated, it listens for changes in the project workspace - in order to trigger a redeploy of the application. - -The watcher can be activated e.g. by running this command in another shell: - -[source, sh] ----- -mvn package ----- - -The watcher will detect that the binary artifact has changed and will first rebuild the docker image, -then start a redeploy of the Kubernetes pod. - -It uses the watch feature of the https://dmp.jkube.io/#docker:watch[docker-maven-plugin] under the hood. - -[[Supported-Properties-Watch]] -=== Supported Properties for Watch goal - -.Options available with watch goal -[cols="1.6.3"] -|=== -| Element | Description | Property(System property or Maven property) - -| *kubernetesManifest* -| The generated kubernetes YAML file. Defaults to `${basedir}/target/classes/META-INF/jkube/kubernetes.yml` -| `jkube.kubernetesManifest` - -|=== \ No newline at end of file diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/image/_configuration.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/image/_configuration.adoc deleted file mode 100644 index b70db0efaf..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/image/_configuration.adoc +++ /dev/null @@ -1,31 +0,0 @@ - -[[config-image]] -.Image Configuration -[cols="1,5"] -|=== -| Element | Description - -| *name* -| Each `` configuration has a mandatory, unique docker -repository _name_. This can include registry and tag parts, but also placeholder parameters. See below for a detailed explanation. - -| *alias* -| Shortcut name for an image which can be used for -identifying the image within this configuration. This is used when -linking images together or for specifying it with the global *image* configuration element. - -| <> -| Registry to use for this image. If the `name` already contains a registry this takes precedence. See <> for more details. - -| <> -| Element which contains all the configuration aspects when doing a <<{plugin}:build>>. This element can be omitted if the image is only pulled from a registry e.g. as support for integration tests like database images. - -ifeval::["{plugin}" == "docker"] -| <> -| Element which describe how containers should be -created and run when <<{plugin}:start>> is called. If this image is only used a _data container_ (i.e. is supposed only to be mounted as a volume) for exporting artifacts via volumes this section can be missing. - -| <> -| Specification of external configuration as an alternative to this XML based configuration with `` and ``. It contains a `` element specifying the handler for getting the configuration. See <> for details. -endif::[] -|=== diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/image/_example.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/image/_example.adoc deleted file mode 100644 index 2e11299cc3..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/image/_example.adoc +++ /dev/null @@ -1,16 +0,0 @@ - -.Example -[source,xml] ----- - - .... - - - %g/docker-demo:0.1 - service - .... - .... - - - ----- diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/image/_naming.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/image/_naming.adoc deleted file mode 100644 index 0577211684..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/image/_naming.adoc +++ /dev/null @@ -1,65 +0,0 @@ -[[image-name]] -## Image Names -When specifying the image name in the configuration with the `` field you can use several placeholders which are replaced during runtime by this plugin. In addition you can use regular Maven properties which are resolved by Maven itself. - -[cols="1,5"] -|=== -| Placeholder | Description - -| *%g* -| The last part of the Maven group name, sanitized so that it can be used as username on GitHub. Only the part after the last dot is used. E.g. for a group id `io.fabric8` this placeholder would insert `fabric8` - -| *%a* -| A sanitized version of the artefact id so that it can be used as part of an Docker image name. I.e. it is converted to all lower case (as required by Docker) - -| *%v* -| The project version. Synonym to `${project.version}` - -| *%l* -| If the project version ends with `-SNAPSHOT` then this placeholder is `latest`, otherwise its the full version (same as `%v`) - -| *%t* -| If the project version ends with `-SNAPSHOT` this placeholder resolves to `snapshot-` where timestamp has the date format `yyMMdd-HHmmss-SSSS` (eg `snapshot-`). This feature is especially useful during development in oder to avoid conflicts when images are to be updated which are still in use. You need to take care yourself of cleaning up old images afterwards, though. -|=== - -ifeval::["{plugin}" == "docker"] -[[container-name]] -## Container Names - -Similar to image name placeholders, for starting and stopping containers and alternate set of placeholders can be configured in order to the name the containers to create. - -These placeholders can be used in the top-level configuration value `containerNamePattern` which is used globally for every container that is created. -This global pattern can be overwritten individually by each image's <> configuration. -If neither is given, then by default the pattern `%n-%i` is used. - -When specifying the container name pattern the following placeholders can be used: - -[cols="1,5"] -|=== -| Placeholder | Description - -| *%a* -| The `` of an image which must be set. The alias is set in the top-level image configuration - -| *%n* -| A sanitized version of the imag's short name from which this container is created. "Sanitized" means that any non letter, digit, dot or dash is replaced by an underscore. - -| *%t* -| The build time stamp. This is the timestamp which created during the building of an image and locally cached. A rebuild of the image will update the timestamp. - -| *%i* -| An index which is incremented if a container has already been created. With this parameter it is easily possible to have multiple, similar containers. See the example below for more details. - -|=== - -You can combine the placeholders in any combination and will be resolved during `docker:start`, `docker:stop` and `docker:watch`. - -The following example is using a container name pattern of `%n-%i` which is also the default. -Given an image `fabric8io/dmp-sample-jolokia:latest`, then during `mvn docker:start` a container with the name `dmp-sample-jolokia-1` is first tried. -If there is already a container with this name, then `dmp-sample-jolokia-2` is the second attempt. -This goes on until a "free" name is found. - -Similar, when stopping containers with `mvn docker:stop` then only the container with the highest index is stopped. -However, if you don't use an index via `%i` then _all_ containers started with `docker:start` are stopped. -Use `mvn docker:stop -Ddocker.allContainers` to also stop every container named via a `%i` pattern. -endif::[] diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/misc/_env.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/misc/_env.adoc deleted file mode 100644 index ae12088467..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/misc/_env.adoc +++ /dev/null @@ -1,28 +0,0 @@ - - -When creating a container one or more environment variables can be set via configuration with the `env` parameter - -.Example -[source,xml] ----- - - /opt/jdk8 - -Djava.security.egd=file:/dev/./urandom - ----- - -If you put this configuration into profiles you can easily create various test variants with a single image (e.g. by switching the JDK or whatever). - -It is also possible to set the environment variables from the outside of the plugin's configuration with the parameter `envPropertyFile`. If given, this property file is used to set the environment variables where the keys and values specify the environment variable. Environment variables specified in this file override any environment variables specified in the configuration. - -Labels can be set inline the same way as environment variables: - -.Example -[source,xml] ----- - - foo - ${project.version} - ${project.artifactId} - ----- diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/misc/_startup.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/misc/_startup.adoc deleted file mode 100644 index 6d05398933..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/misc/_startup.adoc +++ /dev/null @@ -1,74 +0,0 @@ - - -Using `entryPoint` and `cmd` it is possible to specify the https://docs.docker.com/reference/builder/#entrypoint[entry point] -or https://docs.docker.com/reference/builder/#cmd[cmd] for a container. - -The difference is, that an `entrypoint` is the command that always be executed, with the `cmd` as argument. If no `entryPoint` is provided, it defaults to `/bin/sh -c` so any `cmd` given is executed with a shell. The arguments given to `docker run` are always given as arguments to the -`entrypoint`, overriding any given `cmd` option. On the other hand if no extra arguments are given to `docker run` the default `cmd` is used as argument to `entrypoint`. - -**** -See this http://stackoverflow.com/questions/21553353/what-is-the-difference-between-cmd-and-entrypoint-in-a-dockerfile[stackoverflow question] for a detailed explanation. -**** - -An entry point or command can be specified in two alternative formats: - -.Entrypoint and Command Configuration -[cols="1,5"] -|=== -| Mode | Description - -| *shell* -| Shell form in which the whole line is given to `shell -c` for interpretation. - -| *exec* -| List of arguments (with inner ``) arguments which will be given to the `exec` call directly without any shell interpretation. -|=== - -Either shell or params should be specified. - -.Example -[source,xml] ----- - - - java -jar $HOME/server.jar - ----- - -or - -.Example -[source,xml] ----- - - - - java - -jar - /opt/demo/server.jar - - ----- - -This can be formulated also more dense with: - -.Example -[source,xml] ----- - -java -jar $HOME/server.jar ----- - -or - -.Example -[source,xml] ----- - - - java - -jar - /opt/demo/server.jar - ----- - diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/push/_configuration.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/push/_configuration.adoc deleted file mode 100644 index 047b690c55..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/push/_configuration.adoc +++ /dev/null @@ -1,24 +0,0 @@ - - -.Push options -[cols="1,5,1"] -|=== -| Element | Description | Property - -| *skipPush* -| If set to `true` the plugin won't push any images that have been built. -| `docker.skip.push` - -| *skipTag* -| If set to `true` this plugin won't push any tags -| `docker.skip.tag` - -| *pushRegistry* -| The registry to use when pushing the image. See <> for -more details. -| `docker.push.registry` - -| *retries* -| How often should a push be retried before giving up. This useful for flaky registries which tend to return 500 error codes from time to time. The default is 0 which means no retry at all. -| `docker.push.retries` -|=== diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/inc/push/_overview.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/inc/push/_overview.adoc deleted file mode 100644 index d2ac97e453..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/inc/push/_overview.adoc +++ /dev/null @@ -1,5 +0,0 @@ - -This goal uploads images to the registry which have a `` configuration section. The images to push can be restricted with -the global option `filter` (see <> for details). The registry to push is by default `docker.io` but can be specified as part of the images's `name` name the Docker way. E.g. `docker.test.org:5000/data:1.5` will push the image `data` with tag `1.5` to the registry `docker.test.org` at port `5000`. Security information (i.e. user and password) can be specified in multiple ways as described in section <>. - -By default a progress meter is printed out on the console, which is omitted when using Maven in batch mode (option `-B`). A very simplified progress meter is provided when using no color output (i.e. with `-Ddocker.useColor=false`). diff --git a/openshift-maven-plugin/doc/src/main/asciidoc/index.adoc b/openshift-maven-plugin/doc/src/main/asciidoc/index.adoc deleted file mode 100644 index 0d08963556..0000000000 --- a/openshift-maven-plugin/doc/src/main/asciidoc/index.adoc +++ /dev/null @@ -1,43 +0,0 @@ -= org.eclipse.jkube/openshift-maven-plugin -Roland Huß, James Strachan; -:revnumber: {version} -:revdate: {localdate} -:toc: macro -:toclevels: 3 -:toc-title: openshift-maven-plugin -:doctype: book -:icons: font -:plugin: jkube -:plugindir: ../../../../../plugin - -ifndef::ebook-format[:leveloffset: 1] - -(C) 2019 The original authors. - -ifdef::basebackend-html[toc::[]] - -:numbered: - -include::inc/_introduction.adoc[] - -include::inc/_compatibility.adoc[] - -include::inc/_installation.adoc[] - -include::inc/goals/_goals.adoc[] - -include::inc/_generator.adoc[] -include::inc/_enricher.adoc[] -include::inc/_profiles.adoc[] - -include::inc/_access.adoc[] - -include::inc/_registry.adoc[] -include::inc/_authentication.adoc[] -include::inc/_volumes.adoc[] -include::inc/_integrations.adoc[] - -include::inc/_faq.adoc[] - -include::inc/_appendix.adoc[] - diff --git a/openshift-maven-plugin/doc/src/main/java/org/eclipse/jkube/maven/doc/ClasspathIncludeExtension.java b/openshift-maven-plugin/doc/src/main/java/org/eclipse/jkube/maven/doc/ClasspathIncludeExtension.java deleted file mode 100644 index d9b0c9cc9b..0000000000 --- a/openshift-maven-plugin/doc/src/main/java/org/eclipse/jkube/maven/doc/ClasspathIncludeExtension.java +++ /dev/null @@ -1,30 +0,0 @@ -/** - * Copyright (c) 2019 Red Hat, Inc. - * This program and the accompanying materials are made - * available under the terms of the Eclipse Public License 2.0 - * which is available at: - * - * https://www.eclipse.org/legal/epl-2.0/ - * - * SPDX-License-Identifier: EPL-2.0 - * - * Contributors: - * Red Hat, Inc. - initial API and implementation - */ -package org.eclipse.jkube.maven.doc; - -import org.asciidoctor.Asciidoctor; -import org.asciidoctor.extension.JavaExtensionRegistry; -import org.asciidoctor.jruby.extension.spi.ExtensionRegistry; - -/** - * @author roland - * @since 11/07/16 - */ -public class ClasspathIncludeExtension implements ExtensionRegistry { - @Override - public void register(Asciidoctor asciidoctor) { - final JavaExtensionRegistry javaExtensionRegistry = asciidoctor.javaExtensionRegistry(); - javaExtensionRegistry.includeProcessor(new ClasspathIncludeProcessor()); - } -} diff --git a/openshift-maven-plugin/doc/src/main/java/org/eclipse/jkube/maven/doc/ClasspathIncludeProcessor.java b/openshift-maven-plugin/doc/src/main/java/org/eclipse/jkube/maven/doc/ClasspathIncludeProcessor.java deleted file mode 100644 index 678f77a66f..0000000000 --- a/openshift-maven-plugin/doc/src/main/java/org/eclipse/jkube/maven/doc/ClasspathIncludeProcessor.java +++ /dev/null @@ -1,76 +0,0 @@ -/** - * Copyright (c) 2019 Red Hat, Inc. - * This program and the accompanying materials are made - * available under the terms of the Eclipse Public License 2.0 - * which is available at: - * - * https://www.eclipse.org/legal/epl-2.0/ - * - * SPDX-License-Identifier: EPL-2.0 - * - * Contributors: - * Red Hat, Inc. - initial API and implementation - */ -package org.eclipse.jkube.maven.doc; - -import java.io.BufferedReader; -import java.io.IOException; -import java.io.InputStream; -import java.io.InputStreamReader; -import java.util.ArrayList; -import java.util.List; -import java.util.Map; - -import org.asciidoctor.ast.Document; -import org.asciidoctor.extension.IncludeProcessor; -import org.asciidoctor.extension.PreprocessorReader; - -/** - * @author roland - * @since 11/07/16 - */ -public class ClasspathIncludeProcessor extends IncludeProcessor { - - @Override - public boolean handles(String target) { - return target.startsWith("classpath:"); - } - - @Override - public void process(Document document, - PreprocessorReader reader, - String target, - Map attributes) { - List content = readContent(target); - for (int i = content.size() - 1; i >= 0; i--) { - String line = content.get(i); - // See also https://github.com/asciidoctor/asciidoctorj/issues/437#issuecomment-192669617 - // Seems to be a hack to avoid mangling of paragraphes - if (line.trim().equals("")) { - line = " "; - } - reader.push_include(line, target, target, 1, attributes); - } - } - - private List readContent(String target) { - String resourcePath = target.substring("classpath:".length()); - InputStream is = getClass().getResourceAsStream(resourcePath); - if (is == null) { - throw new IllegalArgumentException("No resource " + target + " could be found in the classpath"); - } - - BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(is)); - String line; - List lines = new ArrayList<>(); - try { - while ((line = bufferedReader.readLine()) != null) { - lines.add(line); - } - bufferedReader.close(); - } catch (IOException e) { - throw new IllegalArgumentException(e); - } - return lines; - } -} diff --git a/openshift-maven-plugin/doc/src/main/resources/META-INF/services/org.asciidoctor.jruby.extension.spi.ExtensionRegistry b/openshift-maven-plugin/doc/src/main/resources/META-INF/services/org.asciidoctor.jruby.extension.spi.ExtensionRegistry deleted file mode 100644 index 6dab154089..0000000000 --- a/openshift-maven-plugin/doc/src/main/resources/META-INF/services/org.asciidoctor.jruby.extension.spi.ExtensionRegistry +++ /dev/null @@ -1,15 +0,0 @@ -# -# Copyright (c) 2019 Red Hat, Inc. -# This program and the accompanying materials are made -# available under the terms of the Eclipse Public License 2.0 -# which is available at: -# -# https://www.eclipse.org/legal/epl-2.0/ -# -# SPDX-License-Identifier: EPL-2.0 -# -# Contributors: -# Red Hat, Inc. - initial API and implementation -# - -org.eclipse.jkube.maven.doc.ClasspathIncludeExtension \ No newline at end of file diff --git a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/build/OpenshiftApplyMojo.java b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/build/OpenshiftApplyMojo.java index 346b528fdb..c4f33e94f8 100644 --- a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/build/OpenshiftApplyMojo.java +++ b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/build/OpenshiftApplyMojo.java @@ -37,7 +37,7 @@ public class OpenshiftApplyMojo extends ApplyMojo { @Override public File getManifest(KubernetesClient kubernetesClient) { - return OpenShift.getOpenShiftManifest(kubernetesClient, super.getManifest(kubernetesClient), openshiftManifest); + return OpenShift.getOpenShiftManifest(kubernetesClient, getKubernetesManifest(), openshiftManifest); } @Override diff --git a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/build/OpenshiftBuildMojo.java b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/build/OpenshiftBuildMojo.java index 73a63ce919..2d5e92a54c 100644 --- a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/build/OpenshiftBuildMojo.java +++ b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/build/OpenshiftBuildMojo.java @@ -37,6 +37,13 @@ @Mojo(name = "build", defaultPhase = LifecyclePhase.PRE_INTEGRATION_TEST, requiresDependencyResolution = ResolutionScope.COMPILE) public class OpenshiftBuildMojo extends BuildMojo { + /** + * Whether to perform a Kubernetes build (i.e. against a vanilla Docker daemon) or + * an OpenShift build (with a Docker build against the OpenShift API server. + */ + @Parameter(property = "jkube.mode") + protected RuntimeMode configuredRuntimeMode = RuntimeMode.DEFAULT; + /** * OpenShift build mode when an OpenShift build is performed. * Can be either "s2i" for an s2i binary build mode or "docker" for a binary @@ -59,11 +66,23 @@ public class OpenshiftBuildMojo extends BuildMojo { @Parameter(property = "jkube.s2i.buildNameSuffix", defaultValue = "-s2i") protected String s2iBuildNameSuffix; + /** + * Allow the ImageStream used in the S2I binary build to be used in standard + * Kubernetes resources such as Deployment or StatefulSet. + */ + @Parameter(property = "jkube.s2i.imageStreamLookupPolicyLocal", defaultValue = "true") + protected boolean s2iImageStreamLookupPolicyLocal = true; + @Override protected boolean isDockerAccessRequired() { return runtimeMode == kubernetes; } + @Override + public RuntimeMode getConfiguredRuntimeMode() { + return configuredRuntimeMode; + } + public List customizeConfig(List configs) { if (runtimeMode == RuntimeMode.openshift) { log.info("Using [[B]]OpenShift[[B]] build with strategy [[B]]%s[[B]]", buildStrategy.getLabel()); @@ -76,7 +95,8 @@ protected BuildServiceConfig.BuildServiceConfigBuilder buildServiceConfigBuilder return super.buildServiceConfigBuilder() .openshiftBuildStrategy(buildStrategy) .openshiftPullSecret(openshiftPullSecret) - .s2iBuildNameSuffix(s2iBuildNameSuffix); + .s2iBuildNameSuffix(s2iBuildNameSuffix) + .s2iImageStreamLookupPolicyLocal(s2iImageStreamLookupPolicyLocal); } @Override diff --git a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftDebugMojo.java b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftDebugMojo.java index db3af4801d..e128183061 100644 --- a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftDebugMojo.java +++ b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftDebugMojo.java @@ -37,7 +37,7 @@ public class OpenshiftDebugMojo extends DebugMojo { @Override public File getManifest(KubernetesClient kubernetesClient) { - return OpenShift.getOpenShiftManifest(kubernetesClient, super.getManifest(kubernetesClient), openshiftManifest); + return OpenShift.getOpenShiftManifest(kubernetesClient, getKubernetesManifest(), openshiftManifest); } @Override diff --git a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftDeployMojo.java b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftDeployMojo.java index e78af89693..5f54fc1284 100644 --- a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftDeployMojo.java +++ b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftDeployMojo.java @@ -44,7 +44,7 @@ public class OpenshiftDeployMojo extends DeployMojo { @Override public File getManifest(KubernetesClient kubernetesClient) { - return OpenShift.getOpenShiftManifest(kubernetesClient, super.getManifest(kubernetesClient), openshiftManifest); + return OpenShift.getOpenShiftManifest(kubernetesClient, getKubernetesManifest(), openshiftManifest); } @Override diff --git a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftLogMojo.java b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftLogMojo.java index 92350e2aef..89b22b89c9 100644 --- a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftLogMojo.java +++ b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftLogMojo.java @@ -47,7 +47,7 @@ public class OpenshiftLogMojo extends LogMojo { @Override public File getManifest(KubernetesClient kubernetesClient) { - return OpenShift.getOpenShiftManifest(kubernetesClient, super.getManifest(kubernetesClient), openshiftManifest); + return OpenShift.getOpenShiftManifest(kubernetesClient, getKubernetesManifest(), openshiftManifest); } @Override diff --git a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftUndeployMojo.java b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftUndeployMojo.java index 1775df36f2..9222a9ffaf 100644 --- a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftUndeployMojo.java +++ b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftUndeployMojo.java @@ -66,7 +66,7 @@ protected void applyEntities(KubernetesClient kubernetes, String namespace, Stri @Override public File getManifest(KubernetesClient kubernetesClient) { - return OpenShift.getOpenShiftManifest(kubernetesClient, super.getManifest(kubernetesClient), openshiftManifest); + return OpenShift.getOpenShiftManifest(kubernetesClient, getKubernetesManifest(), openshiftManifest); } @Override diff --git a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftWatchMojo.java b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftWatchMojo.java index 00ecf22072..d74d4ddd69 100644 --- a/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftWatchMojo.java +++ b/openshift-maven-plugin/plugin/src/main/java/org/eclipse/jkube/maven/plugin/mojo/develop/OpenshiftWatchMojo.java @@ -22,6 +22,7 @@ import org.apache.maven.plugins.annotations.ResolutionScope; import org.eclipse.jkube.generator.api.GeneratorContext; import org.eclipse.jkube.kit.config.image.build.OpenShiftBuildStrategy; +import org.eclipse.jkube.kit.config.resource.RuntimeMode; import org.eclipse.jkube.maven.plugin.mojo.OpenShift; import java.io.File; @@ -40,6 +41,13 @@ @Execute(goal = "deploy") public class OpenshiftWatchMojo extends WatchMojo { + /** + * Whether to perform a Kubernetes build (i.e. against a vanilla Docker daemon) or + * an OpenShift build (with a Docker build against the OpenShift API server. + */ + @Parameter(property = "jkube.mode") + protected RuntimeMode configuredRuntimeMode = RuntimeMode.DEFAULT; + /** * OpenShift build mode when an OpenShift build is performed. * Can be either "s2i" for an s2i binary build mode or "docker" for a binary @@ -54,9 +62,14 @@ public class OpenshiftWatchMojo extends WatchMojo { @Parameter(property = "jkube.openshiftManifest", defaultValue = DEFAULT_OPENSHIFT_MANIFEST) private File openshiftManifest; + @Override + public RuntimeMode getConfiguredRuntimeMode() { + return configuredRuntimeMode; + } + @Override public File getManifest(KubernetesClient kubernetesClient) { - return OpenShift.getOpenShiftManifest(kubernetesClient, super.getManifest(kubernetesClient), openshiftManifest); + return OpenShift.getOpenShiftManifest(kubernetesClient, getKubernetesManifest(), openshiftManifest); } @Override diff --git a/openshift-maven-plugin/pom.xml b/openshift-maven-plugin/pom.xml index e85dedf7bd..e585e2228a 100644 --- a/openshift-maven-plugin/pom.xml +++ b/openshift-maven-plugin/pom.xml @@ -32,7 +32,6 @@ plugin it - doc