jib-maven-plugin

Jib - Containerize your Maven project

Jib is a Maven plugin for building Docker and OCI images for your Java applications.

For information about the project, see the Jib project README. For the Gradle plugin, see the jib-gradle-plugin project.

Upcoming Features

See Milestones for planned features. Get involved with the community for the latest updates.

Quickstart

You can containerize your application easily with one command:

mvn compile com.google.cloud.tools:jib-maven-plugin:0.9.11:build -Dimage=<MY IMAGE>

This builds and pushes a container image for your application to a container registry. If you encounter authentication issues, see Authentication Methods.

To build to a Docker daemon, use:

mvn compile com.google.cloud.tools:jib-maven-plugin:0.9.11:dockerBuild

If you would like to set up Jib as part of your Maven build, follow the guide below.

Setup

In your Maven Java project, add the plugin to your pom.xml:

<project>
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>jib-maven-plugin</artifactId>
        <version>0.9.11</version>
        <configuration>
          <to>
            <image>myimage</image>
          </to>
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

Configuration

Configure the plugin by setting the image to push to:

Using Google Container Registry (GCR)...

Make sure you have the docker-credential-gcr command line tool. Jib automatically uses docker-credential-gcr for obtaining credentials. See Authentication Methods for other ways of authenticating.

For example, to build the image gcr.io/my-gcp-project/my-app, the configuration would be:

<configuration>
  <to>
    <image>gcr.io/my-gcp-project/my-app</image>
  </to>
</configuration>

Using Amazon Elastic Container Registry (ECR)...

Make sure you have the docker-credential-ecr-login command line tool. Jib automatically uses docker-credential-ecr-login for obtaining credentials. See Authentication Methods for other ways of authenticating.

For example, to build the image aws_account_id.dkr.ecr.region.amazonaws.com/my-app, the configuration would be:

<configuration>
  <to>
    <image>aws_account_id.dkr.ecr.region.amazonaws.com/my-app</image>
  </to>
</configuration>

Using Docker Hub Registry...

Make sure you have a docker-credential-helper set up. For example, on macOS, the credential helper would be docker-credential-osxkeychain. See Authentication Methods for other ways of authenticating.

For example, to build the image my-docker-id/my-app, the configuration would be:

<configuration>
  <to>
    <image>registry.hub.docker.com/my-docker-id/my-app</image>
  </to>
</configuration>

TODO: Add more examples for common registries.

Build your image

Build your container image with:

mvn compile jib:build

Subsequent builds are much faster than the initial build.

Having trouble? Let us know by submitting an issue, contacting us on Gitter, or posting to the Jib users forum.

Build to Docker daemon

Jib can also build your image directly to a Docker daemon. This uses the docker command line tool and requires that you have docker available on your PATH.

mvn compile jib:dockerBuild

If you are using minikube's remote Docker daemon, make sure you set up the correct environment variables to point to the remote daemon:

eval $(minikube docker-env)
mvn compile jib:dockerBuild

Build an image tarball

You can build and save your image to disk as a tarball with:

mvn compile jib:buildTar

This builds and saves your image to target/jib-image.tar, which you can load into docker with:

docker load --input target/jib-image.tar

Bind to a lifecycle

You can also bind jib:build to a Maven lifecycle, such as package, by adding the following execution to your jib-maven-plugin definition:

<plugin>
  <groupId>com.google.com.tools</groupId>
  <artifactId>jib-maven-plugin</artifactId>
  ...
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>build</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Then, you can build your container image by running:

mvn package

Export to a Docker context

Jib can also export a Docker context so that you can build with Docker, if needed:

mvn compile jib:exportDockerContext

The Docker context will be created at target/jib-docker-context by default. You can change this directory with the targetDir configuration option or the jibTargetDir parameter:

mvn compile jib:exportDockerContext -DjibTargetDir=my/docker/context/

You can then build your image with Docker:

docker build -t myimage my/docker/context/

Extended Usage

Extended configuration options provide additional options for customizing the image build.

Field	Type	Default	Description
to	to	Required	Configures the target image to build your application to.
from	from	See from	Configures the base image to build your application on top of.
container	container	See container	Configures the container that is run from your 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 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.

from is an object with the following properties:

Property	Type	Default	Description
image	string	gcr.io/distroless/java	The image reference for the base image.
auth	auth	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-).

to is an object with the following properties:

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	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-).
tags	list	None	Additional tags to push to.

auth is an object with the following properties (see Using Specific Credentials):

Property	Type
username	String
password	String

