Building Java containers with Jib

---

Jib builds containers without using a Dockerfile or requiring a Docker installation. You can use Jib in the Jib plugins for Maven or Gradle, or you can use the Jib Java library.

What does Jib do?

Jib handles all steps of packaging your application into a container image. You don't need to know best practices for creating Dockerfiles or have Docker installed.

Docker build flow:

Jib build flow:

Jib organizes your application into distinct layers; dependencies, resources, and classes; and utilizes Docker image layer caching to keep builds fast by only rebuilding changes. Jib's layer organization and small base image keeps overall image size small which improves performance and portability.

Before you begin

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Container Registry API.

   Enable the API

7. If you don't have Java, download, install, and configure it.
8. Install Maven 3.5 or newer.
9. Install and initialize the Google Cloud CLI.
10. Authenticate to Container Registry, using the Google Cloud CLI as a Docker credential helper:

    gcloud auth configure-docker

    Optionally, refer to Jib configuration documentation for other ways of authenticating.

Building using Jib

1. Select an existing project and navigate to the source folder or clone the sample with the following command:

        git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
        cd java-docs-samples/run/helloworld

2. Add the plugin to your pom.xml:

   <plugin>
     <groupId>com.google.cloud.tools</groupId>
     <artifactId>jib-maven-plugin</artifactId>
     <version>2.8.0</version>
     <configuration>
       <to>
         <image>gcr.io/PROJECT/IMAGE</image>
       </to>
     </configuration>
   </plugin>
   

   Replace

   • PROJECT with your Google Cloud project ID.
   • IMAGE with your image name.

   If you don't want to modify your pom.xml, you can use the command:

       mvn compile com.google.cloud.tools:jib-maven-plugin:3.1.1:build \
           -Djib.from.image=eclipse-temurin \
           -Djib.to.image=gcr.io/PROJECT/IMAGE

3. Build and push the image to a container registry:

   mvn compile jib:build

   You can verify success by viewing your container in your Container Registry.

   Optionally, if you have Docker installed, you can build to your local Docker installation, so you can inspect or run the image as any other local container:

   mvn compile jib:dockerBuild

   Note: Jib can also containerize WAR applications by automatically using a Servlet engine base image.

Additional customizations

You can customize your Jib builds in similar ways to Dockerfiles, such as adding environment variables and selecting a base image.

Add environment variables

You can add environment variables to your build similar to the ENV instruction in a Dockerfile, as follows:

<plugin>
  <groupId>com.google.cloud.tools</groupId>
  <artifactId>jib-maven-plugin</artifactId>
  <version>2.8.0</version>
  <configuration>
    <to>
      <image>gcr.io/PROJECT/IMAGE</image>
    </to>
    <container>
      <environment>
        <ENV_VAR>VALUE</ENV_VAR>
      </environment>
    </container>
  </configuration>
</plugin>

Replace

• PROJECT with your Google Cloud project ID.
• IMAGE with your image name.
• ENV_VAR with NAME.
• VALUE with the desired value.

Now your application will respond with Hello <var>VALUE</var>!

Change the base image

The base image is equivalent to the FROM instructions in a Dockerfile. The base image can be updated by changing the field from.image.

If you would like to include a shell for debugging, set the base image to alpine:3 or openjdk:VERSION (if Java is needed).

In order to add system packages, you will have to create a base image with those packages installed. Refer to Building containers for more information.

  <plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>jib-maven-plugin</artifactId>
    <version>2.8.0</version>
    <configuration>
      <from>
        <image>gcr.io/PROJECT/BASE_IMAGE</image>
      </from>
      <to>
        <image>gcr.io/PROJECT/IMAGE_NAME</image>
      </to>
    </configuration>
  </plugin>

Try updating the from.image field to another Java base image, such as openjdk:8-alpine.

Customizing other Java aspects

Jib supports Java runtime configurations that may be needed to run your application. For more customizations, see Extended Usage.

Shipping the code

Setting up gcloud defaults

To configure gcloud with defaults for your Cloud Run service:

1. Set your default project:

   gcloud config set project PROJECT_ID

   Replace PROJECT_ID with the name of the project you created for this tutorial.

2. Configure gcloud for your chosen region:

   gcloud config set run/region REGION

   Replace REGION with the supported Cloud Run region of your choice.

Cloud Run locations

Cloud Run is regional, which means the infrastructure that runs your Cloud Run services is located in a specific region and is managed by Google to be redundantly available across all the zones within that region.

