Migration Guide: Spring Auto-reconfiguration to java-cfenv

July 9, 2026 · View on GitHub

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:

cf set-env <APP> SPRING_PROFILES_INCLUDE cloud   # adds 'cloud' to any existing profiles
cf restage <APP>

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 <APP> 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 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

  1. Why Migrate?
  2. What Changes?
  3. Migration Steps
  4. Service-Specific Migration
  5. Testing Your Migration
  6. Troubleshooting
  7. Rollback Plan

Why Migrate?

Spring Auto-reconfiguration is deprecated and disabled by default as of December 2025 because:

  1. Spring Cloud Connectors (the underlying library) entered maintenance mode in July 2019
  2. No security updates or bug fixes will be provided
  3. Not compatible with Spring Boot 3.x
  4. java-cfenv is the official replacement recommended by Pivotal/VMware

Timeline:

  • July 2019: Spring Cloud Connectors deprecated
  • December 2025: Spring Auto-reconfiguration disabled by default
  • Future: Spring Auto-reconfiguration will be removed entirely

What Changes?

Spring Auto-reconfiguration (Old)

<!-- Automatically added by buildpack - NO CODE CHANGES NEEDED -->
<!-- Automatically reconfigures DataSource, MongoDB, Redis, etc. -->

How it worked:

  • Buildpack injected spring-cloud-cloudfoundry-connector at runtime
  • Automatically replaced Spring beans with Cloud Foundry-bound services
  • No application code changes required

java-cfenv (New)

<!-- Add to your pom.xml -->
<dependency>
    <groupId>io.pivotal.cfenv</groupId>
    <artifactId>java-cfenv-all</artifactId>
    <!-- match your Spring Boot major: 3.5.1 for Spring Boot 3, 4.0.0 for Spring Boot 4 -->
    <version>3.5.1</version>
</dependency>

How it works:

  • You add java-cfenv dependency to your application
  • 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

Migration Steps

Step 1: Verify Your Spring Boot Version

java-cfenv requires Spring Boot 2.1+ (Spring Boot 3.x recommended).

Check your pom.xml or build.gradle:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.0</version> <!-- Must be 2.1+ -->
</parent>

If you're on Spring Boot 1.x: Upgrade to Spring Boot 2.x or 3.x first.

Step 2: Add java-cfenv Dependency

Maven (pom.xml)

<dependencies>
    <!-- Add this dependency (match your Spring Boot major: 3.5.1 for Spring Boot 3, 4.0.0 for Spring Boot 4) -->
    <dependency>
        <groupId>io.pivotal.cfenv</groupId>
        <artifactId>java-cfenv-all</artifactId>
        <version>3.5.1</version>
    </dependency>
</dependencies>

Gradle (build.gradle)

dependencies {
    implementation 'io.pivotal.cfenv:java-cfenv-all:3.5.1' // 4.0.0 for Spring Boot 4
}

Note: Check for the latest version at https://github.com/pivotal-cf/java-cfenv

Step 3: Remove Spring Cloud Connectors (if explicitly added)

If you previously added Spring Cloud Connectors manually, remove them:

Remove from Maven (pom.xml)

<!-- REMOVE THESE if present -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-spring-service-connector</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-cloudfoundry-connector</artifactId>
</dependency>

Remove from Gradle (build.gradle)

// REMOVE THESE if present
implementation 'org.springframework.cloud:spring-cloud-spring-service-connector'
implementation 'org.springframework.cloud:spring-cloud-cloudfoundry-connector'

Step 4: Review Custom Service Configurations

If you have custom @Bean configurations for services, you may need to update them.

Before (Spring Cloud Connectors)

@Configuration
public class CloudConfig extends AbstractCloudConfig {
    
    @Bean
    public DataSource dataSource() {
        return connectionFactory().dataSource();
    }
}

After (java-cfenv)

Option 1: Remove custom configuration (let Spring Boot autoconfigure)

// No configuration needed! 
// java-cfenv sets spring.datasource.url automatically
// Spring Boot autoconfiguration creates DataSource

Option 2: Keep custom configuration, use environment properties

@Configuration
public class DataSourceConfig {
    
    @Bean
    public DataSource dataSource(
        @Value("${spring.datasource.url}") String url,
        @Value("${spring.datasource.username}") String username,
        @Value("${spring.datasource.password}") String password) {
        
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl(url);
        config.setUsername(username);
        config.setPassword(password);
        return new HikariDataSource(config);
    }
}

Step 5: Disable Spring Auto-reconfiguration (if enabled)

If you previously enabled Spring Auto-reconfiguration, remove the environment variable:

# Remove this environment variable
cf unset-env my-app JBP_CONFIG_SPRING_AUTO_RECONFIGURATION

Or ensure your manifest.yml doesn't have:

env:
  # REMOVE THIS LINE
  JBP_CONFIG_SPRING_AUTO_RECONFIGURATION: '{enabled: true}'

Step 6: Update Your Application

# Build your application with the new dependency
./mvnw clean package

# Push to Cloud Foundry
cf push my-app

# Check logs to verify java-cfenv is loaded
cf logs my-app --recent | grep java-cf-env

You should see:

