diff --git a/jib-cli/README.md b/jib-cli/README.md index fe44cc6482..a6db53d61f 100644 --- a/jib-cli/README.md +++ b/jib-cli/README.md @@ -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-.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-.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 @@ -30,91 +46,54 @@ $ ./jib-cli/build/install/jib/bin/jib -## Usage - -Currently only one command is supported: `build` - -``` -jib build --target gcr.io/my-project/my-image [options] -``` - -#### Options -``` - [@...] One or more argument files containing options. - --additional-tags=[,...] - Additional tags for target image - --allow-insecure-registries - Allow jib to communicate with registries over http - (insecure) - -b, --build-file= - The path to the build file (ex: path/to/other-jib. - yaml) - --base-image-cache= - A path to a base image cache - -c, --context= - The context root directory of the build (ex: - path/to/my/build/things) - --console= set console output type, candidates: auto, rich, - plain, default: auto - --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-` - --from-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-` - --from-password[=] - password for communicating with base image registry - --from-username= - username for communicating with base image registry - --name= - The image reference to inject into the tar - configuration (required when using --target tar: - //...) - -p, --parameter== - templating parameter to inject into build file, - replace ${} with (repeatable) - --password[=] - password for communicating with both target and - base image registries - --project-cache= - A path to the project cache - --send-credentials-over-http - Allow jib to send credentials over http (very - insecure) - -t, --target= - 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 for communicating with target - registry, either a path to the helper, or a - suffix for an executable named - `docker-credential-` - --to-password[=] - password for communicating with target image - registry - --to-username= - username for communicating with target image - registry - --username= username for communicating with both target and - base image registries - --verbosity= 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 [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 @@ -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 ${} with (repeatable) + + +## Jar Command: Containerizing a JAR app +This command follows the following pattern: +``` +jib jar --target 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: +``` +[@...] 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 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-` + --to-crendential-helper credential helper for communicating with target registry, either a path to the helper, or a suffix for an executable named `docker-credential- + --from-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-` + + --username username for communicating with both target and base image registries + --password password for communicating with both target and base image registries + --to-username username for communicating with target image registry + --to-password password for communicating with target image registry + --from-username username for communicating with base image registry + --from-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 set console output type, candidates: auto, rich, plain, default: auto + --verbosity 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 +```