jib-core

Jib Core - Java library for building containers

Jib Core is a Java library for building Docker and OCI container images. It implements a general-purpose container builder that can be used to build containers without a Docker daemon, for any application. The implementation is pure Java.

The API is currently in alpha and may change substantially.

Jib Core powers the popular Jib plugins for Maven and Gradle. The plugins build containers specifically for JVM languages and separate the application into multiple layers to optimize for fast rebuilds.
For the Maven plugin, see the jib-maven-plugin project.
For the Gradle plugin, see the jib-gradle-plugin project.

For information about the Jib project, see the Jib project README.

Adding Jib Core to your build

Add Jib Core as a dependency using Maven:

<dependency>
  <groupId>com.google.cloud.tools</groupId>
  <artifactId>jib-core</artifactId>
  <version>0.9.2</version>
</dependency>

Add Jib Core as a dependency using Gradle:

dependencies {
  compile 'com.google.cloud.tools:jib-core:0.9.2'
}

Simple example

Jib.from("busybox")
   .addLayer(Arrays.asList(Paths.get("helloworld.sh")), AbsoluteUnixPath.get("/")) 
   .setEntrypoint("sh", "/helloworld.sh")
   .containerize(
       Containerizer.to(RegistryImage.named("gcr.io/my-project/hello-from-jib")
                                     .addCredential("myusername", "mypassword")));

1. Jib.from("busybox") creates a new JibContainerBuilder configured with busybox as the base image.
2. .addLayer(...) configures the JibContainerBuilder with a new layer with helloworld.sh (local file) to be placed into the container at /helloworld.sh.
3. .setEntrypoint("sh", "/helloworld.sh") sets the entrypoint of the container to run /helloworld.sh.
4. RegistryImage.named("gcr.io/my-project/hello-from-jib") creates a new RegistryImage configured with gcr.io/my-project/hello-from-jib as the target image to push to.
5. .addCredential adds the username/password credentials to authenticate the push to gcr.io/my-project/hello-from-jib. See CredentialRetrieverFactory for common credential retrievers (to retrieve credentials from Docker config or credential helpers, for example). These credential retrievers an be used with .addCredentialRetriever.
6. Containerizer.to creates a new Containerizer configured to push to the RegistryImage.
7. .containerize executes the containerization. If successful, the container image will be available at gcr.io/my-project/hello-from-jib.

Tutorials

None yet available. We welcome contributions for examples and tutorials!

API overview

Jib - the main entrypoint for using Jib Core

JibContainerBuilder - configures the container to build

Containerizer - configures how and where to containerize to

JibContainer - information about the built container

Three TargetImage types define the 3 different targets Jib can build to:

• RegistryImage - builds to a container registry
• DockerDaemonImage - builds to a Docker daemon
• TarImage - saves as a tarball archive

Other useful classes:

• ImageReference - represents an image reference and has useful methods for parsing and manipulating image references
• LayerConfiguration - configures a container layer to build
• CredentialRetriever - implement with custom credential retrieval methods for authenticating against a container registry
• CredentialRetrieverFactory - provides useful CredentialRetrievers to retrieve credentials from Docker config and credential helpers
• EventHandlers - attach event handlers to handle events dispatched during the container build execution

Java-specific API:

• JavaContainerBuilder - configures a JibContainerBuilder for Java-specific applications
• MainClassFinder - find the main Java class in a given list of class files

API reference

API reference

How Jib Core works

The Jib Core system consists 3 main parts:

• an execution orchestrator that executes an asynchronous pipeline of containerization steps,
• an image manipulator capable of handling Docker and OCI image formats, and
• a registry client that implements the Docker Registry V2 API.

Some other parts of Jib Core internals include:

• a caching mechanism to speed up builds (configurable with Containerizer.setApplicationLayersCache and Containerizer.setBaseImageLayersCache)
• an eventing system to react to events from Jib Core during its execution (add handlers with Containerizer.setEventHandlers)
• support for fully-concurrent multi-threaded executions

Events

Throughout the build process, Jib Core dispatches events that provide useful information. These events implement the type JibEvent, and can be handled by registering event handlers with the event dispatcher that is passed to Jib.

// Setup event handlers
EventHandlers eventHandlers = new EventHandlers()
    .add(JibEventType.LOGGING, logEvent -> System.out.println(logEvent.getLevel() + ": " + logEvent.getMessage()))
    .add(JibEventType.TIMING, timeEvent -> ...);

// Register with Jib
Jib.from(...)
    ...
    .containerize(
        Containerizer.to(...)
            ...
            .setEventHandlers(eventHandlers));

When Jib dispatches events, the event handlers you defined for that event type will be called. The following are the types of events you can listen for in Jib core (see API reference for more information):

• LogEvent - Log message events. The message and verbosity can be retrieved using getMessage() and getLevel(), respectively.
• TimerEvent - Events used for measuring how long different build steps take. You can retrieve the duration since the timer's creation and the duration since the same timer's previous event using getElapsed() and getDuration(), respectively.
• ProgressEvent - Indicates the amount of progress build steps have made. Since Jib consists of a hierarchy of build steps, each progress event consists of an allocation (containing a fraction representing how much of the root allocation this allocation accounts for) and a number of progress units that indicates the amount of work completed since the previous progress event. In other words, the amount of work a single progress event has completed (out of 1.0) can be calculated using getAllocation().getFractionOfRoot() * getUnits(). Each progress event also carries the type of its corresponding build step, which can be retrieved using getBuildStepType().
• LayerCountEvent - Indicates the number of layers in pull/build/push steps in the build process. Use getBuildStepType() to retrieve the step that the event is part of, and use getCount() to get the number of layers being processed.

Frequently Asked Questions (FAQ)

See the Jib project FAQ.

Upcoming features

• Extensions to make building Java and other language-specific containers easier

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

Community

See the Jib project README.