Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc (jkube-kit/doc) : Documentation for Buildpacks integration #2639

Merged
merged 1 commit into from
Feb 9, 2024
Merged

doc (jkube-kit/doc) : Documentation for Buildpacks integration #2639

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
167 changes: 4 additions & 163 deletions gradle-plugin/doc/src/main/asciidoc/inc/_groovy-configuration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,77 +8,12 @@
|====
| Element | Description | Property

| *authConfig*
| Authentication information when pulling from or pushing to Docker registry. There is a dedicated section
<<authentication, Authentication>> for how to do security.
|
include::{kitdoc-path}/inc/build/_build_configuration_option_entries.adoc[]

| <<cluster-access-configuration, *access*>>
| 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.

Expand All @@ -97,31 +32,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 `<machine>` 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 `<machine>`, 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.

Expand All @@ -136,17 +46,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.

Expand All @@ -160,17 +59,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`).

Expand Down Expand Up @@ -229,49 +117,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 <<profiles,Profiles>> for details.
Expand All @@ -296,10 +153,6 @@ more details.
Defaults to `false`.
| `jkube.recreate`

| *registry*
| Specify globally a registry to use for pulling and pushing images. See <<registry,Registry handling>> 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.

Expand Down Expand Up @@ -373,14 +226,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.

Expand All @@ -406,10 +251,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.
Expand Down Expand Up @@ -449,7 +290,7 @@ The configuration how images should be created are defined in a dedicated `image

The `image` element can contain the following sub elements:

include::image/_configuration.adoc[]
include::{kitdoc-path}/inc/image/_configuration.adoc[]

The `build` section is mandatory and is explained in <<build-configuration, below>>.

Expand All @@ -460,12 +301,12 @@ include::{kitdoc-path}/inc/build/_index.adoc[]
[[misc-env]]
== Environment and Labels

include::misc/_env.adoc[]
include::{kitdoc-path}/inc/build/misc/_env.adoc[]

[[misc-startup]]
== Startup Arguments

include::misc/_startup.adoc[]
include::{kitdoc-path}/inc/build/misc/_startup.adoc[]

INFO:: Startup arguments are not used in S2I builds

Expand Down
47 changes: 0 additions & 47 deletions gradle-plugin/doc/src/main/asciidoc/inc/misc/_startup.adoc
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion gradle-plugin/doc/src/main/asciidoc/inc/tasks/build/_index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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[]

Expand Down
2 changes: 2 additions & 0 deletions gradle-plugin/doc/src/main/asciidoc/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
44 changes: 44 additions & 0 deletions .../src/main/asciidoc/inc/_integrations.adoc → .../src/main/asciidoc/inc/_integrations.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
[[integrations]]
= Integrations

ifeval::["{plugin-type}" == "maven"]
[[integrations.dekorate]]
== Dekorate

Expand Down Expand Up @@ -44,11 +45,54 @@ 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 (`<jkube.mergeWithDekorate>true</jkube.mergeWithDekorate>`).
endif::[]

== JIB (Java Image Builder)
*{plugin}* also provides user an option to build container images without having access to any docker daemon.
You just need to set `jkube.build.strategy` property to `jib`. It will delegate the build process to
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}" == "gradle"]
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 the required features for users to leverage https://buildpacks.io/[Cloud Native Buildpacks] for building container images.
You can enable this build strategy by setting the `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} downloads https://buildpacks.io/docs/tools/pack/[Pack CLI] to the user's `$HOME/.jkube` folder and starts the
`pack build` process. If the download for the https://buildpacks.io/docs/tools/pack/[Pack CLI] binary fails, {plugin} looks for any locally installed https://buildpacks.io/docs/tools/pack/[Pack CLI] version.

=== Buildpack Builder Image
By default {plugin} uses the https://buildpacks.io/docs/concepts/components/builder/[builder image] specified in the https://buildpacks.io/docs/tools/pack/cli/pack_config/[Pack Config] file for building the container image using https://buildpacks.io/docs/tools/pack/[Pack CLI].

For example, if the user has this image set in the `$HOME/.pack/config.toml` file:
[source,toml,indent=2,subs="verbatim,quotes,attributes"]
----
default-builder-image = "testuser/buildpacks-quarkus-builder:latest"
----
{plugin} uses `testuser/buildpacks-quarkus-builder:latest` as Buildpacks builder image. If no image is configured, then {plugin} uses `paketobuildpacks/builder:base` as the default builder image.
Loading
Loading