Getting Started with Spring Cloud Services on Pivotal Application Service

When it comes to creating a robust and resilient cloud-based microservices architecture, Spring Cloud/Netflix OSS components are known and respected enablers. Certain patterns and mechanisms have proven absolutely essential to achieving both high development velocity and high production availability, and Spring Cloud/Netflix OSS has some of the "best of the best".

PAS provides key components from Spring Cloud/Netflix OSS as easily-consumable services via its Marketplace, available from both the PAS Apps Manager and the Cloud Foundry Command Line Interface (CF CLI). These components are particularly useful when deployed, managed, scaled, and secured by PAS:

• Spring Cloud Services Config Server: externalizes your distributed system’s configuration settings a la Spring Cloud Config
• Spring Cloud Services Service Registry: provides a directory for all instances of all of your microservices to "see & be seen" by each other, a la Spring Cloud Netflix Eureka
• Spring Cloud Services Circuit Breaker Dashboard: visual monitor of inter-service "circuits" that shows request stats and circuit status (closed, open, half-open) a la Spring Cloud Netflix Hystrix Dashboard

For this post, I’ll show you how to quickly stand up these services in your PAS environment. Some basic assumptions will help us distill this article to its essence:

1. You’re already familiar with the Spring Cloud/Netflix OSS services upon which these components are based. If not, please reference that material first. Useful references are provided at the end of this article to help get you started.

2. Security is essential for your production-deployed systems, and these services are no exception. For this article, however, we’ll concentrate specifically and solely upon the services themselves and how first to get them working in your non-production environment.

3. Per point 1 above, if you’re already familiar with and using Spring Cloud Config, you likely already have a git repository that can provide your microservices with their required and expected configuration settings. This same repository can be used by SCS Config Server as long as it is reachable by https or ssl. For this article, I point to a repository of service configuration files on Github using https, but for all options available to you, please refer to the SCS documentation linked at the end of this article.

4. You are connected to a PCF/PAS API endpoint, your cloud admins have exposed the above listed services via the marketplace, and you have the appropriate permissions to enable them.

5. Not so much an assumption as a statement: I prefer the command line to graphical interfaces for most activities that can be performed with either, so I’ll be using the CF CLI for most actions. That said, the PAS Apps Manager interface is extremely clean and useful, so I’ll use it when I feel it provides better clarity. But please, do what works best for you.

With that, let’s get started!

The Microservices, Part I

To demonstrate how these SCS services work and support our microservices, we of course need some microservices. We’ll create a backing microservice (providing persistence and domain-specific business logic) and an edge microservice (to provide an outward-facing API for our remotely-deployed client applications).

For this article, I’ve created a backing microservice called coffee-service and an edge microservice called, well, edge-service. The coffee-service exposes a catalog of currently-available coffees, individual coffee details, and an endpoint called /coffees/random that will provide a randomly-chosen coffee upon request.

The edge-service exposes an endpoint called /surpriseme for use by baristas using downstream client applications (web, iOS, Android) to select a random coffee at a customer’s request.

To SCS-enable our application microservices, we must make a few minor changes to them.

coffee-service

Main application class

Be sure to add the @EnableDiscoveryClient annotation to the main application class declaration so coffee-service will register with and poll the Eureka service registry.

bootstrap.properties

spring.application.name=coffee-service

manifest.yml

Create a file called manifest.yml and add it to the Spring Boot project’s root directory for consistent, declarative PAS deployment using cf push. Here are its contents:

Dependencies

To ensure proper interoperation of microservices deployed to PAS and the SCS components, a bit of care must be taken to match versions of libraries used for Spring Boot, Spring Cloud, and SCS. This link provides concise guidance on which versions to select.

Once you’ve arrived at the correct versions, adding SCS capabilities to your microservices is fairly easy. I followed the information at the link above, with a few minor variations. Here are the steps I took for quick setup and longer-term maintainability.

Firstly, I created another property in coffee-service’s pom.xml for spring-cloud-services.version to correspond with the existing spring-cloud.version, using the matching entries in the client dependencies tables.

<properties>

  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

  <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

  <java.version>1.8</java.version>

  <spring-cloud-services.version>1.6.0.RELEASE</spring-cloud-services.version>

  <spring-cloud.version>Edgware.SR2</spring-cloud.version>

