Skip to content

Commit f37fc6f

Browse files
reshnmnebhale
reshnm
authored and
nebhale
committed
SapMachine JRE
This change adds the SapMachine JRE as an alternative JRE for the buildpack. The documentation describes how to enable it. [resolves cloudfoundry#554]
1 parent e5c4855 commit f37fc6f

5 files changed

Lines changed: 223 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,7 @@ The buildpack supports extension through the use of Git repository forking. The
105105
* [IBM® SDK, Java™ Technology Edition](docs/jre-ibm_jre.md) ([Configuration](docs/jre-ibm_jre.md#configuration))
106106
* [OpenJDK](docs/jre-open_jdk_jre.md) ([Configuration](docs/jre-open_jdk_jre.md#configuration))
107107
* [Oracle](docs/jre-oracle_jre.md) ([Configuration](docs/jre-oracle_jre.md#configuration))
108+
* [SapMachine](docs/jre-sap_machine_jre.md) ([Configuration](docs/jre-sap_machine_jre.md#configuration))
108109
* [Extending](docs/extending.md)
109110
* [Application](docs/extending-application.md)
110111
* [Droplet](docs/extending-droplet.md)

‎config/components.yml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,14 +25,15 @@ containers:
2525
- "JavaBuildpack::Container::SpringBootCLI"
2626
- "JavaBuildpack::Container::Tomcat"
2727

28-
# In order to use Oracle JREs instead of OpenJDK, you must comment out the OpenJDK line and uncomment the Oracle line.
29-
# In order to use Zulu JREs instead of OpenJDK, you must comment out the OpenJDK line and uncomment the Zulu line.
28+
# List of available JREs. In order to use a different one either comment out the OpenJDK line and uncomment the desired one or use environment variables to change this configuration.
29+
# Example: cf set-env JBP_CONFIG_COMPONENTS '{jres: ["JavaBuildpack::Jre::OpenJdkJRE"]}'
3030
# Please see the documentation for more detail.
3131
jres:
3232
# - "JavaBuildpack::Jre::IbmJRE"
3333
- "JavaBuildpack::Jre::OpenJdkJRE"
3434
# - "JavaBuildpack::Jre::OracleJRE"
3535
# - "JavaBuildpack::Jre::ZuluJRE"
36+
# - "JavaBuildpack::Jre::SapMachineJRE"
3637

3738
# Frameworks are processed in order.
3839
# The MultiBuildpack framework is first in order to allow any framework to override contributions from earlier buildpacks

‎config/sap_machine_jre.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Cloud Foundry Java Buildpack
2+
# Copyright 2018 the original author or authors.
3+
#
4+
# Licensed under the Apache License, Version 2.0 (the "License");
5+
# you may not use this file except in compliance with the License.
6+
# You may obtain a copy of the License at
7+
#
8+
# http://www.apache.org/licenses/LICENSE-2.0
9+
#
10+
# Unless required by applicable law or agreed to in writing, software
11+
# distributed under the License is distributed on an "AS IS" BASIS,
12+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
# See the License for the specific language governing permissions and
14+
# limitations under the License.
15+
16+
17+
# Configuration for JRE repository
18+
---
19+
jre:
20+
version: 10.+
21+
repository_root: "https://sap.github.io/SapMachine/assets/cf/jre/10/linux/x86_64"
22+
jvmkill_agent:
23+
version: 1.+
24+
repository_root: "{default.repository.root}/jvmkill/{platform}/{architecture}"
25+
memory_calculator:
26+
version: 3.+
27+
repository_root: "{default.repository.root}/memory-calculator/{platform}/{architecture}"
28+
class_count:
29+
stack_threads: 250

‎docs/jre-sap_machine_jre.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# SapMachine JRE
2+
The SapMachine JRE provides Java runtimes from the [SapMachine][] project. Versions of Java from the `10` line are available. Unless otherwise configured, the version of Java that will be used is specified in [`config/sap_machine_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=&lang;version&rang;, open-jdk-like-memory-calculator=&lang;version&rang;, jvmkill=&lang;version&rang;</tt></td>
16+
</tr>
17+
</table>
18+
Tags are printed to standard output by the buildpack detect script
19+
20+
## Configuration
21+
For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][].
22+
23+
The JRE can be configured by modifying the [`config/sap_machine_jre.yml`][] file in the buildpack fork. The JRE uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there.
24+
25+
To use SapMachine JRE instead of OpenJDK without forking java-buildpack, set environment variable:
26+
27+
`cf set-env <app_name> JBP_CONFIG_COMPONENTS '{jres: ["JavaBuildpack::Jre::SapMachineJRE"]}'`
28+
29+
`cf restage <app_name>`
30+
31+
| Name | Description
32+
| ---- | -----------
33+
| `jre.repository_root` | The URL of the SapMachine repository index ([details][repositories]).
34+
| `jre.version` | The version of Java runtime to use. Candidate versions can be found in the listings for [mountainlion][] and [trusty][]. Note: version 1.8.0 and higher require the `memory_sizes` and `memory_heuristics` mappings to specify `metaspace` rather than `permgen`.
35+
| `jvmkill.repository_root` | The URL of the `jvmkill` repository index ([details][repositories]).
36+
| `jvmkill.version` | The version of `jvmkill` to use. Candidate versions can be found in the listings for [mountainlion][jvmkill-mountainlion] and [trusty][jvmkill-trusty].
37+
| `memory_calculator` | Memory calculator defaults, described below under "Memory".
38+
39+
### Additional Resources
40+
The JRE can also be configured by overlaying a set of resources on the default distribution. To do this, add files to the `resources/sap_machine_jre` directory in the buildpack fork.
41+
42+
#### Custom CA Certificates
43+
To add custom SSL certificates, add your `cacerts` file to `resources/sap_machine_jre/lib/security/cacerts`. This file will be overlayed onto the SapMachine distribution.
44+
45+
### `jvmkill`
46+
The `jvmkill` agent runs when an application has experience a resource exhaustion event. When this event occurs, the agent will print out a histogram of the first 100 largest types by total number of bytes.
47+
48+
```plain
49+
Resource exhaustion event: the JVM was unable to allocate memory from the heap.
50+
ResourceExhausted! (1/0)
51+
| Instance Count | Total Bytes | Class Name |
52+
| 18273 | 313157136 | [B |
53+
| 47806 | 7648568 | [C |
54+
| 14635 | 1287880 | Ljava/lang/reflect/Method; |
55+
| 46590 | 1118160 | Ljava/lang/String; |
56+
| 8413 | 938504 | Ljava/lang/Class; |
57+
| 28573 | 914336 | Ljava/util/concurrent/ConcurrentHashMap$Node; |
58+
```
59+
60+
It will also print out a summary of all of the memory spaces in the JVM.
61+
62+
```plain
63+
Memory usage:
64+
Heap memory: init 65011712, used 332392888, committed 351797248, max 351797248
65+
Non-heap memory: init 2555904, used 63098592, committed 64815104, max 377790464
66+
Memory pool usage:
67+
Code Cache: init 2555904, used 14702208, committed 15007744, max 251658240
68+
PS Eden Space: init 16252928, used 84934656, committed 84934656, max 84934656
69+
PS Survivor Space: init 2621440, used 0, committed 19398656, max 19398656
70+
Compressed Class Space: init 0, used 5249512, committed 5505024, max 19214336
71+
Metaspace: init 0, used 43150616, committed 44302336, max 106917888
72+
PS Old Gen: init 43515904, used 247459792, committed 247463936, max 247463936
73+
```
74+
75+
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`
76+
77+
```plain
78+
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
79+
```
80+
81+
### Memory
82+
The total available memory for the application's container is specified when an application is pushed.
83+
The Java buildpack uses this value to control the JRE's use of various
84+
regions of memory and logs the JRE memory settings when the application starts or restarts.
85+
These settings can be influenced by configuring
86+
the `stack_threads` and/or `class_count` mappings (both part of the `memory_calculator` mapping),
87+
and/or Java options relating to memory.
88+
89+
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.
90+
91+
#### Total Memory
92+
93+
The user can change the container's total memory available to influence the JRE memory settings.
94+
Unless the user specifies the heap size Java option (`-Xmx`), increasing or decreasing the total memory
95+
available results in the heap size setting increasing or decreasing by a corresponding amount.
96+
97+
#### Stack Threads
98+
99+
The amount of memory that should be allocated to stacks is given as an amount of memory per
100+
thread with the Java option `-Xss`. If an explicit number of
101+
threads should be used for the calculation of stack memory, then it should be specified as in
102+
the following example:
103+
104+
```yaml
105+
stack_threads: 500
106+
```
107+
108+
#### Loaded Classes
109+
110+
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.
111+
If a specific number of loaded classes should be used for calculations, then it should be specified as in the following example:
112+
113+
```yaml
114+
class_count: 500
115+
```
116+
117+
#### Java Options
118+
119+
If the JRE memory settings need to be fine-tuned, the user can set one or more Java memory options to
120+
specific values. The heap size can be set explicitly, but changing the value of options other
121+
than the heap size can also affect the heap size. For example, if the user increases
122+
the maximum direct memory size from its default value of 10 Mb to 20 Mb, then this will
123+
reduce the calculated heap size by 10 Mb.
124+
125+
#### Memory Calculation
126+
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.
127+
128+
The container's total available memory is allocated into heap, metaspace and compressed class space, direct memory, and stack memory settings.
129+
130+
The memory calculation is described in more detail in the [Memory Calculator's README].
131+
132+
The inputs to the memory calculation, except the container's total memory (which is unknown at staging time), are logged during staging, for example:
133+
```
134+
Loaded Classes: 13974, Threads: 300, JAVA_OPTS: ''
135+
```
136+
137+
The container's total memory is logged during `cf push` and `cf scale`, for example:
138+
```
139+
state since cpu memory disk details
140+
#0 running 2017-04-10 02:20:03 PM 0.0% 896K of 1G 1.3M of 1G
141+
```
142+
143+
The JRE memory settings are logged when the application is started or re-started, for example:
144+
```
145+
JVM Memory Configuration: -XX:MaxDirectMemorySize=10M -XX:MaxMetaspaceSize=99199K \
146+
-XX:ReservedCodeCacheSize=240M -XX:CompressedClassSpaceSize=18134K -Xss1M -Xmx368042K
147+
```
148+
149+
[`config/sap_machine_jre.yml`]: ../config/sap_machine_jre.yml
150+
[Configuration and Extension]: ../README.md#configuration-and-extension
151+
[Java Buildpack Memory Calculator]: https://github.com/cloudfoundry/java-buildpack-memory-calculator
152+
[jvmkill-mountainlion]: http://download.pivotal.io.s3.amazonaws.com/jvmkill/mountainlion/x86_64/index.yml
153+
[jvmkill-trusty]: http://download.pivotal.io.s3.amazonaws.com/jvmkill/trusty/x86_64/index.yml
154+
[Memory Calculator's README]: https://github.com/cloudfoundry/java-buildpack-memory-calculator
155+
[mountainlion]: http://download.pivotal.io.s3.amazonaws.com/openjdk/mountainlion/x86_64/index.yml
156+
[SapMachine]: https://sapmachine.io
157+
[repositories]: extending-repositories.md
158+
[trusty]: http://download.pivotal.io.s3.amazonaws.com/openjdk/trusty/x86_64/index.yml
159+
[version syntax]: extending-repositories.md#version-syntax-and-ordering
160+
[Volume Service]: https://docs.cloudfoundry.org/devguide/services/using-vol-services.html

‎lib/java_buildpack/jre/sap_machine_jre.rb‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# frozen_string_literal: true
2+
3+
# Cloud Foundry Java Buildpack
4+
# Copyright 2018 the original author or authors.
5+
#
6+
# Licensed under the Apache License, Version 2.0 (the "License");
7+
# you may not use this file except in compliance with the License.
8+
# You may obtain a copy of the License at
9+
#
10+
# http://www.apache.org/licenses/LICENSE-2.0
11+
#
12+
# Unless required by applicable law or agreed to in writing, software
13+
# distributed under the License is distributed on an "AS IS" BASIS,
14+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
# See the License for the specific language governing permissions and
16+
# limitations under the License.
17+
18+
require 'fileutils'
19+
require 'java_buildpack/jre'
20+
require 'java_buildpack/jre/open_jdk_like'
21+
22+
module JavaBuildpack
23+
module Jre
24+
25+
# Encapsulates the detect, compile, and release functionality for selecting an SapMachine JRE.
26+
class SapMachineJRE < OpenJDKLike
27+
end
28+
29+
end
30+
end

0 commit comments

Comments
 (0)