From 03d42652e82c543d0a6c6b69bd8827ec8effd82d Mon Sep 17 00:00:00 2001 From: Qingyang Chen Date: Wed, 6 Jun 2018 10:22:25 -0400 Subject: [PATCH] Adds current README to docs for archiving. (#380) --- docs/README.md | 1 + docs/index.md | 8 +- docs/v0.1.1/jib-gradle-plugin.md | 254 ++++++++++++++++++++++++++++++ docs/v0.1.7/jib-maven-plugin.md | 262 +++++++++++++++++++++++++++++++ 4 files changed, 524 insertions(+), 1 deletion(-) create mode 100644 docs/README.md create mode 100644 docs/v0.1.1/jib-gradle-plugin.md create mode 100644 docs/v0.1.7/jib-maven-plugin.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..4f1a51ed9b --- /dev/null +++ b/docs/README.md @@ -0,0 +1 @@ +These docs generate [googlecontainertools.github.io/jib](https://googlecontainertools.github.io/jib/). diff --git a/docs/index.md b/docs/index.md index 4dc3c19ab1..aea451185d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1 +1,7 @@ -Replace this +Documentation for older versions: + +jib-maven-plugin +- [v0.1.7](v0.1.7/jib-maven-plugin.md) + +jib-gradle-plugin +- [v0.1.1](v0.1.1/jib-gradle-plugin.md) \ No newline at end of file diff --git a/docs/v0.1.1/jib-gradle-plugin.md b/docs/v0.1.1/jib-gradle-plugin.md new file mode 100644 index 0000000000..8d7a63423b --- /dev/null +++ b/docs/v0.1.1/jib-gradle-plugin.md @@ -0,0 +1,254 @@ +[![experimental](http://badges.github.io/stability-badges/dist/experimental.svg)](http://github.com/badges/stability-badges) +[![Gradle Plugin Portal](https://img.shields.io/badge/gradle%20plugin-v0.1.1-blue.svg)](https://plugins.gradle.org/plugin/com.google.cloud.tools.jib) +[![Gitter version](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/google/jib) + +# Jib - Containerize your Gradle Java project + +Jib is [Gradle](https://gradle.org/) plugin for building Docker and OCI images for your Java applications. + +For information about the project, see the [Jib project README](..). +For the Maven plugin, see the [jib-maven-plugin project](../jib-maven-plugin). + +## Upcoming Features + +These features are not currently supported but will be added in later releases. + +* Support for WAR format +* Export to a Docker context +* Run and debug the built container + +## Quickstart + +### Setup + +*Make sure you are using Gradle version 4.6 or later.* + +In your Gradle Java project, add the plugin to your `build.gradle`: + +```groovy +plugins { + id 'com.google.cloud.tools.jib' version '0.1.1' +} +``` + +See the [Gradle Plugin Portal](https://plugins.gradle.org/plugin/com.google.cloud.tools.jib) for more details. + +## Configuration + +Configure the plugin by setting the image to push to: + +#### Using [Google Container Registry (GCR)](https://cloud.google.com/container-registry/)... + +*Make sure you have the [`docker-credential-gcr` command line tool](https://cloud.google.com/container-registry/docs/advanced-authentication#docker_credential_helper). Jib automatically uses `docker-credential-gcr` for obtaining credentials. See [Authentication Methods](#authentication-methods) for other ways of authenticating.* + +For example, to build the image `gcr.io/my-gcp-project/my-app`, the configuration would be: + +```groovy +jib.to.image = 'gcr.io/my-gcp-project/my-app' +``` + +#### Using [Amazon Elastic Container Registry (ECR)](https://aws.amazon.com/ecr/)... + +*Make sure you have the [`docker-credential-ecr-login` command line tool](https://github.com/awslabs/amazon-ecr-credential-helper). Jib automatically uses `docker-credential-ecr-login` for obtaining credentials. See [Authentication Methods](#authentication-methods) for other ways of authenticating.* + +For example, to build the image `aws_account_id.dkr.ecr.region.amazonaws.com/my-app`, the configuration would be: + +```groovy +jib.to.image = 'aws_account_id.dkr.ecr.region.amazonaws.com/my-app' +``` + +#### Using [Docker Hub Registry](https://hub.docker.com/)... + +*Make sure you have a [docker-credential-helper](https://github.com/docker/docker-credential-helpers#available-programs) set up. For example, on macOS, the credential helper would be `docker-credential-osxkeychain`. See [Authentication Methods](#authentication-methods) for other ways of authenticating.* + +For example, to build the image `my-docker-id/my-app`, the configuration would be: + +```groovy +jib.to.image = 'my-docker-id/my-app' +``` + +#### *TODO: Add more examples for common registries.* + +### Build Your Image + +Build your container image with: + +```shell +gradle build jib +``` + +Subsequent builds are much faster than the initial build. + +If you want to clear Jib's build cache and force it to re-pull the base image and re-build the application layers, run: + +```shell +gradle clean build jib +``` + +*Having trouble? Let us know by [submitting an issue](/../../issues/new), contacting us on [Gitter](https://gitter.im/google/jib), or posting to the [Jib users forum](https://groups.google.com/forum/#!forum/jib-users).* + +### Run `jib` with each build + +You can also have `jib` run with each build by attaching it to the `build` task: + +```groovy +tasks.build.finalizedBy tasks.jib +``` + +Then, ```gradle build``` will build and containerize your application. + +### Export to a Docker context + +*Not yet supported* + +## Extended Usage + +The plugin provides the `jib` extension for configuration with the following options for customizing the image build: + +Field | Type | Default | Description +--- | --- | --- | --- +`from` | [`from`](#from-closure) | See [`from`](#from-closure) | Configures the base image to build your application on top of. +`to` | [`to`](#to-closure) | *Required* | Configures the target image to build your application to. +`jvmFlags` | `List` | *None* | Additional flags to pass into the JVM when running your application. +`mainClass` | `String` | Uses the main class defined in the `jar` task | The main class to launch your application from. +`reproducible` | `boolean` | `true` | Building with the same application contents always generates the same image.
Note that this does NOT preserve file timestamps and ownership. +`format` | `String` | `Docker` | Use `OCI` to build an [OCI container image](https://www.opencontainers.org/). +`useProjectOnlyCache` | `boolean` | `false` | If set to true, Jib does not share a cache between different Maven projects. + +`from` is a closure with the following properties: + +Property | Type | Default | Description +--- | --- | --- | --- +`image` | `String` | `gcr.io/distroless/java` | The image reference for the base image. +`credHelper` | `String` | *None* | Suffix for the credential helper that can authenticate pulling the base image (following `docker-credential-`). +`auth` | [`auth`](#auth-closure) | *None* | Specify credentials directly (alternative to `credHelper`). + +`to` is a closure with the following properties: + +Property | Type | Default | Description +--- | --- | --- | --- +`image` | `String` | *Required* | The image reference for the target image. +`credHelper` | `String` | *None* | Suffix for the credential helper that can authenticate pulling the base image (following `docker-credential-`). +`auth` | [`auth`](#auth-closure) | *None* | Specify credentials directly (alternative to `credHelper`). + +`auth` is a closure with the following properties (see [Using Specific Credentials](#using-specific-credentials)): + +Property | Type +--- | --- +`username` | `String` +`password` | `String` + +### Example + +In this configuration, the image is: +* Built from a base of `openjdk:alpine` (pulled from Docker Hub) +* Pushed to `localhost:5000/my-image:built-with-jib` +* Runs by calling `java -Xms512m -Xdebug -Xmy:flag=jib-rules -cp app/libs/*:app/resources:app/classes mypackage.MyApp` +* Reproducible +* Built as OCI format + +```groovy +jib { + from { + image = 'openjdk:alpine' + } + to { + image = 'localhost:5000/my-image/built-with-jib' + credHelper = 'osxkeychain' + } + jvmFlags = ['-Xms512m', '-Xdebug', '-Xmy:flag=jib-rules'] + mainClass = 'mypackage.MyApp' + reproducible = true + format = 'OCI' +} +``` + +### Authentication Methods + +Pushing/pulling from private registries require authorization credentials. These can be [retrieved using Docker credential helpers](#using-docker-credential-helpers). If you do not define credentials explicitly, Jib will try to [use credentials defined in your Docker config](/../../issues/101) or infer common credential helpers. + +#### Using Docker Credential Helpers + +Docker credential helpers are CLI tools that handle authentication with various registries. + +Some common credential helpers include: + +* Google Container Registry: [`docker-credential-gcr`](https://cloud.google.com/container-registry/docs/advanced-authentication#docker_credential_helper) +* AWS Elastic Container Registry: [`docker-credential-ecr-login`](https://github.com/awslabs/amazon-ecr-credential-helper) +* Docker Hub Registry: [`docker-credential-*`](https://github.com/docker/docker-credential-helpers) + + +Configure credential helpers to use by specifying them as a `credHelper` for their respective image in the `jib` extension. + +*Example configuration:* +```xml +jib { + from { + image = 'aws_account_id.dkr.ecr.region.amazonaws.com/my-base-image' + credHelper = 'ecr-login' + } + to { + image = 'gcr.io/my-gcp-project/my-app' + credHelper = 'gcr' + } +} +``` + +#### Using Specific Credentials + +You can specify credentials directly in the extension for the `from` and/or `to` images. + +```xml +jib { + from { + image = 'aws_account_id.dkr.ecr.region.amazonaws.com/my-base-image' + auth { + username = USERNAME // Defined in 'gradle.properties'. + password = PASSWORD + } + } + to { + image = 'gcr.io/my-gcp-project/my-app' + auth { + username = 'oauth2accesstoken' + password = 'gcloud auth print-access-token'.execute().text.trim() + } + } +} +``` + +These credentials can be stored in `gradle.properties`, retrieved from a command (like `gcloud auth print-access-token`), or read in from a file. + +For example, you can use a key file for authentication (for GCR, see [Using a JSON key file](https://cloud.google.com/container-registry/docs/advanced-authentication#using_a_json_key_file)): + +```xml +jib { + to { + image = 'gcr.io/my-gcp-project/my-app' + auth { + username = '_json_key' + password = file('keyfile.json').text + } + } +} +``` + +## How Jib Works + +See the [Jib project README](/../../#how-jib-works). + +## Known Limitations + +These limitations will be fixed in later releases. + +* Does not build directly to a Docker daemon. +* Pushing to Azure Container Registry is not currently supported. + +## Frequently Asked Questions (FAQ) + +See the [Jib project README](/../../#frequently-asked-questions-faq). + +## Community + +See the [Jib project README](/../../#community). diff --git a/docs/v0.1.7/jib-maven-plugin.md b/docs/v0.1.7/jib-maven-plugin.md new file mode 100644 index 0000000000..43a27dea2a --- /dev/null +++ b/docs/v0.1.7/jib-maven-plugin.md @@ -0,0 +1,262 @@ +[![experimental](http://badges.github.io/stability-badges/dist/experimental.svg)](http://github.com/badges/stability-badges) +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.google.cloud.tools/jib-maven-plugin/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.google.cloud.tools/jib-maven-plugin) +[![Gitter version](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/google/jib) + +# Jib - Containerize your Maven project + +Jib is a [Maven](https://maven.apache.org/) plugin for building Docker and OCI images for your Java applications. + +For information about the project, see the [Jib project README](..). +For the Gradle plugin, see the [jib-gradle-plugin project](../jib-gradle-plugin). + +## Upcoming Features + +These features are not currently supported but will be added in later releases. + +* Support for WAR format + +## Quickstart + +### Setup + +In your Maven Java project, add the plugin to your `pom.xml`: + +```xml + + com.google.cloud.tools + jib-maven-plugin + 0.1.6 + + myregistry + myapp + + +``` + +### Configuration + +Configure the plugin by changing `registry` and `repository` to be the registry and repository to push the built image to. + +#### Using [Google Container Registry (GCR)](https://cloud.google.com/container-registry/)... + +*Make sure you have the [`docker-credential-gcr` command line tool](https://cloud.google.com/container-registry/docs/advanced-authentication#docker_credential_helper). Jib automatically uses `docker-credential-gcr` for obtaining credentials. See [Authentication Methods](#authentication-methods) for other ways of authenticating.* + +For example, to build the image `gcr.io/my-gcp-project/my-app`, the configuration would be: + +```xml + + gcr.io + my-gcp-project/my-app + +``` + +#### Using [Amazon Elastic Container Registry (ECR)](https://aws.amazon.com/ecr/)... + +*Make sure you have the [`docker-credential-ecr-login` command line tool](https://github.com/awslabs/amazon-ecr-credential-helper). Jib automatically uses `docker-credential-ecr-login` for obtaining credentials. See [Authentication Methods](#authentication-methods) for other ways of authenticating.* + +For example, to build the image `aws_account_id.dkr.ecr.region.amazonaws.com/my-app`, the configuration would be: + +```xml + + aws_account_id.dkr.ecr.region.amazonaws.com + my-app + +``` + +#### Using [Docker Hub Registry](https://hub.docker.com/)... + +*Make sure you have a [docker-credential-helper](https://github.com/docker/docker-credential-helpers#available-programs) set up. For example, on macOS, the credential helper would be `docker-credential-osxkeychain`. See [Authentication Methods](#authentication-methods) for other ways of authenticating.* + +For example, to build the image `my-docker-id/my-app`, the configuration would be: + +```xml + + registry.hub.docker.com + my-docker-id/my-app + osxkeychain + +``` + +#### *TODO: Add more examples for common registries.* + +### Build Your Image + +Build your container image with: + +```shell +mvn compile jib:build +``` + +Subsequent builds are much faster than the initial build. + +If you want to clear Jib's build cache and force it to re-pull the base image and re-build the application layers, run: + +```shell +mvn clean compile jib:build +``` + +*Having trouble? Let us know by [submitting an issue](/../../issues/new), contacting us on [Gitter](https://gitter.im/google/jib), or posting to the [Jib users forum](https://groups.google.com/forum/#!forum/jib-users).* + +### Bind to a lifecycle + +You can also bind `jib:build` to a Maven lifecycle, such as `package`, by adding the following execution to your `jib-maven-plugin` definition: + +```xml + + com.google.com.tools + jib-maven-plugin + ... + + + package + + build + + + + +``` + +Then, you can build your container image by running: + +```shell +mvn package +``` + +### Export to a Docker context + +Jib can also export to a Docker context so that you can build with Docker, if needed: + +```shell +mvn compile jib:dockercontext +``` + +The Docker context will be created at `target/jib-dockercontext` by default. You can change this directory with the `targetDir` configuration option or the `jib.dockerDir` parameter: + +```shell +mvn compile jib:dockercontext -Djib.dockerDir=my/docker/context/ +``` + +You can then build your image with Docker: + +```shell +docker build -t myregistry/myapp my/docker/context/ +``` + +## Extended Usage + +Extended configuration options provide additional options for customizing the image build. + +Field | Default | Description +--- | --- | --- +`from`|[`gcr.io/distroless/java`](https://github.com/GoogleCloudPlatform/distroless)|The base image to build your application on top of. +`registry`|*Required*|The registry server to push the built image to. +`repository`|*Required*|The image name/repository of the built image. +`tag`|`latest`|The image tag of the built image (the part after the colon). +`credHelpers`|*Required*|Suffixes for credential helpers (following `docker-credential-`) +`jvmFlags`|*None*|Additional flags to pass into the JVM when running your application. +`mainClass`|Uses `mainClass` from `maven-jar-plugin`|The main class to launch the application from. +`enableReproducibleBuilds`|`true`|Building with the same application contents always generates the same image. Note that this does *not* preserve file timestamps and ownership. +`imageFormat`|`Docker`|Use `OCI` to build an [OCI container image](https://www.opencontainers.org/). +`useOnlyProjectCache`|`false`|If set to true, Jib does not share a cache between different Maven projects. + +### Example + +In this configuration, the image is: +* Built from a base of `openjdk:alpine` (pulled from Docker Hub) +* Pushed to `localhost:5000/my-image:built-with-jib` +* Runs by calling `java -Xms512m -Xdebug -Xmy:flag=jib-rules -cp app/libs/*:app/resources:app/classes mypackage.MyApp` +* Reproducible +* Built as OCI format + +```xml + + openjdk:alpine + localhost:5000 + my-image + built-with-jib + + osxkeychain + + + -Xms512m + -Xdebug + -Xmy:flag=jib-rules + + mypackage.MyApp + true + OCI + +``` + +### Authentication Methods + +Pushing/pulling from private registries require authorization credentials. These can be [retrieved using Docker credential helpers](#using-docker-credential-helpers) or [defined in your Maven settings](#using-maven-settings). If you do not define credentials explicitly, Jib will try to [use credentials defined in your Docker config](/../../issues/101) or infer common credential helpers. + +#### Using Docker Credential Helpers + +Docker credential helpers are CLI tools that handle authentication with various registries. + +Some common credential helpers include: + +* Google Container Registry: [`docker-credential-gcr`](https://cloud.google.com/container-registry/docs/advanced-authentication#docker_credential_helper) +* AWS Elastic Container Registry: [`docker-credential-ecr-login`](https://github.com/awslabs/amazon-ecr-credential-helper) +* Docker Hub Registry: [`docker-credential-*`](https://github.com/docker/docker-credential-helpers) + + +Configure credential helpers to use by specifying them in the `credHelpers` configuration. + +*Example configuration:* +```xml + + ... + + osxkeychain + + ... + +``` + +#### Using Maven Settings + +Registry credentials can be added to your [Maven settings](https://maven.apache.org/settings.html). These credentials will be used if credentials could not be found in any specified Docker credential helpers. + +If you're considering putting credentials in Maven, we highly *recommend* using [maven password encryption](https://maven.apache.org/guides/mini/guide-encryption.html). + +*Example `settings.xml`:* +```xml + + ... + + ... + + MY_REGISTRY + MY_USERNAME + {MY_SECRET} + + + +``` + +* The `id` field should be the registry server these credentials are for. +* We *do not* recommend putting your raw password in `settings.xml`. + +## How Jib Works + +See the [Jib project README](/../../#how-jib-works). + +## Known Limitations + +These limitations will be fixed in later releases. + +* Does not build directly to a Docker daemon. +* Pushing to Azure Container Registry is not currently supported. + +## Frequently Asked Questions (FAQ) + +See the [Jib project README](/../../#frequently-asked-questions-faq). + +## Community + +See the [Jib project README](/../../#community).