</properties>

Secondly, I added config-client and service-registry client libraries under Maven’s <dependencies> section.

<dependency>

  <groupId>io.pivotal.spring.cloud</groupId>

  <artifactId>spring-cloud-services-starter-config-client</artifactId>

</dependency>

<dependency>

  <groupId>io.pivotal.spring.cloud</groupId>

  <artifactId>spring-cloud-services-starter-service-registry</artifactId>

</dependency>

Thirdly, I added the appropriate dependencies under Maven’s <dependencyManagement> section, referencing the spring-cloud-services.version property created above.

<dependency>

  <groupId>io.pivotal.spring.cloud</groupId>

  <artifactId>spring-cloud-services-dependencies</artifactId>

  <version>${spring-cloud-services.version}</version>

  <type>pom</type>

  <scope>import</scope>

</dependency>

edge-service

Main application class

Be sure to add both @EnableCircuitBreaker and @EnableDiscoveryClient annotations to the main application class declaration so edge-service will register with and poll the Eureka service registry and support Hystrix circuit breakers.

bootstrap.properties

spring.application.name=edge-service

NOTE: For our non-production environment (please see assumptions above!), we disable HTTP basic security and Actuator management endpoint security (if using Spring Boot Actuator). As with the coffee-service, properties that do so are security.basic.enabled and management.security.enabled and are set to false in the edge-service’s properties obtained from the SCS Config Server.

manifest.yml

Create a file called manifest.yml and add it to the Spring Boot project’s root directory for consistent, declarative PAS deployment using cf push. Here are the contents:

Dependencies

As with coffee-service, I created another property in edge-service’s pom.xml for spring-cloud-services.version to correspond with the existing spring-cloud.version.

<properties>

    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

    <java.version>1.8</java.version>

    <spring-cloud-services.version>1.6.0.RELEASE</spring-cloud-services.version>

    <spring-cloud.version>Edgware.SR2</spring-cloud.version>

</properties>

Secondly, I added config-client, service-registry, and circuit-breaker client libraries to Maven’s <dependencies> section.

<dependency>

  <groupId>io.pivotal.spring.cloud</groupId>

  <artifactId>spring-cloud-services-starter-config-client</artifactId>

</dependency>

<dependency>

  <groupId>io.pivotal.spring.cloud</groupId>

  <artifactId>spring-cloud-services-starter-service-registry</artifactId>

</dependency>

<dependency>

  <groupId>io.pivotal.spring.cloud</groupId>

  <artifactId>spring-cloud-services-starter-circuit-breaker</artifactId>

</dependency>

Thirdly, I added the appropriate dependencies under Maven’s <dependencyManagement> section, referencing the spring-cloud-services.version property created above.

<dependency>

  <groupId>io.pivotal.spring.cloud</groupId>

  <artifactId>spring-cloud-services-dependencies</artifactId>

  <version>${spring-cloud-services.version}</version>

  <type>pom</type>

  <scope>import</scope>

</dependency>

Both microservices

Finally, I built both projects using mvn clean package and did a cf push --no-start to PAS. We’ll use the --no-start flag to upload the microservices, but not run them, pending their connection to the SCS services.

This is as far as we can go for now. Next, we must create those SCS services we plan to use with our microservices.

The Marketplace

Each service that is made available to you via the PAS Marketplace may have one or more plans from which to choose. These are displayed in the Apps Manager Marketplace by selecting the desired service and opening its information page, or from the CF CLI by typing cf marketplace, or simply cf m.

Apps Manager Marketplace listing

CF CLI Marketplace listing

For each service you wish to enable from the PAS Marketplace, you must determine which plan to choose. For services with only one plan (at least the only one that is exposed to you by your PAS instance and/or cloud admins), this is easy: choose the plan. 🙂

For more information about a particular Marketplace service, this CF CLI command is helpful:

Spring Cloud Services: Config Server

To stand up the SCS Config Server, you really only need two things: your CF CLI and a suitable repository of configuration files with settings for your desired microservices. To connect the two, here is the command you’ll enter from the CF CLI (with appropriate changes to SERVICE_INSTANCE name and repository uri, of course):

Let’s unpack this a bit.

cf is the CF CLI utility

cs is the command to "create service".