container is an object with the following properties:

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.
entrypoint	list	None	The command to start the container with (similar to Docker's 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 instruction).
format	string	Docker	Use OCI to build an OCI container image.
jvmFlags	list	None	Additional flags to pass into the JVM when running your application.
labels	map	None	Key-value pairs for applying image metadata (similar to Docker's LABEL instruction).
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 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.

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):

mvn compile jib:build -Djib.httpTimeout=3000

* Uses mainClass from maven-jar-plugin or tries to find a valid main class.

Example

In this configuration, the image:

• Is built from a base of openjdk:alpine (pulled from Docker Hub)
• Is pushed to localhost:5000/my-image:built-with-jib, localhost:5000/my-image:tag2, and localhost:5000/my-image:latest
• Runs by calling java -Xms512m -Xdebug -Xmy:flag=jib-rules -cp app/libs/*:app/resources:app/classes mypackage.MyApp some args
• Exposes port 1000 for tcp (default), and ports 2000, 2001, 2002, and 2003 for udp
• Has two labels (key1:value1 and key2:value2)
• Is built as OCI format

<configuration>
  <from>
    <image>openjdk:alpine</image>
  </from>
  <to>
    <image>localhost:5000/my-image:built-with-jib</image>
    <credHelper>osxkeychain</credHelper>
    <tags>
      <tag>tag2</tag>
      <tag>latest</tag>
    </tags>
  </to>
  <container>
    <jvmFlags>
      <jvmFlag>-Xms512m</jvmFlag>
      <jvmFlag>-Xdebug</jvmFlag>
      <jvmFlag>-Xmy:flag=jib-rules</jvmFlag>
    </jvmFlags>
    <mainClass>mypackage.MyApp</mainClass>
    <args>
      <arg>some</arg>
      <arg>args</arg>
    </args>
    <ports>
      <port>1000</port>
      <port>2000-2003/udp</port>
    </ports>
    <labels>
      <key1>value1</key1>
      <key2>value2</key2>
    </labels>
    <format>OCI</format>
  </container>
</configuration>

Adding Arbitrary Files to the Image

* Note: this is an incubating feature and may change in the future.

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:

<configuration>
  ...
  <!-- Copies files from 'src/main/custom-extra-dir' instead of 'src/main/jib' -->
  <extraDirectory>${project.basedir}/src/main/custom-extra-dir</extraDirectory>
  ...
</configuration>

Authentication Methods

Pushing/pulling from private registries require authorization credentials. These can be retrieved using Docker credential helpers or defined in your Maven settings. If you do not define credentials explicitly, Jib will try to use credentials defined in your Docker config or infer common credential helpers.

Using Docker Credential Helpers

Docker credential helpers are CLI tools that handle authentication with various registries.

Some common credential helpers include:

• Google Container Registry: docker-credential-gcr
• AWS Elastic Container Registry: docker-credential-ecr-login
• Docker Hub Registry: docker-credential-*

Configure credential helpers to use by specifying them as a credHelper for their respective image.

Example configuration:

<configuration>
  ...
  <from>
    <image>aws_account_id.dkr.ecr.region.amazonaws.com/my-base-image</image>
    <credHelper>ecr-login</credHelper>
  </from>
  <to>
    <image>gcr.io/my-gcp-project/my-app</image>
    <credHelper>gcr</credHelper>
  </to>
  ...
</configuration>

Using Specific Credentials

You can specify credentials directly in the <auth> parameter for the from and/or to images. In the example below, to credentials are retrieved from the REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables.

<configuration>
  ...
  <from>
    <image>aws_account_id.dkr.ecr.region.amazonaws.com/my-base-image</image>
    <auth>
      <username>my_username</username>
      <password>my_password</password>
    </auth>
  </from>
  <to>
    <image>gcr.io/my-gcp-project/my-app</image>
    <auth>
      <username>${env.REGISTRY_USERNAME}</username>
      <password>${env.REGISTRY_PASSWORD}</password>
    </auth>
  </to>
  ...
</configuration>

Alternatively, you can specify credentials via commandline using the following system properties.

Property	Description
-Djib.from.auth.username	Username for base image registry.
-Djib.from.auth.password	Password for base image registry.
-Djib.to.auth.username	Username for target image registry.
-Djib.to.auth.password	Password for target image registry.

e.g. mvn compile jib:build -Djib.to.auth.username=user -Djib.to.auth.password=pass

Note: This method of authentication should be used only as a last resort, as it is insecure to make your password visible in plain text.

Using Maven Settings

Registry credentials can be added to your Maven settings. These credentials will be used if credentials could not be found in any specified Docker credential helpers.

If you're considering putting credentials in Maven, we highly recommend using maven password encryption.

Example settings.xml:

<settings>
  ...
  <servers>
    ...
    <server>
      <id>MY_REGISTRY</id>
      <username>MY_USERNAME</username>
      <password>{MY_SECRET}</password>
    </server>
  </servers>
</settings>

• The id field should be the registry server these credentials are for.
• We do not recommend putting your raw password in settings.xml.

How Jib Works

See the Jib project README.

Frequently Asked Questions (FAQ)

See the Jib project FAQ.

Community

See the Jib project README.