Skip to content

Commit

Permalink
Update documentation for 0.10.1 (GoogleContainerTools#1265)
Browse files Browse the repository at this point in the history
  • Loading branch information
@TadCordle
TadCordle committed Dec 4, 2018
1 parent 6ce73c5 commit 420d334
Show file tree
Hide file tree
Showing 3 changed files with 94 additions and 48 deletions.
32 changes: 32 additions & 0 deletions docs/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ If a question you have is not answered below, please [submit an issue](/../../is
[Can I ADD a custom directory to the image?](#can-i-add-a-custom-directory-to-the-image)\
[I need to add files generated during the build process to a custom directory on the image.](#i-need-to-add-files-generated-during-the-build-process-to-a-custom-directory-on-the-image)\
[Can I build to a local Docker daemon?](#can-i-build-to-a-local-docker-daemon)\
[What would a Dockerfile for a Jib-built image look like?](#what-would-a-dockerfile-for-a-jib-built-image-look-like)\
[How can I inspect the image Jib built?](#how-can-i-inspect-the-image-jib-built)\
[I am seeing `ImagePullBackoff` on my pods.](#i-am-seeing-imagepullbackoff-on-my-pods-in-minikube)\
[How do I configure a proxy?](#how-do-i-configure-a-proxy)\
[How can I diagnose problems pulling or pushing from remote registries?](#how-can-i-diagnose-problems-pulling-or-pushing-from-remote-registries)\
Expand Down Expand Up @@ -276,6 +278,36 @@ There are several ways of doing this:
- [`docker pull`](https://docs.docker.com/engine/reference/commandline/pull/) the image built with Jib to have it available in your local Docker daemon.
- Alternatively, instead of using a Docker daemon, you can run a local container registry, such as [Docker registry](https://docs.docker.com/registry/deploying/) or other repository managers, and point Jib to push to the local registry.

### What would a Dockerfile for a Jib-built image look like?

A Dockerfile that performs a Jib-like build is shown below:

```Dockerfile
# Jib uses distroless java as the default base image
FROM gcr.io/distroless/java:latest
# Multiple copy statements are used to break the app into layers, allowing for faster rebuilds after small changes
COPY dependencyJars /app/libs
COPY snapshotDependencyJars /app/libs
COPY resources /app/resources
COPY classFiles /app/classes
# Jib's extra directory ("src/main/jib" by default) is used to add extra, non-classpath files
COPY src/main/jib /
# Jib's default entrypoint when container.entrypoint is not set
ENTRYPOINT ["java", jib.container.jvmFlags, "-cp", "/app/resources:/app/classes:/app/libs/*", jib.container.mainClass]
CMD [jib.container.args]
```

When unset, Jib will infer the value for `jib.container.mainClass`.

Some plugins, such as the [Docker Prepare Gradle Plugin](https://github.com/gclayburg/dockerPreparePlugin), will even automatically generate a Docker context for your project, including a Dockerfile.

### How can I inspect the image Jib built?

To inspect the image that is produced from the build using Docker, you can use commands such as `docker inspect your/image:tag` to view the image configuration, or you can also download the image using `docker save` to manually inspect the container image. Other tools, such as [dive](https://github.com/wagoodman/dive), provide nicer UI to inspect the image.

### I am seeing `ImagePullBackoff` on my pods (in [minikube](https://github.com/kubernetes/minikube)).

When you use your private image built with Jib in a [Kubernetes cluster](kubernetes.io), the cluster needs to be configured with credentials to pull the image. This involves 1) creating a [Secret](https://kubernetes.io/docs/concepts/configuration/secret/), and 2) using the Secret as [`imagePullSecrets`](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#add-imagepullsecrets-to-a-service-account).
Expand Down
55 changes: 31 additions & 24 deletions jib-gradle-plugin/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,29 @@ Jib is a [Gradle](https://gradle.org/) plugin for building Docker and [OCI](http
For information about the project, see the [Jib project README](../README.md).
For the Maven plugin, see the [jib-maven-plugin project](../jib-maven-plugin).

## Table of Contents

* [Upcoming Features](#upcoming-features)
* [Quickstart](#quickstart)
* [Setup](#setup)
* [Configuration](#configuration)
* [Build your image](#build-your-image)
* [Build to Docker Daemon](#build-to-docker-daemon)
* [Build an image tarball](#build-an-image-tarball)
* [Run `jib` with each build](#run-jib-with-each-build)
* [Additional Build Artifacts](#additional-build-artifacts)
* [Extended Usage](#extended-usage)
* [System Properties](#system-properties)
* [Example](#example)
* [Adding Arbitrary Files to the Image](#adding-arbitrary-files-to-the-image)
* [Authentication Methods](#authentication-methods)
* [Using Docker Credential Helpers](#using-docker-credential-helpers)
* [Using Specific Credentials](#using-specific-credentials)
* [WAR Projects](#war-projects)
* [How Jib Works](#how-jib-works)
* [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq)
* [Community](#community)

## Upcoming Features

See [Milestones](https://github.com/GoogleContainerTools/jib/milestones) for planned features. [Get involved with the community](https://github.com/GoogleContainerTools/jib/tree/master#get-involved-with-the-community) for the latest updates.
Expand Down Expand Up @@ -132,30 +155,10 @@ tasks.build.dependsOn tasks.jib

Then, ```gradle build``` will build and containerize your application.

### Export to a Docker context

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

```shell
gradle jibExportDockerContext
```

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

```shell
gradle jibExportDockerContext --jibTargetDir=my/docker/context/
```

You can then build your image with Docker:

```shell
docker build -t myimage my/docker/context/
```

### Additional Build Artifacts

As part of an image build, Jib also writes out the _image digest_ to
`build/jib-image.digest`.
`build/jib-image.digest`, as well as the _image ID_ to `build/jib-image.id`

## Extended Usage

Expand Down Expand Up @@ -200,15 +203,17 @@ Property | Type | Default | Description
--- | --- | --- | ---
`appRoot` | `String` | `/app` | The root directory on the container where the app's contents are placed. Particularly useful for WAR-packaging projects to work with different Servlet engine base images by designating where to put exploded WAR contents; see [WAR usage](#war-projects) as an example.
`args` | `List<String>` | *None* | Additional program arguments appended to the command to start the container (similar to Docker's [CMD](https://docs.docker.com/engine/reference/builder/#cmd) instruction in relation with [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint)). In the default case where you do not set a custom `entrypoint`, this parameter is effectively the arguments to the main method of your Java application.
`entrypoint` | `List<String>` | *None* | The command to start the container with (similar to Docker's [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) instruction). If set, then `jvmFlags` and `mainClass` are ignored.
`entrypoint` | `List<String>` | *None* | The command to start the container with (similar to Docker's [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) instruction). If set, then `jvmFlags` and `mainClass` are ignored. You may also set `jib.container.entrypoint = 'INHERIT'` to indicate that the `entrypoint` and `args` should be inherited from the base image.\*
`environment` | `Map<String, String>` | *None* | Key-value pairs for setting environment variables on the container (similar to Docker's [ENV](https://docs.docker.com/engine/reference/builder/#env) instruction).
`format` | `String` | `Docker` | Use `OCI` to build an [OCI container image](https://www.opencontainers.org/).
`jvmFlags` | `List<String>` | *None* | Additional flags to pass into the JVM when running your application.
`labels` | `Map<String, String>` | *None* | Key-value pairs for applying image metadata (similar to Docker's [LABEL](https://docs.docker.com/engine/reference/builder/#label) instruction).
`mainClass` | `String` | *Inferred\** | The main class to launch your application from.
`mainClass` | `String` | *Inferred*\*\* | The main class to launch your application from.
`ports` | `List<String>` | *None* | Ports that the container exposes at runtime (similar to Docker's [EXPOSE](https://docs.docker.com/engine/reference/builder/#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.
`user` | `String` | *None* | The user and group to run the container as. The value can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`.
`volumes` | `List<String>` | *None* | Specifies a list of mount points on the container.
`workingDirectory` | `String` | *None* | The working directory in the container.

<a name="extradirectory-closure"></a>`extraDirectory` is an object with the following properties (see [Adding Arbitrary Files to the Image](#adding-arbitrary-files-to-the-image)):

Expand Down Expand Up @@ -239,7 +244,9 @@ You can also configure HTTP connection/read timeouts for registry interactions u
gradle jib -Djib.httpTimeout=3000
```

*\* Uses the main class defined in the `jar` task or tries to find a valid main class.*
*\* If you configure `args` while `entrypoint` is set to `'INHERIT'`, the configured `args` value will take precedence over the CMD propagated from the base image.*

*\*\* Uses the main class defined in the `jar` task or tries to find a valid main class.*

### Example

Expand Down
55 changes: 31 additions & 24 deletions jib-maven-plugin/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,29 @@ Jib is a [Maven](https://maven.apache.org/) plugin for building Docker and [OCI]
For information about the project, see the [Jib project README](../README.md).
For the Gradle plugin, see the [jib-gradle-plugin project](../jib-gradle-plugin).

## Table of Contents

* [Upcoming Features](#upcoming-features)
* [Quickstart](#quickstart)
* [Setup](#setup)
* [Configuration](#configuration)
* [Build your image](#build-your-image)
* [Build to Docker Daemon](#build-to-docker-daemon)
* [Build an image tarball](#build-an-image-tarball)
* [Bind to a lifecycle](#bind-to-a-lifecycle)
* [Additional Build Artifacts](#additional-build-artifacts)
* [Extended Usage](#extended-usage)
* [System Properties](#system-properties)
* [Example](#example)
* [Adding Arbitrary Files to the Image](#adding-arbitrary-files-to-the-image)
* [Authentication Methods](#authentication-methods)
* [Using Docker Credential Helpers](#using-docker-credential-helpers)
* [Using Specific Credentials](#using-specific-credentials)
* [WAR Projects](#war-projects)
* [How Jib Works](#how-jib-works)
* [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq)
* [Community](#community)

## Upcoming Features

See [Milestones](https://github.com/GoogleContainerTools/jib/milestones) for planned features. [Get involved with the community](https://github.com/GoogleContainerTools/jib/tree/master#get-involved-with-the-community) for the latest updates.
Expand Down Expand Up @@ -173,30 +196,10 @@ 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:

```shell
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:

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

You can then build your image with Docker:

```shell
docker build -t myimage my/docker/context/
```

### Additional Build Artifacts

As part of an image build, Jib also writes out the _image digest_ to
`target/jib-image.digest`.
`target/jib-image.digest`, as well as the _image ID_ to `target/jib-image.id`.

## Extended Usage

Expand Down Expand Up @@ -242,15 +245,17 @@ Property | Type | Default | Description
--- | --- | --- | ---
`appRoot` | string | `/app` | The root directory on the container where the app's contents are placed. Particularly useful for WAR-packaging projects to work with different Servlet engine base images by designating where to put exploded WAR contents; see [WAR usage](#war-projects) as an example.
`args` | list | *None* | Additional program arguments appended to the command to start the container (similar to Docker's [CMD](https://docs.docker.com/engine/reference/builder/#cmd) instruction in relation with [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint)). In the default case where you do not set a custom `entrypoint`, this parameter is effectively the arguments to the main method of your Java application.
`entrypoint` | list | *None* | The command to start the container with (similar to Docker's [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) instruction). If set, then `jvmFlags` and `mainClass` are ignored.
`entrypoint` | list | *None* | The command to start the container with (similar to Docker's [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) instruction). If set, then `jvmFlags` and `mainClass` are ignored. You may also set `<entrypoint>INHERIT</entrypoint>` to indicate that the `entrypoint` and `args` should be inherited from the base image.\*
`environment` | map | *None* | Key-value pairs for setting environment variables on the container (similar to Docker's [ENV](https://docs.docker.com/engine/reference/builder/#env) instruction).
`format` | string | `Docker` | Use `OCI` to build an [OCI container image](https://www.opencontainers.org/).
`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](https://docs.docker.com/engine/reference/builder/#label) instruction).
`mainClass` | string | *Inferred\** | The main class to launch the application from.
`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](https://docs.docker.com/engine/reference/builder/#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.
`user` | string | *None* | The user and group to run the container as. The value can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`.
`volumes` | list | *None* | Specifies a list of mount points on the container.
`workingDirectory` | string | *None* | The working directory in the container.

<a name="extradirectory-object"></a>`extraDirectory` is an object with the following properties (see [Adding Arbitrary Files to the Image](#adding-arbitrary-files-to-the-image)):

Expand Down Expand Up @@ -281,7 +286,9 @@ You can also configure HTTP connection/read timeouts for registry interactions u
mvn compile jib:build -Djib.httpTimeout=3000
```

*\* Uses `mainClass` from `maven-jar-plugin` or tries to find a valid main class.*
*\* If you configure `args` while `entrypoint` is set to `'INHERIT'`, the configured `args` value will take precedence over the CMD propagated from the base image.*

*\*\* Uses the main class defined in the `jar` task or tries to find a valid main class.*

### Example

Expand Down

0 comments on commit 420d334

Please sign in to comment.