Skip to content
Branch: master
Find file History
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
examples
gradle/wrapper
kokoro
scripts
src
.gitignore
CHANGELOG.md
README.md
build.gradle
gradle.properties
gradlew
gradlew.bat Upgrade / add Gradle wrappers (#1095) Oct 5, 2018
settings.gradle

README.md

experimental Maven Central Gitter version

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.1.2</version>
</dependency>

Add Jib Core as a dependency using Gradle:

dependencies {
  compile 'com.google.cloud.tools:jib-core:0.1.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:

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:

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:

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.

Analytics

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.