LATEST VERSION: 1.3 - CHANGELOG
Spring Cloud Services v1.3

Spring Cloud Connectors

Page last updated:

To connect client applications to the Service Registry, Spring Cloud Services uses Spring Cloud Connectors, including the Spring Cloud Cloud Foundry Connector, which discovers services bound to applications running in Cloud Foundry.

Service Detection

The connector inspects Cloud Foundry’s VCAP_SERVICES environment variable, which stores connection and identification information for service instances that are bound to Cloud Foundry applications, to detect available services. Below is an example of a VCAP_SERVICES entry for the Spring Cloud Services Service Registry.

{
 "VCAP_SERVICES": {
  "p-service-registry": [
   {
    "credentials": {
     "access_token_uri": "https://p-spring-cloud-services.uaa.cf.wise.com/oauth/token",
     "client_id": "p-service-registry-57bdc399-5b2e-4131-b941-d0a4275c2da4",
     "client_secret": "GAmFDRU4KGnS",
     "uri": "https://eureka-32fb7386-2d57-4054-91b4-9fd4dcbac221.wise.com"
    },
    "label": "p-service-registry",
    "name": "service-registry",
    "plan": "standard",
    "tags": [
     "eureka",
     "discovery",
     "registry",
     "spring-cloud"
    ]
   }
  ]

For each service in the VCAP_SERVICES variable, the connector considers the following fields:

  • tags: Attributes or names of backing technologies behind the service.
  • label: The service offering’s name (not to be confused with a service instance’s name).
  • credentials.uri: A URI pertaining to the service instance.
  • credentials.uris: URIs pertaining to the service instance.

Service Registry Detection Criteria

To establish availability of the Service Registry, the Spring Cloud Cloud Foundry Connector compares VCAP_SERVICES service entries against the following criteria:

  • tags including eureka

Application Configuration

In a Spring Boot application which is bound to a Service Registry service instance, the connector automatically configures a Spring Cloud Netflix Eureka client configuration bean. The client configuration includes the discovery zone, which is configured using the URL from the service binding; this is equivalent to setting the eureka.client.serviceUrl.defaultZone property.

Eureka Application Name Configuration

A client application registers with the Spring Cloud Services Service Registry using an application name. This value is used by Netflix Eureka to look up instances of an application and to set Eureka’s virtual hostname and secure virtual hostname for the application. In an application that registers with a Spring Cloud Netflix Eureka server, the Eureka application name is by default the value of the application’s spring.application.name property. If the value of the application’s spring.application.name property is used for the Eureka application name and contains one or more characters which are invalid in a hostname, the Spring Cloud Services connector for Service Registry sanitizes that value by using a hyphen (-) to replace each invalid character.

You can register a client application with the Service Registry using an application name that differs from spring.application.name. To do so, you must set the eureka.instance.appname property. If set, this value will be used verbatim for the application’s Eureka application name, virtual hostname, and secure virtual hostname; it therefore must contain only characters which are valid in a hostname.

Examples of values provided for the eureka.instance.appname property, values provided for the spring.application.name property, and the Eureka application names resulting from combinations of these values or from providing a given value for spring.application.name but none for eureka.instance.appname are listed below.

eureka.instance.appname spring.application.name Resultant application name
vhn san vhn
v_hn san v_hn
(not provided) san san
(not provided) s_an s-an
x_y x_y x_y

Application Name Property Restrictions

To identify instances of an application, Netflix Eureka uses three eureka.instance properties: appname, virtualHostName, and secureVirtualHostName. For consistency with Spring Cloud features such as Spring Cloud Netflix Zuul’s automatic routing to registered applications and the load-balanced RestTemplate using Spring Cloud Netflix Ribbon, and to secure ownership of Eureka application names, the Spring Cloud Services Service Registry rejects a registration that includes different non-null values for any of these three properties.

If you set only the spring.application.name property or the eureka.instance.appname property, the Spring Cloud Services connector will set the eureka.instance.virtualHostName and eureka.instance.secureVirtualHostname properties to the same value. If you explicitly set different values for eureka.instance.appname, eureka.instance.virtualHostName, and eureka.instance.secureVirtualHostName, the Spring Cloud Services connector will prevent the application from starting, and you will see an error message in the application logs:

eureka.instance.virtualHostName 'foo' is set to a different value than
eureka.instance.appname 'bar', and is disallowed in Spring Cloud Services.
Try only setting eureka.instance.appname. Please refer to our documentation
and reach out to us if you think you require different values.

Instance-Specific Routing in Ribbon

As of the 1.4.0 release, the Spring Cloud Services Connectors now include the Cloud Foundry application GUID and instance ID in Ribbon request headers when these values are available. This allows Ribbon to specify a particular instance of an application when making a request. In Pivotal Cloud Foundry 1.8 or later, the Gorouter will respect such instance-specific routing decisions as made by Ribbon.

Instance-specific routing is performed by Ribbon in the Spring Cloud Services Connectors automatically. For example, if an application has three instances A, B, and C, and A has a Eureka status other than UP, Ribbon specifies another instance—either B or C—when making a request to that application, and the Gorouter respects this specific choice by Ribbon even if the Gorouter considers A healthy. The application GUID and instance ID metadata included in Ribbon requests can also be used to write custom routing logic in Ribbon clients within applications using the Spring Cloud Services Services Connectors.

See Also

For more information about Spring Cloud Connectors, see the following:

Create a pull request or raise an issue on the source for this page in GitHub