From d7b7ffda089c1ba2bd19b3612c2ef1ca6a5a299a Mon Sep 17 00:00:00 2001 From: Chanseok Oh Date: Tue, 16 Oct 2018 10:45:11 -0400 Subject: [PATCH 01/19] Update README for container.user --- jib-gradle-plugin/README.md | 2 ++ jib-maven-plugin/README.md | 1 + 2 files changed, 3 insertions(+) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index b99706709c..89d0de94b7 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -202,6 +202,8 @@ Property | Type | Default | Description `mainClass` | `String` | *Inferred\** | The main class to launch your application from. `ports` | `List` | *None* | Ports that the container exposes at runtime (similar to Docker's [EXPOSE](https://docs.docker.com/engine/reference/builder/#expose) instruction). `useCurrentTimestamp` | `boolean` | `false` | By default, Jib wipes all timestamps to guarantee reproducibility. If this parameter is set to `true`, Jib will set the image's creation timestamp to the time of the build, which sacrifices reproducibility for easily being able to tell when your image was created. +`user` | `String` | `0:0` | The user and group to run the container as. {@code user} can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. + You can also configure HTTP connection/read timeouts for registry interactions using the `jib.httpTimeout` system property, configured in milliseconds via commandline (the default is `20000`; you can also set it to `0` for infinite timeout): diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index 11c161ef2b..a65b0d1855 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -244,6 +244,7 @@ Property | Type | Default | Description `mainClass` | string | *Inferred\** | The main class to launch the application from. `ports` | list | *None* | Ports that the container exposes at runtime (similar to Docker's [EXPOSE](https://docs.docker.com/engine/reference/builder/#expose) instruction). `useCurrentTimestamp` | boolean | `false` | By default, Jib wipes all timestamps to guarantee reproducibility. If this parameter is set to `true`, Jib will set the image's creation timestamp to the time of the build, which sacrifices reproducibility for easily being able to tell when your image was created. +`user` | string | `0:0` | The user and group to run the container as. {@code user} can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. You can also configure HTTP connection/read timeouts for registry interactions using the `jib.httpTimeout` system property, configured in milliseconds via commandline (the default is `20000`; you can also set it to `0` for infinite timeout): From 7dc735d018ded7ca4def19deabc11702776cf020 Mon Sep 17 00:00:00 2001 From: Chanseok Oh Date: Tue, 16 Oct 2018 11:13:56 -0400 Subject: [PATCH 02/19] Update README.md --- jib-gradle-plugin/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index 89d0de94b7..bb536ef06a 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -202,7 +202,7 @@ Property | Type | Default | Description `mainClass` | `String` | *Inferred\** | The main class to launch your application from. `ports` | `List` | *None* | Ports that the container exposes at runtime (similar to Docker's [EXPOSE](https://docs.docker.com/engine/reference/builder/#expose) instruction). `useCurrentTimestamp` | `boolean` | `false` | By default, Jib wipes all timestamps to guarantee reproducibility. If this parameter is set to `true`, Jib will set the image's creation timestamp to the time of the build, which sacrifices reproducibility for easily being able to tell when your image was created. -`user` | `String` | `0:0` | The user and group to run the container as. {@code user} can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. +`user` | `String` | `0:0` | The user and group to run the container as. The value can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. You can also configure HTTP connection/read timeouts for registry interactions using the `jib.httpTimeout` system property, configured in milliseconds via commandline (the default is `20000`; you can also set it to `0` for infinite timeout): From ec568ea103605fd6c8fdb60c64c245d5bb649b86 Mon Sep 17 00:00:00 2001 From: Chanseok Oh Date: Tue, 16 Oct 2018 11:14:29 -0400 Subject: [PATCH 03/19] Update README.md --- jib-maven-plugin/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index a65b0d1855..90acfbe2cc 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -244,7 +244,7 @@ Property | Type | Default | Description `mainClass` | string | *Inferred\** | The main class to launch the application from. `ports` | list | *None* | Ports that the container exposes at runtime (similar to Docker's [EXPOSE](https://docs.docker.com/engine/reference/builder/#expose) instruction). `useCurrentTimestamp` | boolean | `false` | By default, Jib wipes all timestamps to guarantee reproducibility. If this parameter is set to `true`, Jib will set the image's creation timestamp to the time of the build, which sacrifices reproducibility for easily being able to tell when your image was created. -`user` | string | `0:0` | The user and group to run the container as. {@code user} can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. +`user` | string | `0:0` | The user and group to run the container as. The value can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. You can also configure HTTP connection/read timeouts for registry interactions using the `jib.httpTimeout` system property, configured in milliseconds via commandline (the default is `20000`; you can also set it to `0` for infinite timeout): From 3e38f1d40188f10cb8f84fdb783ef5a080f3901e Mon Sep 17 00:00:00 2001 From: Chanseok Oh Date: Tue, 16 Oct 2018 12:11:32 -0400 Subject: [PATCH 04/19] Update README.md --- jib-gradle-plugin/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index bb536ef06a..1c7d681e05 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -202,7 +202,7 @@ Property | Type | Default | Description `mainClass` | `String` | *Inferred\** | The main class to launch your application from. `ports` | `List` | *None* | Ports that the container exposes at runtime (similar to Docker's [EXPOSE](https://docs.docker.com/engine/reference/builder/#expose) instruction). `useCurrentTimestamp` | `boolean` | `false` | By default, Jib wipes all timestamps to guarantee reproducibility. If this parameter is set to `true`, Jib will set the image's creation timestamp to the time of the build, which sacrifices reproducibility for easily being able to tell when your image was created. -`user` | `String` | `0:0` | The user and group to run the container as. The value can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. +`user` | `String` | *None* | The user and group to run the container as. The value can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. You can also configure HTTP connection/read timeouts for registry interactions using the `jib.httpTimeout` system property, configured in milliseconds via commandline (the default is `20000`; you can also set it to `0` for infinite timeout): From fc721a1a951148287e18d9afee6a1c5193d47870 Mon Sep 17 00:00:00 2001 From: Chanseok Oh Date: Tue, 16 Oct 2018 12:11:54 -0400 Subject: [PATCH 05/19] Update README.md --- jib-maven-plugin/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index 90acfbe2cc..1eaefe58a7 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -244,7 +244,7 @@ Property | Type | Default | Description `mainClass` | string | *Inferred\** | The main class to launch the application from. `ports` | list | *None* | Ports that the container exposes at runtime (similar to Docker's [EXPOSE](https://docs.docker.com/engine/reference/builder/#expose) instruction). `useCurrentTimestamp` | boolean | `false` | By default, Jib wipes all timestamps to guarantee reproducibility. If this parameter is set to `true`, Jib will set the image's creation timestamp to the time of the build, which sacrifices reproducibility for easily being able to tell when your image was created. -`user` | string | `0:0` | The user and group to run the container as. The value can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. +`user` | string | *None* | The user and group to run the container as. The value can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. You can also configure HTTP connection/read timeouts for registry interactions using the `jib.httpTimeout` system property, configured in milliseconds via commandline (the default is `20000`; you can also set it to `0` for infinite timeout): From c05a9865a73625727c30e2a9c5a73682665d9dee Mon Sep 17 00:00:00 2001 From: Tad Cordle Date: Tue, 30 Oct 2018 11:28:56 -0400 Subject: [PATCH 06/19] Add extraDirectory changes --- jib-gradle-plugin/README.md | 33 ++++++++++++++++++++++------ jib-maven-plugin/README.md | 44 +++++++++++++++++++++++++++++++------ 2 files changed, 63 insertions(+), 14 deletions(-) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index 1c7d681e05..51a5f9e950 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -161,6 +161,7 @@ Field | Type | Default | Description `to` | [`to`](#to-closure) | *Required* | Configures the target image to build your application to. `from` | [`from`](#from-closure) | See [`from`](#from-closure) | Configures the base image to build your application on top of. `container` | [`container`](#container-closure) | See [`container`](#container-closure) | Configures the container that is run from your built image. +`extraDirectory` | [`extraDirectory`](#extraDirectory-object) / `File` | See `extraDirectory` | Configures the directory used to add arbitrary files to the image. `allowInsecureRegistries` | `boolean` | `false` | If set to true, Jib ignores HTTPS certificate errors and may fall back to HTTP as a last resort. Leaving this parameter set to `false` is strongly recommended, since HTTP communication is unencrypted and visible to others on the network, and insecure HTTPS is no better than plain HTTP. [If accessing a registry with a self-signed certificate, adding the certificate to your Java runtime's trusted keys](https://github.com/GoogleContainerTools/jib/tree/master/docs/self_sign_cert.md) may be an alternative to enabling this option. `useProjectOnlyCache` | `boolean` | `false` | If set to `true`, Jib does not share a cache between different Maven projects. @@ -204,6 +205,12 @@ Property | Type | Default | Description `useCurrentTimestamp` | `boolean` | `false` | By default, Jib wipes all timestamps to guarantee reproducibility. If this parameter is set to `true`, Jib will set the image's creation timestamp to the time of the build, which sacrifices reproducibility for easily being able to tell when your image was created. `user` | `String` | *None* | The user and group to run the container as. The value can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. +`extraDirectory` is an object with the following properties (see [Adding Arbitrary Files to the Image](#adding-arbitrary-files-to-the-image)): + +Property | Type +--- | --- +`path` | `File` +`permissions` | `Map` You can also configure HTTP connection/read timeouts for registry interactions using the `jib.httpTimeout` system property, configured in milliseconds via commandline (the default is `20000`; you can also set it to `0` for infinite timeout): @@ -250,15 +257,27 @@ jib { You can add arbitrary, non-classpath files to the image by placing them in a `src/main/jib` directory. This will copy all files within the `jib` folder to the image's root directory, maintaining the same structure (e.g. if you have a text file at `src/main/jib/dir/hello.txt`, then your image will contain `/dir/hello.txt` after being built with Jib). -You can configure a different directory by using the `extraDirectory` parameter in your `build.gradle`: +You can configure a different directory by using the `extraDirectory` parameter in your `build.gradle`, either by using the `jib.extraDirectory.path` parameter: ```groovy -jib { - ... - // Copies files from 'src/main/custom-extra-dir' instead of 'src/main/jib' - extraDirectory = file('src/main/custom-extra-dir') - ... -} +// Copies files from 'src/main/custom-extra-dir' instead of 'src/main/jib' +jib.extraDirectory.path = file('src/main/custom-extra-dir') +``` + +or by setting the path on the `extraDirectory` parameter directly: + +```groovy +// Copies files from 'src/main/custom-extra-dir' instead of 'src/main/jib' +jib.extraDirectory = file('src/main/custom-extra-dir') +``` + +The `extraDirectory` parameter can also be used to set the file permissions of files added to the container by specifying the absolute path of the file on the container as well as the octal representation of its file permission bits in the `jib.extraDirectory.permissions` field: + +```groovy +jib.extraDirectory.permissions = [ + '/path/on/container/to/fileA': '755', // Read/write/execute for owner, read/execute for group/other + '/path/to/another/file': '644' // Read/write for owner, read-only for group/other +] ``` ### Authentication Methods diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index 1eaefe58a7..61e577beef 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -202,6 +202,7 @@ Field | Type | Default | Description `to` | [`to`](#to-object) | *Required* | Configures the target image to build your application to. `from` | [`from`](#from-object) | See [`from`](#from-object) | Configures the base image to build your application on top of. `container` | [`container`](#container-object) | See [`container`](#container-object) | Configures the container that is run from your image. +`extraDirectory` | [`extraDirectory`](#extraDirectory-object) / string | See `extraDirectory` | Configures the directory used to add arbitrary files to the image. `allowInsecureRegistries` | boolean | `false` | If set to true, Jib ignores HTTPS certificate errors and may fall back to HTTP as a last resort. Leaving this parameter set to `false` is strongly recommended, since HTTP communication is unencrypted and visible to others on the network, and insecure HTTPS is no better than plain HTTP. [If accessing a registry with a self-signed certificate, adding the certificate to your Java runtime's trusted keys](https://github.com/GoogleContainerTools/jib/tree/master/docs/self_sign_cert.md) may be an alternative to enabling this option. `skip` | boolean | `false` | If set to true, Jib execution is skipped (useful for multi-module projects). This can also be specified via the `-Djib.skip` command line option. `useOnlyProjectCache` | boolean | `false` | If set to true, Jib does not share a cache between different Maven projects. @@ -246,6 +247,13 @@ Property | Type | Default | Description `useCurrentTimestamp` | boolean | `false` | By default, Jib wipes all timestamps to guarantee reproducibility. If this parameter is set to `true`, Jib will set the image's creation timestamp to the time of the build, which sacrifices reproducibility for easily being able to tell when your image was created. `user` | string | *None* | The user and group to run the container as. The value can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. +`extraDirectory` is an object with the following properties (see [Adding Arbitrary Files to the Image](#adding-arbitrary-files-to-the-image)): + +Property | Type +--- | --- +`path` | string +`permissions` | list + You can also configure HTTP connection/read timeouts for registry interactions using the `jib.httpTimeout` system property, configured in milliseconds via commandline (the default is `20000`; you can also set it to `0` for infinite timeout): ```shell @@ -307,15 +315,37 @@ In this configuration, the image: You can add arbitrary, non-classpath files to the image by placing them in a `src/main/jib` directory. This will copy all files within the `jib` folder to the image's root directory, maintaining the same structure (e.g. if you have a text file at `src/main/jib/dir/hello.txt`, then your image will contain `/dir/hello.txt` after being built with Jib). -You can configure a different directory by using the `extraDirectory` parameter in your `pom.xml`: +You can configure a different directory by using the `extraDirectory` parameter in your `pom.xml`, either by using the `` parameter: ```xml - - ... - - ${project.basedir}/src/main/custom-extra-dir - ... - + + + ${project.basedir}/src/main/custom-extra-dir + +``` + +or by setting the path on the `extraDirectory` parameter directly: + +```xml + +${project.basedir}/src/main/custom-extra-dir +``` + +The `extraDirectory` parameter can also be used to set the file permissions of files added to the container by specifying the absolute path of the file on the container as well as the octal representation of its file permission bits in the `` field: + +```xml + + + + /path/on/container/to/fileA + 755 + + + /path/to/another/file + 644 + + + ``` ### Authentication Methods From c8956fd3d4112bb2ea16361b5825636215131069 Mon Sep 17 00:00:00 2001 From: Tad Cordle Date: Tue, 30 Oct 2018 11:32:02 -0400 Subject: [PATCH 07/19] Fix links --- jib-gradle-plugin/README.md | 4 ++-- jib-maven-plugin/README.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index 51a5f9e950..aeab76f1d1 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -161,7 +161,7 @@ Field | Type | Default | Description `to` | [`to`](#to-closure) | *Required* | Configures the target image to build your application to. `from` | [`from`](#from-closure) | See [`from`](#from-closure) | Configures the base image to build your application on top of. `container` | [`container`](#container-closure) | See [`container`](#container-closure) | Configures the container that is run from your built image. -`extraDirectory` | [`extraDirectory`](#extraDirectory-object) / `File` | See `extraDirectory` | Configures the directory used to add arbitrary files to the image. +`extraDirectory` | [`extraDirectory`](#extradirectory-closure) / `File` | See `extraDirectory` | Configures the directory used to add arbitrary files to the image. `allowInsecureRegistries` | `boolean` | `false` | If set to true, Jib ignores HTTPS certificate errors and may fall back to HTTP as a last resort. Leaving this parameter set to `false` is strongly recommended, since HTTP communication is unencrypted and visible to others on the network, and insecure HTTPS is no better than plain HTTP. [If accessing a registry with a self-signed certificate, adding the certificate to your Java runtime's trusted keys](https://github.com/GoogleContainerTools/jib/tree/master/docs/self_sign_cert.md) may be an alternative to enabling this option. `useProjectOnlyCache` | `boolean` | `false` | If set to `true`, Jib does not share a cache between different Maven projects. @@ -205,7 +205,7 @@ Property | Type | Default | Description `useCurrentTimestamp` | `boolean` | `false` | By default, Jib wipes all timestamps to guarantee reproducibility. If this parameter is set to `true`, Jib will set the image's creation timestamp to the time of the build, which sacrifices reproducibility for easily being able to tell when your image was created. `user` | `String` | *None* | The user and group to run the container as. The value can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. -`extraDirectory` is an object with the following properties (see [Adding Arbitrary Files to the Image](#adding-arbitrary-files-to-the-image)): +`extraDirectory` is an object with the following properties (see [Adding Arbitrary Files to the Image](#adding-arbitrary-files-to-the-image)): Property | Type --- | --- diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index 61e577beef..139ec551bd 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -202,7 +202,7 @@ Field | Type | Default | Description `to` | [`to`](#to-object) | *Required* | Configures the target image to build your application to. `from` | [`from`](#from-object) | See [`from`](#from-object) | Configures the base image to build your application on top of. `container` | [`container`](#container-object) | See [`container`](#container-object) | Configures the container that is run from your image. -`extraDirectory` | [`extraDirectory`](#extraDirectory-object) / string | See `extraDirectory` | Configures the directory used to add arbitrary files to the image. +`extraDirectory` | [`extraDirectory`](#extradirectory-object) / string | See `extraDirectory` | Configures the directory used to add arbitrary files to the image. `allowInsecureRegistries` | boolean | `false` | If set to true, Jib ignores HTTPS certificate errors and may fall back to HTTP as a last resort. Leaving this parameter set to `false` is strongly recommended, since HTTP communication is unencrypted and visible to others on the network, and insecure HTTPS is no better than plain HTTP. [If accessing a registry with a self-signed certificate, adding the certificate to your Java runtime's trusted keys](https://github.com/GoogleContainerTools/jib/tree/master/docs/self_sign_cert.md) may be an alternative to enabling this option. `skip` | boolean | `false` | If set to true, Jib execution is skipped (useful for multi-module projects). This can also be specified via the `-Djib.skip` command line option. `useOnlyProjectCache` | boolean | `false` | If set to true, Jib does not share a cache between different Maven projects. @@ -247,7 +247,7 @@ Property | Type | Default | Description `useCurrentTimestamp` | boolean | `false` | By default, Jib wipes all timestamps to guarantee reproducibility. If this parameter is set to `true`, Jib will set the image's creation timestamp to the time of the build, which sacrifices reproducibility for easily being able to tell when your image was created. `user` | string | *None* | The user and group to run the container as. The value can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`. -`extraDirectory` is an object with the following properties (see [Adding Arbitrary Files to the Image](#adding-arbitrary-files-to-the-image)): +`extraDirectory` is an object with the following properties (see [Adding Arbitrary Files to the Image](#adding-arbitrary-files-to-the-image)): Property | Type --- | --- From 3e21c7b584cf91a1e4c9e3ab1f2dfbd3a4bb2480 Mon Sep 17 00:00:00 2001 From: Tad Cordle Date: Tue, 30 Oct 2018 14:17:11 -0400 Subject: [PATCH 08/19] Simplify extraDirectory explanation --- jib-gradle-plugin/README.md | 33 ++++++++++++------------- jib-maven-plugin/README.md | 49 +++++++++++++++++-------------------- 2 files changed, 38 insertions(+), 44 deletions(-) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index aeab76f1d1..426081f4b6 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -161,7 +161,7 @@ Field | Type | Default | Description `to` | [`to`](#to-closure) | *Required* | Configures the target image to build your application to. `from` | [`from`](#from-closure) | See [`from`](#from-closure) | Configures the base image to build your application on top of. `container` | [`container`](#container-closure) | See [`container`](#container-closure) | Configures the container that is run from your built image. -`extraDirectory` | [`extraDirectory`](#extradirectory-closure) / `File` | See `extraDirectory` | Configures the directory used to add arbitrary files to the image. +`extraDirectory` | [`extraDirectory`](#extradirectory-closure) / `File` | `(project-dir)/src/main/jib` | Configures the directory used to add arbitrary files to the image. `allowInsecureRegistries` | `boolean` | `false` | If set to true, Jib ignores HTTPS certificate errors and may fall back to HTTP as a last resort. Leaving this parameter set to `false` is strongly recommended, since HTTP communication is unencrypted and visible to others on the network, and insecure HTTPS is no better than plain HTTP. [If accessing a registry with a self-signed certificate, adding the certificate to your Java runtime's trusted keys](https://github.com/GoogleContainerTools/jib/tree/master/docs/self_sign_cert.md) may be an alternative to enabling this option. `useProjectOnlyCache` | `boolean` | `false` | If set to `true`, Jib does not share a cache between different Maven projects. @@ -257,27 +257,26 @@ jib { You can add arbitrary, non-classpath files to the image by placing them in a `src/main/jib` directory. This will copy all files within the `jib` folder to the image's root directory, maintaining the same structure (e.g. if you have a text file at `src/main/jib/dir/hello.txt`, then your image will contain `/dir/hello.txt` after being built with Jib). -You can configure a different directory by using the `extraDirectory` parameter in your `build.gradle`, either by using the `jib.extraDirectory.path` parameter: - -```groovy -// Copies files from 'src/main/custom-extra-dir' instead of 'src/main/jib' -jib.extraDirectory.path = file('src/main/custom-extra-dir') -``` - -or by setting the path on the `extraDirectory` parameter directly: - +You can configure a different directory by using the `jib.extraDirectory` parameter in your `build.gradle`: ```groovy -// Copies files from 'src/main/custom-extra-dir' instead of 'src/main/jib' -jib.extraDirectory = file('src/main/custom-extra-dir') +jib { + // Copies files from 'src/main/custom-extra-dir' instead of 'src/main/jib' + jib.extraDirectory = file('src/main/custom-extra-dir') +} ``` -The `extraDirectory` parameter can also be used to set the file permissions of files added to the container by specifying the absolute path of the file on the container as well as the octal representation of its file permission bits in the `jib.extraDirectory.permissions` field: +Alternatively, the `jib.extraDirectory` parameter can be used as a closure to set a custom extra directory, as well as the extra files' permissions on the container: ```groovy -jib.extraDirectory.permissions = [ - '/path/on/container/to/fileA': '755', // Read/write/execute for owner, read/execute for group/other - '/path/to/another/file': '644' // Read/write for owner, read-only for group/other -] +jib { + extraDirectory { + path = file('src/main/custom-extra-dir') // Copies files from 'src/main/custom-extra-dir' + permissions = [ + '/path/on/container/to/fileA': '755', // Read/write/execute for owner, read/execute for group/other + '/path/to/another/file': '644' // Read/write for owner, read-only for group/other + ] + } +} ``` ### Authentication Methods diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index 139ec551bd..260552e7a2 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -202,7 +202,7 @@ Field | Type | Default | Description `to` | [`to`](#to-object) | *Required* | Configures the target image to build your application to. `from` | [`from`](#from-object) | See [`from`](#from-object) | Configures the base image to build your application on top of. `container` | [`container`](#container-object) | See [`container`](#container-object) | Configures the container that is run from your image. -`extraDirectory` | [`extraDirectory`](#extradirectory-object) / string | See `extraDirectory` | Configures the directory used to add arbitrary files to the image. +`extraDirectory` | [`extraDirectory`](#extradirectory-object) / string | `(project-dir)/src/main/jib` | Configures the directory used to add arbitrary files to the image. `allowInsecureRegistries` | boolean | `false` | If set to true, Jib ignores HTTPS certificate errors and may fall back to HTTP as a last resort. Leaving this parameter set to `false` is strongly recommended, since HTTP communication is unencrypted and visible to others on the network, and insecure HTTPS is no better than plain HTTP. [If accessing a registry with a self-signed certificate, adding the certificate to your Java runtime's trusted keys](https://github.com/GoogleContainerTools/jib/tree/master/docs/self_sign_cert.md) may be an alternative to enabling this option. `skip` | boolean | `false` | If set to true, Jib execution is skipped (useful for multi-module projects). This can also be specified via the `-Djib.skip` command line option. `useOnlyProjectCache` | boolean | `false` | If set to true, Jib does not share a cache between different Maven projects. @@ -315,37 +315,32 @@ In this configuration, the image: You can add arbitrary, non-classpath files to the image by placing them in a `src/main/jib` directory. This will copy all files within the `jib` folder to the image's root directory, maintaining the same structure (e.g. if you have a text file at `src/main/jib/dir/hello.txt`, then your image will contain `/dir/hello.txt` after being built with Jib). -You can configure a different directory by using the `extraDirectory` parameter in your `pom.xml`, either by using the `` parameter: - -```xml - - - ${project.basedir}/src/main/custom-extra-dir - -``` - -or by setting the path on the `extraDirectory` parameter directly: - +You can configure a different directory by using the `` parameter in your `pom.xml`: ```xml - -${project.basedir}/src/main/custom-extra-dir + + + ${project.basedir}/src/main/custom-extra-dir + ``` -The `extraDirectory` parameter can also be used to set the file permissions of files added to the container by specifying the absolute path of the file on the container as well as the octal representation of its file permission bits in the `` field: +Alternatively, the `` parameter can be used as an object to set a custom extra directory, as well as the extra files' permissions on the container: ```xml - - - - /path/on/container/to/fileA - 755 - - - /path/to/another/file - 644 - - - + + + ${project.basedir}/src/main/custom-extra-dir + + + /path/on/container/to/fileA + 755 + + + /path/to/another/file + 644 + + + + ``` ### Authentication Methods From ff633e68171ce8c83ba61dd77e2f9b9faaed46a4 Mon Sep 17 00:00:00 2001 From: Tad Cordle Date: Tue, 30 Oct 2018 16:10:00 -0400 Subject: [PATCH 09/19] Fix extra jib --- jib-gradle-plugin/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index 426081f4b6..41a4e9ce66 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -261,7 +261,7 @@ You can configure a different directory by using the `jib.extraDirectory` parame ```groovy jib { // Copies files from 'src/main/custom-extra-dir' instead of 'src/main/jib' - jib.extraDirectory = file('src/main/custom-extra-dir') + extraDirectory = file('src/main/custom-extra-dir') } ``` From b156c7370d22229640711245be7408c2be6228fa Mon Sep 17 00:00:00 2001 From: Tad Cordle Date: Tue, 30 Oct 2018 16:25:08 -0400 Subject: [PATCH 10/19] Fix args explanation --- jib-gradle-plugin/README.md | 2 +- jib-maven-plugin/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index 41a4e9ce66..a5c44fca9d 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -194,7 +194,7 @@ Property | Type Property | Type | Default | Description --- | --- | --- | --- `appRoot` | `String` | `/app` | The root directory on the container where the app's contents are placed. -`args` | `List` | *None* | Default main method arguments to run your application with. +`args` | `List` | *None* | Additional program arguments appended to the command to start the container (similar to Docker's [CMD](https://docs.docker.com/engine/reference/builder/#cmd) instruction in relation with [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint)). In the default case where you do not set a custom `entrypoint`, this parameter is effectively the arguments to the main method of your Java application. `entrypoint` | `List` | *None* | The command to start the container with (similar to Docker's [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) instruction). If set, then `jvmFlags` and `mainClass` are ignored. `environment` | `Map` | *None* | Key-value pairs for setting environment variables on the container (similar to Docker's [ENV](https://docs.docker.com/engine/reference/builder/#env) instruction). `format` | `String` | `Docker` | Use `OCI` to build an [OCI container image](https://www.opencontainers.org/). diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index 260552e7a2..862fd324ff 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -236,7 +236,7 @@ Property | Type Property | Type | Default | Description --- | --- | --- | --- `appRoot` | string | `/app` | The root directory on the container where the app's contents are placed. -`args` | list | *None* | Default main method arguments to run your application with. +`args` | list | *None* | Additional program arguments appended to the command to start the container (similar to Docker's [CMD](https://docs.docker.com/engine/reference/builder/#cmd) instruction in relation with [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint)). In the default case where you do not set a custom `entrypoint`, this parameter is effectively the arguments to the main method of your Java application. `entrypoint` | list | *None* | The command to start the container with (similar to Docker's [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) instruction). If set, then `jvmFlags` and `mainClass` are ignored. `environment` | map | *None* | Key-value pairs for setting environment variables on the container (similar to Docker's [ENV](https://docs.docker.com/engine/reference/builder/#env) instruction). `format` | string | `Docker` | Use `OCI` to build an [OCI container image](https://www.opencontainers.org/). From 4fb9526d234fe3ba1fce29bb299b61ee0cc73163 Mon Sep 17 00:00:00 2001 From: Chanseok Oh Date: Fri, 2 Nov 2018 17:28:44 -0400 Subject: [PATCH 11/19] Add WAR documentation --- jib-gradle-plugin/README.md | 22 +++++++++++++++++++++- jib-maven-plugin/README.md | 27 ++++++++++++++++++++++++++- 2 files changed, 47 insertions(+), 2 deletions(-) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index a5c44fca9d..99e58c117b 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -193,7 +193,7 @@ Property | Type Property | Type | Default | Description --- | --- | --- | --- -`appRoot` | `String` | `/app` | The root directory on the container where the app's contents are placed. +`appRoot` | `String` | `/app` | The root directory on the container where the app's contents are placed. This property can particularly be useful for WAR packaging projects to work with different Servlet engine base images by placing exploded WAR contents into a certain location in the base image; see the [WAR usage](#war-projects) as an example. `args` | `List` | *None* | Additional program arguments appended to the command to start the container (similar to Docker's [CMD](https://docs.docker.com/engine/reference/builder/#cmd) instruction in relation with [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint)). In the default case where you do not set a custom `entrypoint`, this parameter is effectively the arguments to the main method of your Java application. `entrypoint` | `List` | *None* | The command to start the container with (similar to Docker's [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) instruction). If set, then `jvmFlags` and `mainClass` are ignored. `environment` | `Map` | *None* | Key-value pairs for setting environment variables on the container (similar to Docker's [ENV](https://docs.docker.com/engine/reference/builder/#env) instruction). @@ -350,6 +350,26 @@ jib { } ``` +### WAR Projects + +Jib supports creating images for projects that build a WAR. If the Gradle project uses the [WAR Plugin](https://docs.gradle.org/current/userguide/war_plugin.html), Jib will by default use the [distroless Jetty]https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) image as a base image to deploy the project WAR. No extra configuration is necessary than using the WAR Plugin to make Jib build WAR images. + +Note that Jib will work slightly differently for WAR projects from plain Java projects: + - `container.mainClass` and `container.jvmFlags` are ignored. + - The WAR will be exploded into `/jetty/webapps/ROOT`, which is the expected WAR location for the distroless Jetty base image. + +To use a different Servlet engine base image, you can customize `container.appRoot`, `container.entrypoint`, and `container.args`. If you do not set `entrypoint` or `args`, Jib will inherit the `ENTRYPOINT` and `CMD` of the base image, so in many cases, you may need to configure them. However, you will most likely have to set `container.appRoot` to a proper location depending on the base image. Here is an example of using a Tomcat image: + +```gradle +jib { + from.image = 'tomcat:8.5-jre8-alpine' + + // For demonstration only: this directory in the base image contains a Tomcat default + // app (welcome page), so you may first want to delete this directory in the base image. + container.appRoot = '/usr/local/tomcat/webapps/ROOT' +} +``` + ## How Jib Works See the [Jib project README](/../../#how-jib-works). diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index 862fd324ff..605269926b 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -235,7 +235,7 @@ Property | Type Property | Type | Default | Description --- | --- | --- | --- -`appRoot` | string | `/app` | The root directory on the container where the app's contents are placed. +`appRoot` | string | `/app` | The root directory on the container where the app's contents are placed. This property can particularly be useful for WAR packaging projects to work with different Servlet engine base images by placing exploded WAR contents into a certain location in the base image; see the [WAR usage](#war-projects) as an example. `args` | list | *None* | Additional program arguments appended to the command to start the container (similar to Docker's [CMD](https://docs.docker.com/engine/reference/builder/#cmd) instruction in relation with [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint)). In the default case where you do not set a custom `entrypoint`, this parameter is effectively the arguments to the main method of your Java application. `entrypoint` | list | *None* | The command to start the container with (similar to Docker's [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) instruction). If set, then `jvmFlags` and `mainClass` are ignored. `environment` | map | *None* | Key-value pairs for setting environment variables on the container (similar to Docker's [ENV](https://docs.docker.com/engine/reference/builder/#env) instruction). @@ -439,6 +439,31 @@ If you're considering putting credentials in Maven, we highly *recommend* using * The `id` field should be the registry server these credentials are for. * We *do not* recommend putting your raw password in `settings.xml`. +### WAR Projects + +Jib supports creating images for projects that build a WAR. If the Gradle project uses the [WAR Plugin](https://docs.gradle.org/current/userguide/war_plugin.html), Jib will by default use the [distroless Jetty]https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) image as a base image to deploy the project WAR. No extra configuration is necessary than using the WAR Plugin to make Jib build WAR images. + +Note that Jib will work slightly differently for WAR projects from plain Java projects: + - `container.mainClass` and `container.jvmFlags` are ignored. + - The WAR will be exploded into `/jetty/webapps/ROOT`, which is the expected WAR location for the distroless Jetty base image. + +To use a different Servlet engine base image, you can customize `container.appRoot`, `container.entrypoint`, and `container.args`. If you do not set `entrypoint` or `args`, Jib will inherit the `ENTRYPOINT` and `CMD` of the base image, so in many cases, you may need to configure them. However, you will most likely have to set `container.appRoot` to a proper location depending on the base image. Here is an example of using a Tomcat image: + +```xml + + + tomcat:8.5-jre8-alpine + + + + /usr/local/tomcat/webapps/ROOT + + +``` + ## How Jib Works See the [Jib project README](/../../#how-jib-works). From e5b9ecd59d9ebcfbc8034ac17d998227f6a13375 Mon Sep 17 00:00:00 2001 From: Chanseok Oh Date: Fri, 2 Nov 2018 17:31:47 -0400 Subject: [PATCH 12/19] Update wording --- jib-gradle-plugin/README.md | 2 +- jib-maven-plugin/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index 99e58c117b..558a8e5439 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -193,7 +193,7 @@ Property | Type Property | Type | Default | Description --- | --- | --- | --- -`appRoot` | `String` | `/app` | The root directory on the container where the app's contents are placed. This property can particularly be useful for WAR packaging projects to work with different Servlet engine base images by placing exploded WAR contents into a certain location in the base image; see the [WAR usage](#war-projects) as an example. +`appRoot` | `String` | `/app` | The root directory on the container where the app's contents are placed. Particularly useful for WAR packaging projects to work with different Servlet engine base images by designating where to exploded WAR contents; see the [WAR usage](#war-projects) as an example. `args` | `List` | *None* | Additional program arguments appended to the command to start the container (similar to Docker's [CMD](https://docs.docker.com/engine/reference/builder/#cmd) instruction in relation with [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint)). In the default case where you do not set a custom `entrypoint`, this parameter is effectively the arguments to the main method of your Java application. `entrypoint` | `List` | *None* | The command to start the container with (similar to Docker's [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) instruction). If set, then `jvmFlags` and `mainClass` are ignored. `environment` | `Map` | *None* | Key-value pairs for setting environment variables on the container (similar to Docker's [ENV](https://docs.docker.com/engine/reference/builder/#env) instruction). diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index 605269926b..82b3a1e1db 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -235,7 +235,7 @@ Property | Type Property | Type | Default | Description --- | --- | --- | --- -`appRoot` | string | `/app` | The root directory on the container where the app's contents are placed. This property can particularly be useful for WAR packaging projects to work with different Servlet engine base images by placing exploded WAR contents into a certain location in the base image; see the [WAR usage](#war-projects) as an example. +`appRoot` | string | `/app` | The root directory on the container where the app's contents are placed. Particularly useful for WAR packaging projects to work with different Servlet engine base images by designating where to exploded WAR contents; see the [WAR usage](#war-projects) as an example. `args` | list | *None* | Additional program arguments appended to the command to start the container (similar to Docker's [CMD](https://docs.docker.com/engine/reference/builder/#cmd) instruction in relation with [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint)). In the default case where you do not set a custom `entrypoint`, this parameter is effectively the arguments to the main method of your Java application. `entrypoint` | list | *None* | The command to start the container with (similar to Docker's [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) instruction). If set, then `jvmFlags` and `mainClass` are ignored. `environment` | map | *None* | Key-value pairs for setting environment variables on the container (similar to Docker's [ENV](https://docs.docker.com/engine/reference/builder/#env) instruction). From 957435447fe035c4657ab79595605a08dd85467a Mon Sep 17 00:00:00 2001 From: Chanseok Oh Date: Fri, 2 Nov 2018 17:33:15 -0400 Subject: [PATCH 13/19] Fix Maven --- jib-maven-plugin/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index 82b3a1e1db..d5b59ac676 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -441,7 +441,7 @@ If you're considering putting credentials in Maven, we highly *recommend* using ### WAR Projects -Jib supports creating images for projects that build a WAR. If the Gradle project uses the [WAR Plugin](https://docs.gradle.org/current/userguide/war_plugin.html), Jib will by default use the [distroless Jetty]https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) image as a base image to deploy the project WAR. No extra configuration is necessary than using the WAR Plugin to make Jib build WAR images. +Jib supports creating images for projects that build a WAR. If the packaging of the Maven project is `war`, Jib will by default use the [distroless Jetty]https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) image as a base image to deploy the project WAR. No extra configuration is necessary than using the WAR Plugin to make Jib build WAR images. Note that Jib will work slightly differently for WAR projects from plain Java projects: - `container.mainClass` and `container.jvmFlags` are ignored. From cc8587e736ead04237bd92350735d21b622aa210 Mon Sep 17 00:00:00 2001 From: Chanseok Oh Date: Fri, 2 Nov 2018 17:45:45 -0400 Subject: [PATCH 14/19] More fixes --- jib-gradle-plugin/README.md | 2 +- jib-maven-plugin/README.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index 558a8e5439..cf0e1ada4d 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -352,7 +352,7 @@ jib { ### WAR Projects -Jib supports creating images for projects that build a WAR. If the Gradle project uses the [WAR Plugin](https://docs.gradle.org/current/userguide/war_plugin.html), Jib will by default use the [distroless Jetty]https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) image as a base image to deploy the project WAR. No extra configuration is necessary than using the WAR Plugin to make Jib build WAR images. +Jib supports creating images for projects that build a WAR. If the Gradle project uses the [WAR Plugin](https://docs.gradle.org/current/userguide/war_plugin.html), Jib will by default use the [distroless Jetty]https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) as a base image to deploy the project WAR. No extra configuration is necessary than using the WAR Plugin to make Jib build WAR images. Note that Jib will work slightly differently for WAR projects from plain Java projects: - `container.mainClass` and `container.jvmFlags` are ignored. diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index d5b59ac676..8d999ae0e5 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -441,10 +441,10 @@ If you're considering putting credentials in Maven, we highly *recommend* using ### WAR Projects -Jib supports creating images for projects that build a WAR. If the packaging of the Maven project is `war`, Jib will by default use the [distroless Jetty]https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) image as a base image to deploy the project WAR. No extra configuration is necessary than using the WAR Plugin to make Jib build WAR images. +Jib supports creating images for projects that build a WAR. If the Maven project uses [the `war` packaging type](https://maven.apache.org/plugins/maven-war-plugin/index.html), Jib will by default use the [distroless Jetty]https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) as a base image to deploy the project WAR. No extra configuration is necessary than having the packaging type to `war`. Note that Jib will work slightly differently for WAR projects from plain Java projects: - - `container.mainClass` and `container.jvmFlags` are ignored. + - `` and `` are ignored. - The WAR will be exploded into `/jetty/webapps/ROOT`, which is the expected WAR location for the distroless Jetty base image. To use a different Servlet engine base image, you can customize `container.appRoot`, `container.entrypoint`, and `container.args`. If you do not set `entrypoint` or `args`, Jib will inherit the `ENTRYPOINT` and `CMD` of the base image, so in many cases, you may need to configure them. However, you will most likely have to set `container.appRoot` to a proper location depending on the base image. Here is an example of using a Tomcat image: From 85585de13394c113e71c5a79cdf4dccc98316010 Mon Sep 17 00:00:00 2001 From: Chanseok Oh Date: Mon, 5 Nov 2018 12:25:58 -0500 Subject: [PATCH 15/19] Update wordings --- jib-gradle-plugin/README.md | 6 +++--- jib-maven-plugin/README.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index cf0e1ada4d..14831248b2 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -193,7 +193,7 @@ Property | Type Property | Type | Default | Description --- | --- | --- | --- -`appRoot` | `String` | `/app` | The root directory on the container where the app's contents are placed. Particularly useful for WAR packaging projects to work with different Servlet engine base images by designating where to exploded WAR contents; see the [WAR usage](#war-projects) as an example. +`appRoot` | `String` | `/app` | The root directory on the container where the app's contents are placed. Particularly useful for WAR-packaging projects to work with different Servlet engine base images by designating where to put exploded WAR contents; see [WAR usage](#war-projects) as an example. `args` | `List` | *None* | Additional program arguments appended to the command to start the container (similar to Docker's [CMD](https://docs.docker.com/engine/reference/builder/#cmd) instruction in relation with [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint)). In the default case where you do not set a custom `entrypoint`, this parameter is effectively the arguments to the main method of your Java application. `entrypoint` | `List` | *None* | The command to start the container with (similar to Docker's [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) instruction). If set, then `jvmFlags` and `mainClass` are ignored. `environment` | `Map` | *None* | Key-value pairs for setting environment variables on the container (similar to Docker's [ENV](https://docs.docker.com/engine/reference/builder/#env) instruction). @@ -352,9 +352,9 @@ jib { ### WAR Projects -Jib supports creating images for projects that build a WAR. If the Gradle project uses the [WAR Plugin](https://docs.gradle.org/current/userguide/war_plugin.html), Jib will by default use the [distroless Jetty]https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) as a base image to deploy the project WAR. No extra configuration is necessary than using the WAR Plugin to make Jib build WAR images. +Jib also containerizes WAR projects. If the Gradle project uses the [WAR Plugin](https://docs.gradle.org/current/userguide/war_plugin.html), Jib will by default use the [distroless Jetty](https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) as a base image to deploy the project WAR. No extra configuration is necessary other than using the WAR Plugin to make Jib build WAR images. -Note that Jib will work slightly differently for WAR projects from plain Java projects: +Note that Jib will work slightly differently for WAR projects from JAR projects: - `container.mainClass` and `container.jvmFlags` are ignored. - The WAR will be exploded into `/jetty/webapps/ROOT`, which is the expected WAR location for the distroless Jetty base image. diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index 8d999ae0e5..16be3e8e08 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -235,7 +235,7 @@ Property | Type Property | Type | Default | Description --- | --- | --- | --- -`appRoot` | string | `/app` | The root directory on the container where the app's contents are placed. Particularly useful for WAR packaging projects to work with different Servlet engine base images by designating where to exploded WAR contents; see the [WAR usage](#war-projects) as an example. +`appRoot` | string | `/app` | The root directory on the container where the app's contents are placed. Particularly useful for WAR-packaging projects to work with different Servlet engine base images by designating where to put exploded WAR contents; see [WAR usage](#war-projects) as an example. `args` | list | *None* | Additional program arguments appended to the command to start the container (similar to Docker's [CMD](https://docs.docker.com/engine/reference/builder/#cmd) instruction in relation with [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint)). In the default case where you do not set a custom `entrypoint`, this parameter is effectively the arguments to the main method of your Java application. `entrypoint` | list | *None* | The command to start the container with (similar to Docker's [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) instruction). If set, then `jvmFlags` and `mainClass` are ignored. `environment` | map | *None* | Key-value pairs for setting environment variables on the container (similar to Docker's [ENV](https://docs.docker.com/engine/reference/builder/#env) instruction). @@ -441,9 +441,9 @@ If you're considering putting credentials in Maven, we highly *recommend* using ### WAR Projects -Jib supports creating images for projects that build a WAR. If the Maven project uses [the `war` packaging type](https://maven.apache.org/plugins/maven-war-plugin/index.html), Jib will by default use the [distroless Jetty]https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) as a base image to deploy the project WAR. No extra configuration is necessary than having the packaging type to `war`. +Jib also containerizes WAR projects. If the Maven project uses [the `war` packaging type](https://maven.apache.org/plugins/maven-war-plugin/index.html), Jib will by default use the [distroless Jetty](https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) as a base image to deploy the project WAR. No extra configuration is necessary other than having the packaging type to `war`. -Note that Jib will work slightly differently for WAR projects from plain Java projects: +Note that Jib will work slightly differently for WAR projects from JAR projects: - `` and `` are ignored. - The WAR will be exploded into `/jetty/webapps/ROOT`, which is the expected WAR location for the distroless Jetty base image. From 89b794dece6862c1bb61014b7921b305530f782d Mon Sep 17 00:00:00 2001 From: Chanseok Oh Date: Mon, 5 Nov 2018 12:30:53 -0500 Subject: [PATCH 16/19] In Maven style --- jib-maven-plugin/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index 16be3e8e08..f0b5602044 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -441,13 +441,13 @@ If you're considering putting credentials in Maven, we highly *recommend* using ### WAR Projects -Jib also containerizes WAR projects. If the Maven project uses [the `war` packaging type](https://maven.apache.org/plugins/maven-war-plugin/index.html), Jib will by default use the [distroless Jetty](https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) as a base image to deploy the project WAR. No extra configuration is necessary other than having the packaging type to `war`. +Jib also containerizes WAR projects. If the Maven project uses [the `war`-packaging type](https://maven.apache.org/plugins/maven-war-plugin/index.html), Jib will by default use the [distroless Jetty](https://github.com/GoogleContainerTools/distroless/tree/master/java/jetty) as a base image to deploy the project WAR. No extra configuration is necessary other than having the packaging type to `war`. Note that Jib will work slightly differently for WAR projects from JAR projects: - `` and `` are ignored. - The WAR will be exploded into `/jetty/webapps/ROOT`, which is the expected WAR location for the distroless Jetty base image. -To use a different Servlet engine base image, you can customize `container.appRoot`, `container.entrypoint`, and `container.args`. If you do not set `entrypoint` or `args`, Jib will inherit the `ENTRYPOINT` and `CMD` of the base image, so in many cases, you may need to configure them. However, you will most likely have to set `container.appRoot` to a proper location depending on the base image. Here is an example of using a Tomcat image: +To use a different Servlet engine base image, you can customize ``, ``, and ``. If you do not set `entrypoint` or `args`, Jib will inherit the `ENTRYPOINT` and `CMD` of the base image, so in many cases, you may need to configure them. However, you will most likely have to set `` to a proper location depending on the base image. Here is an example of using a Tomcat image: ```xml From 4255457c1106d43c77ce3cab99c9842d99d8a4c6 Mon Sep 17 00:00:00 2001 From: Tad Cordle Date: Mon, 5 Nov 2018 15:55:28 -0500 Subject: [PATCH 17/19] Update credHelper explanation --- jib-gradle-plugin/README.md | 4 ++-- jib-maven-plugin/README.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index 14831248b2..816ab89a37 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -171,7 +171,7 @@ Property | Type | Default | Description --- | --- | --- | --- `image` | `String` | `gcr.io/distroless/java` | The image reference for the base image. `auth` | [`auth`](#auth-closure) | *None* | Specify credentials directly (alternative to `credHelper`). -`credHelper` | `String` | *None* | Suffix for the credential helper that can authenticate pulling the base image (following `docker-credential-`). +`credHelper` | `String` | *None* | Specifies a credential helper that can authenticate pulling the base image. This parameter can either be configured as an absolute path to the credential helper executable or as a credential helper suffix (following `docker-credential-`). `to` is a closure with the following properties: @@ -179,7 +179,7 @@ Property | Type | Default | Description --- | --- | --- | --- `image` | `String` | *Required* | The image reference for the target image. This can also be specified via the `--image` command line option. `auth` | [`auth`](#auth-closure) | *None* | Specify credentials directly (alternative to `credHelper`). -`credHelper` | `String` | *None* | Suffix for the credential helper that can authenticate pulling the base image (following `docker-credential-`). +`credHelper` | `String` | *None* | Specifies a credential helper that can authenticate pushing the target image. This parameter can either be configured as an absolute path to the credential helper executable or as a credential helper suffix (following `docker-credential-`). `tags` | `List` | *None* | Additional tags to push to. `auth` is a closure with the following properties (see [Using Specific Credentials](#using-specific-credentials)): diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index f0b5602044..00e4118a8c 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -213,7 +213,7 @@ Property | Type | Default | Description --- | --- | --- | --- `image` | string | `gcr.io/distroless/java` | The image reference for the base image. `auth` | [`auth`](#auth-object) | *None* | Specify credentials directly (alternative to `credHelper`). -`credHelper` | string | *None* | Suffix for the credential helper that can authenticate pulling the base image (following `docker-credential-`). +`credHelper` | string | *None* | Specifies a credential helper that can authenticate pulling the base image. This parameter can either be configured as an absolute path to the credential helper executable or as a credential helper suffix (following `docker-credential-`). `to` is an object with the following properties: @@ -221,7 +221,7 @@ Property | Type | Default | Description --- | --- | --- | --- `image` | string | *Required* | The image reference for the target image. This can also be specified via the `-Dimage` command line option. `auth` | [`auth`](#auth-object) | *None* | Specify credentials directly (alternative to `credHelper`). -`credHelper` | string | *None* | Suffix for the credential helper that can authenticate pulling the base image (following `docker-credential-`). +`credHelper` | string | *None* | Specifies a credential helper that can authenticate pushing the target image. This parameter can either be configured as an absolute path to the credential helper executable or as a credential helper suffix (following `docker-credential-`). `tags` | list | *None* | Additional tags to push to. `auth` is an object with the following properties (see [Using Specific Credentials](#using-specific-credentials)): From a4779597b51a75c336e7b9e61d7921ef5353a013 Mon Sep 17 00:00:00 2001 From: Tad Cordle Date: Wed, 7 Nov 2018 16:16:45 -0500 Subject: [PATCH 18/19] Add system property explanation and examples --- jib-gradle-plugin/README.md | 16 ++++++++++++++++ jib-maven-plugin/README.md | 16 ++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index 816ab89a37..94c13c4cab 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -212,6 +212,22 @@ Property | Type `path` | `File` `permissions` | `Map` +#### System Properties + +Each of these parameters is configurable via commandline using system properties. Jib's system properties follow the same naming convention as the configuration parameters, with each level separated by dots (i.e. `-Djib.parameterName[.nestedParameter.[...]]=value`). Some examples are below: +```shell +gradle jib \ + -Djib.to.image=myregistry/myimage:latest \ + -Djib.to.auth.username=$USERNAME \ + -Djib.to.auth.password=$PASSWORD + +gradle jibDockerBuild \ + -Djib.container.environment=key1="value1",key2="value2" \ + -Djib.container.args=arg1,arg2,arg3 + +gradle jibBuildTar -Djib.useProjectOnlyCache=true +``` + You can also configure HTTP connection/read timeouts for registry interactions using the `jib.httpTimeout` system property, configured in milliseconds via commandline (the default is `20000`; you can also set it to `0` for infinite timeout): ```shell diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index 00e4118a8c..d8e85d9c8b 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -254,6 +254,22 @@ Property | Type `path` | string `permissions` | list +#### System Properties + +Each of these parameters is configurable via commandline using system properties. Jib's system properties follow the same naming convention as the configuration parameters, with each level separated by dots (i.e. `-Djib.parameterName[.nestedParameter.[...]]=value`). Some examples are below: +```shell +mvn compile jib:build \ + -Djib.to.image=myregistry/myimage:latest \ + -Djib.to.auth.username=$USERNAME \ + -Djib.to.auth.password=$PASSWORD + +mvn compile jib:dockerBuild \ + -Djib.container.environment=key1="value1",key2="value2" \ + -Djib.container.args=arg1,arg2,arg3 + +mvn jib:buildTar -Djib.useProjectOnlyCache=true +``` + You can also configure HTTP connection/read timeouts for registry interactions using the `jib.httpTimeout` system property, configured in milliseconds via commandline (the default is `20000`; you can also set it to `0` for infinite timeout): ```shell From 1b38a5baf281f322a08b1b616720aaad131acc32 Mon Sep 17 00:00:00 2001 From: Brian de Alwis Date: Thu, 8 Nov 2018 11:10:12 -0500 Subject: [PATCH 19/19] Add jib-image.digest notes to README --- jib-gradle-plugin/README.md | 5 +++++ jib-maven-plugin/README.md | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md index 94c13c4cab..c3d86e846c 100644 --- a/jib-gradle-plugin/README.md +++ b/jib-gradle-plugin/README.md @@ -152,6 +152,11 @@ You can then build your image with Docker: docker build -t myimage my/docker/context/ ``` +### Additional Build Artifacts + +As part of an image build, Jib also writes out the _image digest_ to +`build/jib-image.digest`. + ## Extended Usage The plugin provides the `jib` extension for configuration with the following options for customizing the image build: diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md index d8e85d9c8b..f86d567da9 100644 --- a/jib-maven-plugin/README.md +++ b/jib-maven-plugin/README.md @@ -193,6 +193,11 @@ You can then build your image with Docker: docker build -t myimage my/docker/context/ ``` +### Additional Build Artifacts + +As part of an image build, Jib also writes out the _image digest_ to +`target/jib-image.digest`. + ## Extended Usage Extended configuration options provide additional options for customizing the image build.