diff --git a/CHANGELOG.md b/CHANGELOG.md index 88cfa88649..5c3c4a0796 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,6 +33,7 @@ Usage: * Fix #2423: Change default VolumePermissionEnricher's initContainer image from `busybox` to `quay.io/quay/busybox` * Fix #2444: Add support for Spring Boot application properties placeholders * Fix #2456: Add utility class to decompress archive files +* Fix #2465: Add support for `buildpacks` build strategy with opinionated defaults (Zero config) * Fix #2472: Support for Helm Chart.yaml appVersion field defaulting to project version * Fix #2474: Remove Docker-related classes providing unused functionality * Fix #2477: Support for Spring Boot 3.2.0 (and newer) layered jar format diff --git a/gradle-plugin/doc/src/main/asciidoc/inc/_groovy-configuration.adoc b/gradle-plugin/doc/src/main/asciidoc/inc/_groovy-configuration.adoc index 12cf55f1ab..46266027ac 100644 --- a/gradle-plugin/doc/src/main/asciidoc/inc/_groovy-configuration.adoc +++ b/gradle-plugin/doc/src/main/asciidoc/inc/_groovy-configuration.adoc @@ -8,77 +8,15 @@ |==== | Element | Description | Property - | *authConfig* -| Authentication information when pulling from or pushing to Docker registry. There is a dedicated section - <> for how to do security. -| - | <> | Group of configuration parameters to connect to Kubernetes/OpenShift cluster. | -| *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. - -| `jkube.docker.autoPull` - -ifeval::["{task-prefix}" == "oc"] -| *buildOutputKind* -| Allow to specify in which registry to push the container image at the end of the build. -If the output kind is ImageStreamTag, then the image will be pushed to the internal OpenShift registry. -If the output is of type DockerImage, then the name of the output reference will be used as a Docker push specification. -The default value is `ImageStreamTag` - -| `jkube.build.buildOutput.kind` -endif::[] - -| *buildRecreate* -a| If the effective build mode 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` - | *buildSourceDirectory* | 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 `{task-prefix}Build` task. | `jkube.build.source.dir` -| *buildStrategy* -a| Defines what build strategy to choose while building container image. -Possible values are `docker` and `jib` out of which `docker` is default. - -ifeval::["{task-prefix}" == "oc"] -If the effective build mode is `openshift` an additional `s2i` option is available -and selected by default. - -Available strategies for OpenShift are: - -* `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 - -endif::[] -| `jkube.build.strategy` - -| *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. -| `jkube.docker.certPath` - | *createNewResources* | Create new {cluster} resources. @@ -97,31 +35,6 @@ Defaults to `false`. Defaults to `true`. | `jkube.deploy.deletePods` -| *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* (`jkube.docker.host`) -. The Docker host associated with the docker-machine named in ``, i.e. the `DOCKER_HOST` from `docker-machine env`. -. The value of the environment variable `DOCKER_HOST`. -. `unix:///var/run/docker.sock` if it is a readable socket. -| `jkube.docker.host` - -| *filter* -| In order to temporarily restrict the operation of plugin tasks this configuration option can be used. -Typically this will be set via the system property `jkube.image.filter` when Gradle 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. -| `jkube.image.filter` - | *failOnNoKubernetesJson* | Fail if there is no kubernetes json present. @@ -136,17 +49,6 @@ otherwise. | `jkube.failOnValidationError` ifeval::["{task-prefix}" == "oc"] -|*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` - | *ignoreRunningOAuthClients* | Ignore OAuthClients which are already running. OAuthClients are shared across namespaces so we should not try to update or create/delete global oauth clients. @@ -160,17 +62,6 @@ endif::[] Defaults to `false`. | `jkube.deploy.ignoreServices` -| [[image-pull-policy]] *imagePullPolicy* -a| Specify whether images should be pull when looking for base images while building or images for starting. -This property can take the following values (case insensitive): - -* `IfNotPresent`: Automatic download any missing images (default) -* `Never` : Automatic pulling is switched off always -* `Always` : Pull images always even when they already exist locally. - -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 `-Djkube.useColor=false`). -| `jkube.docker.imagePullPolicy` - | *interpolateTemplateParameters* | Interpolate parameter values from `*template.yml` fragments in the generated resource list (`kubernetes.yml`). @@ -229,49 +120,18 @@ Defaults to `5005`. Defaults to `null`. | `jkube.log.pod` -| *machine* -| Docker machine configuration. -| - -| *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. -| `jkube.docker.maxConnections` - | *mergeWithDekorate* | When resource generation is delegated to Dekorate, should JKube resources be merged with Dekorate generated ones. Defaults to `false`. | `jkube.mergeWithDekorate` -| *outputDirectory* -| Default output directory to be used by this plugin. -The default value is `build/docker` and is only used for the task `{task-prefix}Build`. -| `jkube.build.target.dir` - | *offline* | Whether to try detecting Kubernetes Cluster or stay offline. Defaults to `false`. | `jkube.offline` -ifeval::["{task-prefix}" == "oc"] -| *openshiftPullSecret* -| 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 `jkube.docker.pull.registry`/`jkube.docker.registry`. -| `jkube.build.pullSecret` - -| *openshiftPushSecret* -| The name of pushSecret to be used to push the final image in case pushing from a -protected registry which requires authentication. - -| `jkube.build.pushSecret` - -endif::[] - // TODO - Add when support is complete //| *profile* //| Profile to which contains enricher and generators configuration. See <> for details. @@ -296,10 +156,6 @@ more details. Defaults to `false`. | `jkube.recreate` -| *registry* -| Specify globally a registry to use for pulling and pushing images. See <> for details. -| `jkube.docker.registry` - | *pushRetries* | 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. @@ -373,14 +229,6 @@ Defaults to `false`. | If not set resource manifests would be generated with `{task-prefix}Resource`. | `jkube.skip.resource` -| *skipTag* -| If set to `true` this plugin won't add any tags to images that have been built with `{task-prefix}Build`. -| `jkube.skip.tag` - -| *skipMachine* -| Skip using docker machine in any case -| `jkube.docker.skip.machine` - | *skipPush* | If set to true the plugin won’t push any images that have been built. @@ -406,10 +254,6 @@ Defaults to `false`. Defaults to `false`. | `jkube.useProjectClassPath` -| *verbose* -| Boolean attribute for switching on verbose output like the build steps when doing a Docker build. Default is `false`. -| `jkube.docker.verbose` - | *watchMode* a| How to watch for image changes. diff --git a/gradle-plugin/doc/src/main/asciidoc/inc/tasks/build/_index.adoc b/gradle-plugin/doc/src/main/asciidoc/inc/tasks/build/_index.adoc index 3f6809ad4e..a1704a1f63 100644 --- a/gradle-plugin/doc/src/main/asciidoc/inc/tasks/build/_index.adoc +++ b/gradle-plugin/doc/src/main/asciidoc/inc/tasks/build/_index.adoc @@ -1,7 +1,7 @@ [[task-overview-build]] == Build And Deployment Tasks -include::_jkube-build.adoc[] +include::{kitdoc-path}/inc/build/_jkube-build.adoc[] include::_jkube-push.adoc[] diff --git a/gradle-plugin/doc/src/main/asciidoc/index.adoc b/gradle-plugin/doc/src/main/asciidoc/index.adoc index 092008cec2..45ebc626bc 100644 --- a/gradle-plugin/doc/src/main/asciidoc/index.adoc +++ b/gradle-plugin/doc/src/main/asciidoc/index.adoc @@ -41,6 +41,8 @@ include::inc/_registry.adoc[] include::inc/_authentication.adoc[] +include::{kitdoc-path}/inc/_integrations.adoc[] + include::{kitdoc-path}/inc/mapping-config/_index.adoc[] include::{kitdoc-path}/inc/_faq.adoc[] \ No newline at end of file diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_integrations.adoc b/jkube-kit/doc/src/main/asciidoc/inc/_integrations.adoc similarity index 51% rename from kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_integrations.adoc rename to jkube-kit/doc/src/main/asciidoc/inc/_integrations.adoc index 35dafb565c..4846aa48df 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/_integrations.adoc +++ b/jkube-kit/doc/src/main/asciidoc/inc/_integrations.adoc @@ -2,6 +2,7 @@ [[integrations]] = Integrations +ifeval::["{plugin-type}" == "maven"] [[integrations.dekorate]] == Dekorate @@ -44,6 +45,7 @@ https://github.com/eclipse/jkube/tree/master/quickstarts/maven/spring-boot-dekor 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`). +endif::[] == JIB (Java Image Builder) *{plugin}* also provides user an option to build container images without having access to any docker daemon. @@ -51,4 +53,46 @@ You just need to set `jkube.build.strategy` property to `jib`. It will delegate https://github.com/GoogleContainerTools/jib[JIB]. It creates a tarball inside your target directory which can be loaded into any docker daemon afterwards. You may also push the image to your specified registry using push goal with feature flag enabled. +ifeval::["{plugin-type}" == "maven"] You can find more details at https://github.com/eclipse/jkube/tree/master/quickstarts/maven/spring-boot-with-jib[Spring Boot JIB Quickstart]. +endif::[] +ifeval::["{plugin-type}" == "maven"] +You can find more details at https://github.com/eclipse/jkube/tree/master/quickstarts/gradle/spring-boot-with-jib-assembly/[Spring Boot JIB With Assembly Quickstart]. +endif::[] + +[[integrations.buildpacks]] +== Buildpacks + +*{plugin}* provides user to leverage on https://buildpacks.io/[Cloud Native Buildpacks] for building container images. +You just need to set `jkube.build.strategy` property to `buildpacks`. + +[IMPORTANT] +==== +Access to a Docker daemon is required in order to use Buildpacks as mentioned in https://buildpacks.io/docs/app-developer-guide/#prerequisites[Buildpack Prerequisites]. +==== + +ifeval::["{plugin-type}" == "maven"] +[source,shell,indent=2,subs="verbatim,quotes,attributes"] +---- +mvn {goal-prefix}:build -Djkube.build.strategy=buildpacks +---- +endif::[] +ifeval::["{plugin-type}" == "gradle"] +[source,shell,indent=2,subs="verbatim,quotes,attributes"] +---- +gradle {task-prefix}Build -Djkube.build.strategy=buildpacks +---- +endif::[] + +{plugin} will download https://buildpacks.io/docs/tools/pack/[Pack CLI] to user's `$HOME/.jkube` folder and start the +`pack build` process. If somehow https://buildpacks.io/docs/tools/pack/[Pack CLI] download fails, {plugin} tries to search for any local installed https://buildpacks.io/docs/tools/pack/[Pack CLI]. + +=== Buildpack Builder Image +By default {plugin} would try to use https://buildpacks.io/docs/concepts/components/builder/[builder image] specified in https://buildpacks.io/docs/tools/pack/cli/pack_config/[Pack Config] for building container image using https://buildpacks.io/docs/tools/pack/[Pack CLI]. + +For example, if user has this image set in `$HOME/.pack/config.toml`: +[source,toml,indent=2,subs="verbatim,quotes,attributes"] +---- +default-builder-image = "testuser/buildpacks-quarkus-builder:latest" +---- +{plugin} would use `testuser/buildpacks-quarkus-builder:latest` as Buildpacks builder image. If no image is configured, then `paketobuildpacks/builder:base` is used as default builder image. \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/_assembly.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/_assembly.adoc index c1cce9bb5e..c547c37b5a 100644 --- a/jkube-kit/doc/src/main/asciidoc/inc/build/_assembly.adoc +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/_assembly.adoc @@ -74,44 +74,23 @@ For example, the image `jboss/wildfly` use a "jboss" user under which all comman 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-layer]] +ifeval::["{plugin-type}" == "maven"] === Assembly - Inline/Layer +endif::[] +ifeval::["{plugin-type}" == "gradle"] +==== Assembly - Inline/Layer +endif::[] + Inlined assembly description with a format very similar to https://maven.apache.org/plugins/maven-assembly-plugin/assembly.html[Maven Assembly Plugin]. .Partial configuration example of an inline/layer element ifeval::["{plugin-type}" == "gradle"] -[source,groovy,subs="attributes+"] ----- -assembly { - targetDir = "/deployments" - layers = [{ - fileSets = [{ - directory = file("${project.rootDir}/build/dependencies") - outputDirectory = "static" - }] - }] -} ----- +include::gradle/_assembly_layers_filesets.adoc[] endif::[] ifeval::["{plugin-type}" == "maven"] -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - - static-files - - - src/static - static - - - - - ----- +include::maven/_assembly_layers_filesets.adoc[] endif::[] diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/_build_configuration_options.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/_build_configuration_options.adoc new file mode 100644 index 0000000000..f60f859fa9 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/_build_configuration_options.adoc @@ -0,0 +1,188 @@ +[[build-goal-configuration]] +ifeval::["{plugin-type}" == "maven"] +=== Configuration ({plugin-configuration-type}) +endif::[] +ifeval::["{plugin-type}" == "gradle"] +==== Configuration ({plugin-configuration-type}) +endif::[] + + +The following sections describe the usual configuration, which is similar to the build configuration used in the +https://dmp.fabric8.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 <>. Note that if you're providing your own XML image configuration, it would be given more precedence. Generators won't be used in case you're already using your own custom image configuration. + +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 + +| *buildStrategy* +a| Defines what build strategy to choose while building container image. +Possible values are `docker`, `buildpacks` and `jib` out of which `docker` is default. + +ifeval::["{goal-prefix}" == "oc"] +include::_openshift_s2i_buildstrategy_entry.adoc[] +endif::[] +ifeval::["{task-prefix}" == "oc"] +include::_openshift_s2i_buildstrategy_entry.adoc[] +endif::[] +| `jkube.build.strategy` + + | *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. + +| `jkube.docker.autoPull` + + +| [[image-pull-policy]] *imagePullPolicy* +a| Specify whether images should be pull when looking for base images while building or images for starting. +This property can take the following values (case insensitive): + +* `IfNotPresent`: Automatic download any missing images (default) +* `Never` : Automatic pulling is switched off always +* `Always` : Pull images always even when they already exist locally. + +By default, a progress meter is printed out on the console, which is omitted when using {plugin-type} in batch mode (option `-B`). A very simplified progress meter is provided when using no color output (i.e. with `-Djkube.useColor=false`). +| `jkube.docker.imagePullPolicy` + +| *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. +| `jkube.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* (`jkube.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. +| `jkube.docker.host` + +| *filter* +| 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 `jkube.image.filter` when {plugin-type} 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. +| `jkube.image.filter` + +| *machine* +| Docker machine configuration. See <> for possible values. +| + +| *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. +| `jkube.docker.maxConnections` + +| *outputDirectory* +| Default output directory to be used by this plugin. +ifeval::["{plugin-type}" == "maven"] +The default value is `target/docker` and is only used for the goal `{goal-prefix}:build`. +endif::[] +ifeval::["{plugin-type}" == "gradle"] +The default value is `build/docker` and is only used for the goal `{task-prefix}Build`. +endif::[] +| `jkube.build.target.dir` + +| *profile* +| Profile to which contains enricher and generators configuration. See <> for details. +| `jkube.profile` + +ifeval::["{goal-prefix}" == "oc"] +include::_openshift_build_configuration_entries.adoc[] +endif::[] + +ifeval::["{task-prefix}" == "oc"] +include::_openshift_build_configuration_entries.adoc[] +endif::[] + +| *registry* +| Specify globally a registry to use for pulling and pushing images. See <> for details. +| `jkube.docker.registry` + +| *skip* +| With this parameter the execution of this plugin can be skipped completely. +| `jkube.skip` + +| *skipBuild* +| +ifeval::["{plugin-type}" == "maven"] +If set not images will be build (which implies also _skip.tag_) with `{goal-prefix}:build`. +endif::[] +ifeval::["{plugin-type}" == "gradle"] +If set not images will be build (which implies also _skip.tag_) with `{task-prefix}Build`. +endif::[] + +| `jkube.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* +| +ifeval::["{plugin-type}" == "maven"] +If set to `true` this plugin won't add any tags to images that have been built with `{goal-prefix}:build`. +endif::[] +ifeval::["{plugin-type}" == "gradle"] +If set to `true` this plugin won't add any tags to images that have been built with `{task-prefix}Build`. +endif::[] + +| `jkube.skip.tag` + +| *skipMachine* +| Skip using docker machine in any case +| `jkube.docker.skip.machine` + +| *sourceDirectory* +| Default directory that contains the assembly descriptor(s) used by the plugin. The default value is `src/main/docker`. +ifeval::["{plugin-type}" == "maven"] +This option is only relevant for the `{goal-prefix}:build` goal. +endif::[] +ifeval::["{plugin-type}" == "gradle"] +This option is only relevant for the `{task-prefix}Build` goal. +endif::[] +| `jkube.build.source.dir` + +| *verbose* +| Boolean attribute for switching on verbose output like the build steps when doing a Docker build. Default is `false`. +| `jkube.docker.verbose` + +| *logDate* +| The date format to use when logging messages from Docker. Default is `DEFAULT` (`HH:mm:ss.SSS`) +| `jkube.docker.logDate` + +| *logStdout* +| Log to stdout regardless if log files are configured or not. Default is `false`. +| `jkube.docker.logStdout` + +|=== \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/_index.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/_index.adoc index f7086cad8f..a185828862 100644 --- a/jkube-kit/doc/src/main/asciidoc/inc/build/_index.adoc +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/_index.adoc @@ -1,23 +1,47 @@ +ifeval::["{plugin-type}" == "maven"] [[build-configuration]] === Build Configuration +endif::[] +ifeval::["{plugin-type}" == "gradle"] +[[build-configuration]] +==== Build Configuration +endif::[] + include::_overview.adoc[] include::_configuration.adoc[] [[build-assembly]] +ifeval::["{plugin-type}" == "maven"] === Assembly +endif::[] +ifeval::["{plugin-type}" == "gradle"] +==== Assembly +endif::[] + include::_assembly.adoc[] [[build-buildargs]] +ifeval::["{plugin-type}" == "maven"] === Build Args +endif::[] +ifeval::["{plugin-type}" == "gradle"] +==== Build Args +endif::[] + include::_buildargs.adoc[] ifeval::["{plugin-type}" == "maven"] [[build-healthcheck]] +ifeval::["{plugin-type}" == "maven"] === Healthcheck +endif::[] +ifeval::["{plugin-type}" == "gradle"] +==== Healthcheck +endif::[] include::_healthcheck.adoc[] endif::[] diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/_jkube-build.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/_jkube-build.adoc new file mode 100644 index 0000000000..d9aa4a608e --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/_jkube-build.adoc @@ -0,0 +1,78 @@ +ifeval::["{plugin-type}" == "maven"] +[[jkube:build]] +== *{goal-prefix}:build* +endif::[] + +ifeval::["{plugin-type}" == "gradle"] +[[jkubeBuild]] +=== *{task-prefix}Build* +endif::[] + +This task is for building container images for your application. + +ifeval::["{task-prefix}" == "k8s"] +include::_kubernetes-build.adoc[] +endif::[] +ifeval::["{goal-prefix}" == "k8s"] +include::_kubernetes-build.adoc[] +endif::[] + +ifeval::["{task-prefix}" == "oc"] +include::_openshift-build.adoc[] +endif::[] +ifeval::["{goal-prefix}" == "oc"] +include::_openshift-build.adoc[] +endif::[] + +include::_build_configuration_options.adoc[] + +ifeval::["{plugin-type}" == "maven"] +=== Image Configuration +endif::[] +ifeval::["{plugin-type}" == "gradle"] +==== Image Configuration +endif::[] + +The configuration how images should be created a defined in a dedicated `images` sections. These are specified for +each image within the `images` element of the configuration with one `image` element per image to use. + +The `image` element can contain the following sub elements: + +include::../image/_configuration.adoc[] + +The `build` section is mandatory and is explained in <>. + +include::../image/_naming.adoc[] + +ifeval::["{plugin-type}" == "maven"] +include::maven/_mvn_image_example.adoc[] +endif::[] +ifeval::["{plugin-type}" == "gradle"] +include::gradle/_gradle_image_example.adoc[] +endif::[] + +include::_index.adoc[] + +[[misc-env]] +ifeval::["{plugin-type}" == "maven"] +=== Environment and Labels +endif::[] +ifeval::["{plugin-type}" == "gradle"] +==== Environment and Labels +endif::[] + + +include::misc/_env.adoc[] + +[[misc-startup]] +ifeval::["{plugin-type}" == "maven"] +=== Startup Arguments +endif::[] +ifeval::["{plugin-type}" == "gradle"] +==== Startup Arguments +endif::[] + + +include::misc/_startup.adoc[] + +INFO:: Startup arguments are not used in S2I builds diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/_kubernetes-build.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/_kubernetes-build.adoc new file mode 100644 index 0000000000..a05933280f --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/_kubernetes-build.adoc @@ -0,0 +1,39 @@ +A normal Docker build is performed by default.For Kubernetes 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. + +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. + +If you don't have access to docker daemon, you can change build strategy using `buildStrategy` option in Groovy configuration like this: + +ifeval::["{plugin-type}" == "maven"] +include::maven/_mvn_buildstrategy.adoc[] +endif::[] +ifeval::["{plugin-type}" == "gradle"] +include::gradle/_gradle_buildstrategy.adoc[] +endif::[] + + +These are the different options supported by `buildStrategy`: + +.JKube Build Strategies +[cols="1,5"] +|=== +| *buildStrategy* | *Description* +| `docker` +| Docker build with a binary source + +| `buildpacks` +| Docker build using https://buildpacks.io/[Cloud Native Buildpacks] + +| `jib` +| Deamonless container image creation using https://github.com/GoogleContainerTools/jib[JIB] build +|=== + +ifeval::["{plugin-type}" == "maven"] +{plugin} by default tries to build up an opinionated <> by inspecting `pom.xml`. +endif::[] +ifeval::["{plugin-type}" == "gradle"] +{plugin} by default tries to build up an opinionated <> by inspecting `build.gradle`. +endif::[] + + +You can also provide your own <> or provide Custom ImageConfiguration via <>. \ No newline at end of file diff --git a/gradle-plugin/doc/src/main/asciidoc/inc/tasks/build/_jkube-build.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/_openshift-build.adoc similarity index 65% rename from gradle-plugin/doc/src/main/asciidoc/inc/tasks/build/_jkube-build.adoc rename to jkube-kit/doc/src/main/asciidoc/inc/build/_openshift-build.adoc index a148769853..d6f0ab948a 100644 --- a/gradle-plugin/doc/src/main/asciidoc/inc/tasks/build/_jkube-build.adoc +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/_openshift-build.adoc @@ -1,47 +1,3 @@ -[[jkubeBuild]] -=== *{task-prefix}Build* - -This task is for building container images for your application. - -ifeval::["{task-prefix}" == "k8s"] -[[build-kubernetes]] -==== Kubernetes Build - -A normal Docker build is performed by default.For Kubernetes 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. - -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. - -If you don't have access to docker daemon, you can change build strategy using `buildStrategy` option in Groovy configuration like this: - -.Example of overriding default build strategy -[source,groovy,subs="attributes+"] ----- -{pluginExtension} { - buildStrategy = 'jib' -} ----- - -These are the different options supported by `buildStrategy`: - -.JKube Build Strategies -[cols="1,5"] -|=== -| *buildStrategy* | *Description* -| `docker` -| Docker build with a binary source - -| `jib` -| Deamonless container image creation using https://github.com/GoogleContainerTools/jib[JIB] build -|=== - -{plugin} by default tries to build up an opinionated <> by inspecting `build.gradle`. -You can also provide your own <> or provide Custom ImageConfiguration via <>. -endif::[] - -ifeval::["{task-prefix}" == "oc"] - -[[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. @@ -73,13 +29,27 @@ 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. +ifeval::["{plugin-type}" == "maven"] +If they do not exist, they will be automatically created by `{goal-prefix}:build`. +endif::[] +ifeval::["{plugin-type}" == "gradle"] If they do not exist, they will be automatically created by `{task-prefix}Build`. +endif::[] + 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). +ifeval::["{plugin-type}" == "maven"] +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 <>. +endif::[] +ifeval::["{plugin-type}" == "gradle"] 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 <>. +endif::[] + 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. @@ -98,38 +68,26 @@ Many of the options below are relevant for the <> one because the build depends on which buider/base image is used and how it interprets the content of the uploaded `docker.tar`. +ifeval::["{plugin-type}" == "maven"] +[[setting-quota-openshift-build]] +=== Setting Quotas for OpenShift Build +endif::[] +ifeval::["{plugin-type}" == "gradle"] [[setting-quota-openshift-build]] ==== Setting Quotas for OpenShift Build +endif::[] + You can also limit resource use by specifying resource limits as part of the build configuration. -You can do this by providing `` field in `` configuration. +You can do this by providing `openshiftBuildConfig` field in `resource` configuration. Below is an example on how to do this: -.Example of OpenShift S2I Build resource/limit Configuration -[source,groovy,subs="attributes+"] ----- -{pluginExtension} { - resources { - openshiftBuildConfig { - requests { //<1> - cpu = '500m' //<2> - memory = '512Mi' //<3> - } - limits { //<4> - cpu = '1000m' //<5> - memory = '1Gi' //<6> - } - } - } -} ----- - -<1> Request field which maps to created BuildConfig's `.spec.resources.requests` -<2> Minimum CPU required by Build Pod -<3> Minimum memory required by Build Pod -<4> Limits field which maps to created BuildConfig's (`.spec.resources.limits`) -<5> Maximum CPU required by Build Pod -<6> Maximum memory required by Build Pod +ifeval::["{plugin-type}" == "maven"] +include::maven/_oc_s2i_build_resource_limit.adoc[] +endif::[] +ifeval::["{plugin-type}" == "gradle"] +include::gradle/_oc_s2i_build_resource_limit.adoc[] +endif::[] It's also possible to provide a `buildconfig.yml` BuildConfig resource fragment in `src/main/jkube` directory like this: @@ -144,9 +102,4 @@ spec: requests: cpu: "500m" memory: "300Mi" ----- -endif::[] - - - - +---- \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/_openshift_build_configuration_entries.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/_openshift_build_configuration_entries.adoc new file mode 100644 index 0000000000..0c008178cc --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/_openshift_build_configuration_entries.adoc @@ -0,0 +1,44 @@ +|*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` + +| *openshiftPullSecret* +| 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 `jkube.docker.pull.registry`/`jkube.docker.registry`. +| `jkube.build.pullSecret` + +| *openshiftPushSecret* +| The name of pushSecret to be used to push the final image in case pushing from a +protected registry which requires authentication. + +| `jkube.build.pushSecret` + +| *buildOutputKind* +| Allow to specify in which registry to push the container image at the end of the build. +If the output kind is ImageStreamTag, then the image will be pushed to the internal OpenShift registry. +If the output is of type DockerImage, then the name of the output reference will be used as a Docker push specification. +The default value is `ImageStreamTag` + +| `jkube.build.buildOutput.kind` + + +| *buildRecreate* +a| If the build is performed in an OpenShift cluster 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` \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/_openshift_s2i_buildstrategy_entry.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/_openshift_s2i_buildstrategy_entry.adoc new file mode 100644 index 0000000000..ca4095fd47 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/_openshift_s2i_buildstrategy_entry.adoc @@ -0,0 +1,7 @@ +If the build is performed in an OpenShift cluster an additional `s2i` option is available +and selected by default. + +Available strategies for OpenShift are: + +* `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 diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/gradle/_assembly_layers_filesets.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/gradle/_assembly_layers_filesets.adoc new file mode 100644 index 0000000000..e264680457 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/gradle/_assembly_layers_filesets.adoc @@ -0,0 +1,12 @@ +[source,groovy,subs="attributes+"] +---- +assembly { + targetDir = "/deployments" + layers = [{ + fileSets = [{ + directory = file("${project.rootDir}/build/dependencies") + outputDirectory = "static" + }] + }] +} +---- \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/gradle/_gradle_buildstrategy.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/gradle/_gradle_buildstrategy.adoc new file mode 100644 index 0000000000..df2db06d70 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/gradle/_gradle_buildstrategy.adoc @@ -0,0 +1,7 @@ +.Example of overriding default build strategy +[source,groovy,subs="attributes+"] +---- +{pluginExtension} { + buildStrategy = 'jib' +} +---- \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/gradle/_gradle_image_example.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/gradle/_gradle_image_example.adoc new file mode 100644 index 0000000000..5cd722f156 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/gradle/_gradle_image_example.adoc @@ -0,0 +1,18 @@ +.Example for `image` +[source,groovy,indent=0,subs="verbatim,quotes,attributes"] +---- +{pluginExtension} { + images { + image { //<1> + name = "%g/jkube-build-demo:0.1" //<2> + alias = "service" //<3> + build { //<4> + } + } + } +} +---- +<1> One or more `image` definitions +<2> The Docker image name used when creating the image. Note that `%g` would be replaced by project group id. +<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 `build` section as described in <> diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/gradle/_oc_s2i_build_resource_limit.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/gradle/_oc_s2i_build_resource_limit.adoc new file mode 100644 index 0000000000..f861526ac5 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/gradle/_oc_s2i_build_resource_limit.adoc @@ -0,0 +1,26 @@ + +.Example of OpenShift S2I Build resource/limit Configuration +[source,groovy,subs="attributes+"] +---- +{pluginExtension} { + resources { + openshiftBuildConfig { + requests { //<1> + cpu = '500m' //<2> + memory = '512Mi' //<3> + } + limits { //<4> + cpu = '1000m' //<5> + memory = '1Gi' //<6> + } + } + } +} +---- + +<1> Request field which maps to created BuildConfig's `.spec.resources.requests` +<2> Minimum CPU required by Build Pod +<3> Minimum memory required by Build Pod +<4> Limits field which maps to created BuildConfig's (`.spec.resources.limits`) +<5> Maximum CPU required by Build Pod +<6> Maximum memory required by Build Pod \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/maven/_assembly_layers_filesets.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/maven/_assembly_layers_filesets.adoc new file mode 100644 index 0000000000..45de0e1fca --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/maven/_assembly_layers_filesets.adoc @@ -0,0 +1,17 @@ +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + + static-files + + + src/static + static + + + + + +---- \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/maven/_mvn_buildstrategy.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/maven/_mvn_buildstrategy.adoc new file mode 100644 index 0000000000..f6f2c0dd79 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/maven/_mvn_buildstrategy.adoc @@ -0,0 +1,7 @@ +.Example of overriding default build strategy +[source,xml,subs="attributes+"] +---- + + jib + +---- \ No newline at end of file diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_example.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/maven/_mvn_image_example.adoc similarity index 87% rename from kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_example.adoc rename to jkube-kit/doc/src/main/asciidoc/inc/build/maven/_mvn_image_example.adoc index 6fabfc8f04..ef6a0f2783 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_example.adoc +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/maven/_mvn_image_example.adoc @@ -18,4 +18,4 @@ <1> One or more `` definitions <2> The Docker image name used when creating the image. Note that `%g` would be replaced by project group id. <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 <> +<4> A `` section as described in <> diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/maven/_oc_s2i_build_resource_limit.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/maven/_oc_s2i_build_resource_limit.adoc new file mode 100644 index 0000000000..cd8ba7015b --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/maven/_oc_s2i_build_resource_limit.adoc @@ -0,0 +1,25 @@ +.Example of OpenShift S2I Build resource/limit Configuration +[source,xml] +---- + + + + + 500m + 512Mi + + + 1000m + 1Gi + + + + +---- + +<1> Request field which maps to created BuildConfig's `.spec.resources.requests` +<2> Minimum CPU required by Build Pod +<3> Minimum memory required by Build Pod +<4> Limits field which maps to created BuildConfig's (`.spec.resources.limits`) +<5> Maximum CPU required by Build Pod +<6> Maximum memory required by Build Pod \ No newline at end of file diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_env.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/_env.adoc similarity index 61% rename from kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_env.adoc rename to jkube-kit/doc/src/main/asciidoc/inc/build/misc/_env.adoc index 2aeedb95c8..e37ea58cf9 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_env.adoc +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/_env.adoc @@ -2,27 +2,22 @@ When creating a container one or more environment variables can be set via configuration with the `env` parameter -.Example -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - /opt/jdk8 - -Djava.security.egd=file:/dev/./urandom - ----- +ifeval::["{plugin-type}" == "maven"] +include::maven/_mvn_env.adoc[] 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). +endif::[] +ifeval::["{plugin-type}" == "gradle"] +include::gradle/_gradle_env.adoc[] +endif::[] 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,indent=0,subs="verbatim,quotes,attributes"] ----- - - foo - ${project.version} - ${project.artifactId} - ----- +ifeval::["{plugin-type}" == "maven"] +include::maven/_mvn_image_labels.adoc[] +endif::[] +ifeval::["{plugin-type}" == "gradle"] +include::gradle/_gradle_image_labels.adoc[] +endif::[] diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_startup.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/_startup.adoc similarity index 73% rename from kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_startup.adoc rename to jkube-kit/doc/src/main/asciidoc/inc/build/misc/_startup.adoc index b55f80df94..27b8dae3db 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/misc/_startup.adoc +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/_startup.adoc @@ -21,35 +21,28 @@ An entry point or command can be specified in two alternative formats: | 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. +| List of arguments (with inner `args`) arguments which will be given to the `exec` call directly without any shell interpretation. |=== Either shell or params should be specified. -.Example -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - java -jar $HOME/server.jar - ----- +ifeval::["{plugin-type}" == "maven"] +include::maven/_mvn_entrypoint_shell.adoc[] +endif::[] +ifeval::["{plugin-type}" == "gradle"] +include::gradle/_gradle_entrypoint_shell.adoc[] +endif::[] or -.Example -[source,xml,indent=0,subs="verbatim,quotes,attributes"] ----- - - - - java - -jar - /opt/demo/server.jar - - ----- +ifeval::["{plugin-type}" == "maven"] +include::maven/_mvn_entrypoint_exec.adoc[] +endif::[] +ifeval::["{plugin-type}" == "gradle"] +include::gradle/_gradle_entrypoint_exec.adoc[] +endif::[] +ifeval::["{plugin-type}" == "maven"] This can be formulated also more dense with: .Example @@ -72,3 +65,4 @@ or ---- +endif::[] diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/misc/gradle/_gradle_entrypoint_exec.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/gradle/_gradle_entrypoint_exec.adoc new file mode 100644 index 0000000000..12a812a5b7 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/gradle/_gradle_entrypoint_exec.adoc @@ -0,0 +1,15 @@ +.Example +[source,groovy,indent=0,subs="verbatim,quotes,attributes"] +---- +{pluginExtension} { + images { + image { + build { + entryPoint { + exec = ["java", "-jar", "/opt/demo/server.jar"] + } + } + } + } +} +---- \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/misc/gradle/_gradle_entrypoint_shell.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/gradle/_gradle_entrypoint_shell.adoc new file mode 100644 index 0000000000..fc80cc3333 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/gradle/_gradle_entrypoint_shell.adoc @@ -0,0 +1,15 @@ +.Example +[source,groovy,indent=0,subs="verbatim,quotes,attributes"] +---- +{pluginExtension} { + images { + image { + build { + entryPoint { + shell = "java -jar \$HOME/server.jar" + } + } + } + } +} +---- \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/misc/gradle/_gradle_env.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/gradle/_gradle_env.adoc new file mode 100644 index 0000000000..050a48664b --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/gradle/_gradle_env.adoc @@ -0,0 +1,16 @@ +.Example +[source,groovy,indent=0,subs="verbatim,quotes,attributes"] +---- +{pluginExtension} { + images { + image { + build { + env { + JAVA_HOME = '/opt/jdk8' + CATALINA_OPTS = '-Djava.security.egd=file:/dev/./urandom' + } + } + } + } +} +---- \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/misc/gradle/_gradle_image_labels.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/gradle/_gradle_image_labels.adoc new file mode 100644 index 0000000000..ec264897f6 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/gradle/_gradle_image_labels.adoc @@ -0,0 +1,16 @@ +.Example +[source,groovy,indent=0,subs="verbatim,quotes,attributes"] +---- +{pluginExtension} { + images { + image { + build { + labels = { + version = "${project.version}" + artifactId = "${project.name}" + } + } + } + } +} +---- \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/misc/maven/_mvn_entrypoint_exec.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/maven/_mvn_entrypoint_exec.adoc new file mode 100644 index 0000000000..910436252e --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/maven/_mvn_entrypoint_exec.adoc @@ -0,0 +1,12 @@ +.Example +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + + java + -jar + /opt/demo/server.jar + + +---- \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/misc/maven/_mvn_entrypoint_shell.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/maven/_mvn_entrypoint_shell.adoc new file mode 100644 index 0000000000..e79e98133b --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/maven/_mvn_entrypoint_shell.adoc @@ -0,0 +1,8 @@ +.Example +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + + java -jar $HOME/server.jar + +---- \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/misc/maven/_mvn_env.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/maven/_mvn_env.adoc new file mode 100644 index 0000000000..38ca12c7ba --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/maven/_mvn_env.adoc @@ -0,0 +1,8 @@ +.Example +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + /opt/jdk8 + -Djava.security.egd=file:/dev/./urandom + +---- \ No newline at end of file diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/misc/maven/_mvn_image_labels.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/maven/_mvn_image_labels.adoc new file mode 100644 index 0000000000..ab87c0bca9 --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/misc/maven/_mvn_image_labels.adoc @@ -0,0 +1,9 @@ +.Example +[source,xml,indent=0,subs="verbatim,quotes,attributes"] +---- + + foo + ${project.version} + ${project.artifactId} + +---- \ No newline at end of file diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_configuration.adoc b/jkube-kit/doc/src/main/asciidoc/inc/image/_configuration.adoc similarity index 57% rename from kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_configuration.adoc rename to jkube-kit/doc/src/main/asciidoc/inc/image/_configuration.adoc index ccbcae5e22..c45b767849 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/image/_configuration.adoc +++ b/jkube-kit/doc/src/main/asciidoc/inc/image/_configuration.adoc @@ -1,4 +1,3 @@ - [[config-image]] .Image Configuration [cols="1,5"] @@ -6,7 +5,7 @@ | Element | Description | <> -| Each `` configuration has a mandatory, unique docker +| Each `image` 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* @@ -18,6 +17,14 @@ 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 <>. 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-type}" == "maven"] +Element which contains all the configuration aspects when doing a <>. +endif::[] +ifeval::["{plugin-type}" == "gradle"] +Element which contains all the configuration aspects when doing a <>. +endif::[] + +This element can be omitted if the image is only pulled from a registry e.g. as support for integration tests like database images. |=== diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_goals.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_goals.adoc index 8e951e79b9..5cc6e9b818 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_goals.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_goals.adoc @@ -3,7 +3,7 @@ # Build Goals include::_jkube-resource.adoc[] -include::_jkube-build.adoc[] +include::{kitdoc-path}/inc/build/_jkube-build.adoc[] include::_jkube-push.adoc[] include::_jkube-apply.adoc[] include::_jkube-helm.adoc[] 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 deleted file mode 100644 index e252c15d82..0000000000 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/inc/goals/build/_jkube-build.adoc +++ /dev/null @@ -1,360 +0,0 @@ -[[jkube:build]] -== *{goal-prefix}:build* - -This goal is for building Docker images. - -[[build-kubernetes]] -=== Kubernetes Build - -A normal Docker build is performed by default. 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. - -ifeval::["{goal-prefix}" == "oc"] -[[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 `{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 <>. -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`. - -[[setting-quota-openshift-build]] -==== Setting Quotas for OpenShift Build -You can also limit resource use by specifying resource limits as part of the build configuration. You can do this by providing `` field in `` configuration. Below is an example on how to do this: - -.Example of OpenShift S2I Build resource/limit Configuration -[source,xml] ----- - - - - - 500m - 512Mi - - - 1000m - 1Gi - - - - ----- - -<1> Request field which maps to created BuildConfig's `.spec.resources.requests` -<2> Minimum CPU required by Build Pod -<3> Minimum memory required by Build Pod -<4> Limits field which maps to created BuildConfig's (`.spec.resources.limits`) -<5> Maximum CPU required by Build Pod -<6> Maximum memory required by Build Pod - -It's also possible to provide a `buildconfig.yml` BuildConfig resource fragment in `src/main/jkube` directory like this: - -.BuildConfig fragment Example(`buildconfig.yml`) -[source,yaml] ----- -spec: - resources: - limits: - cpu: "600m" - memory: "512Mi" - requests: - cpu: "500m" - memory: "300Mi" ----- -endif::[] - -[[build-goal-configuration]] -=== Configuration (XML) - -The following sections describe the usual configuration, which is similar to the build configuration used in the - https://dmp.fabric8.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 <>. Note that if you're providing your own XML image configuration, it would be given more precedence. Generators won't be used in case you're already using your own custom image configuration. - -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 - -| *buildStrategy* -a| Defines what build strategy to choose while building container image. -Possible values are `docker` and `jib` out of which `docker` is default. - -ifeval::["{goal-prefix}" == "oc"] -If the build is performed in an OpenShift cluster an additional `s2i` option is available -and selected by default. - -Available strategies for OpenShift are: - -* `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 - -endif::[] -| `jkube.build.strategy` - - | *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. - -| `jkube.docker.autoPull` - -| *buildRecreate* -a| If the build is performed in an OpenShift cluster 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` - - -ifeval::["{goal-prefix}" == "oc"] -|*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` -endif::[] - -| [[image-pull-policy]] *imagePullPolicy* -a| Specify whether images should be pull when looking for base images while building or images for starting. -This property can take the following values (case insensitive): - -* `IfNotPresent`: Automatic download any missing images (default) -* `Never` : Automatic pulling is switched off always -* `Always` : Pull images always even when they already exist locally. - -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 `-Djkube.useColor=false`). -| `jkube.docker.imagePullPolicy` - -| *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. -| `jkube.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* (`jkube.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. -| `jkube.docker.host` - -| *filter* -| 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 `jkube.image.filter` 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. -| `jkube.image.filter` - -| *machine* -| Docker machine configuration. See <> for possible values. -| - -| *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. -| `jkube.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 `{goal-prefix}:build`. -| `jkube.build.target.dir` - -| *profile* -| Profile to which contains enricher and generators configuration. See <> for details. -| `jkube.profile` - -ifeval::["{goal-prefix}" == "oc"] -| *openshiftPullSecret* -| 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 `jkube.docker.pull.registry`/`jkube.docker.registry`. -| `jkube.build.pullSecret` -endif::[] - -ifeval::["{goal-prefix}" == "oc"] -| *openshiftPushSecret* -| The name of pushSecret to be used to push the final image in case pushing from a - protected registry which requires authentication. - -| `jkube.build.pushSecret` -endif::[] - - -ifeval::["{goal-prefix}" == "oc"] -| *buildOutputKind* -| Allow to specify in which registry to push the container image at the end of the build. - If the output kind is ImageStreamTag, then the image will be pushed to the internal OpenShift registry. - If the output is of type DockerImage, then the name of the output reference will be used as a Docker push specification. - The default value is `ImageStreamTag` - -| `jkube.build.buildOutput.kind` -endif::[] - -| *registry* -| Specify globally a registry to use for pulling and pushing images. See <> for details. -| `jkube.docker.registry` - -| *skip* -| With this parameter the execution of this plugin can be skipped completely. -| `jkube.skip` - -| *skipBuild* -| If set not images will be build (which implies also _skip.tag_) with `{goal-prefix}:build`. -| `jkube.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 `{goal-prefix}:build`. -| `jkube.skip.tag` - -| *skipMachine* -| Skip using docker machine in any case -| `jkube.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 `{goal-prefix}:build` goal. -| `jkube.build.source.dir` - -| *verbose* -| Boolean attribute for switching on verbose output like the build steps when doing a Docker build. Default is `false`. -| `jkube.docker.verbose` - -| *logDate* -| The date format to use when logging messages from Docker. Default is `DEFAULT` (`HH:mm:ss.SSS`) -| `jkube.docker.logDate` - -| *logStdout* -| Log to stdout regardless if log files are configured or not. Default is `false`. -| `jkube.docker.logStdout` - -|=== - -=== 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 <>. - -include::{kitdoc-path}/inc/image/_naming.adoc[] -include::../../image/_example.adoc[] - -include::{kitdoc-path}/inc/build/_index.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 - diff --git a/kubernetes-maven-plugin/doc/src/main/asciidoc/index.adoc b/kubernetes-maven-plugin/doc/src/main/asciidoc/index.adoc index 5fc7af9768..b4b5fc6e48 100644 --- a/kubernetes-maven-plugin/doc/src/main/asciidoc/index.adoc +++ b/kubernetes-maven-plugin/doc/src/main/asciidoc/index.adoc @@ -41,7 +41,7 @@ include::inc/_access.adoc[] include::inc/_registry.adoc[] include::inc/_authentication.adoc[] include::inc/_volumes.adoc[] -include::inc/_integrations.adoc[] +include::{kitdoc-path}/inc/_integrations.adoc[] include::{kitdoc-path}/inc/_faq.adoc[]