Skip to content

Commit

Permalink
Update Jib CLI README.md (#3105)
Browse files Browse the repository at this point in the history 
* Update README
  • Loading branch information
@mpeddada1
mpeddada1 authored Mar 3, 2021
1 parent 57571a3 commit d2074b9
Showing 1 changed file with 160 additions and 86 deletions.
246 changes: 160 additions & 86 deletions jib-cli/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,29 @@ a Java library for building containers without Docker.
This CLI tool is _experimental_ and its options and structure
are almost certain to change.

## Table of Contents
* [Get the Jib CLI](#get-the-jib-cli)
* [Download a java application](#download-a-java-application)
* [Build yourself from source](#build-yourself-from-source)
* [Supported Commands](#supported-commands)
* [Build](#build)
* [Quickstart](#quickstart)
* [Fully Annotated `jib.yaml`](#fully-annotated-jibyaml)
* [Options](#options)
* [Jar](#jar)
* [Options](#options)
* [Common Jib CLI Options](#common-cli-options)
* [Auth/Security](#authsecurity)
* [Info Params](#info-params)
* [Debugging Params](#debugging-params)

## Get the Jib CLI

### Download a java application

A JRE is required to run this Jib CLI distribution.

Find the latest jib-core release on the [Releases page](https://github.com/GoogleContainerTools/jib/releases), download `jib-jre-<version>.zip`, and unzip it. The zip file contains the `jib` (`jib.bat` for Windows) script at `jib/bin/`. Optionally, add the binary directory to your `$PATH` so that you can call `jib` from anywhere.
Find the [latest jib-cli 0.2.0 release](https://github.com/GoogleContainerTools/jib/releases/tag/v0.2.0-cli) on the [Releases page](https://github.com/GoogleContainerTools/jib/releases), download `jib-jre-<version>.zip`, and unzip it. The zip file contains the `jib` (`jib.bat` for Windows) script at `jib/bin/`. Optionally, add the binary directory to your `$PATH` so that you can call `jib` from anywhere.

### Build yourself from source

Expand All @@ -30,91 +46,54 @@ $ ./jib-cli/build/install/jib/bin/jib

<!-- TODO: ### Download an executable -->

## Usage

Currently only one command is supported: `build`

```
jib build --target gcr.io/my-project/my-image [options]
```

#### Options
```
[@<filename>...] One or more argument files containing options.
--additional-tags=<tag>[,<tag>...]
Additional tags for target image
--allow-insecure-registries
Allow jib to communicate with registries over http
(insecure)
-b, --build-file=<build-file>
The path to the build file (ex: path/to/other-jib.
yaml)
--base-image-cache=<cache-directory>
A path to a base image cache
-c, --context=<project-root>
The context root directory of the build (ex:
path/to/my/build/things)
--console=<type> set console output type, candidates: auto, rich,
plain, default: auto
--credential-helper=<credential-helper>
credential helper for communicating with both
target and base image registries, either a path
to the helper, or a suffix for an executable
named `docker-credential-<suffix>`
--from-credential-helper=<credential-helper>
credential helper for communicating with base image
registry, either a path to the helper, or a
suffix for an executable named
`docker-credential-<suffix>`
--from-password[=<password>]
password for communicating with base image registry
--from-username=<username>
username for communicating with base image registry
--name=<image-reference>
The image reference to inject into the tar
configuration (required when using --target tar:
//...)
-p, --parameter=<name>=<value>
templating parameter to inject into build file,
replace ${<name>} with <value> (repeatable)
--password[=<password>]
password for communicating with both target and
base image registries
--project-cache=<cache-directory>
A path to the project cache
--send-credentials-over-http
Allow jib to send credentials over http (very
insecure)
-t, --target=<target-image>
The destination image reference or jib style url,
examples:
gcr.io/project/image,
registry://image-ref,
docker://image,
tar://path
--to-credential-helper=<credential-helper>
credential helper for communicating with target
registry, either a path to the helper, or a
suffix for an executable named
`docker-credential-<suffix>`
--to-password[=<password>]
password for communicating with target image
registry
--to-username=<username>
username for communicating with target image
registry
--username=<username> username for communicating with both target and
base image registries
--verbosity=<level> set logging verbosity, candidates: quiet, error,
warn, lifecycle, info, debug, default: lifecycle
```

## Build File

The CLI uses a build file to define the container being built. The default is a file named `jib.yaml` in the project root.

### Annotated `jib.yaml`
## Supported Commands

The Jib CLI currently supports two commands:
1. `build` - To build a container with the help of a build file.
2. `jar` - To containerize a jar.

## Build
This command follows the following pattern:
```
jib build --target <image name> [options]
```
### Quickstart
1. Create a hello world script (`script.sh`) containing:
```
#!/bin/sh
echo "Hello World"
```
2. Create a buildfile. The default is a file named `jib.yaml` in the project root.
```
apiVersion: jib/v1alpha1
kind: BuildFile
from:
image: ubuntu
entrypoint: ["./script.sh"]
layers:
entries:
- name: scripts
files:
- properties:
filePermissions: 755
src: script.sh
dest: /script.sh
```
3. Build to docker daemon
```
$ jib build --target=docker://jib-cli-quickstart
```
4. Run the container
```
$ docker run jib-cli-quickstart
Hello World
```

### Fully Annotated `jib.yaml`

```yaml
# required apiVersion and kind, for compatibility over versions of the cli
Expand Down Expand Up @@ -253,3 +232,98 @@ Parameters that will be overwritten:
- `workingDirectory`
- `entrypoint`
- `cmd`


### Options
Here is the list of optional flags for the `build` command:

Option | Description
--- | ---
`-b, --build-file` | The path to the build file (ex: path/to/other-jib.yaml)
`-c, --context` | The context root directory of the build (ex: path/to/my/build/things)
`-p, --parameter` | Templating parameter to inject into build file, replace ${<name>} with <value> (repeatable)


## Jar Command: Containerizing a JAR app
This command follows the following pattern:
```
jib jar --target <image name> path/to/myapp.jar [options]
```

### Options
Here is a list of optional flags for the `jar` command:

Option | Description
--- | ---
`--creation-time` | The creation time of the container in milliseconds since epoch or iso8601 format. Overrides the default (1970-01-01T00:00:00Z)
`--entrypoint` | Entrypoint for container. Overrides the default entrypoint, example: `--entrypoint='custom entrypoint'`
`--environment-variables` | Environment variables to write into container, example: `--environment-variables env1=env_value1, env2=env_value2`.
`--expose` | Ports to expose on container, example: `--expose=5000,7/udp`.
`--from` | The base image to use.
`--image-format` | Format of container, candidates: Docker, OCI, default: Docker.
`--jvm-flags` | JVM arguments, example: `--jvm-flags=-Dmy.property=value,-Xshare:off`
`--labels` | Labels to write into container metadata, example: `--labels=label1=value1,label2=value2`.
`--mode` | The jar processing mode, candidates: exploded, packaged, default: exploded
`--program-args` | Program arguments for container entrypoint.
`-u, --user` | The user to run the container as, example: `--user=myuser:mygroup`.
`--volumes` | Directories on container to hold extra volumes, example: `--volumes=/var/log,/var/log2`.


## Common Jib CLI Options
The options can either be specified in the command line or defined in a configuration file:
```
[@<filename>...] One or more argument files containing options.
```
### Auth/Security
```
--allow-insecure-registries Allow jib to send credentials over http (insecure)
--send-credentials-over-http Allow jib to send credentials over http (very insecure)
```
#### Credentials
Credentials can be specified using credential helpers or username + password. The following options are available:
```
--credential-helper <credHelper> credential helper for communicating with both target and base image registries, either a path to the helper, or a suffix for an executable named `docker-credential-<suffix>`
--to-crendential-helper <credHelper> credential helper for communicating with target registry, either a path to the helper, or a suffix for an executable named `docker-credential-<suffix>
--from-credential-helper <credHelper> credential helper for communicating with base image registry, either a path to the helper, or a suffix for an executable named `docker-credential-<suffix>`

--username <username> username for communicating with both target and base image registries
--password <password> password for communicating with both target and base image registries
--to-username <username> username for communicating with target image registry
--to-password <password> password for communicating with target image registry
--from-username <username> username for communicating with base image registry
--from-password <password> password for communicating with base image registry
```
*Note* - Combinations of `credential-helper`, `username` and `password` flags come with restrictions and can be use only in the following ways:
Only Credential Helper
1. `--credential-helper`
2. `--to-credential-helper`
3. `--from-credential-helper`
4. `--to-credential-helper`, `--from-credential-helper`
Only Username and Password
1. `--username`, `--password`
2. `--to-username`, `--to-password`
3. `--from-username`, `--from-password`
4. `--to-username`, `--to-password`, `--from-username`, `--from-password`
Mixed Mode
1. `--to-credential-helper`, `--from-username`, `--from-password`
2. `--from-credential-helper`, `--to-username`, `--to-password`
#### Info Params
```
--help print usage and exit
--console <type> set console output type, candidates: auto, rich, plain, default: auto
--verbosity <level> set logging verbosity, candidates: quiet, error, warn, lifecycle, info, debug, default: lifecycle
-v, --version Jib CLI version information
```
#### Debugging Params
```
--stacktrace print stacktrace on error (for debugging issues in the jib-cli)
--http-trace enable http tracing at level=config, output=console
--serialize run jib in serialized mode
```

0 comments on commit d2074b9

Please sign in to comment.