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

* Add 'container' config to readmes * Fix syntax highlighting in gradle readme * Add 'ports' descriptions/examples
HeyZhuan · 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>
 ```