Add 'container' config to READMEs (GoogleContainerTools#427)

* Add 'container' config to readmes * Fix syntax highlighting in gradle readme * Add 'ports' descriptions/examples
40a · Jun 28, 2018 · e0bdeea · e0bdeea
1 parent 2451652
commit e0bdeea
Show file tree

Hide file tree

Showing 2 changed files with 59 additions and 36 deletions.
diff --git a/jib-gradle-plugin/README.md b/jib-gradle-plugin/README.md
@@ -143,10 +143,7 @@ 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<String>` | *None* | Additional flags to pass into the JVM when running your application.
-`mainClass` | `String` | *Inferred\** | The main class to launch your application from.
-`args` | `List<String>` | *None* | Default main method arguments to run your application with.
-`format` | `String` | `Docker` | Use `OCI` to build an [OCI container image](https://www.opencontainers.org/).
+`container` | [`container`](#container-closure) | See [`container`](#container-closure) | Configures the container that is run from your built image.
 `useProjectOnlyCache` | `boolean` | `false` | If set to true, Jib does not share a cache between different Maven projects.
 
 *\* Uses the main class defined in the `jar` task or tries to find a valid main class.*
@@ -174,14 +171,24 @@ Property | Type
 `username` | `String`
 `password` | `String`
 
+<a name="container-closure"></a>`container` is a closure with the following properties:
+
+Property | Type | Default | Description
+--- | --- | --- | ---
+`jvmFlags` | `List<String>` | *None* | Additional flags to pass into the JVM when running your application.
+`mainClass` | `String` | *Inferred\** | The main class to launch your application from.
+`args` | `List<String>` | *None* | Default main method arguments to run your application with.
+`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).
+`format` | `String` | `Docker` | Use `OCI` to build an [OCI container image](https://www.opencontainers.org/).
+
 ### 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`
+In this configuration, the image:
+* Is built from a base of `openjdk:alpine` (pulled from Docker Hub)
+* Is 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 some args`
-* Reproducible
-* Built as OCI format
+* Exposes port 1000 for tcp (default), and ports 2000, 2001, 2002, and 2003 for udp
+* Is built as OCI format
 
 ```groovy
 jib {
@@ -192,10 +199,13 @@ jib {
  image = 'localhost:5000/my-image/built-with-jib'
  credHelper = 'osxkeychain'
  }
- jvmFlags = ['-Xms512m', '-Xdebug', '-Xmy:flag=jib-rules']
- args = ['some', 'args']
- mainClass = 'mypackage.MyApp'
- format = 'OCI'
+ container {
+ jvmFlags = ['-Xms512m', '-Xdebug', '-Xmy:flag=jib-rules']
+ mainClass = 'mypackage.MyApp'
+ args = ['some', 'args']
+ ports = ['1000', '2000-2003/udp']
+ format = 'OCI'
+ }
 }
 ```
 
@@ -218,7 +228,7 @@ Some common credential helpers include:
 Configure credential helpers to use by specifying them as a `credHelper` for their respective image in the `jib` extension.
 
 *Example configuration:* 
-```xml
+```groovy
 jib {
  from {
  image = 'aws_account_id.dkr.ecr.region.amazonaws.com/my-base-image'
@@ -235,7 +245,7 @@ jib {
 
 You can specify credentials directly in the extension for the `from` and/or `to` images.
 
-```xml
+```groovy
 jib {
  from {
  image = 'aws_account_id.dkr.ecr.region.amazonaws.com/my-base-image'
@@ -258,7 +268,7 @@ These credentials can be stored in `gradle.properties`, retrieved from a command
 
 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
+```groovy
 jib {
  to {
  image = 'gcr.io/my-gcp-project/my-app'

diff --git a/jib-maven-plugin/README.md b/jib-maven-plugin/README.md
@@ -184,10 +184,7 @@ Field | Type | Default | Description
 --- | --- | --- | ---
 `from` | [`from`](#from-object) | See [`from`](#from-object) | Configures the base image to build your application on top of.
 `to` | [`to`](#to-object) | *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 | *Inferred\** | The main class to launch the application from.
-`args` | list | *None* | Default main method arguments to run your application with.
-`format` | string | `Docker` | Use `OCI` to build an [OCI container image](https://www.opencontainers.org/).
+`container` | [`container`](#container-object) | See [`container`](#container-object) | Configures the container that is run from your image.
 `useOnlyProjectCache` | boolean | `false` | If set to true, Jib does not share a cache between different Gradle projects.
 
 *\* Uses `mainClass` from `maven-jar-plugin` or tries to find a valid main class.*
@@ -206,14 +203,24 @@ Property | Type | Default | Description
 `image` | string | *Required* | The image reference for the target image. This can also be specified via the `-Dimage` command line option.
 `credHelper` | string | *None* | Suffix for the credential helper that can authenticate pulling the base image (following `docker-credential-`).
 
+<a name="container-object"></a>`container` is an object with the following properties:
+
+Property | Type | Default | Description
+--- | --- | --- | ---
+`jvmFlags` | list | *None* | Additional flags to pass into the JVM when running your application.
+`mainClass` | string | *Inferred\** | The main class to launch the application from.
+`args` | list | *None* | Default main method arguments to run your application with.
+`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).
+`format` | string | `Docker` | Use `OCI` to build an [OCI container image](https://www.opencontainers.org/).
+
 ### 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`
+In this configuration, the image:
+* Is built from a base of `openjdk:alpine` (pulled from Docker Hub)
+* Is 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 some args`
-* Reproducible
-* Built as OCI format
+* Exposes port 1000 for tcp (default), and ports 2000, 2001, 2002, and 2003 for udp
+* Is built as OCI format
 
 ```xml
 <configuration>
@@ -224,17 +231,23 @@ In this configuration, the image is:
  <image>localhost:5000/my-image:built-with-jib</image>
  <credHelper>osxkeychain</credHelper>
  </to>
- <jvmFlags>
- <jvmFlag>-Xms512m</jvmFlag>
- <jvmFlag>-Xdebug</jvmFlag>
- <jvmFlag>-Xmy:flag=jib-rules</jvmFlag>
- </jvmFlags>
- <args>
- <arg>some</arg>
- <arg>args</arg>
- </args>
- <mainClass>mypackage.MyApp</mainClass>
- <format>OCI</format>
+ <container>
+ <jvmFlags>
+ <jvmFlag>-Xms512m</jvmFlag>
+ <jvmFlag>-Xdebug</jvmFlag>
+ <jvmFlag>-Xmy:flag=jib-rules</jvmFlag>
+ </jvmFlags>
+ <mainClass>mypackage.MyApp</mainClass>
+ <args>
+ <arg>some</arg>
+ <arg>args</arg>
+ </args>
+ <ports>
+ <port>1000</port>
+ <port>2000-2003/udp</port>
+ </ports>
+ <format>OCI</format>
+ </container>
 </configuration>
 ```