Client dependencies

Here you will find information about the dependencies for client apps using Spring Cloud Services service instances.

What are the client dependencies?

To use a Spring Cloud Services service instance, a client app must be bound to the service instance and must include the necessary client dependencies. Although these are based on dependencies used by client apps with Spring Cloud OSS, you must use the Spring Cloud Services dependencies in your app if you are using Spring Cloud Services. See below for information about the structure and uses of the client dependencies.

Bill Of Materials (BOM) dependencies

The Spring Cloud OSS project encompasses a wide variety of subprojects, each with an independent release cadence. A release of the overall Spring Cloud project is called a release train, and includes particular versions of each of the subprojects. (See the Client Dependency Versioning section below for more information about versioning of the Spring Cloud OSS dependencies.)

Spring Cloud includes a Maven Bill Of Materials (BOM) file for each release train version. This file describes the subproject versions included in the release train. After importing the BOM file, a client app can reference one of the Spring Cloud subprojects without specifying its version, which is provided by the BOM. The subproject versions in the BOM are compatible with each other and represent the subproject releases included in the corresponding release train version.

Spring Cloud Services also includes a Maven BOM file for each version, serving similar purposes. The Spring Cloud Services BOM describes dependencies required for Spring Cloud Services, so that a client app similarly does not need to specify those dependency versions. The Spring Cloud Services BOM may override versions included in the Spring Cloud OSS BOM.

Starter dependencies

A Spring Cloud OSS project can include a library for use by client apps that work with its server component. For example, the Spring Cloud Config project includes a Spring Cloud Config Client library, which reads configuration properties served by a Spring Cloud Config Server server app and creates a Spring PropertySource for them. A Spring Cloud project may also take advantage of other open-source libraries on the client side. For example, the Spring Cloud Config Client library uses the Jackson Project for parsing JSON configuration.

To simplify dependency management for a client app, each Spring Cloud OSS project includes a starter: a maintained set of dependencies used by a client app, packaged in one Maven POM and included in the client app as a single dependency.

Each of the Spring Cloud Services services has a corresponding starter. Similarly to a Spring Cloud OSS project, a Spring Cloud Services starter bundles the dependencies used by a client app to consume the service. These dependencies are similar to those used by the corresponding Spring Cloud OSS project (for example, the Config Server is based on the Spring Cloud Config project), with some differences specific to Spring Cloud Services (for example, Spring Cloud Security OAuth2 is added so that a client app can navigate the security built into Config Server).

Including Spring Cloud Services dependencies

If your app currently uses Spring Cloud OSS components, you must update your app's build file to include the specific dependencies shown below.

To be compatible with Spring Cloud Services (SCS) service instances, a Spring Boot client app can include the following BOMs:

spring-cloud-services-dependencies
spring-cloud-dependencies
spring-boot-dependencies (unless you use the spring-boot-starter-parent or Spring Boot Gradle plug-in)

The SCS client starters use the java-cfenv library.

For important information about using SCS client starters, see Using Spring Cloud Services Starters v3.x and java-cfenv.

See below for compatible versions of the SCS client dependencies, Spring Boot, and Spring Cloud. The SCS client dependencies are backward-compatible and forward-compatible with one minor Spring Cloud version.

SCS Client Starters	Spring Boot	Spring Cloud
4.1.3 (uses java-cfenv)	3.3	2023.0.x
4.1.2 (uses java-cfenv)	3.2	2023.0.x
4.0.5 (uses java-cfenv)	3.1	2022.0.5+
4.0.2 (uses java-cfenv)	3.0	2022.0.x
3.5 (uses java-cfenv)	2.7	2021.0.3+
3.4 (uses java-cfenv)	2.6	2021.0.x
3.3 (uses java-cfenv)	2.5	2020.0.x

Important Config Server client applications should not use Hoxton.* or previous releases of the OSS client, but rather use any of the 2020.* or higher releases to avoid unnecessary health checks against CredHub.

Important Ensure that the ordering of the Maven BOM dependencies listed below is preserved in your app's build file. Dependency resolution is affected in both Maven and Gradle by the order in which dependencies are declared.

If using Maven, include in pom.xml:

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.0</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>

  <dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.pivotal.spring.cloud</groupId>
            <artifactId>spring-cloud-services-dependencies</artifactId>
            <version>4.1.3</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2023.0.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
  </dependencyManagement>

If not using the spring-boot-starter-parent, include in the <dependencyManagement> block of pom.xml:

  <dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.3.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>

        <!-- ... -->

    </dependencies>
  </dependencyManagement>

If using Gradle, you will also need to use the Gradle dependency management plug-in.

Include in build.gradle:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("io.spring.gradle:dependency-management-plugin:1.1.5")
        classpath("org.springframework.boot:spring-boot-gradle-plugin:3.3.0")
    }
}

apply plugin: "java"
apply plugin: "org.springframework.boot"
apply plugin: "io.spring.dependency-management"

dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:2023.0.1"
        mavenBom "io.pivotal.spring.cloud:spring-cloud-services-dependencies:4.1.3"
    }
}

repositories {
    maven {
        url "https://repo.spring.io/plugins-release"
    }
}