Java Buildpack v1.x.x | https://github.com/cloudfoundry/java-buildpack
-----> Supplying frameworks...
       java-cf-env=3.5.1

Service-Specific Migration

PostgreSQL / MySQL / SQL Server

Spring Auto-reconfiguration (automatic):

  • Automatically created DataSource bean

java-cfenv (automatic):

  • Sets spring.datasource.url, spring.datasource.username, spring.datasource.password
  • Spring Boot autoconfiguration creates DataSource

Migration: No code changes needed! Just add the dependency.

MongoDB

Spring Auto-reconfiguration:

// Automatically created MongoClient bean

java-cfenv:

# Automatically sets:
# spring.data.mongodb.uri=mongodb://...

Migration: No code changes needed! Spring Boot autoconfiguration handles it.

Redis

Spring Auto-reconfiguration:

// Automatically created RedisConnectionFactory bean

java-cfenv:

# Automatically sets:
# spring.data.redis.host=...
# spring.data.redis.port=...
# spring.data.redis.password=...

Migration: No code changes needed!

RabbitMQ

Spring Auto-reconfiguration:

// Automatically created ConnectionFactory bean

java-cfenv:

# Automatically sets:
# spring.rabbitmq.host=...
# spring.rabbitmq.port=...
# spring.rabbitmq.username=...
# spring.rabbitmq.password=...

Migration: No code changes needed!

Custom User-Provided Services

If you're using user-provided services (cf cups), you may need to access them manually.

java-cfenv API:

import io.pivotal.cfenv.core.CfEnv;
import io.pivotal.cfenv.core.CfService;

@Configuration
public class CustomServiceConfig {
    
    @Bean
    public MyCustomService customService() {
        CfEnv cfEnv = new CfEnv();
        CfService service = cfEnv.findServiceByName("my-custom-service");
        
        String url = service.getCredentials().getString("url");
        String apiKey = service.getCredentials().getString("api_key");
        
        return new MyCustomService(url, apiKey);
    }
}

Testing Your Migration

1. Local Testing (without Cloud Foundry)

java-cfenv gracefully handles missing VCAP_SERVICES:

# Run locally - uses application.properties
./mvnw spring-boot:run

Your local application.properties will be used as normal.

2. Cloud Foundry Testing

# Push to CF
cf push my-app

# Check that services are bound
cf services

# Verify environment
cf env my-app | grep VCAP_SERVICES

# Check logs for java-cfenv
cf logs my-app --recent | grep "java-cf-env"

# Test application endpoints
curl https://my-app.example.com/health

3. Verify Service Connections

Add this debug endpoint to verify connections:

@RestController
public class DebugController {
    
    @Autowired
    private DataSource dataSource;
    
    @GetMapping("/debug/datasource")
    public String testDataSource() throws Exception {
        try (Connection conn = dataSource.getConnection()) {
            return "Database connected: " + conn.getMetaData().getURL();
        }
    }
}

Troubleshooting

Issue: "No suitable driver found"

Cause: Missing JDBC driver dependency

Solution: Add the appropriate driver:

<!-- PostgreSQL -->
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
</dependency>

<!-- MySQL -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
</dependency>

Issue: Application can't find services

Cause: Service not bound to application

Solution: Verify service binding:

cf services
cf bind-service my-app my-database
cf restage my-app

Issue: Custom properties not being set

Cause: java-cfenv may not support your service type

Solution: Use the CfEnv API to manually extract credentials:

import io.pivotal.cfenv.core.CfEnv;

@Configuration
public class CustomConfig {
    
    @Bean
    public MyService myService() {
        CfEnv cfEnv = new CfEnv();
        CfService service = cfEnv.findServiceByLabel("my-service-type");
        // Extract credentials manually
        return new MyService(service.getCredentials());
    }
}

Issue: "cloud" profile not active

Cause: The cloud profile is activated by CloudProfileApplicationListener, which ships 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: 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:

cf set-env <APP> SPRING_PROFILES_INCLUDE cloud   # adds 'cloud' to any existing profiles
cf restage <APP>

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

If you encounter issues and need to rollback:

Step 1: Re-enable Spring Auto-reconfiguration

cf set-env my-app JBP_CONFIG_SPRING_AUTO_RECONFIGURATION '{enabled: true}'
cf restage my-app

Step 2: Remove java-cfenv dependency (optional)

You can leave java-cfenv in place - it won't conflict with Spring Auto-reconfiguration.

Step 3: Report Issues

If you encounter migration issues:

  1. Check buildpack logs: cf logs my-app --recent
  2. Report issues to: https://github.com/cloudfoundry/java-buildpack/issues
  3. For java-cfenv issues: https://github.com/pivotal-cf/java-cfenv/issues

Additional Resources

Summary Checklist

  • Verify Spring Boot version (2.1+ required, 3.x recommended)
  • 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
  • Build and test locally
  • Deploy to Cloud Foundry
  • Verify services are connected
  • Test application functionality
  • Monitor logs for errors

Migration complete! Your application now uses the modern, supported java-cfenv library.

If you have questions or issues, please consult the java-cfenv documentation or file an issue on the Java Buildpack repository.