diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/_configuration.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/_configuration.adoc index fbe5ca81bf..f59a408170 100644 --- a/jkube-kit/doc/src/main/asciidoc/inc/build/_configuration.adoc +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/_configuration.adoc @@ -10,17 +10,23 @@ of an image configuration. The following configuration options are supported: | <> | Specifies the assembly configuration as described in <> +This field is applicable for all build strategies. + | <> | 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 {plugin-type} 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 <> +This field is applicable only for `docker` build strategy + | *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 <>. +This field is applicable only for `docker` build strategy + | *createImageOptions* | Map specifying the create image options to provide to the docker daemon when pulling or importing an image. @@ -28,15 +34,23 @@ https://docs.docker.com/engine/reference/api/docker_remote_api_v1.24/#build-imag https://docs.docker.com/engine/api/v1.41/#operation/ImageCreate[Docker Remote API] and are restricted to simple options (e.g.: fromImage, fromSrc, platform). +This field is applicable only for `docker` build strategy + | *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. +This field is applicable only for `docker` build strategy + | [[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. +This field is applicable only for `docker` build strategy + | <> | A command to execute by default (i.e. if no command is provided when a container for this image is started). See <> for details. +This field is applicable for all build strategies. + | *compression* | ifeval::["{plugin-type}" == "gradle"] @@ -46,21 +60,33 @@ ifeval::["{plugin-type}" == "maven"] The compression mode how the build archive is transmitted to the docker daemon (`{goal-prefix}:build`) and how docker build archives are attached to this build as sources. The value can be `none` (default), `gzip` or `bzip2`. endif::[] +This field is applicable only for `docker` build strategy + | *dockerFile* | Path to a `Dockerfile` which also triggers _Dockerfile mode_. See <> for details. +This field is applicable only for `docker` build strategy + | *dockerArchive* | Path to a saved image archive which is then imported. See <> for details. +This field is applicable only for `docker` build strategy + | <> | An entrypoint allows you to configure a container that will run as an executable. See <> for details. +This field is applicable for all build strategies. + | <> | The environments as described in <>. +This field is applicable for all build strategies. + | *filter* | Enable and set the delimiters for property replacements. By default, properties in the format `${..}` are replaced with {plugin-type} 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. +This field is applicable only for `docker` build strategy + | [[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::["{task-prefix}" == "oc"] @@ -70,6 +96,8 @@ ifeval::["{goal-prefix}" == "oc"] 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::[] +This field is applicable for all build strategies. + | [[build-config-from-ext]]**fromExt** a| Extended definition for a base image. This field holds a map of defined in `key = "value"` format. The known keys are: @@ -85,51 +113,89 @@ endif::[] A provided `from` takes precedence over the name given here. This tag is useful for extensions of this plugin. +This field is applicable for all build strategies. + | *imagePullPolicy* | Specific pull policy for the base image. This overwrites any global pull policy. See the global configuration option <> for the possible values and the default. +This field is applicable for all build strategies. + | <> | Labels as described in <>. +This field is applicable for all build strategies. + | *maintainer* | The author (`MAINTAINER`) field for the generated image +This field is applicable only for `docker` build strategy + | *noCache* | Don't use Docker's build cache. This can be overwritten by setting a system property `docker.noCache` when running {plugin-type}. +This field is applicable only for `docker` build strategy + | *cacheFrom* | A list of `image` elements specifying image names to use as cache sources. +This field is applicable only for `docker` build strategy + | *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. +This field is applicable only for `docker` build strategy + | *ports* | The exposed ports which is a list of `port` 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"). +This field is applicable for all build strategies. + | *shell* | Shell to be used for the *runCmds*. It contains *arg* elements which are defining the executable and its params. +This field is applicable only for `docker` build strategy + | *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 field is applicable only for `docker` build strategy + | *skip* | if set to true disables building of the image. This config option is best used together with a {plugin-type} property +This field is applicable for all build strategies. + | *skipTag* | If set to `true` this plugin won't add any tags to images. | *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. +This field is applicable for all build strategies. + | *user* | User to which the Dockerfile should switch to the end (corresponds to the `USER` Dockerfile directive). +This field is applicable for all build strategies. + | *volumes* | List of `volume` elements to create a container volume. Whitespace is trimmed from each element and empty elements are ignored. +This field is applicable for all build strategies. + | *workdir* | Directory to change to when starting the container. + +This field is applicable for all build strategies. + +ifeval::["{goal-prefix}" == "oc"] +include::_openshift_s2i_build_strategy_configuration_entries.adoc[] +endif::[] + +ifeval::["{task-prefix}" == "oc"] +include::_openshift_s2i_build_strategy_configuration_entries.adoc +endif::[] |=== diff --git a/jkube-kit/doc/src/main/asciidoc/inc/build/_openshift_s2i_build_strategy_configuration_entries.adoc b/jkube-kit/doc/src/main/asciidoc/inc/build/_openshift_s2i_build_strategy_configuration_entries.adoc new file mode 100644 index 0000000000..66c47df37d --- /dev/null +++ b/jkube-kit/doc/src/main/asciidoc/inc/build/_openshift_s2i_build_strategy_configuration_entries.adoc @@ -0,0 +1,55 @@ +|*openshiftForcePull* +| 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 openshiftForcePull will override the local image and refresh it from the registry the image stream points to. + +This field is applicable in case of `s2i` build strategy. + +| *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`. + +This field is applicable in case of `s2i` build strategy. + +| *openshiftPushSecret* +| The name of pushSecret to be used to push the final image in case pushing from a +protected registry which requires authentication. + +This field is applicable in case of `s2i` build strategy. + +| *openshiftBuildOutputKind* +| 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` + + +This field is applicable in case of `s2i` build strategy. + +| *openshiftS2iBuildNameSuffix* +| The S2I binary builder BuildConfig name suffix appended to the image name to avoid + clashing with the underlying BuildConfig for the Jenkins pipeline + +This field is applicable in case of `s2i` build strategy. + +| *openshiftS2iImageStreamLookupPolicyLocal* +| Allow the ImageStream used in the S2I binary build to be used in standard +Kubernetes resources such as Deployment or StatefulSet. + +This field is applicable in case of `s2i` build strategy. + +| *openshiftBuildRecreateMode* +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. + +This field is applicable in case of `s2i` build strategy. \ No newline at end of file