From 2f6acf80f30f3cf0b00aded10b89b16fae1770d6 Mon Sep 17 00:00:00 2001 From: Peter Paul Bakker Date: Wed, 1 Jul 2026 09:35:06 +0000 Subject: [PATCH 01/10] feat(cf-env): add Spring Boot 4.x support and improve docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add detection tests for SB 4.0 and 4.1 (BOOT-INF/lib, lib/, WEB-INF/lib, MANIFEST.MF) - Update detection criterion to cover both SB 3.x and 4.x - Add version mapping table: SB 3.x → cfenv 3.x, SB 4.x → cfenv 4.x - Clarify cloud profile is activated by the library at runtime, not the buildpack - Add JBP_CONFIG_JAVA_CF_ENV configuration section with enable/disable examples - Document when to disable (manual VCAP_SERVICES handling, unwanted cloud profile, conflicts) --- docs/framework-java-cfenv.md | 42 ++++++++++++++++++++++--- src/java/frameworks/java_cf_env_test.go | 25 +++++++++++---- 2 files changed, 56 insertions(+), 11 deletions(-) diff --git a/docs/framework-java-cfenv.md b/docs/framework-java-cfenv.md index e9bbb31c71..521b93e0fd 100644 --- a/docs/framework-java-cfenv.md +++ b/docs/framework-java-cfenv.md @@ -1,15 +1,22 @@ # Java CfEnv Framework -The Java CfEnv Framework provides the `java-cfenv` library for Spring Boot 3+ applications. This library sets various Spring Boot properties by parsing CloudFoundry variables such as `VCAP_SERVICES`, allowing Spring Boot's autoconfiguration to kick in. +The Java CfEnv Framework provides the `java-cfenv` library for Spring Boot 3.x and 4.x applications. This library sets various Spring Boot properties by parsing CloudFoundry variables such as `VCAP_SERVICES`, allowing Spring Boot's autoconfiguration to kick in. -This is the recommended replacement for Spring AutoReconfiguration library which is deprecated. See the `java-cfenv` repostitory for more detail. +This is the recommended replacement for Spring AutoReconfiguration library which is deprecated. See the `java-cfenv` repository for more detail. -It also sets the 'cloud' profile for Spring Boot applications, as the Spring AutoReconfiguration framework did. +The included `java-cfenv` library activates the `cloud` Spring profile at runtime when `VCAP_SERVICES` is present, as the Spring AutoReconfiguration framework did. The buildpack itself does not set any Spring profile. + +The buildpack selects the appropriate `java-cfenv` version based on the detected Spring Boot major version: + +| Spring Boot | java-cfenv | +|-------------|------------| +| 3.x | 3.x (latest) | +| 4.x | 4.x (latest) | - - + + @@ -17,3 +24,28 @@ It also sets the 'cloud' profile for Spring Boot applications, as the Spring Aut
Detection CriterionExistence of a `Spring-Boot-Version: 3.*` manifest entryNo existing `java-cfenv` library foundExistence of a spring-boot-3.*.jar or spring-boot-4.*.jar in BOOT-INF/lib, WEB-INF/lib, or lib/; or a Spring-Boot-Version: 3.* / Spring-Boot-Version: 4.* entry in META-INF/MANIFEST.MFNo existing java-cfenv library found in the application
Tags
Tags are printed to standard output by the buildpack detect script + +## Configuration + +The framework can be disabled via the `JBP_CONFIG_JAVA_CF_ENV` environment variable: + +```bash +cf set-env JBP_CONFIG_JAVA_CF_ENV '{enabled: false}' +``` + +To re-enable, either set it back to `{enabled: true}` or remove the variable entirely: + +```bash +cf unset-env JBP_CONFIG_JAVA_CF_ENV +``` + +| Variable | Default | Description | +|----------|---------|-------------| +| `JBP_CONFIG_JAVA_CF_ENV` | `{enabled: true}` | Enable or disable the framework | + +Note: if `java-cfenv*.jar` is already present in the application, the buildpack skips injection automatically — no need to disable explicitly for that case. + +Disable when: +- The application handles `VCAP_SERVICES` manually with custom binding logic +- The automatic `cloud` profile activation is unwanted +- Another service binding library conflicts with `java-cfenv` \ No newline at end of file diff --git a/src/java/frameworks/java_cf_env_test.go b/src/java/frameworks/java_cf_env_test.go index b307be606f..dbff69a089 100644 --- a/src/java/frameworks/java_cf_env_test.go +++ b/src/java/frameworks/java_cf_env_test.go @@ -68,10 +68,23 @@ var _ = Describe("Java CF Env", func() { }) }) - Context("with Spring Boot 3.x JAR in lib/", func() { + Context("with Spring Boot 4.1.x JAR in BOOT-INF/lib", func() { + BeforeEach(func() { + Expect(os.MkdirAll(filepath.Join(buildDir, "BOOT-INF", "lib"), 0755)).To(Succeed()) + Expect(os.WriteFile(filepath.Join(buildDir, "BOOT-INF", "lib", "spring-boot-4.1.0.jar"), []byte("fake"), 0644)).To(Succeed()) + }) + + It("returns 'Java CF Env'", func() { + name, err := fw.Detect() + Expect(err).NotTo(HaveOccurred()) + Expect(name).To(Equal("Java CF Env")) + }) + }) + + Context("with Spring Boot 4.1.x JAR in lib/", func() { BeforeEach(func() { Expect(os.MkdirAll(filepath.Join(buildDir, "lib"), 0755)).To(Succeed()) - Expect(os.WriteFile(filepath.Join(buildDir, "lib", "spring-boot-3.1.5.jar"), []byte("fake"), 0644)).To(Succeed()) + Expect(os.WriteFile(filepath.Join(buildDir, "lib", "spring-boot-4.1.0.jar"), []byte("fake"), 0644)).To(Succeed()) }) It("returns 'Java CF Env'", func() { @@ -81,10 +94,10 @@ var _ = Describe("Java CF Env", func() { }) }) - Context("with Spring Boot 3.x JAR in WEB-INF/lib", func() { + Context("with Spring Boot 4.1.x JAR in WEB-INF/lib", func() { BeforeEach(func() { Expect(os.MkdirAll(filepath.Join(buildDir, "WEB-INF", "lib"), 0755)).To(Succeed()) - Expect(os.WriteFile(filepath.Join(buildDir, "WEB-INF", "lib", "spring-boot-3.0.0.jar"), []byte("fake"), 0644)).To(Succeed()) + Expect(os.WriteFile(filepath.Join(buildDir, "WEB-INF", "lib", "spring-boot-4.1.0.jar"), []byte("fake"), 0644)).To(Succeed()) }) It("returns 'Java CF Env'", func() { @@ -94,12 +107,12 @@ var _ = Describe("Java CF Env", func() { }) }) - Context("with Spring-Boot-Version: 3.x in META-INF/MANIFEST.MF", func() { + Context("with Spring-Boot-Version: 4.1.x in META-INF/MANIFEST.MF", func() { BeforeEach(func() { Expect(os.MkdirAll(filepath.Join(buildDir, "META-INF"), 0755)).To(Succeed()) Expect(os.WriteFile( filepath.Join(buildDir, "META-INF", "MANIFEST.MF"), - []byte("Manifest-Version: 1.0\nSpring-Boot-Version: 3.2.0\nMain-Class: org.springframework.boot.loader.JarLauncher\n"), + []byte("Manifest-Version: 1.0\nSpring-Boot-Version: 4.1.0\nMain-Class: org.springframework.boot.loader.JarLauncher\n"), 0644, )).To(Succeed()) }) From 11fce93b656076d75cf6fcf909fb0eb803a20e61 Mon Sep 17 00:00:00 2001 From: Peter Paul Bakker Date: Wed, 1 Jul 2026 19:47:39 +0000 Subject: [PATCH 02/10] fix(supply): show manifest default version label in framework install log - frameworkVersionSuffix now shows '(default: X.Y.Z)' instead of '(X.Y.Z)' making clear this is the manifest default, not necessarily the installed version - Reverts java-cfenv DependencyIdentifier back to 'java-cfenv' (no hack needed) - Removes extra Info log from JavaCfEnvFramework.Supply() Result: single 'Installing Java CF Env (default: 3.5.1)' line; actual installed version visible from libbuildpack install line --- src/java/frameworks/java_cf_env.go | 1 - src/java/frameworks/java_cf_env_test.go | 6 ++++++ src/java/supply/supply.go | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/src/java/frameworks/java_cf_env.go b/src/java/frameworks/java_cf_env.go index 48bf3f91f2..7a70e04cec 100644 --- a/src/java/frameworks/java_cf_env.go +++ b/src/java/frameworks/java_cf_env.go @@ -71,7 +71,6 @@ func (j *JavaCfEnvFramework) Supply() error { } else { j.context.Log.Debug("Resolved Java CF Env version pattern '%s' to %s", versionPattern, resolvedVersion) } - // Install java-cfenv JAR javaCfEnvDir := filepath.Join(j.context.Stager.DepDir(), "java_cf_env") if err := j.context.Installer.InstallDependency(dep, javaCfEnvDir); err != nil { diff --git a/src/java/frameworks/java_cf_env_test.go b/src/java/frameworks/java_cf_env_test.go index dbff69a089..b10f305699 100644 --- a/src/java/frameworks/java_cf_env_test.go +++ b/src/java/frameworks/java_cf_env_test.go @@ -219,6 +219,12 @@ var _ = Describe("Java CF Env", func() { }) }) + Describe("DependencyIdentifier", func() { + It("returns java-cfenv so supply.go can look up the manifest default version", func() { + Expect(fw.DependencyIdentifier()).To(Equal("java-cfenv")) + }) + }) + Describe("Finalize", func() { Context("when the JAR is present", func() { BeforeEach(func() { diff --git a/src/java/supply/supply.go b/src/java/supply/supply.go index afcd8d0943..bc4d156805 100644 --- a/src/java/supply/supply.go +++ b/src/java/supply/supply.go @@ -181,5 +181,5 @@ func (s *Supplier) frameworkVersionSuffix(framework frameworks.Framework) string return "" } - return fmt.Sprintf(" (%s)", dependency.Version) + return fmt.Sprintf(" (default: %s)", dependency.Version) } From 084629892d092b7337b9c341085575b8f9c50b01 Mon Sep 17 00:00:00 2001 From: Peter Paul Bakker Date: Mon, 6 Jul 2026 15:00:00 +0000 Subject: [PATCH 03/10] =?UTF-8?q?docs(cf-env):=20address=20Copilot=20revie?= =?UTF-8?q?w=20=E2=80=94=20restage=20steps,=20grammar=20fixes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add cf restage to set-env/unset-env examples; buildpack only re-reads JBP_CONFIG_JAVA_CF_ENV during staging - Fix CloudFoundry -> Cloud Foundry, detail -> details - Add trailing newline --- docs/framework-java-cfenv.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/framework-java-cfenv.md b/docs/framework-java-cfenv.md index 521b93e0fd..819967f55b 100644 --- a/docs/framework-java-cfenv.md +++ b/docs/framework-java-cfenv.md @@ -1,7 +1,7 @@ # Java CfEnv Framework -The Java CfEnv Framework provides the `java-cfenv` library for Spring Boot 3.x and 4.x applications. This library sets various Spring Boot properties by parsing CloudFoundry variables such as `VCAP_SERVICES`, allowing Spring Boot's autoconfiguration to kick in. +The Java CfEnv Framework provides the `java-cfenv` library for Spring Boot 3.x and 4.x applications. This library sets various Spring Boot properties by parsing Cloud Foundry variables such as `VCAP_SERVICES`, allowing Spring Boot's autoconfiguration to kick in. -This is the recommended replacement for Spring AutoReconfiguration library which is deprecated. See the `java-cfenv` repository for more detail. +This is the recommended replacement for Spring AutoReconfiguration library which is deprecated. See the `java-cfenv` repository for more details. The included `java-cfenv` library activates the `cloud` Spring profile at runtime when `VCAP_SERVICES` is present, as the Spring AutoReconfiguration framework did. The buildpack itself does not set any Spring profile. @@ -31,12 +31,16 @@ The framework can be disabled via the `JBP_CONFIG_JAVA_CF_ENV` environment varia ```bash cf set-env JBP_CONFIG_JAVA_CF_ENV '{enabled: false}' +cf restage ``` +The buildpack only re-reads this variable during staging, so a `cf restage` is required for the change to take effect. + To re-enable, either set it back to `{enabled: true}` or remove the variable entirely: ```bash cf unset-env JBP_CONFIG_JAVA_CF_ENV +cf restage ``` | Variable | Default | Description | @@ -48,4 +52,4 @@ Note: if `java-cfenv*.jar` is already present in the application, the buildpack Disable when: - The application handles `VCAP_SERVICES` manually with custom binding logic - The automatic `cloud` profile activation is unwanted -- Another service binding library conflicts with `java-cfenv` \ No newline at end of file +- Another service binding library conflicts with `java-cfenv` From 6e341b9003c0253ccfd4a8d5ac2bd09b94b655c8 Mon Sep 17 00:00:00 2001 From: Peter Paul Bakker Date: Tue, 7 Jul 2026 15:13:34 +0000 Subject: [PATCH 04/10] docs: clarify cloud profile activation in java-cfenv docs The `cloud` Spring profile is activated by CloudProfileApplicationListener, which ships only in the java-cfenv-all module (not java-cfenv-boot or the core module). Correct the framework doc and the migration guide's troubleshooting entry, and show SPRING_PROFILES_INCLUDE (add alongside existing profiles) vs SPRING_PROFILES_ACTIVE (replace) for explicit activation. Refs #1349. --- docs/framework-java-cfenv.md | 2 +- docs/spring-auto-reconfiguration-migration.md | 35 ++++++++++++++++--- 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/docs/framework-java-cfenv.md b/docs/framework-java-cfenv.md index 819967f55b..5e90d9487c 100644 --- a/docs/framework-java-cfenv.md +++ b/docs/framework-java-cfenv.md @@ -3,7 +3,7 @@ The Java CfEnv Framework provides the `java-cfenv` library for Spring Boot 3.x a This is the recommended replacement for Spring AutoReconfiguration library which is deprecated. See the `java-cfenv` repository for more details. -The included `java-cfenv` library activates the `cloud` Spring profile at runtime when `VCAP_SERVICES` is present, as the Spring AutoReconfiguration framework did. The buildpack itself does not set any Spring profile. +The `cloud` Spring profile is activated at runtime by java-cfenv's `CloudProfileApplicationListener`, which ships in the `java-cfenv-all` module. To ensure the profile is active — or to activate it independently of java-cfenv — set it explicitly. Use `SPRING_PROFILES_INCLUDE=cloud` to add `cloud` alongside any other active profiles, or `SPRING_PROFILES_ACTIVE=cloud` to set it as the sole active profile (this replaces any others). The buildpack itself does not set any Spring profile. The buildpack selects the appropriate `java-cfenv` version based on the detected Spring Boot major version: diff --git a/docs/spring-auto-reconfiguration-migration.md b/docs/spring-auto-reconfiguration-migration.md index 734fccd4ec..e098cd54f6 100644 --- a/docs/spring-auto-reconfiguration-migration.md +++ b/docs/spring-auto-reconfiguration-migration.md @@ -2,6 +2,24 @@ This guide provides step-by-step instructions for migrating from the deprecated **Spring Auto-reconfiguration** framework to **java-cfenv**. +> **Note — the `cloud` Spring profile** +> +> Spring Auto-reconfiguration activated a Spring profile named `cloud`. java-cfenv only +> activates that profile if the `java-cfenv-all` module is on the classpath (it contains +> `CloudProfileApplicationListener`); the `java-cfenv-boot` module does **not**. If your +> application relies on the `cloud` profile — for example `application-cloud.yml` / +> `application-cloud.properties` or `@Profile("cloud")` beans — either use `java-cfenv-all`, +> or activate it explicitly. If the application already sets other active profiles, use +> `SPRING_PROFILES_INCLUDE` to add `cloud` alongside them: +> +> ```bash +> cf set-env SPRING_PROFILES_INCLUDE cloud # adds 'cloud' to any existing profiles +> cf restage +> ``` +> +> Use `SPRING_PROFILES_ACTIVE=cloud` only if `cloud` should be the sole active profile (it +> replaces any others). + --- ## Table of Contents @@ -453,16 +471,23 @@ public class CustomConfig { ### Issue: "cloud" profile not active -**Cause**: java-cfenv only activates "cloud" profile on Cloud Foundry - -**Solution**: This is expected. Locally, the "cloud" profile won't be active. +**Cause**: The `cloud` profile is activated by `CloudProfileApplicationListener`, which ships +only in the `java-cfenv-all` module. The `java-cfenv-boot` dependency shown above does **not** +activate it. If you previously depended on the `cloud` profile under Spring Auto-reconfiguration, +it will not be active after migrating to `java-cfenv-boot` alone. -To test cloud profile locally: +**Solution**: Either depend on `java-cfenv-all` instead of `java-cfenv-boot`, or activate the +profile explicitly. If the application already sets other active profiles, add `cloud` alongside +them with `SPRING_PROFILES_INCLUDE`: ```bash -java -jar myapp.jar --spring.profiles.active=cloud +cf set-env SPRING_PROFILES_INCLUDE cloud # adds 'cloud' to any existing profiles +cf restage ``` +Use `SPRING_PROFILES_ACTIVE=cloud` only if `cloud` should be the sole active profile (it replaces +any others). To activate it locally: `java -jar myapp.jar --spring.profiles.active=cloud`. + --- ## Rollback Plan From 6d0b71daa93bcb6cfb6545d62bc32d3a0f87c927 Mon Sep 17 00:00:00 2001 From: Peter Paul Bakker Date: Wed, 8 Jul 2026 10:17:01 +0000 Subject: [PATCH 05/10] docs(cf-env): migration guide should use java-cfenv-all The main migration steps recommended java-cfenv-boot 3.1.4, which does not carry CloudProfileApplicationListener and so drops the `cloud` profile -- contradicting the guide's own notes. Switch the pom/gradle snippets and checklist to java-cfenv-all, version-matched to the app's Spring Boot major (3.5.1 for 3.x, 4.0.0 for 4.x), and note java-cfenv-boot as the lighter option for apps that do not need the `cloud` profile. Refs #1349. --- docs/spring-auto-reconfiguration-migration.md | 30 ++++++++++--------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/spring-auto-reconfiguration-migration.md b/docs/spring-auto-reconfiguration-migration.md index e098cd54f6..6866e768ee 100644 --- a/docs/spring-auto-reconfiguration-migration.md +++ b/docs/spring-auto-reconfiguration-migration.md @@ -70,8 +70,9 @@ This guide provides step-by-step instructions for migrating from the deprecated io.pivotal.cfenv - java-cfenv-boot - 3.1.4 + java-cfenv-all + + 3.5.1 ``` @@ -80,6 +81,7 @@ This guide provides step-by-step instructions for migrating from the deprecated - Library reads `VCAP_SERVICES` and sets Spring Boot properties - Spring Boot autoconfiguration uses these properties - More transparent and Spring Boot native +- `java-cfenv-all` bundles the property post-processors **and** the `cloud` profile listener (`CloudProfileApplicationListener`); use the lighter `java-cfenv-boot` instead only if you do not rely on the `cloud` profile --- @@ -109,11 +111,11 @@ Check your `pom.xml` or `build.gradle`: ```xml - + io.pivotal.cfenv - java-cfenv-boot - 3.1.4 + java-cfenv-all + 3.5.1 ``` @@ -122,7 +124,7 @@ Check your `pom.xml` or `build.gradle`: ```groovy dependencies { - implementation 'io.pivotal.cfenv:java-cfenv-boot:3.1.4' + implementation 'io.pivotal.cfenv:java-cfenv-all:3.5.1' // 4.0.0 for Spring Boot 4 } ``` @@ -245,7 +247,7 @@ You should see: ``` Java Buildpack v1.x.x | https://github.com/cloudfoundry/java-buildpack -----> Supplying frameworks... - java-cf-env=3.1.4 + java-cf-env=3.5.1 ``` --- @@ -472,13 +474,13 @@ public class CustomConfig { ### Issue: "cloud" profile not active **Cause**: The `cloud` profile is activated by `CloudProfileApplicationListener`, which ships -only in the `java-cfenv-all` module. The `java-cfenv-boot` dependency shown above does **not** -activate it. If you previously depended on the `cloud` profile under Spring Auto-reconfiguration, -it will not be active after migrating to `java-cfenv-boot` alone. +only in the `java-cfenv-all` module. If you migrated with the lighter `java-cfenv-boot` module +instead, it does **not** carry that listener, so the `cloud` profile you had under Spring +Auto-reconfiguration will not be active. -**Solution**: Either depend on `java-cfenv-all` instead of `java-cfenv-boot`, or activate the -profile explicitly. If the application already sets other active profiles, add `cloud` alongside -them with `SPRING_PROFILES_INCLUDE`: +**Solution**: Depend on `java-cfenv-all` (as shown in the steps above), or activate the profile +explicitly. If the application already sets other active profiles, add `cloud` alongside them with +`SPRING_PROFILES_INCLUDE`: ```bash cf set-env SPRING_PROFILES_INCLUDE cloud # adds 'cloud' to any existing profiles @@ -527,7 +529,7 @@ If you encounter migration issues: ## Summary Checklist - [ ] Verify Spring Boot version (2.1+ required, 3.x recommended) -- [ ] Add `java-cfenv-boot` dependency to `pom.xml` or `build.gradle` +- [ ] Add `java-cfenv-all` dependency to `pom.xml` or `build.gradle` (match your Spring Boot major) - [ ] Remove Spring Cloud Connectors dependencies (if present) - [ ] Review and simplify custom service configurations - [ ] Remove `JBP_CONFIG_SPRING_AUTO_RECONFIGURATION` environment variable From 9f6208054162b0f4a57a0981b70d8f4eac8c5168 Mon Sep 17 00:00:00 2001 From: Peter Paul Bakker Date: Thu, 9 Jul 2026 13:44:05 +0000 Subject: [PATCH 06/10] fix(supply): label framework install version as 'manifest default' MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Copilot review: '(default: X)' could read as 'the buildpack installs this by default'. Say 'manifest default' — for java-cfenv the manifest default differs from the version actually installed (resolved per Spring Boot major). --- src/java/supply/supply.go | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/java/supply/supply.go b/src/java/supply/supply.go index bc4d156805..4fa238a6fe 100644 --- a/src/java/supply/supply.go +++ b/src/java/supply/supply.go @@ -181,5 +181,7 @@ func (s *Supplier) frameworkVersionSuffix(framework frameworks.Framework) string return "" } - return fmt.Sprintf(" (default: %s)", dependency.Version) + // "manifest default" — the default version listed in manifest.yml, not necessarily what + // gets installed (e.g. java-cfenv resolves to a Spring-Boot-major-specific version). + return fmt.Sprintf(" (manifest default: %s)", dependency.Version) } From d1e0aac377f79013a1d3976694b8e6b3e3024ab0 Mon Sep 17 00:00:00 2001 From: Peter Paul Bakker Date: Thu, 9 Jul 2026 14:00:12 +0000 Subject: [PATCH 07/10] docs: cloud profile comes from java-cfenv, not Spring Auto-reconfiguration Spring Auto-reconfiguration is deprecated and disabled by default; the container docs still claimed it sets the `cloud` profile. java-cfenv (the java-cfenv-all module) is the replacement and activates `cloud` at runtime. Update the five container docs; also mention SPRING_PROFILES_INCLUDE for explicit activation. Refs #1349. --- docs/container-dist_zip.md | 2 +- docs/container-java_main.md | 2 +- docs/container-spring_boot.md | 2 +- docs/container-spring_boot_cli.md | 2 +- docs/container-tomcat.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/container-dist_zip.md b/docs/container-dist_zip.md index aadd126a96..25814fba0c 100644 --- a/docs/container-dist_zip.md +++ b/docs/container-dist_zip.md @@ -16,7 +16,7 @@ The Dist Zip Container allows applications packaged in [`distZip`-style][] to be Tags are printed to standard output by the buildpack detect script -If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The Spring Auto-reconfiguration Framework will specify the `cloud` profile in addition to any others. +If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The [Java CfEnv](framework-java-cfenv.md) framework — the replacement for the deprecated Spring Auto-reconfiguration — activates the `cloud` profile at runtime; you can also add it explicitly with `SPRING_PROFILES_INCLUDE=cloud`. ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. diff --git a/docs/container-java_main.md b/docs/container-java_main.md index fa0a943461..2061c3d03a 100644 --- a/docs/container-java_main.md +++ b/docs/container-java_main.md @@ -19,7 +19,7 @@ Command line arguments may optionally be configured. Tags are printed to standard output by the buildpack detect script -If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The Spring Auto-reconfiguration Framework will specify the `cloud` profile in addition to any others. +If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The [Java CfEnv](framework-java-cfenv.md) framework — the replacement for the deprecated Spring Auto-reconfiguration — activates the `cloud` profile at runtime; you can also add it explicitly with `SPRING_PROFILES_INCLUDE=cloud`. ## Spring Boot diff --git a/docs/container-spring_boot.md b/docs/container-spring_boot.md index 17c8833acf..2a303b92d9 100644 --- a/docs/container-spring_boot.md +++ b/docs/container-spring_boot.md @@ -15,7 +15,7 @@ Tags are printed to standard output by the buildpack detect script The container expects to run the application creating by running [`gradle distZip`][d] in an application built with the Spring Boot Gradle plugin. -If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The Spring Auto-reconfiguration Framework will specify the `cloud` profile in addition to any others. +If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The [Java CfEnv](framework-java-cfenv.md) framework — the replacement for the deprecated Spring Auto-reconfiguration — activates the `cloud` profile at runtime; you can also add it explicitly with `SPRING_PROFILES_INCLUDE=cloud`. ## CF Tasks diff --git a/docs/container-spring_boot_cli.md b/docs/container-spring_boot_cli.md index 93199f21ca..4f56c6b665 100644 --- a/docs/container-spring_boot_cli.md +++ b/docs/container-spring_boot_cli.md @@ -19,7 +19,7 @@ The Spring Boot CLI Container runs one or more Groovy (i.e. `*.groovy`) files us Tags are printed to standard output by the buildpack detect script. -If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The Spring Auto-reconfiguration Framework will specify the `cloud` profile in addition to any others. +If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The [Java CfEnv](framework-java-cfenv.md) framework — the replacement for the deprecated Spring Auto-reconfiguration — activates the `cloud` profile at runtime; you can also add it explicitly with `SPRING_PROFILES_INCLUDE=cloud`. ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. diff --git a/docs/container-tomcat.md b/docs/container-tomcat.md index 95feb35dc8..55022d68c0 100644 --- a/docs/container-tomcat.md +++ b/docs/container-tomcat.md @@ -13,7 +13,7 @@ The Tomcat Container allows servlet 2 and 3 web applications to be run. These a Tags are printed to standard output by the buildpack detect script -If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The Spring Auto-reconfiguration Framework will specify the `cloud` profile in addition to any others. +If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The [Java CfEnv](framework-java-cfenv.md) framework — the replacement for the deprecated Spring Auto-reconfiguration — activates the `cloud` profile at runtime; you can also add it explicitly with `SPRING_PROFILES_INCLUDE=cloud`. ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. From 956733f7393a8144a4a5af9508d5fc88dcd3e841 Mon Sep 17 00:00:00 2001 From: Peter Paul Bakker Date: Thu, 9 Jul 2026 14:06:07 +0000 Subject: [PATCH 08/10] docs: leave container-tomcat unchanged (java-cfenv is Spring Boot only) Revert the cloud-profile reword in the Tomcat/WAR container doc: java-cfenv detects only Spring Boot 3.x/4.x apps, so it does not apply to plain Spring MVC WARs served by the Tomcat container. The four Spring Boot container docs keep the java-cfenv wording. --- docs/container-tomcat.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/container-tomcat.md b/docs/container-tomcat.md index 55022d68c0..95feb35dc8 100644 --- a/docs/container-tomcat.md +++ b/docs/container-tomcat.md @@ -13,7 +13,7 @@ The Tomcat Container allows servlet 2 and 3 web applications to be run. These a Tags are printed to standard output by the buildpack detect script -If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The [Java CfEnv](framework-java-cfenv.md) framework — the replacement for the deprecated Spring Auto-reconfiguration — activates the `cloud` profile at runtime; you can also add it explicitly with `SPRING_PROFILES_INCLUDE=cloud`. +If the application uses Spring, [Spring profiles][] can be specified by setting the [`SPRING_PROFILES_ACTIVE`][] environment variable. This is automatically detected and used by Spring. The Spring Auto-reconfiguration Framework will specify the `cloud` profile in addition to any others. ## Configuration For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to [Configuration and Extension][]. From 1411792dc19860a3d9ece5702945e2430d49afb3 Mon Sep 17 00:00:00 2001 From: Peter Paul Bakker Date: Thu, 9 Jul 2026 14:19:10 +0000 Subject: [PATCH 09/10] docs(cf-env): document framework logic + disable options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a 'How it works' section (Detect/Supply/Finalize/Runtime) describing the java_cf_env framework, and document how to limit the automatic behaviour: JBP_CONFIG_JAVA_CF_ENV '{enabled: false}' disables the whole framework, and — since the buildpack backs off when the app bundles its own java-cfenv*.jar — an app can bundle java-cfenv-boot (props, no cloud profile) or java-cfenv core (neither) to scope it. Refs #1349. --- docs/framework-java-cfenv.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/framework-java-cfenv.md b/docs/framework-java-cfenv.md index 5e90d9487c..0a94b27e2f 100644 --- a/docs/framework-java-cfenv.md +++ b/docs/framework-java-cfenv.md @@ -25,6 +25,15 @@ The buildpack selects the appropriate `java-cfenv` version based on the detected Tags are printed to standard output by the buildpack detect script +## How it works + +The framework is implemented in `src/java/frameworks/java_cf_env.go`: + +1. **Detect** — activates only when all of these hold: the framework is enabled (see [Configuration](#configuration)); a Spring Boot 3.x or 4.x marker is found (a `spring-boot-{3,4}.*.jar` under `BOOT-INF/lib`, `WEB-INF/lib`, or `lib/`, or a `Spring-Boot-Version: 3.*` / `4.*` entry in `META-INF/MANIFEST.MF`); and the application does not already bundle a `java-cfenv*.jar` (if it does, the buildpack backs off and uses the application's own copy). +2. **Supply** — selects the java-cfenv version from the detected Spring Boot major (Spring Boot 3 → the manifest's `3.x` line, Spring Boot 4 → the `4.x` line) and installs the `java-cfenv-all` jar into the dependency directory. +3. **Finalize** — appends the installed jar to `CLASSPATH` via a `.profile.d/java_cf_env.sh` script, so it is on the application's runtime classpath. +4. **Runtime** — Spring Boot reads the jar's `META-INF/spring.factories`: the `EnvironmentPostProcessor`s map `VCAP_SERVICES` to Spring properties, and `CloudProfileApplicationListener` (in the `java-cfenv-all` module) activates the `cloud` profile when running in Cloud Foundry. + ## Configuration The framework can be disabled via the `JBP_CONFIG_JAVA_CF_ENV` environment variable: @@ -53,3 +62,16 @@ Disable when: - The application handles `VCAP_SERVICES` manually with custom binding logic - The automatic `cloud` profile activation is unwanted - Another service binding library conflicts with `java-cfenv` + +`{enabled: false}` disables the **whole** framework — both the `VCAP_SERVICES` → Spring property mapping and the `cloud` profile activation. There is no option to disable only the `cloud` profile. + +For finer control, bundle a java-cfenv artifact in the application yourself. Because the buildpack backs off whenever a `java-cfenv*.jar` is already present, the app's choice wins: + +| App bundles | Property mapping | `cloud` profile | +|-------------|------------------|-----------------| +| _(nothing — buildpack injects `java-cfenv-all`)_ | yes | yes | +| `java-cfenv-all` | yes | yes (app pins the version) | +| `java-cfenv-boot` | yes | **no** (no `CloudProfileApplicationListener`) | +| `java-cfenv` (core) | **no** (API only) | **no** | + +So an app can include `java-cfenv-boot` to keep property mapping without the `cloud` profile, or the bare `java-cfenv` core to opt out of all automatic behaviour and use the `CfEnv` API directly. From 78a86806eb8129c8ebbfaaced809da249e71a429 Mon Sep 17 00:00:00 2001 From: Peter Paul Bakker Date: Thu, 9 Jul 2026 14:22:50 +0000 Subject: [PATCH 10/10] =?UTF-8?q?docs(cf-env):=20migration=20guide=20?= =?UTF-8?q?=E2=80=94=20disable/scope=20options=20+=204.x=20backwards-compa?= =?UTF-8?q?t=20note?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirror the framework doc's control options (JBP_CONFIG_JAVA_CF_ENV disable; bundle java-cfenv-boot/core to scope behaviour) and note that from java-buildpack 5.0.6 the default java-cfenv-all injection restores 4.x parity for the cloud profile and VCAP_SERVICES property mapping (5.0.0-5.0.5 shipped bare core; see #1349). Refs #1349. --- docs/spring-auto-reconfiguration-migration.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/spring-auto-reconfiguration-migration.md b/docs/spring-auto-reconfiguration-migration.md index 6866e768ee..52e7f4e541 100644 --- a/docs/spring-auto-reconfiguration-migration.md +++ b/docs/spring-auto-reconfiguration-migration.md @@ -20,6 +20,27 @@ This guide provides step-by-step instructions for migrating from the deprecated > Use `SPRING_PROFILES_ACTIVE=cloud` only if `cloud` should be the sole active profile (it > replaces any others). +> **Note — controlling the automatic behaviour** +> +> When the application does not bundle java-cfenv itself, the buildpack injects `java-cfenv-all` +> (property mapping **and** `cloud` profile). To scope this: +> - `cf set-env JBP_CONFIG_JAVA_CF_ENV '{enabled: false}'` (+ `cf restage`) disables the +> **whole** framework — both property mapping and the `cloud` profile. There is no +> `cloud`-profile-only toggle. +> - Because the buildpack backs off when the app already bundles a `java-cfenv*.jar`, bundling your +> own artifact wins: `java-cfenv-boot` = property mapping without the `cloud` profile; +> `java-cfenv` (core) = neither, use the `CfEnv` API directly. +> +> See [Java CfEnv Framework](framework-java-cfenv.md) for details. + +> **Note — backwards compatible with buildpack 4.x (java-buildpack 5.0.6+)** +> +> As of java-buildpack **5.0.6**, the buildpack injects `java-cfenv-all` by default, so the `cloud` +> profile activation and the `VCAP_SERVICES` → Spring property mapping behave the same as under +> java-buildpack 4.x. Apps that relied on either under 4.x keep working after upgrading — no +> application change is required for the `cloud`/VCAP behaviour. (Buildpack 5.0.0–5.0.5 shipped the +> bare `java-cfenv` core module, which activated neither; see #1349.) + --- ## Table of Contents