|
| 1 | +# Azul Platform Prime JRE |
| 2 | +Azul Platform Prime JRE provides Java runtimes developed by Azul. No versions of the JRE are available by default due to licensing restrictions. Instead you will need to create a repository with the Prime JREs in it and configure the buildpack to use that repository. Unless otherwise configured, the version of Java that will be used is specified in [`config/zing_jre.yml`][]. |
| 3 | + |
| 4 | +<table> |
| 5 | + <tr> |
| 6 | + <td><strong>Detection Criterion</strong></td> |
| 7 | + <td>Unconditional. Existence of a single bound Volume Service will result in Terminal heap dumps being written. |
| 8 | + <ul> |
| 9 | + <li>Existence of a Volume Service service is defined as the <a href="http://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES"><code>VCAP_SERVICES</code></a> payload containing a service who's name, label or tag has <code>heap-dump</code> as a substring.</li> |
| 10 | + </ul> |
| 11 | + </td> |
| 12 | + </tr> |
| 13 | + <tr> |
| 14 | + <td><strong>Tags</strong></td> |
| 15 | + <td><tt>open-jdk-like-jre=⟨version⟩, open-jdk-like-memory-calculator=⟨version⟩, jvmkill=⟨version⟩</tt></td> |
| 16 | + </tr> |
| 17 | +</table> |
| 18 | +Tags are printed to standard output by the buildpack detect script. |
| 19 | + |
| 20 | + |
| 21 | +## Configuration |
| 22 | +For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. |
| 23 | + |
| 24 | +The JRE can be configured by modifying the [`config/zing_jre.yml`][] file in the buildpack fork. The JRE uses the [`Repository` utility support][repositories] and so, it supports the [version syntax][] defined there. |
| 25 | + |
| 26 | +To use Azul Platform Prime JRE instead of OpenJDK without forking java-buildpack, set environment variable and restage: |
| 27 | + |
| 28 | +```bash |
| 29 | +cf set-env <app_name> JBP_CONFIG_COMPONENTS '{jres: ["JavaBuildpack::Jre::ZingJRE"]}' |
| 30 | +cf set-env <app_name> JBP_CONFIG_ZING_JRE '{ jre: { repository_root: "<INTERNAL_REPOSITORY_URI>" } }' |
| 31 | +cf restage <app_name> |
| 32 | +``` |
| 33 | + |
| 34 | +| Name | Description |
| 35 | +| ---- | ----------- |
| 36 | +| `jre.repository_root` | The URL of the Azul Platform Prime repository index ([details][repositories]). |
| 37 | +| `jre.version` | The version of Java runtime to use. Note: version 1.8.0 and higher require the `memory_sizes` and `memory_heuristics` mappings to specify `metaspace` rather than `permgen`. |
| 38 | +| `jvmkill.repository_root` | The URL of the `jvmkill` repository index ([details][repositories]). |
| 39 | +| `jvmkill.version` | The version of `jvmkill` to use. Candidate versions can be found in the listings for [bionic][jvmkill-bionic]. |
| 40 | +| `memory_calculator` | Memory calculator defaults, described below under "Memory". |
| 41 | + |
| 42 | +### Additional Resources |
| 43 | +The JRE can also be configured by overlaying a set of resources on the default distribution. To do this, add files to the `resources/zing_jre` directory in the buildpack fork. |
| 44 | + |
| 45 | +#### JCE Unlimited Strength |
| 46 | +To add the JCE Unlimited Strength `local_policy.jar`, add your file to `resources/zing_jre/lib/security/local_policy.jar`. This file will be overlayed onto the Azul Platform Prime distribution. |
| 47 | + |
| 48 | +#### Custom CA Certificates |
| 49 | +To add custom SSL certificates, add your `cacerts` file to `resources/zing_jre/lib/security/cacerts`. This file will be overlayed onto the Azul Platform Prime distribution. |
| 50 | + |
| 51 | +### `jvmkill` |
| 52 | +Azul Platform Prime JRE does not use the jvmkill agent instead by default uses the -XX:ExitOnOutOfMemoryError flag which terminates the JVM process when an out-of-memory error occurs. |
| 53 | + |
| 54 | +If a [Volume Service][] with the string `heap-dump` in its name or tag is bound to the application, terminal heap dumps will be written with the pattern `<CONTAINER_DIR>/<SPACE_NAME>-<SPACE_ID[0,8]>/<APPLICATION_NAME>-<APPLICATION_ID[0,8]>/<INSTANCE_INDEX>-<TIMESTAMP>-<INSTANCE_ID[0,8]>.hprof` |
| 55 | + |
| 56 | +```plain |
| 57 | +Heapdump written to /var/vcap/data/9ae0b817-1446-4915-9990-74c1bb26f147/pcfdev-space-e91c5c39/java-main-application-892f20ab/0-2017-06-13T18:31:29+0000-7b23124e.hprof |
| 58 | +``` |
| 59 | + |
| 60 | +### Memory |
| 61 | +The total available memory for the application's container is specified when an application is pushed. |
| 62 | +The Java buildpack uses this value to control the JRE's use of various |
| 63 | +regions of memory and logs the JRE memory settings when the application starts or restarts. |
| 64 | +These settings can be influenced by configuring |
| 65 | +the `stack_threads` and/or `class_count` mappings (both part of the `memory_calculator` mapping), |
| 66 | +and/or Java options relating to memory. |
| 67 | + |
| 68 | +Note: If the total available memory is scaled up or down, the Java buildpack will re-calculate the JRE memory settings the next time the application is started. |
| 69 | + |
| 70 | +#### Total Memory |
| 71 | + |
| 72 | +The user can change the container's total memory available to influence the JRE memory settings. |
| 73 | +Unless the user specifies the heap size Java option (`-Xmx`), increasing or decreasing the total memory |
| 74 | +available results in the heap size setting increasing or decreasing by a corresponding amount. |
| 75 | + |
| 76 | +#### Loaded Classes |
| 77 | + |
| 78 | +The amount of memory that is allocated to metaspace and compressed class space (or, on Java 7, the permanent generation) is calculated from an estimate of the number of classes that will be loaded. The default behaviour is to estimate the number of loaded classes as a fraction of the number of class files in the application. |
| 79 | +If a specific number of loaded classes should be used for calculations, then it should be specified as in the following example: |
| 80 | + |
| 81 | +```yaml |
| 82 | +class_count: 500 |
| 83 | +``` |
| 84 | +
|
| 85 | +#### Headroom |
| 86 | +
|
| 87 | +A percentage of the total memory allocated to the container to be left as headroom and excluded from the memory calculation. |
| 88 | +
|
| 89 | +```yaml |
| 90 | +headroom: 10 |
| 91 | +``` |
| 92 | +
|
| 93 | +#### Stack Threads |
| 94 | +
|
| 95 | +The amount of memory that should be allocated to stacks is given as an amount of memory per thread with the Java option `-Xss`. If an explicit number of threads should be used for the calculation of stack memory, then it should be specified as in the following example: |
| 96 | + |
| 97 | +```yaml |
| 98 | +stack_threads: 500 |
| 99 | +``` |
| 100 | + |
| 101 | +Note that the default value of 250 threads is optimized for a default Tomcat configuration. If you are using another container, especially something non-blocking like Netty, it's more appropriate to use a significantly smaller value. Typically 25 threads would cover the needs of both the server (Netty) and the threads started by the JVM itself. |
| 102 | + |
| 103 | +#### Java Options |
| 104 | + |
| 105 | +If the JRE memory settings need to be fine-tuned, the user can set one or more Java memory options to |
| 106 | +specific values. The heap size can be set explicitly, but changing the value of options other |
| 107 | +than the heap size can also affect the heap size. For example, if the user increases |
| 108 | +the maximum direct memory size from its default value of 10 Mb to 20 Mb, then this will |
| 109 | +reduce the calculated heap size by 10 Mb. |
| 110 | + |
| 111 | +#### Memory Calculation |
| 112 | +Memory calculation happens before every `start` of an application and is performed by an external program, the [Java Buildpack Memory Calculator]. There is no need to `restage` an application after scaling the memory as restarting will cause the memory settings to be recalculated. |
| 113 | + |
| 114 | +The container's total available memory is allocated into heap, metaspace and compressed class space (or permanent generation for Java 7), |
| 115 | +direct memory, and stack memory settings. |
| 116 | + |
| 117 | +The memory calculation is described in more detail in the [Memory Calculator's README]. |
| 118 | + |
| 119 | +The inputs to the memory calculation, except the container's total memory (which is unknown at staging time), are logged during staging, for example: |
| 120 | +``` |
| 121 | +Loaded Classes: 13974, Threads: 300, JAVA_OPTS: '' |
| 122 | +``` |
| 123 | + |
| 124 | +The container's total memory is logged during `cf push` and `cf scale`, for example: |
| 125 | +``` |
| 126 | + state since cpu memory disk details |
| 127 | +#0 running 2017-04-10 02:20:03 PM 0.0% 896K of 1G 1.3M of 1G |
| 128 | +``` |
| 129 | + |
| 130 | +The JRE memory settings are logged when the application is started or re-started, for example: |
| 131 | +``` |
| 132 | +JVM Memory Configuration: -XX:MaxDirectMemorySize=10M -XX:MaxMetaspaceSize=99199K \ |
| 133 | + -XX:ReservedCodeCacheSize=240M -XX:CompressedClassSpaceSize=18134K -Xss1M -Xmx368042K |
| 134 | +``` |
| 135 | + |
| 136 | +[`config/components.yml`]: ../config/components.yml |
| 137 | +[`config/zing_jre.yml`]: ../config/zing_jre.yml |
| 138 | +[Azul Platform Prime]: https://www.azul.com/products/prime/ |
| 139 | +[Configuration and Extension]: ../README.md#configuration-and-extension |
| 140 | +[Java Buildpack Memory Calculator]: https://github.com/cloudfoundry/java-buildpack-memory-calculator |
| 141 | +[jvmkill-bionic]: https://java-buildpack.cloudfoundry.org/jvmkill/bionic/x86_64/index.yml |
| 142 | +[Memory Calculator's README]: https://github.com/cloudfoundry/java-buildpack-memory-calculator |
| 143 | +[repositories]: extending-repositories.md |
| 144 | +[version syntax]: extending-repositories.md#version-syntax-and-ordering |
| 145 | +[Volume Service]: https://docs.cloudfoundry.org/devguide/services/using-vol-services.html |
| 146 | +[Azul Platform Prime JRE]: jre-zing_jre.md |
0 commit comments