Meeting your latency, availability, or durability requirements are primary factors for selecting the region where your Cloud Run services are run. You can generally select the region nearest to your users but you should consider the location of the other Google Cloud products that are used by your Cloud Run service. Using Google Cloud products together across multiple locations can affect your service's latency as well as cost.

Cloud Run is available in the following regions:

Subject to Tier 1 pricing

• asia-east1 (Taiwan)
• asia-northeast1 (Tokyo)
• asia-northeast2 (Osaka)
• asia-south1 (Mumbai, India)
• europe-north1 (Finland) Low CO₂
• europe-southwest1 (Madrid) Low CO₂
• europe-west1 (Belgium) Low CO₂
• europe-west4 (Netherlands) Low CO₂
• europe-west8 (Milan)
• europe-west9 (Paris) Low CO₂
• me-west1 (Tel Aviv)
• us-central1 (Iowa) Low CO₂
• us-east1 (South Carolina)
• us-east4 (Northern Virginia)
• us-east5 (Columbus)
• us-south1 (Dallas) Low CO₂
• us-west1 (Oregon) Low CO₂

Subject to Tier 2 pricing

• africa-south1 (Johannesburg)
• asia-east2 (Hong Kong)
• asia-northeast3 (Seoul, South Korea)
• asia-southeast1 (Singapore)
• asia-southeast2 (Jakarta)
• asia-south2 (Delhi, India)
• australia-southeast1 (Sydney)
• australia-southeast2 (Melbourne)
• europe-central2 (Warsaw, Poland)
• europe-west10 (Berlin) Low CO₂
• europe-west12 (Turin)
• europe-west2 (London, UK) Low CO₂
• europe-west3 (Frankfurt, Germany) Low CO₂
• europe-west6 (Zurich, Switzerland) Low CO₂
• me-central1 (Doha)
• me-central2 (Dammam)
• northamerica-northeast1 (Montreal) Low CO₂
• northamerica-northeast2 (Toronto) Low CO₂
• southamerica-east1 (Sao Paulo, Brazil) Low CO₂
• southamerica-west1 (Santiago, Chile) Low CO₂
• us-west2 (Los Angeles)
• us-west3 (Salt Lake City)
• us-west4 (Las Vegas)

If you already created a Cloud Run service, you can view the region in the Cloud Run dashboard in the Google Cloud console.

OK

Deploy to Cloud Run

Deploy your container from Container Registry using the gcloud CLI to Cloud Run or Knative serving.

Deploy the container image using the following command:

gcloud run deploy SERVICE-NAME \
    --image gcr.io/PROJECT/IMAGE \
    --platform managed

Replace

• SERVICE-NAME with your chosen service name.
• PROJECT with your Google Cloud project ID.
• IMAGE with your image name.

Notice that the container image is deployed to the service and region (Cloud Run) or cluster (Knative serving) that you configured previously under Setting up gcloud.

If deploying to Cloud Run, you will be prompted to allow unauthenticated invocations. If you want immediate access to your service, respond y, "Yes" to the "allow unauthenticated" prompt. If your service is private and requests must include authentication, respond n, "No" to the "allow unauthenticated" prompt.

If your service is public, use the URL displayed after a successful deployment to visit your deployed container. If your service is private, use the following curl command to invoke your service:

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" SERVICE_URL

If deployed to Knative serving, see Accessing your deployed service.

Clean up

If you created a new project for this tutorial, delete the project. If you used an existing project and wish to keep it without the changes added in this tutorial, delete resources created for the tutorial.

Deleting the project

The easiest way to eliminate billing is to delete the project that you created for the tutorial.

To delete the project:

Caution: Deleting a project has the following effects:

• Everything in the project is deleted. If you used an existing project for the tasks in this document, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an appspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple architectures, tutorials, or quickstarts, reusing projects can help you avoid exceeding project quota limits.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Deleting tutorial resources

1. Delete the Cloud Run service you deployed in this tutorial:

   gcloud run services delete SERVICE-NAME

   Where SERVICE-NAME is your chosen service name.

   You can also delete Cloud Run services from the Google Cloud console.

2. Remove the gcloud default region configuration you added during tutorial setup:

    gcloud config unset run/region
   

3. Remove the project configuration:

    gcloud config unset project
   

What's next

• To learn more about the contract your containers must respect to be deployed to Cloud Run, see Container contract.
• To automate the builds and deployments of your Cloud Run services using Cloud Build Triggers, set up Continuous deployment.
• To learn more about using and customizing Jib, see Jib's GitHub Repository.