If not using the Spring Boot Gradle plug-in, include in the dependencyManagement block of build.gradle:

dependencyManagement {
    imports {
        mavenBom "org.springframework.boot:spring-boot-dependencies:3.3.0"
    }
}

Config Server

Your app must declare spring-cloud-services-starter-config-client as a dependency.

If using Maven, include in pom.xml:

  <dependencies>
    <dependency>
      <groupId>io.pivotal.spring.cloud</groupId>
      <artifactId>spring-cloud-services-starter-config-client</artifactId>
    </dependency>
  </dependencies>

If using Gradle, include in build.gradle:

dependencies {
    compile("io.pivotal.spring.cloud:spring-cloud-services-starter-config-client")
}

The Spring Cloud Services starter for Config Server includes:

The Spring Cloud Config Client library
The Spring Security OAuth2 library

Service Registry

Your app must declare spring-cloud-services-starter-service-registry as a dependency.

If using Maven, include in pom.xml:

  <dependencies>
    <dependency>
      <groupId>io.pivotal.spring.cloud</groupId>
      <artifactId>spring-cloud-services-starter-service-registry</artifactId>
    </dependency>
  </dependencies>

If using Gradle, include in build.gradle:

dependencies {
    compile("io.pivotal.spring.cloud:spring-cloud-services-starter-service-registry")
}

The Spring Cloud Services starter for Service Registry includes:

The Spring Cloud Netflix Eureka Client starter
The Jersey Client libraries
The Spring Security OAuth2 library

Using Spring Cloud Services Starters v3.x and java-cfenv

The Spring Cloud Services starters v3.0 and later use the java-cfenv library instead of Spring Cloud Connectors (which is used by the SCS client starters v2.2 and earlier). java-cfenv and Spring Cloud Connectors are incompatible libraries, so if you use the SCS starters v3.0 or later in your app, you must use java-cfenv (and not use Spring Cloud Connectors) throughout your app.

Because the Cloud Foundry Java buildpack (the JBP) includes Spring Cloud Connectors by default, if you use the SCS starters v3.0 or later in your app, you must also deactivate the JBP auto-reconfiguration feature. You can do this by setting a JBP_CONFIG_SPRING_AUTO_RECONFIGURATION environment variable on the app, as in the following Cloud Foundry Command Line Interface tool (cf CLI) command:

$ cf set-env <APP> JBP_CONFIG_SPRING_AUTO_RECONFIGURATION '{enabled: false}'

Or you can set the environment variable in your app's manifest.yml file:

env:
 SPRING_PROFILES_ACTIVE: cloud
 JBP_CONFIG_SPRING_AUTO_RECONFIGURATION: '{enabled: false}'

Client dependency versioning

A release of the Spring Cloud Services client dependencies follows a release of the underlying open-source Spring Cloud components, which are based on particular releases of Spring Boot. For more information about the basis of Spring Cloud or Spring Cloud Services library releases, see below.

Spring Cloud OSS releases

Each Spring Cloud major release is named after a London Underground station (as in "Spring Cloud Camden.RELEASE"). Minor releases are known as service releases and are designated SR[n] (as in "Spring Cloud Camden.SR7"), where [n] is the minor release number.

A given major release of Spring Cloud supports the current Spring Boot minor release and one Spring Boot minor release following. When a new Spring Boot major release is published, it will be supported only in the next major release of Spring Cloud. (The Spring Boot 2.0 release follows the Spring Boot 1.5 release; there was no 1.6 release.)

Spring Cloud Release	Supported Spring Boot Release
2023.0.x	3.3
2023.0.x	3.2
2022.0.5+	3.1
2022.0.x	3.0
2021.0.3+	2.6/2.7
2021.0.x	2.6
2020.0.x	2.4/2.5
Hoxton	2.2/2.3
Greenwich	2.1
Finchley	2.0
Edgware	1.5

Spring Cloud Services client releases

The Spring Cloud Services connectors, as well as the starters dependencies that include the connectors, are versioned and released independently of the Spring Cloud Services tile. The connectors and starters are based on the open-source Spring Cloud client libraries for Config Server and Spring Cloud Netflix Eureka, and have a new release to follow each Spring Cloud release that affects these components.

A given minor release of the Spring Cloud Services starters uses a particular release of Spring Cloud.

Spring Cloud Services Starters Release	Underlying Spring Cloud Release
4.1	2023.0.x
4.0	2022.0.x
3.5	2021.0.3+
3.4	2021.0.x
3.3	2020.0.x
3.2	2020.0.x
3.1	Hoxton.RELEASE
3.0	Greenwich.SR4
2.4	2020.0.x
2.3	Hoxton.RELEASE
2.2	Hoxton.RELEASE
2.1	Greenwich.RELEASE
2.0	Finchley.RELEASE

Spring Cloud Services tile releases

The Spring Cloud Services tile is versioned and released independently of the Spring Cloud Services connectors and starters. The tile contains the server-side components from Spring Cloud for Config Server and Spring Cloud Netflix Eureka, and typically has a new release following each Spring Cloud service release that affects these components.

A given minor release of the tile includes server-side components from a particular release of Spring Cloud, typically the last stable release. The Spring Cloud Services v3.1 tile is based on Spring Cloud Greenwich.