diff --git a/README.md b/README.md index 489bd72cf..122f14c17 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,9 @@ The following are _very_ simple examples for deploying the artifact types that w ## Configuration and Extension -The buildpack default configuration can be overridden with an environment variable matching the configuration file you wish to override minus the `.yml` extension. It is not possible to add new configuration properties and properties with `nil` or empty values will be ignored by the buildpack (in this case you will have to extend the buildpack, see below). The value of the variable should be valid inline yaml, referred to as "flow style" in the yaml spec ([Wikipedia][] has a good description of this yaml syntax). +Configurable framework and JRE settings are overridden through component-specific `JBP_CONFIG_*` environment variables (for example, `JBP_CONFIG_OPEN_JDK_JRE` and `JBP_CONFIG_DEBUG`). Consult each component's documentation for its exact variable name and supported fields. The value must be valid inline YAML, referred to as "flow style" in the YAML spec ([Wikipedia][] has a good description of this syntax). + +> **Note:** The Ruby buildpack's `config/*.yml` file-based configuration is not used by this buildpack. All configuration is done through environment variables as described below. There are two levels of overrides: operator and application developer. @@ -119,11 +121,19 @@ To learn how to configure various properties of the buildpack, follow the "Confi The buildpack supports extension through the use of Git repository forking. The easiest way to accomplish this is to use [GitHub's forking functionality][] to create a copy of this repository. Make the required extension changes in the copy of the repository. Then specify the URL of the new repository when pushing Cloud Foundry applications. If the modifications are generally applicable to the Cloud Foundry community, please submit a [pull request][] with the changes. More information on extending the buildpack is available [here](docs/extending.md). +## GA Status + +**v5.1.0 is the first generally available (GA) release of the Go-based Java Buildpack.** + +This release is declared GA in accordance with [RFC-0050][] and supersedes the experimental Go buildpack releases in the 5.0.x line. The Ruby-based buildpack (4.x) is no longer receiving feature updates; operators are encouraged to migrate to v5.1.0 or later. + +[RFC-0050]: https://github.com/cloudfoundry/community/blob/main/toc/rfc/rfc-0050-java-buildpack-migration-to-golang.md + ## Ruby vs Go Migration Status This Go-based buildpack is a migration from the original Ruby-based Cloud Foundry Java Buildpack. For comprehensive information about the migration status, component parity, and architectural differences: -* **[Ruby vs Go Buildpack Comparison](ruby_vs_go_buildpack_comparison.md)** - Technical deep-dive into how dependency extraction differs between Ruby and Go implementations +* **[Ruby vs Go Buildpack Comparison](RUBY_VS_GO_BUILDPACK_COMPARISON.md)** - Technical deep-dive into how dependency extraction differs between Ruby and Go implementations **⚠️ Important Migration Note:** The Go buildpack does **NOT** support the Ruby buildpack's `repository_root` configuration approach for custom JREs (via `JBP_CONFIG_*` environment variables). Custom JREs now require forking the buildpack and modifying `manifest.yml`. See [Custom JRE Usage](docs/custom-jre-usage.md) for details. @@ -375,15 +385,14 @@ For detailed guidelines about setting up and running tests please check this [Te ## License This buildpack is released under version 2.0 of the [Apache License][]. -[`config/` directory]: config [Apache License]: http://www.apache.org/licenses/LICENSE-2.0 [Cloud Foundry]: http://www.cloudfoundry.org [contributor guidelines]: CONTRIBUTING.md [disables `remote_downloads`]: docs/extending-caches.md#configuration [Environment Variables]: http://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html#env-block [GitHub's forking functionality]: https://help.github.com/articles/fork-a-repo -[Grails]: http://grails.org -[Groovy]: http://groovy.codehaus.org +[Grails]: https://grails.apache.org/ +[Groovy]: https://groovy-lang.org/ [Play Framework]: http://www.playframework.com [pull request]: https://help.github.com/articles/using-pull-requests [Pull requests]: http://help.github.com/send-pull-requests diff --git a/RUBY_VS_GO_BUILDPACK_COMPARISON.md b/RUBY_VS_GO_BUILDPACK_COMPARISON.md index 1bd298909..12bbc98e7 100644 --- a/RUBY_VS_GO_BUILDPACK_COMPARISON.md +++ b/RUBY_VS_GO_BUILDPACK_COMPARISON.md @@ -1,10 +1,12 @@ # Ruby vs Go Java Buildpack: Comprehensive Architectural Comparison -**Date**: January 5, 2026 -**Migration Status**: Complete (Production Ready) -**Ruby Buildpack**: /home/ramonskie/workspace/tmp/orig-java (Legacy) +**Date**: September 18, 2026 +**Migration Status**: Complete — v5.1.0 is the first generally available (GA) release ([RFC-0050][]) +**Ruby Buildpack**: [main-before-go-migration](https://github.com/cloudfoundry/java-buildpack/tree/backup/main-before-go-migration) (Legacy) **Go Buildpack**: Current repository (Active Development) +[RFC-0050]: https://github.com/cloudfoundry/community/blob/main/toc/rfc/rfc-0050-java-buildpack-migration-to-golang.md + --- ## Executive Summary @@ -2245,6 +2247,8 @@ required memory 1269289K is greater than 750M available for allocation ## 11. Conclusion +**v5.1.0 is the first generally available (GA) release of the Go-based Java Buildpack**, declared GA in accordance with [RFC-0050][]. It supersedes the experimental 5.0.x releases; the Ruby-based buildpack (4.x) is no longer receiving feature updates. + The Go-based Java buildpack is a **production-ready, feature-complete** migration from the Ruby buildpack, achieving: - ✅ **92.9% component parity** (52/56 components) diff --git a/adoption-migration-details.md b/adoption-migration-details.md index 4851fbc95..d8757f015 100644 --- a/adoption-migration-details.md +++ b/adoption-migration-details.md @@ -36,11 +36,11 @@ Applications compiled with Java 8 should generally run on Java 17 without issues - Tomcat 9 by default - Java 1.8.x by default -**Starting with the Go-based Java Buildpack, they will be switched to:** +**With the Go-based Java Buildpack, the defaults are:** - Tomcat 10 - Java 17 -**This change will take effect only after redeploy or restage.** +**These new defaults apply after redeploy or restage.** ## How to Maintain Current Versions @@ -70,16 +70,16 @@ This section highlights significant breaking changes introduced in the Go-based ### Custom JRE Usage -Custom JRE usage will be supported only as documented in the [Custom JRE Usage Guide](custom-jre-usage.md). +Custom JRE usage is supported only as documented in the [Custom JRE Usage Guide](docs/custom-jre-usage.md). ### Changed Default Configuration - **SpringAutoReconfigurationFramework is now disabled by default.** Please note that `SpringAutoReconfigurationFramework` is deprecated, and the recommended alternative is [java-cfenv](https://github.com/pivotal-cf/java-cfenv). -- **JRE selection based on `JBP_CONFIG_COMPONENTS` is deprecated.** The Go-based buildpack supports JRE selection based on `JBP_CONFIG_` as described in the [README](https://github.com/cloudfoundry/java-buildpack/blob/feature/go-migration/README.md#jre-selection). +- **JRE selection based on `JBP_CONFIG_COMPONENTS` is deprecated.** The Go-based buildpack supports JRE selection based on `JBP_CONFIG_` as described in the [README](README.md#jre-selection). ### Frameworks Not Included -The following frameworks will not be migrated to the Go buildpack: +The following frameworks were not migrated to the Go buildpack: - **Takipi Agent (OverOps)**: Removed because the agent has moved behind a licensed login wall, making it inaccessible for automated buildpack integration. - **Java Security**: Rarely used and custom security policies should be implemented at the platform level or within application code. @@ -176,7 +176,7 @@ The Ruby buildpack only added `-XX:ActiveProcessorCount=$(nproc)` in the OpenJDK If you encounter issues during migration or have questions: 1. Review the [buildpack documentation](../README.md) -2. Check the [RFC document](https://github.com/cloudfoundry/community/pull/1392) for detailed technical information +2. Check [RFC-0050](https://github.com/cloudfoundry/community/blob/main/toc/rfc/rfc-0050-java-buildpack-migration-to-golang.md) for detailed technical information 3. Open an issue in the [Java Buildpack repository](https://github.com/cloudfoundry/java-buildpack) ## Summary Checklist diff --git a/docs/framework-app_dynamics_agent.md b/docs/framework-app_dynamics_agent.md index 37dba6aee..3e556e0d6 100644 --- a/docs/framework-app_dynamics_agent.md +++ b/docs/framework-app_dynamics_agent.md @@ -33,15 +33,7 @@ To provide more complex values such as the `tier-name`, using the interactive mo ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/app_dynamics_agent.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. - -| Name | Description -| ---- | ----------- -| `default_application_name` | This is omitted by default but can be added to specify the application name in the AppDynamics dashboard. This can be overridden by an `application-name` entry in the credentials payload. If neither are supplied the default is the `application_name` as specified by Cloud Foundry. -| `default_node_name` | The default node name for this application in the AppDynamics dashboard. The default value is an expression that will be evaluated based on the `instance_index` of the application. This can be overridden by a `node-name` entry in the credentials payload. -| `default_tier_name` | This is omitted by default but can be added to specify the tier name for this application in the AppDynamics dashboard. This can be overridden by a `tier-name` entry in the credentials payload. If neither are supplied the default is the `application_name` as specified by Cloud Foundry. -| `repository_root` | The URL of the AppDynamics repository index ([details][repositories]). -| `version` | The version of AppDynamics to use. Candidate versions can be found in [this listing][]. +The framework has no user-configurable options. The AppDynamics agent version is managed by the buildpack manifest. See [Additional Resources](#additional-resources) below for application-level configuration options. ### Additional Resources The framework can be configured by providing custom configuration files. @@ -100,10 +92,6 @@ The Java buildpack will take the `app_root` + `APPD_CONF_DIR` directory and atte Any files that exist will be copied to the configuration directory. The buildpack does not fail if files are missing. -[`config/app_dynamics_agent.yml`]: ../config/app_dynamics_agent.yml [AppDynamics Java Agent Configuration Properties]: https://docs.appdynamics.com/display/PRO42/Java+Agent+Configuration+Properties [AppDynamics Service]: http://www.appdynamics.com [Configuration and Extension]: ../README.md#configuration-and-extension -[repositories]: extending-repositories.md -[this listing]: https://packages.appdynamics.com/java/index.yml -[version syntax]: extending-repositories.md#version-syntax-and-ordering diff --git a/docs/framework-aspectj_weaver_agent.md b/docs/framework-aspectj_weaver_agent.md index 926315def..cbb4f9009 100644 --- a/docs/framework-aspectj_weaver_agent.md +++ b/docs/framework-aspectj_weaver_agent.md @@ -16,11 +16,18 @@ Tags are printed to standard output by the buildpack detect script ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by creating or modifying the [`config/aspectj_weaver_agent.yml`][] file in the buildpack fork. +The framework can be configured by setting the `JBP_CONFIG_ASPECTJ_WEAVER_AGENT` environment variable. The value must be valid inline YAML. | Name | Description | ---- | ----------- -| `enabled` | Whether to enable the AspectJ Runtime Weaving agent. +| `enabled` | Whether to enable the AspectJ Runtime Weaving agent. Defaults to `true`. + +### Example + +Disable the AspectJ weaver agent: + +```yaml +JBP_CONFIG_ASPECTJ_WEAVER_AGENT: '{enabled: false}' +``` -[`config/aspectj_weaver_agent.yml`]: ../config/aspect_weaver_agent.yml [Configuration and Extension]: ../README.md#configuration-and-extension diff --git a/docs/framework-client_certificate_mapper.md b/docs/framework-client_certificate_mapper.md index 5d3852b5a..cc6c65a0d 100644 --- a/docs/framework-client_certificate_mapper.md +++ b/docs/framework-client_certificate_mapper.md @@ -18,20 +18,23 @@ Tags are printed to standard output by the buildpack detect script ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/client_certificate_mapper.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. +The framework can be configured by setting the `JBP_CONFIG_CLIENT_CERTIFICATE_MAPPER` environment variable. The value must be valid inline YAML. | Name | Description |-------------------| ----------- -| `repository_root` | The URL of the Container Customizer repository index ([details][repositories]). -| `version` | The version of Container Customizer to use. Candidate versions can be found in [this listing][]. +| `enabled` | Whether to enable the Client Certificate Mapper. Defaults to `true`. + +### Example + +Disable the client certificate mapper: + +```yaml +JBP_CONFIG_CLIENT_CERTIFICATE_MAPPER: '{enabled: false}' +``` ## Servlet Filter The [Servlet Filter][] added by this framework maps the `X-Forwarded-Client-Cert` to the `javax.servlet.request.X509Certificate` Servlet attribute for each request. The `X-Forwarded-Client-Cert` header is contributed by the Cloud Foundry Router and contains the any TLS certificate presented by a client for mututal TLS authentication. This certificate can then be used by any standard Java security framework to establish authentication and authorization for a request. -[`config/client_certificate_mapper.yml`]: ../config/client_certificate_mapper.yml [Configuration and Extension]: ../README.md#configuration-and-extension -[repositories]: extending-repositories.md [Servlet Filter]: https://github.com/cloudfoundry/java-buildpack-client-certificate-mapper -[this listing]: http://download.pivotal.io.s3.amazonaws.com/container-security-provider/index.yml -[version syntax]: extending-repositories.md#version-syntax-and-ordering [library repository]: https://github.com:cloudfoundry/java-buildpack-client-certificate-mapper.git diff --git a/docs/framework-container_customizer.md b/docs/framework-container_customizer.md index 97538ea05..5554ab01b 100644 --- a/docs/framework-container_customizer.md +++ b/docs/framework-container_customizer.md @@ -16,15 +16,6 @@ Tags are printed to standard output by the buildpack detect script ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/container_customizer.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. - -| Name | Description -| ---- | ----------- -| `repository_root` | The URL of the Container Customizer repository index ([details][repositories]). -| `version` | The version of Container Customizer to use. Candidate versions can be found in [this listing][]. +The framework has no user-configurable buildpack options. The Container Customizer version is managed by the buildpack manifest. [Configuration and Extension]: ../README.md#configuration-and-extension -[`config/container_customizer.yml`]: ../config/container_customizer.yml -[repositories]: extending-repositories.md -[this listing]: http://download.pivotal.io.s3.amazonaws.com/container-customizer/index.yml -[version syntax]: extending-repositories.md#version-syntax-and-ordering diff --git a/docs/framework-container_security_provider.md b/docs/framework-container_security_provider.md index bb5f7c422..f922b3f96 100644 --- a/docs/framework-container_security_provider.md +++ b/docs/framework-container_security_provider.md @@ -16,24 +16,37 @@ Tags are printed to standard output by the buildpack detect script ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/container_security_provider.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. +The framework can be configured by setting the `JBP_CONFIG_CONTAINER_SECURITY_PROVIDER` environment variable. The value must be valid inline YAML. | Name | Description | ---- | ----------- -| `repository_root` | The URL of the Container Customizer repository index ([details][repositories]). -| `version` | The version of Container Customizer to use. Candidate versions can be found in [this listing][]. | `key_manager_enabled` | Whether the container `KeyManager` is enabled. Defaults to `true`. | `trust_manager_enabled` | Whether the container `TrustManager` is enabled. Defaults to `true`. +### Examples + +Disable the `KeyManager`: + +```yaml +JBP_CONFIG_CONTAINER_SECURITY_PROVIDER: '{key_manager_enabled: false}' +``` + +Disable the `TrustManager`: + +```yaml +JBP_CONFIG_CONTAINER_SECURITY_PROVIDER: '{trust_manager_enabled: false}' +``` + ## Security Provider The [security provider][] added by this framework contributes two types, a `TrustManagerFactory` and a `KeyManagerFactory`. The `TrustManagerFactory` adds an additional new `TrustManager` after the configured system `TrustManager` which reads the contents of `/etc/ssl/certs/ca-certificates.crt` which is where [BOSH trusted certificates][] are placed. The `KeyManagerFactory` adds an additional `KeyManager` after the configured system `KeyManager` which reads the contents of the files specified by `$CF_INSTANCE_CERT` and `$CF_INSTANCE_KEY` which are set by Diego to give each container a unique cryptographic identity. These `TrustManager`s and `KeyManager`s are used transparently by any networking library that reads standard system SSL configuration and can be used to enable system-wide trust and [mutual TLS authentication][]. +The path read by the `TrustManager` defaults to `/etc/ssl/certs/ca-certificates.crt` but can be overridden by setting the `CF_CA_CERTS` environment variable to an alternate file path. + +> **Note:** This is distinct from — but complementary to — Cloud Foundry's [Trusted System Certificates][] feature (`CF_SYSTEM_CERT_PATH`, `/etc/cf-system-certificates`). Diego's executor merges operator-deployed trusted system certificates into `/etc/ssl/certs`, so they are automatically picked up by the `TrustManager`'s default path without any additional configuration. + -[`config/container_security_provider.yml`]: ../config/container_security_provider.yml [BOSH trusted certificates]: https://bosh.io/docs/trusted-certs.html [Configuration and Extension]: ../README.md#configuration-and-extension [mutual TLS authentication]: https://en.wikipedia.org/wiki/Mutual_authentication -[repositories]: extending-repositories.md [security provider]: https://github.com/cloudfoundry/java-buildpack-security-provider -[this listing]: http://download.pivotal.io.s3.amazonaws.com/container-security-provider/index.yml -[version syntax]: extending-repositories.md#version-syntax-and-ordering +[Trusted System Certificates]: https://docs.cloudfoundry.org/devguide/deploy-apps/trusted-system-certificates.html diff --git a/docs/framework-contrast_security_agent.md b/docs/framework-contrast_security_agent.md index ab6e5d4ea..646bf8a56 100644 --- a/docs/framework-contrast_security_agent.md +++ b/docs/framework-contrast_security_agent.md @@ -22,18 +22,8 @@ When binding ContrastSecurity using a user-provided service, it must have name o ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/contrast_security_agent.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. - -| Name | Description -| ---- | ----------- -| `repository_root` | The URL of the Contrast Security repository index ([details][repositories]). -| `version` | The version of Contrast Security to use. Candidate versions can be found in [this listing][]. +The framework has no user-configurable options. The Contrast Security agent version is managed by the buildpack manifest. [Contrast Security]: https://www.contrastsecurity.com [Configuration and Extension]: ../README.md#configuration-and-extension [Contrast Security Service]: https://www.contrastsecurity.com -[`config/contrast_security_agent.yml`]: ../config/contrast_security_agent.yml -[Configuration and Extension]: ../README.md#configuration-and-extension -[repositories]: extending-repositories.md -[this listing]: https://artifacts.contrastsecurity.com/agents/java/index.yml -[version syntax]: extending-repositories.md#version-syntax-and-ordering diff --git a/docs/framework-debug.md b/docs/framework-debug.md index 303ce3fe2..f29f3fce4 100644 --- a/docs/framework-debug.md +++ b/docs/framework-debug.md @@ -4,7 +4,7 @@ The Debug Framework contributes Java debug configuration to the application at r - + @@ -16,14 +16,35 @@ Tags are printed to standard output by the buildpack detect script ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by creating or modifying the [`config/debug.yml`][] file in the buildpack fork. +The framework can be configured by setting the `JBP_CONFIG_DEBUG` environment variable. The value must be valid inline YAML. Environment variables `BPL_DEBUG_ENABLED` and `BPL_DEBUG_PORT` are also supported and take precedence over `JBP_CONFIG_DEBUG`. | Name | Description | ---- | ----------- -| `enabled` | Whether to enable Java debugging +| `enabled` | Whether to enable Java debugging. Defaults to `false`. | `port` | The port that the debug agent will listen on. Defaults to `8000`. | `suspend` | Whether to suspend execution until a debugger has attached. Note, you cannot ssh to a container until the container has decided the application is running. Therefore when enabling this setting you must also push the application using the parameter `-u process` which disables container health checking. +### Examples + +Enable debugging on the default port: + +```yaml +JBP_CONFIG_DEBUG: '{enabled: true}' +``` + +Enable debugging on a custom port with suspend: + +```yaml +JBP_CONFIG_DEBUG: '{enabled: true, port: 9000, suspend: true}' +``` + +Using Cloud Native Buildpacks conventions: + +```bash +BPL_DEBUG_ENABLED=true +BPL_DEBUG_PORT=9000 +``` + ## Creating SSH Tunnel After starting an application with debugging enabled, an SSH tunnel must be created to the container. To create that SSH container, execute the following command: @@ -37,5 +58,4 @@ Once the SSH tunnel has been created, your IDE should connect to `localhost: - + @@ -15,7 +15,7 @@ Tags are printed to standard output by the buildpack detect script. ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/java_memory_assistant.yml`][] file in the buildpack fork. +The framework can be configured by setting the `JBP_CONFIG_JAVA_MEMORY_ASSISTANT` environment variable. The value must be valid inline YAML. | Name | Description | ---- | ----------- @@ -54,7 +54,7 @@ The timestamp pattern `%ts:yyyyMMdd'T'mmssSSSZ%` is equivalent to the `%FT%T%z` Different builds and versions of Java Virtual Machines offer different memory areas. The list of supported Java Virtual Machines and the respective memory areas can be found in the [Java Memory Assistant documentation](https://github.com/SAP/java-memory-assistant#supported-jvms). -The default values can be found in the [`config/java_memory_assistant.yml`][] file. +The default values can be found in the Go source at `src/java/frameworks/java_memory_assistant.go`. ### Examples @@ -121,5 +121,4 @@ To prevent heap dumps from "going down" with the container, you should consider If you are using a filesystem service that mounts persistent volumes to the container, it is enough to name one of the volume services `heap-dump` or tag one volume with `heap-dump`, and the path specified as the `heap_dump_folder` configuration will be resolved against `/-/-`. The default directory convention matches the [`jvmkill`][] directory convention. -[`config/java_memory_assistant.yml`]: ../config/java_memory_assistant.yml [`jvmkill`]: jre-open_jdk_jre.md#jvmkill diff --git a/docs/framework-java_opts.md b/docs/framework-java_opts.md index 1b83d3555..958291ac7 100644 --- a/docs/framework-java_opts.md +++ b/docs/framework-java_opts.md @@ -5,7 +5,7 @@ The Java Options Framework contributes arbitrary Java options to the application
Detection Criterionenabled set in the config/debug.yml fileenabled set via JBP_CONFIG_DEBUG or BPL_DEBUG_ENABLED
Tags
Detection Criterionenabled set in the config/java_memory_assistant.ymlDetection Criterionenabled set via JBP_CONFIG_JAVA_MEMORY_ASSISTANT
Tagsjava-memory-assistant=<version>
- + @@ -17,14 +17,14 @@ Tags are printed to standard output by the buildpack detect script ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by creating or modifying the [`config/java_opts.yml`][] file in the buildpack fork. +The framework can be configured by setting the `JBP_CONFIG_JAVA_OPTS` environment variable. The value must be valid inline YAML. | Name | Description | ---- | ----------- | `from_environment` | Whether to append the value of the `JAVA_OPTS` environment variable to the collection of Java options | `java_opts` | The Java options to use when running the application. All values are used without modification when invoking the JVM. The options are specified as a single YAML scalar in plain style or enclosed in single or double quotes. -Any `JAVA_OPTS` from either the config file or environment variables will be specified in the start command after any Java Opts added by other frameworks. +Any `JAVA_OPTS` from either `JBP_CONFIG_JAVA_OPTS` or the `JAVA_OPTS` environment variable will be specified in the start command after any Java options added by other frameworks. ## Runtime variable expansion @@ -46,8 +46,7 @@ cf set-env my-application JAVA_OPTS '-Dserver.port=$PORT' ``` ```yaml -# config/java_opts.yml -java_opts: '-Xloggc:$PWD/beacon_gc.log -verbose:gc' +JBP_CONFIG_JAVA_OPTS: '{ java_opts: "-Xloggc:$PWD/beacon_gc.log -verbose:gc" }' ``` ### Command substitutions are never executed @@ -105,12 +104,9 @@ cf set-env my-application JAVA_OPTS '-DcronExpr=0 */7 * * *' ## Examples -### Configuration File Example +### Environment Variable Example ```yaml -# config/java_opts.yml ---- -from_environment: false -java_opts: -Xloggc:$PWD/beacon_gc.log -verbose:gc +JBP_CONFIG_JAVA_OPTS: '{ from_environment: false, java_opts: ["-Xloggc:$PWD/beacon_gc.log", "-verbose:gc"] }' ``` ### Environment Variable Override Examples @@ -171,7 +167,6 @@ However, using an array format is recommended for clarity and to avoid parsing a | `-XX:SurvivorRatio=` | Ratio of eden/survivor space. Solaris only. | `-XX:TargetSurvivorRatio=` | Desired ratio of survivor space used after scavenge. -[`config/java_opts.yml`]: ../config/java_opts.yml [Configuration and Extension]: ../README.md#configuration-and-extension [Java Support for Large Memory Pages]: http://www.oracle.com/technetwork/java/javase/tech/largememory-jsp-137182.html [JRE Memory]: jre-open_jdk_jre.md#memory diff --git a/docs/framework-jmx.md b/docs/framework-jmx.md index 8d122ccca..776ba812e 100644 --- a/docs/framework-jmx.md +++ b/docs/framework-jmx.md @@ -4,7 +4,7 @@ The JMX Framework contributes Java JMX configuration to the application at runti
Detection Criterionjava_opts set in the config/java_opts.yml file or the JAVA_OPTS environment variable setjava_opts set in JBP_CONFIG_JAVA_OPTS or the JAVA_OPTS environment variable set
Tags
- + @@ -16,12 +16,33 @@ Tags are printed to standard output by the buildpack detect script ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by creating or modifying the [`config/jmx.yml`][] file in the buildpack fork. +The framework can be configured by setting the `JBP_CONFIG_JMX` environment variable. The value must be valid inline YAML. The Cloud Native Buildpacks environment variables `BPL_JMX_ENABLED` and `BPL_JMX_PORT` are also supported and take precedence over `JBP_CONFIG_JMX`. | Name | Description | ---- | ----------- -| `enabled` | Whether to enable JMX -| `port` | The port that the debug agent will listen on. Defaults to `5000`. +| `enabled` | Whether to enable JMX. Defaults to `false`. +| `port` | The port that the JMX agent will listen on. Defaults to `5000`. + +### Examples + +Enable JMX on the default port: + +```yaml +JBP_CONFIG_JMX: '{enabled: true}' +``` + +Enable JMX on a custom port: + +```yaml +JBP_CONFIG_JMX: '{enabled: true, port: 6000}' +``` + +Using Cloud Native Buildpacks conventions: + +```bash +BPL_JMX_ENABLED=true +BPL_JMX_PORT=6000 +``` ## Creating SSH Tunnel After starting an application with JMX enabled, an SSH tunnel must be created to the container. To create that SSH container, execute the following command: @@ -36,5 +57,4 @@ Once the SSH tunnel has been created, your JConsole should connect to `localhost ![JConsole Configuration](framework-jmx-jconsole.png) -[`config/jmx.yml`]: ../config/jmx.yml [Configuration and Extension]: ../README.md#configuration-and-extension diff --git a/docs/framework-jprofiler_profiler.md b/docs/framework-jprofiler_profiler.md index 87a5f5124..28a3d187d 100644 --- a/docs/framework-jprofiler_profiler.md +++ b/docs/framework-jprofiler_profiler.md @@ -4,7 +4,7 @@ The JProfiler Profiler Framework contributes JProfiler configuration to the appl
Detection Criterionenabled set in the config/jmx.yml fileenabled set via JBP_CONFIG_JMX or BPL_JMX_ENABLED
Tags
- + @@ -16,15 +16,27 @@ Tags are printed to standard output by the buildpack detect script ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by creating or modifying the [`config/jprofiler_profiler.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. +The framework can be configured by setting the `JBP_CONFIG_JPROFILER_PROFILER` environment variable. The value must be valid inline YAML. | Name | Description | ---- | ----------- -| `enabled` | Whether to enable the JProfiler Profiler +| `enabled` | Whether to enable the JProfiler Profiler. Defaults to `false`. | `port` | The port that the JProfiler Profiler will listen on. Defaults to `8849`. -| `nowait` | Whether to start process without waiting for JProfiler to connect first. Defaults to `true`. -| `repository_root` | The URL of the JProfiler Profiler repository index ([details][repositories]). -| `version` | The version of the JProfiler Profiler to use. Candidate versions can be found in [this listing][]. +| `nowait` | Whether to start the process without waiting for JProfiler to connect first. Defaults to `true`. + +### Examples + +Enable JProfiler on the default port: + +```yaml +JBP_CONFIG_JPROFILER_PROFILER: '{enabled: true}' +``` + +Enable JProfiler on a custom port, waiting for connection: + +```yaml +JBP_CONFIG_JPROFILER_PROFILER: '{enabled: true, port: 9000, nowait: false}' +``` ## Creating SSH Tunnel After starting an application with the JProfiler Profiler enabled, an SSH tunnel must be created to the container. To create that SSH container, execute the following command: @@ -39,8 +51,4 @@ Once the SSH tunnel has been created, your JProfiler Profiler should connect to ![JProfiler Configuration](framework-jprofiler_profiler.png) -[`config/jprofiler_profiler.yml`]: ../config/jprofiler_profiler.yml [Configuration and Extension]: ../README.md#configuration-and-extension -[this listing]: http://download.pivotal.io.s3.amazonaws.com/jprofiler/index.yml -[repositories]: extending-repositories.md -[version syntax]: extending-repositories.md#version-syntax-and-ordering diff --git a/docs/framework-jrebel_agent.md b/docs/framework-jrebel_agent.md index a8923c305..1d2052087 100644 --- a/docs/framework-jrebel_agent.md +++ b/docs/framework-jrebel_agent.md @@ -19,19 +19,21 @@ For more information regarding setup and configuration, please refer to the [JRe ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/jrebel_agent.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. +The framework can be configured by setting the `JBP_CONFIG_JREBEL` environment variable. The value must be valid inline YAML. | Name | Description | ---- | ----------- -| `repository_root` | The URL of the JRebel repository index ([details][repositories]). -| `version` | The version of JRebel to use. Candidate versions can be found in [this listing][]. -| `enabled` | Whether to activate JRebel (upon the presence of `rebel-remote.xml`) or not. +| `enabled` | Whether to activate JRebel upon the presence of `rebel-remote.xml`. Defaults to `true`. + +### Example + +Disable JRebel even when `rebel-remote.xml` is present: + +```yaml +JBP_CONFIG_JREBEL: '{enabled: false}' +``` [Configuration and Extension]: ../README.md#configuration-and-extension -[`config/jrebel_agent.yml`]: ../config/jrebel_agent.yml [JRebel Cloud/Remote]: http://manuals.zeroturnaround.com/jrebel/remoteserver/index.html [JRebel]: http://zeroturnaround.com/software/jrebel/ [pivotal]: http://manuals.zeroturnaround.com/jrebel/remoteserver/pivotal.html -[repositories]: extending-repositories.md -[this listing]: http://dl.zeroturnaround.com/jrebel/index.yml -[version syntax]: extending-repositories.md#version-syntax-and-ordering diff --git a/docs/framework-luna_security_provider.md b/docs/framework-luna_security_provider.md index bea0a0491..5d4255187 100644 --- a/docs/framework-luna_security_provider.md +++ b/docs/framework-luna_security_provider.md @@ -87,15 +87,21 @@ $ cf create-user-provided-service luna -p '{"client":{"certificate":"-----BEGIN ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/luna_security_provider.yml`][] file in the buildpack. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. +The framework can be configured by setting the `JBP_CONFIG_LUNA_SECURITY_PROVIDER` environment variable. The value must be valid inline YAML. | Name | Description | ---- | ----------- | `ha_logging_enabled` | Whether to enable HA logging for the Luna Security Provider. Defaults to `true`. | `logging_enabled` | Whether to enable the logging wrapper for the Luna Security Provider. Defaults to `false`. | `tcp_keep_alive_enabled` | Whether to enable the client TCP keep alive setting for the Luna Security Provider. Defaults to `false`. -| `repository_root` | The URL of the Luna Security Provider repository index ([details][repositories]). -| `version` | Version of the Luna Security Provider to use. + +### Example + +Enable Cryptoki logging and TCP keep-alive: + +```yaml +JBP_CONFIG_LUNA_SECURITY_PROVIDER: '{logging_enabled: true, tcp_keep_alive_enabled: true}' +``` ### Configuration Generation @@ -116,8 +122,5 @@ To customize the default Luna Security Provider configuration across all applica This approach is useful for operators who want to enforce organization-wide Luna Security Provider settings. -[`config/luna_security_provider.yml`]: ../config/luna_security_provider.yml [Luna Security Service]: http://www.safenet-inc.com/data-encryption/hardware-security-modules-hsms/ [Configuration and Extension]: ../README.md#configuration-and-extension -[repositories]: extending-repositories.md -[version syntax]: extending-repositories.md#version-syntax-and-ordering diff --git a/docs/framework-maria_db_jdbc.md b/docs/framework-maria_db_jdbc.md index 635767f92..6bc1324ba 100644 --- a/docs/framework-maria_db_jdbc.md +++ b/docs/framework-maria_db_jdbc.md @@ -26,17 +26,8 @@ Users may optionally provide their own MariaDB or MySQL service. A user-provided ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/maria_db_jdbc.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. - -| Name | Description -| ---- | ----------- -| `repository_root` | The URL of the MariaDB JDBC repository index ([details][repositories]). -| `version` | The version of MariaDB JDBC to use. Candidate versions can be found in [this listing][]. +The framework has no user-configurable buildpack options. The MariaDB JDBC driver version is managed by the buildpack manifest. [Configuration and Extension]: ../README.md#configuration-and-extension -[`config/maria_db_jdbc.yml`]: ../config/maria_db_jdbc.yml [MariaDB]: https://mariadb.com [MySQL Service]: http://www.mysql.org -[repositories]: extending-repositories.md -[this listing]: http://download.pivotal.io.s3.amazonaws.com/mariadb-jdbc/index.yml -[version syntax]: extending-repositories.md#version-syntax-and-ordering diff --git a/docs/framework-metric_writer.md b/docs/framework-metric_writer.md index aeaaff0a5..f8a4e745c 100644 --- a/docs/framework-metric_writer.md +++ b/docs/framework-metric_writer.md @@ -29,16 +29,18 @@ The Metric Writer Framework adds a set of CloudFoundry-specific Micrometer tags ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/metric_writer.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. +The framework can be configured by setting the `JBP_CONFIG_METRIC_WRITER` environment variable. The value must be valid inline YAML. | Name | Description | ---- | ----------- -| `enabled` | Whether to attempt metric augmentation -| `repository_root` | The URL of the Metric Writer repository index ([details][repositories]). -| `version` | The version of Metric Writer to use. Candidate versions can be found in [this listing][]. +| `enabled` | Whether to attempt metric augmentation. Defaults to `false`. + +### Example + +Enable the metric writer: + +```yaml +JBP_CONFIG_METRIC_WRITER: '{enabled: true}' +``` [Configuration and Extension]: ../README.md#configuration-and-extension -[`config/metric_writer.yml`]: ../config/metric_writer.yml -[repositories]: extending-repositories.md -[this listing]: https://java-buildpack.cloudfoundry.org/metric-writer/index.yml -[version syntax]: extending-repositories.md#version-syntax-and-ordering diff --git a/docs/framework-new_relic_agent.md b/docs/framework-new_relic_agent.md index bdee9719d..ca76861b7 100644 --- a/docs/framework-new_relic_agent.md +++ b/docs/framework-new_relic_agent.md @@ -30,14 +30,7 @@ The credential payload of the service may contain the following entries: ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/new_relic_agent.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. - -| Name | Description -| ---- | ----------- -| `repository_root` | The URL of the New Relic repository index ([details][repositories]). -| `version` | The version of New Relic to use. Candidate versions can be found in [this listing][]. -| `extensions.repository_root` | The URL of the Extensions repository index ([details][repositories]). -| `extensions.version` | The version of the Extensions to use. Candidate versions can be found in the the repository that you have created to house the Extensions. +The framework has no user-configurable buildpack options for version selection. The New Relic agent version is managed by the buildpack manifest. ### Extensions @@ -77,9 +70,5 @@ To customize the default New Relic configuration across all applications using y This approach is useful for operators who want to enforce organization-wide New Relic settings. [Configuration and Extension]: ../README.md#configuration-and-extension -[`config/new_relic_agent.yml`]: ../config/new_relic_agent.yml [New Relic Service]: https://newrelic.com -[repositories]: extending-repositories.md -[this listing]: https://download.run.pivotal.io/new-relic/index.yml -[version syntax]: extending-repositories.md#version-syntax-and-ordering [Extension XML Files]: https://docs.newrelic.com/docs/agents/java-agent/custom-instrumentation/java-instrumentation-xml diff --git a/docs/framework-postgresql_jdbc.md b/docs/framework-postgresql_jdbc.md index bff4a1784..3dd2485d4 100644 --- a/docs/framework-postgresql_jdbc.md +++ b/docs/framework-postgresql_jdbc.md @@ -24,16 +24,7 @@ Users may optionally provide their own PostgreSQL service. A user-provided Postg ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/postgresql_jdbc.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. - -| Name | Description -| ---- | ----------- -| `repository_root` | The URL of the PostgreSQL JDBC repository index ([details][repositories]). -| `version` | The version of PostgreSQL JDBC to use. Candidate versions can be found in [this listing][]. +The framework has no user-configurable buildpack options. The PostgreSQL JDBC driver version is managed by the buildpack manifest. [Configuration and Extension]: ../README.md#configuration-and-extension -[`config/postgresql_jdbc.yml`]: ../config/postgresql_jdbc.yml [PostgreSQL Service]: http://www.postgresql.org -[repositories]: extending-repositories.md -[this listing]: http://download.pivotal.io.s3.amazonaws.com/postgresql-jdbc/index.yml -[version syntax]: extending-repositories.md#version-syntax-and-ordering diff --git a/docs/framework-protect_app_security_provider.md b/docs/framework-protect_app_security_provider.md index d1d4229e9..f5b4a0b7a 100644 --- a/docs/framework-protect_app_security_provider.md +++ b/docs/framework-protect_app_security_provider.md @@ -79,12 +79,7 @@ So, here are a few steps you can take to normalize your certificate: ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/protect_app_security_provider.yml`][] file in the buildpack. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. - -| Name | Description -| ---- | ----------- -| `repository_root` | The URL of the ProtectApp Security Provider repository index ([details][repositories]). -| `version` | Version of the ProtectApp Security Provider to use. +The framework has no user-configurable buildpack options. The ProtectApp Security Provider version is managed by the buildpack manifest. See [Additional Configuration](#additional-configuration) below for application-level configuration options. ### Additional Configuration @@ -107,8 +102,5 @@ All ProtectApp configuration can also be provided via: - System properties passed through VCAP_SERVICES credentials (using the `-Dcom.ingrian.security.nae.*` prefix) - The credentials payload as documented above -[`config/protect_app_security_provider.yml`]: ../config/protect_app_security_provider.yml [ProtectApp Security Service]: https://safenet.gemalto.com/data-encryption/protectapp-application-protection/ [Configuration and Extension]: ../README.md#configuration-and-extension -[repositories]: extending-repositories.md -[version syntax]: extending-repositories.md#version-syntax-and-ordering diff --git a/docs/framework-riverbed_appinternals_agent.md b/docs/framework-riverbed_appinternals_agent.md index f0012a01f..2e74e958a 100644 --- a/docs/framework-riverbed_appinternals_agent.md +++ b/docs/framework-riverbed_appinternals_agent.md @@ -36,22 +36,9 @@ cf bind-service spring-music spring-music-appinternals ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/riverbed_appinternals_agent.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. - -| Name | Description -| ---- | ----------- -| `repository_root` | The URL of the Riverbed Appinternals agent repository index ([details][repositories]). -| `version` | The version of the Riverbed Appinternals agent to use. +The framework has no user-configurable buildpack options. The Riverbed AppInternals agent version is managed by the buildpack manifest. [Configuration and Extension]: ../README.md#configuration-and-extension -[repositories]: extending-repositories.md -[version syntax]: extending-repositories.md#version-syntax-and-ordering -[`config/riverbed_appinternals_agent.yml`]: ../config/riverbed_appinternals_agent.yml - - -**NOTE** - -If the Riverbed Service Broker's version is greater than or equal to 10.20, the buildpack will instead download Riverbed AppInternals agent from Riverbed Service Broker and will fall back to using `repository_root` in [`config/riverbed_appinternals_agent.yml`][] only if Service Broker failed to serve the Agent artifact. **NOTE** diff --git a/docs/framework-sealights_agent.md b/docs/framework-sealights_agent.md index 235254b8a..3f02d13f4 100644 --- a/docs/framework-sealights_agent.md +++ b/docs/framework-sealights_agent.md @@ -27,28 +27,31 @@ All fields above except the agent token may be also specified in the [Configurat ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/sealights_agent.yml`][] file. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. +The framework can be configured by setting the `JBP_CONFIG_SEALIGHTS` environment variable. The value must be valid inline YAML. | Name | Description | ---- | ----------- -| `build_session_id` | Sealights [Build Session ID][] for the application. Leave blank to use the value embedded in the jar/war artifacts -| `proxy` | Specify a HTTP proxy used to communicate with the Sealights backend. Required when a corporate network prohibits communication to cloud services. The default is to have no proxy configured. This does not inherit from `http_proxy`/`https_proxy` or `http.proxyHost/https.proxyHost`, you must set this specifically if a proxy is needed. -| `lab_id` | Specify a Sealights [Lab ID][] -| `auto_upgrade` | Enable/disable agent auto-upgrade. Off by default -| `version` | The version of Auto-reconfiguration to use. Candidate versions can be found in [this listing][]. If auto_upgrade is turned on, a different version may be downloaded and used at runtime +| `build_session_id` | Sealights [Build Session ID][] for the application. Leave blank to use the value embedded in the jar/war artifacts. +| `proxy` | Specify an HTTP proxy used to communicate with the Sealights backend. Required when a corporate network prohibits communication to cloud services. The default is to have no proxy configured. This does not inherit from `http_proxy`/`https_proxy` or `http.proxyHost/https.proxyHost`. +| `lab_id` | Specify a Sealights [Lab ID][]. +| `auto_upgrade` | Enable agent auto-upgrade by passing `-Dsl.enableUpgrade=true` to the JVM. Defaults to `false`. If the bound service's credentials include an `enableUpgrade` entry, that value takes precedence over this setting. Configuration settings will take precedence over the ones specified in the [User-Provided Service](#user-provided-service), if those are defined. +### Example + +Configure a build session with a proxy: + +```yaml +JBP_CONFIG_SEALIGHTS: '{build_session_id: "bsid_abc123", proxy: "http://proxy.example.com:8080"}' +``` + ## Troubleshooting and Support For additional documentation and support, visit the official [Sealights Java agents documentation] page -[`config/sealights_agent.yml`]: ../config/sealights_agent.yml [Configuration and Extension]: ../README.md#configuration-and-extension -[repositories]: extending-repositories.md -[version syntax]: extending-repositories.md#version-syntax-and-ordering [Sealights Service]: https://www.sealights.io [Build Session ID]: https://sealights.atlassian.net/wiki/spaces/SUP/pages/3473472/Using+Java+Agents+-+Generating+a+session+ID [Lab ID]: https://sealights.atlassian.net/wiki/spaces/SUP/pages/762413124/Using+Java+Agents+-+Running+Tests+in+Parallel+Lab+Id -[this listing]: https://agents.sealights.co/pcf/index.yml [Sealights Java agents documentation]: https://sealights.atlassian.net/wiki/spaces/SUP/pages/3014685/SeaLights+Java+agents diff --git a/docs/framework-sky_walking_agent.md b/docs/framework-sky_walking_agent.md index b0cd2f84d..96f693715 100644 --- a/docs/framework-sky_walking_agent.md +++ b/docs/framework-sky_walking_agent.md @@ -17,33 +17,39 @@ When binding SkyWalking using a user-provided service, it must have name or tag | Name | Description | ---- | ----------- -| `application-name` | (Optional) The application's name +| `collector_backend_services` | The collector backend address(es). Examples: single collector — `127.0.0.1:11800`; cluster — `10.2.45.126:11800,10.2.45.127:11800`. Also accepted as `collectorBackendServices` or `backend_service`. | `sample-n-per-3-secs` | (Optional) The number of sampled traces per 3 seconds. Negative number means sample traces as many as possible, most likely 100% | `span-limit-per-segment` | (Optional) The max amount of spans in a single segment | `ignore-suffix` | (Optional) Ignore the segments if their operation names start with these suffix | `open-debugging-class` | (Optional) If true, skywalking agent will save all instrumented classes files in `/debugging` folder.Skywalking team may ask for these files in order to resolve compatible problem -| `servers` | Server addresses .Examples: Single collector：servers="127.0.0.1:8080",Collector cluster：servers="10.2.45.126:8080,10.2.45.127:7600" | `logging-level` | (Optional) Logging level ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/sky_walking_agent.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. +The framework can be configured by setting the `JBP_CONFIG_SKY_WALKING_AGENT` environment variable. The value must be valid inline YAML. | Name | Description | ---- | ----------- -| `default_application_name` | This is omitted by default but can be added to specify the application name in the SkyWalking dashboard. This can be overridden by an `application-name` entry in the credentials payload. If neither are supplied the default is the `application_name` as specified by Cloud Foundry. -| `repository_root` | The URL of the SkyWalking repository index ([details][repositories]). -| `version` | The version of SkyWalking to use. Candidate versions can be found in [this listing][]. +| `default_application_name` | Fallback application name used in the SkyWalking dashboard **only when `VCAP_APPLICATION` is not available** (i.e. outside a Cloud Foundry container). On Cloud Foundry, `VCAP_APPLICATION.application_name` is always used instead, prefixed with the space name (`space:app`), and this setting is ignored. + +### Application name resolution order + +1. **`VCAP_APPLICATION`** — the buildpack reads `space_name` and `application_name` from this variable and sets the service name to `:`. This is the value used for every normal Cloud Foundry deployment; `default_application_name` has no effect here. +2. **`default_application_name`** (fallback) — used only when `VCAP_APPLICATION` is absent or unparseable (e.g. running the agent outside Cloud Foundry). + +### Example + +Set a fallback name for non-CF environments: + +```yaml +JBP_CONFIG_SKY_WALKING_AGENT: '{default_application_name: my-service}' +``` ### Additional Resources **Note:** The `resources/sky_walking_agent` directory approach from the Ruby buildpack (2013-2025) is no longer supported. This was a **buildpack-level** feature where teams would fork the java-buildpack repository, add custom files to `resources/sky_walking_agent/`, and package their custom buildpack. The Go buildpack does not package the `resources/` directory. -[`config/sky_walking_agent.yml`]: ../config/sky_walking_agent.yml [SkyWalking Java Agent Configuration Properties]: https://github.com/apache/incubator-skywalking/blob/master/docs/en/Deploy-skywalking-agent.md [SkyWalking Service]: http://skywalking.io [Configuration and Extension]: ../README.md#configuration-and-extension -[repositories]: extending-repositories.md -[this listing]: https://download.run.pivotal.io/sky-walking/index.yml -[version syntax]: extending-repositories.md#version-syntax-and-ordering diff --git a/docs/framework-spring_auto_reconfiguration.md b/docs/framework-spring_auto_reconfiguration.md index a7a7dfc53..be4773acf 100644 --- a/docs/framework-spring_auto_reconfiguration.md +++ b/docs/framework-spring_auto_reconfiguration.md @@ -64,13 +64,11 @@ The Spring Auto-reconfiguration Framework adds the `cloud` profile to any existi ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by modifying the [`config/spring_auto_reconfiguration.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. +The framework can be configured by setting the `JBP_CONFIG_SPRING_AUTO_RECONFIGURATION` environment variable. The value must be valid inline YAML. | Name | Description | ---- | ----------- -| `enabled` | Whether to attempt auto-reconfiguration. **Default: `false`** (disabled since Dec 2025) -| `repository_root` | The URL of the Auto-reconfiguration repository index ([details][repositories]). -| `version` | The version of Auto-reconfiguration to use. Candidate versions can be found in [this listing][]. +| `enabled` | Whether to attempt auto-reconfiguration. **Default: `false`** (disabled since Dec 2025) ### Enabling Spring Auto-reconfiguration @@ -85,9 +83,5 @@ cf restage my-app [Auto-Reconfiguration]: https://github.com/cloudfoundry/java-buildpack-auto-reconfiguration [Configuration and Extension]: ../README.md#configuration-and-extension -[`config/spring_auto_reconfiguration.yml`]: ../config/spring_auto_reconfiguration.yml -[repositories]: extending-repositories.md [Spring Cloud Cloud Foundry Connector]: https://cloud.spring.io/spring-cloud-connectors/spring-cloud-cloud-foundry-connector.html -[this listing]: http://download.pivotal.io.s3.amazonaws.com/auto-reconfiguration/index.yml -[version syntax]: extending-repositories.md#version-syntax-and-ordering [`SPRING_PROFILES_ACTIVE`]: http://docs.spring.io/spring/docs/4.0.0.RELEASE/javadoc-api/org/springframework/core/env/AbstractEnvironment.html#ACTIVE_PROFILES_PROPERTY_NAME diff --git a/docs/framework-your_kit_profiler.md b/docs/framework-your_kit_profiler.md index 8c5609511..91b916a72 100644 --- a/docs/framework-your_kit_profiler.md +++ b/docs/framework-your_kit_profiler.md @@ -4,7 +4,7 @@ The YourKit Profiler Framework contributes YourKit Profiler configuration to the
Detection Criterionenabled set in the config/jprofiler_profiler.yml fileenabled set via JBP_CONFIG_JPROFILER_PROFILER
Tags
- + @@ -16,15 +16,26 @@ Tags are printed to standard output by the buildpack detect script ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. -The framework can be configured by creating or modifying the [`config/your_kit_profiler.yml`][] file in the buildpack fork. The framework uses the [`Repository` utility support][repositories] and so it supports the [version syntax][] defined there. +The framework can be configured by setting the `JBP_CONFIG_YOUR_KIT_PROFILER` environment variable. The value must be valid inline YAML. | Name | Description | ---- | ----------- -| `default_session_name` | The session name to display in the YourKit Profiler UI. Defaults to `:`. -| `enabled` | Whether to enable the YourKit Profiler +| `enabled` | Whether to enable the YourKit Profiler. Defaults to `false`. | `port` | The port that the YourKit Profiler will listen on. Defaults to `10001`. -| `repository_root` | The URL of the YourKit Profiler repository index ([details][repositories]). -| `version` | The version of the YourKit Profiler to use. Candidate versions can be found in the listings for [jammy][]. + +### Examples + +Enable YourKit Profiler on the default port: + +```yaml +JBP_CONFIG_YOUR_KIT_PROFILER: '{enabled: true}' +``` + +Enable YourKit Profiler on a custom port: + +```yaml +JBP_CONFIG_YOUR_KIT_PROFILER: '{enabled: true, port: 10002}' +``` ## Creating SSH Tunnel After starting an application with the YourKit Profiler enabled, an SSH tunnel must be created to the container. To create that SSH container, execute the following command: @@ -39,8 +50,4 @@ Once the SSH tunnel has been created, your YourKit Profiler should connect to `l ![YourKit Configuration](framework-your_kit_profiler.png) -[`config/your_kit_profiler.yml`]: ../config/your_kit_profiler.yml -[jammy]: https://download.run.pivotal.io/your-kit/bioni/x86_64/index.yml [Configuration and Extension]: ../README.md#configuration-and-extension -[repositories]: extending-repositories.md -[version syntax]: extending-repositories.md#version-syntax-and-ordering diff --git a/src/java/frameworks/sealights_agent.go b/src/java/frameworks/sealights_agent.go index 742da3612..3a22f6d84 100644 --- a/src/java/frameworks/sealights_agent.go +++ b/src/java/frameworks/sealights_agent.go @@ -156,12 +156,22 @@ func (f *SealightsAgentFramework) Finalize() error { // Optional: sl.tags, sl.enableUpgrade, sl.log.level, sl.log.folder systemProps := fmt.Sprintf("-Dsl.token=%s", token) + // Load JBP_CONFIG_SEALIGHTS before processing optional properties so config + // values are available as fallbacks throughout the block below. + config, err := f.loadConfig() + if err != nil { + f.context.Log.Warning("Failed to load sealight config: %s", err.Error()) + return nil // Don't fail the build + } + // Add optional properties from service credentials if tags, ok := service.Credentials["tags"].(string); ok && tags != "" { systemProps += fmt.Sprintf(" -Dsl.tags=%s", tags) } if enableUpgrade, ok := service.Credentials["enableUpgrade"].(string); ok && enableUpgrade != "" { systemProps += fmt.Sprintf(" -Dsl.enableUpgrade=%s", enableUpgrade) + } else if config.AutoUpgrade { + systemProps += " -Dsl.enableUpgrade=true" } if logLevel, ok := service.Credentials["logLevel"].(string); ok && logLevel != "" { systemProps += fmt.Sprintf(" -Dsl.log.level=%s", logLevel) @@ -173,12 +183,6 @@ func (f *SealightsAgentFramework) Finalize() error { // Build javaagent argument javaAgent := fmt.Sprintf("-javaagent:%s", runtimeAgentPath) - // Add if custom config is at place - config, err := f.loadConfig() - if err != nil { - f.context.Log.Warning("Failed to load sealight config: %s", err.Error()) - return nil // Don't fail the build - } if config.BuildSessionId != "" { systemProps += fmt.Sprintf(" -Dsl.buildSessionId=%s", config.BuildSessionId) } diff --git a/src/java/frameworks/sealights_agent_test.go b/src/java/frameworks/sealights_agent_test.go index d84378201..e1a124ede 100644 --- a/src/java/frameworks/sealights_agent_test.go +++ b/src/java/frameworks/sealights_agent_test.go @@ -262,6 +262,52 @@ var _ = Describe("SealightsAgent", func() { }) }) + Context("with auto_upgrade: true set via JBP_CONFIG_SEALIGHTS (no service credential)", func() { + BeforeEach(func() { + installSealightsAgent(depsDir, "sl-test-listener.jar") + os.Setenv("VCAP_SERVICES", sealightsVCAPServices("sealights", "my-sl", nil, "tok", "")) + os.Setenv("JBP_CONFIG_SEALIGHTS", "auto_upgrade: true") + }) + + It("opts file contains -Dsl.enableUpgrade=true", func() { + Expect(fw.Finalize()).To(Succeed()) + content, err := os.ReadFile(filepath.Join(depsDir, "0", "java_opts", "39_sealights_agent.opts")) + Expect(err).NotTo(HaveOccurred()) + Expect(string(content)).To(ContainSubstring("-Dsl.enableUpgrade=true")) + }) + }) + + Context("with auto_upgrade: false set via JBP_CONFIG_SEALIGHTS (no service credential)", func() { + BeforeEach(func() { + installSealightsAgent(depsDir, "sl-test-listener.jar") + os.Setenv("VCAP_SERVICES", sealightsVCAPServices("sealights", "my-sl", nil, "tok", "")) + os.Setenv("JBP_CONFIG_SEALIGHTS", "auto_upgrade: false") + }) + + It("opts file does not contain -Dsl.enableUpgrade", func() { + Expect(fw.Finalize()).To(Succeed()) + content, err := os.ReadFile(filepath.Join(depsDir, "0", "java_opts", "39_sealights_agent.opts")) + Expect(err).NotTo(HaveOccurred()) + Expect(string(content)).NotTo(ContainSubstring("-Dsl.enableUpgrade")) + }) + }) + + Context("with service credential 'enableUpgrade' and auto_upgrade: false in JBP_CONFIG_SEALIGHTS", func() { + BeforeEach(func() { + installSealightsAgent(depsDir, "sl-test-listener.jar") + os.Setenv("VCAP_SERVICES", sealightsVCAPServices("sealights", "my-sl", nil, "tok", + `"enableUpgrade":"true"`)) + os.Setenv("JBP_CONFIG_SEALIGHTS", "auto_upgrade: false") + }) + + It("service credential takes precedence (enableUpgrade=true)", func() { + Expect(fw.Finalize()).To(Succeed()) + content, err := os.ReadFile(filepath.Join(depsDir, "0", "java_opts", "39_sealights_agent.opts")) + Expect(err).NotTo(HaveOccurred()) + Expect(string(content)).To(ContainSubstring("-Dsl.enableUpgrade=true")) + }) + }) + Context("with optional 'logLevel' credential", func() { BeforeEach(func() { installSealightsAgent(depsDir, "sl-test-listener.jar") diff --git a/src/java/frameworks/your_kit_profiler.go b/src/java/frameworks/your_kit_profiler.go index 0b0321ec8..e5aed7261 100644 --- a/src/java/frameworks/your_kit_profiler.go +++ b/src/java/frameworks/your_kit_profiler.go @@ -151,17 +151,15 @@ func (f *YourKitProfilerFramework) Finalize() error { // Get session name from VCAP_APPLICATION (space:app) sessionName := "cloudfoundry" - // Get port from config (default: 10001) - port := "10001" - portConfig := os.Getenv("JBP_CONFIG_YOUR_KIT_PROFILER") - if portConfig != "" && common.ContainsIgnoreCase(portConfig, "port") { - // Simple extraction (would need proper YAML parsing in production) - // For now, use default + // Load config and use the parsed port value + cfg, err := f.loadConfig() + if err != nil { + return fmt.Errorf("failed to load yourkit config: %w", err) } // Build agent path with options using runtime paths - agentOptions := fmt.Sprintf("dir=%s,logdir=%s,port=%s,sessionname=%s", - runtimeHomeDir, runtimeHomeDir, port, sessionName) + agentOptions := fmt.Sprintf("dir=%s,logdir=%s,port=%d,sessionname=%s", + runtimeHomeDir, runtimeHomeDir, cfg.Port, sessionName) javaAgent := fmt.Sprintf("-agentpath:%s=%s", runtimeAgentPath, agentOptions) // Write to .opts file using priority 45 @@ -173,3 +171,26 @@ func (f *YourKitProfilerFramework) Finalize() error { return nil } +func (f *YourKitProfilerFramework) loadConfig() (*yourKitConfig, error) { + cfg := yourKitConfig{ + Enabled: false, + Port: 10001, + } + config := os.Getenv("JBP_CONFIG_YOUR_KIT_PROFILER") + if config != "" { + yamlHandler := common.YamlHandler{} + if err := yamlHandler.ValidateFields([]byte(config), &cfg); err != nil { + f.context.Log.Warning("Unknown user config values: %s", err.Error()) + } + if err := yamlHandler.Unmarshal([]byte(config), &cfg); err != nil { + return nil, fmt.Errorf("failed to parse JBP_CONFIG_YOUR_KIT_PROFILER: %w", err) + } + } + return &cfg, nil +} + +type yourKitConfig struct { + Enabled bool `yaml:"enabled"` + Port int `yaml:"port"` +} + diff --git a/src/java/frameworks/your_kit_profiler_test.go b/src/java/frameworks/your_kit_profiler_test.go index 8287ff8cc..20bda82c2 100644 --- a/src/java/frameworks/your_kit_profiler_test.go +++ b/src/java/frameworks/your_kit_profiler_test.go @@ -241,6 +241,20 @@ var _ = Describe("YourKitProfiler", func() { Expect(string(content)).To(ContainSubstring("port=10001")) }) + Context("when a custom port is configured", func() { + BeforeEach(func() { + os.Setenv("JBP_CONFIG_YOUR_KIT_PROFILER", "{enabled: true, port: 10002}") + }) + + It("opts file contains the configured port", func() { + Expect(fw.Finalize()).To(Succeed()) + content, err := os.ReadFile(filepath.Join(depsDir, "0", "java_opts", "45_your_kit_profiler.opts")) + Expect(err).NotTo(HaveOccurred()) + Expect(string(content)).To(ContainSubstring("port=10002")) + Expect(string(content)).NotTo(ContainSubstring("port=10001")) + }) + }) + It("opts file contains dir and logdir pointing to $DEPS_DIR runtime path", func() { Expect(fw.Finalize()).To(Succeed()) content, err := os.ReadFile(filepath.Join(depsDir, "0", "java_opts", "45_your_kit_profiler.opts"))
Detection Criterionenabled set in the config/your_kit_profiler.yml fileenabled set via JBP_CONFIG_YOUR_KIT_PROFILER
Tags