Containerising Kotlin with Jib

Writing a Dockerfile to containerise an application can often be a non-trivial task. Many times I’ve spent hours fiddling with different base images and configurations and never being quite satisfied with the result. Well I recently tried Jib, one of Google’s container tools, and I love it! It builds optimised Docker and Open Container Initiative (OCI) spec images for JVM applications. For containerising JVM apps I will definitely try and use Jib where possible in future.

Jib images are distroless!

I had been interested in trying Google’s “Distroless” Docker images for a while, and so it was great to read that Jib uses these as base images by default. “Distroless” images are stripped down to the bare essentials. They contain only the application and its runtime dependencies. There is no bloat from unnecessary programs, shells, package managers, etc.

Jib images are reproducible

The layers, metadata, files and directories are all added to the image by Jib in a consistent order. Additionally, timestamps of all files and directories are set to one second after the Epoch, and the image creation time is set exactly to the Epoch. This makes the image build process deterministic and able to rebuild layers so that they have the exact same digest each time.

Don’t be surprised that it reports the image was created 49+ years ago⁠—it’s for reproducibility!

REPOSITORY                 TAG          IMAGE ID          CREATED           SIZE
peterevans/webservice      0.1          493233af1b87      49 years ago      137MB
peterevans/webservice      0.1.0        493233af1b87      49 years ago      137MB
peterevans/webservice      latest       493233af1b87      49 years ago      137MB

The result is that Jib produces lean, efficient and reproducible images that have a number of benefits.

• An accurate diff of changes and provenance between image releases becomes much less of a burden
• Reduced attack surface
• Improves the signal to noise ratio of vulnerability scanners

Using Jib with Gradle’s Kotlin DSL

Here is a quick introduction of how to use Jib with Gradle’s Kotlin DSL. A complete example project is contained in this repository.

First add the plugin to build.gradle.kts

plugins {
    id("com.google.cloud.tools.jib") version "1.3.0"
}

Add a configuration section for Jib to build.gradle.kts specifying the image name. Don’t forget to prefix with the registry host for pushing to registries other than io.dockerhub.

jib {
    to {
        image = "peterevans/webservice"
    }
}

The jib gradle task will build and push to the registry. You might also need to specify an authentication method. This is the preferred way to build Jib images as it is daemonless. There is no requirement for your CI environment to be running the Docker daemon.

gradle jib

The jibDockerBuild gradle task will build the image and load it into the Docker daemon. This can be useful if during your CI release process you want to smoke test the image after being built but before being pushed to the registry.

gradle jibDockerBuild

Image Configuration

Tags

By default, Jib builds every image with no tag, meaning it will always produce an image with the default tag latest. A set of additional tags can be added under jib.to.tags. The following example tags the image with a major.minor version and a major.minor.build version.

version = "0.1"
val buildNumber by extra("0")

jib {
    to {
        image = "peterevans/webservice"
        tags = setOf("$version", "$version.${extra["buildNumber"]}")
    }
}

Labels

Labels can be specified as a map under jib.container.labels as follows.

jib {
    container {
        labels = mapOf(
            "maintainer" to "Peter Evans <[email protected]>",
            "org.opencontainers.image.title" to "webservice",
            "org.opencontainers.image.description" to "An example webservice",
            "org.opencontainers.image.version" to "$version",
            "org.opencontainers.image.authors" to "Peter Evans <[email protected]>",
            "org.opencontainers.image.url" to "https://github.com/peter-evans/kotlin-jib",
            "org.opencontainers.image.vendor" to "https://peterevans.dev",
            "org.opencontainers.image.licenses" to "MIT"
        )
    }
}

Further Container Configuration

You can customise almost everything about the image including JVM flags, environment variables, volumes, ports, etc. Further configuration options can be found in the documentation here.

jib {
    container {
        jvmFlags = listOf(
            "-server",
            "-Djava.awt.headless=true",
            "-XX:InitialRAMFraction=2",
            "-XX:MinRAMFraction=2",
            "-XX:MaxRAMFraction=2",
            "-XX:+UseG1GC",
            "-XX:MaxGCPauseMillis=100",
            "-XX:+UseStringDeduplication"
        )
        environment = mapOf(
            "USERNAME" to "user1",
            "PASSWORD" to "1234")
        workingDirectory = "/webservice"
        volumes = listOf("/data")
        ports = listOf("8080")
        args = listOf("--help")
    }
}

See the code in this repository for a more complete example of using Jib to containerise Kotlin.