p-config-server is the service name exposed via the Marketplace for the SCS Config Server.

standard is the plan we’re choosing.

config-service is the name I assigned to the service instance I’m creating. Feel free to choose a name that fits your tastes and/or naming standards.

-c is followed by a JSON object containing configuration parameters. In this case, our git object contains properties for a uri (pointing to an accessible git repository, in this example one hosted on Github) and the appropriate label (here, "master")

Once we’ve issued the command, typing cf s from the command line shows a list of our currently-active services. Of particular note is the column titled "last operation", which will show "create succeeded" for the Config Server once it is ready for use.

Spring Cloud Services: Service Registry

To create and configure the SCS Service Registry, simply run the following command from the CF CLI (with your choice of SERVICE_INSTANCE name, of course):

To view the SCS Service Registry Dashboard, navigate to the dashboard link provided as a result of running the command cf service eureka-service (or by selecting "Manage" from the SCS Service Registry page in Apps Manager).

NOTE: Our two microservices, coffee-service and edge-service haven’t yet been bound to the registry and, indeed, are not even running at this point, so they won’t (yet) appear here.

Spring Cloud Services: Circuit Breaker Dashboard

To enable the Spring Cloud Netflix Hystrix Dashboard to run as an SCS component, simply execute the following command from the CF CLI, changing the SERVICE_INSTANCE name as desired:

To view the SCS Circuit Breaker Dashboard, navigate to the dashboard link provided as a result of running the command cf service hystrix-dashboard (or by selecting "Manage" from the SCS Circuit Breaker Dashboard page in Apps Manager).

NOTE: Our two microservices, coffee-service and edge-service are not yet running, so there are currently no active circuits to monitor.

The Microservices, Part II

Now that we have microservices deployed to PAS and SCS configured to support them, the last step is to make the necessary connections.

cf bind-service

In order for our microservices to use services we create in PAS, we need to bind our applications to the appropriate services. This is easily done with the cf bind-service command or its handier (but somewhat unfortunate shortened) form, cf bs. 🙂

Since we have two microservices and some SCS services to which to bind each of them, we must issue the following commands:

Restarting our microservices

The response messages we receive when we issue the above commands indicates that we must restage both microservices for changes to take effect, but since we deployed our microservices using the --no-start flag, we actually need to restart our applications to fully configure and create the container:

Our microservices should now be up and running, relying upon SCS to provide essential scaffolding for our distributed system. Let’s verify, just to be certain.

First, we’ll check our Service Registry.

We can check the health and status of both microservices by navigating endpoints exposed by Spring Boot Actuator, which we included in both projects and exposed via properties supplied to each via the SCS Config Server. To do so, we access the /actuator endpoint from each application’s uri, as in the following example with coffee-service:

We can, of course, navigate coffee-service’s API endpoints we created as well: /coffees, /coffees/{id}, and /coffees/random. For now, let’s skip ahead to test our edge-service’s /surpriseme endpoint, which of course accesses coffee-service’s /coffees/random endpoint and offers us a quick way to test both microservices at once:

It works (of course)! Now that we have traffic, we should be able to monitor our circuit via the SCS Circuit Breaker Dashboard:

There is more (of course!), but we’ll leave further discussions for future updates.

Summary

Spring Cloud/Netflix OSS components provide a solid foundation for creating a robust and resilient cloud-based microservices architecture, and Pivotal Application Services makes it easy to create and configure these critical enablers as platform-managed services. In this article, we created some domain microservices and then connected them via three key enablers:

• SCS Config Server for supplying configuration settings to our domain microservices.

• SCS Service Registry to serve as a directory for all instances of our microservices.

• SCS Circuit Breaker Dashboard to provide monitoring capabilities for "circuits" formed among our microservices

Spring Cloud/Netflix OSS components are powerful tools that support countless mission-critical distributed systems; they’re even more powerful when deployed, managed, scaled, and secured by PAS.

Stay tuned (and follow me on Twitter) for future updates!

Start building microservices with Spring Cloud Services and Pivotal Web Services. Sign-up for a free trial today!

Useful reference links

Spring Cloud Services home

Pivotal documentation (including PCF/PAS)

Cloud Foundry documentation

Spring docs

Spring Cloud docs

Meta repository for config and domain microservices