Integration with Cloud Foundry

For this lab, we will use Pivotal Web Services (PWS), a public installation of PCF. The first thing we need is an account.

You should end up at a screen that resembles the following:

Orgs contain spaces. Initially no spaces may exist in your newly-created org. If so, create yourself a space: click the "Add a space" button, name it dev or development. Drill in to your space by clicking anywhere in the area representing it.

Applications are deployed to PCF with the cf Command Line Interface (the cf CLI, for short).

Verify whether the cf cli is already installed on your machine with the following command:

If you get a reply with a specific version number, you should be all set. If not, then your next step is to download and install the CLI.

➜ In the navigation panel on the left hand side, click on the link labeled Tools.

The tools page has a simple download link, along with instructions for logging in.

➜ Download the cf cli. After download, proceed to locate the downloaded file, and run the installer.

Open a terminal, and log in to PWS from the command line:

➜ Type cf login

You’ll be prompted to enter three pieces of information:

We could at this point deploy the demo application with a single command. But let’s do this formally, by writing a deployment manifest.

PCF deployment manifests are written in YAML, have the conventional name manifest.yml, and typically reside in the base directory of your application or project. To learn more about the deployment manifest format and the many options supported, see https://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html

➜ Create the file manifest.yml in the base directory of your project, and compose the manifest.

Here’s an example:

The contents of the file are relatively easy to understand. We specify:

➜ In a terminal, navigate to the demo application’s base directory, build your application (to ensure you have a jar file to deploy), and enter the command cf push:

Observe the console output as the application is uploaded and deployed to PCF. After the application is deployed, make note of its url. Back in the apps manager web UI, navigate to your space and click on the tab named Apps. The demo application should appear in the listing, in the running state.

➜ In the instances area on the right hand side, click on the [one and only] instance row to expand it:

PCF monitors the health of the application via the health endpoint.

Click on the tab labeled Settings. Scroll down a little to the Spring Info section:

Click on the button "View raw JSON". The dialog displays the contents of the /info endpoint (build number, git sha-1, etc..)

Click on the tab labeled Logs. Not only can we view the logs, but we can configure the logging levels via the /loggers actuator endpoint:

Note how the ROOT logger is set to INFO and the logger for the com.example package is at DEBUG, per the application’s initial configuration.

The Threads tab gives us a rich view of running threads as well as a button to obtain a thread dump:

Click the View App button in the upper right-hand corner, and visit the application’s endpoints: /hello, /todos, /api/todos, /api/todos/1.

In the Apps Manager, click on the tab labeled Trace, where you’ll find a listing of recent HTTP requests (you may need to click the "REFRESH" button):

All of the above are custom integrations for Spring Boot. To find out more about these integrations, see these sections of the PCF reference guide:

Review the service marketplace in PWS for a service that provisions instances of mysql:

Here’s the output:

On that list is a service named cleardb which fits our needs.

Create a mysql instance in the cloud with the following command:

We now have a mysql database.

In Cloudfoundry, the process of attaching an application to a backing service such as a database is called binding.

We can bind this database to our demo application by specifying it in the manifest file under services, like so:

Our application running in Cloudfoundry will no longer read the mysql connection information from the application.yml file. This information will now come from an environment variable. And so, technically we don’t need to bother to even set the application’s active profile to mysql.

But we are missing one configuration property: spring.jpa.generate-ddl. We need to set that to property so that when the application starts up, it will create the necessary tables. That setting can also be applied in the manifest, as an environment variable, like this:

We’re now ready to effect the switch over to mysql:

➜ Redeploy the application

One simple way to test that we’re no longer using an in-memory database is to:

With an in-memory database, the Todo we just created would not have survived a restart.

Another way is to use the cf mysql plugin to connect directly to the database and inspect the contents of the todo table.

Binding the todos_db service to the application had the effect of populating an environment variable named VCAP_SERVICES. We can inspect it with this command:

So the information that the application needs to setup its database connection is right there, in the form of a JSON block that can be read, parsed, and used.

If you recall, When we deployed the application locally, we configured the datasource parameters through the application.yml file:

When running in PCF, this information is not applicable. Instead of the above, Spring Boot uses the information from VCAP_SERVICES.

But how does the application know whether it’s running locally on in the cloud?

➜ Visit your application’s actuator environment endpoint (/actuator/env) in cloud foundry:

The list of active profiles shows that when the application runs in Cloudfoundry, the cloud profile is added to the list.

To understand how the application obtained this additional profile, we have to understand how the application is deployed.

Here is a screenshot of some of the console output when we ran cf push:

See the line that says "Downloading Spring Auto Reconfiguration.."?

The Java buildpack (the mechanism that assists with the deployment of the application) detects that we’re pushing a Spring Boot application, and so it bundles an extra library, known as the auto-reconfiguration lilbrary. This library ends up in the classpath of our application, and, as its name implies, it reconfigures the application.

It is this code that adds the cloud profile, but it goes a step further: it transitively pulls in another library named the Spring Cloud Connectors, which looks for and parses the VCAP_SERVICES environment variable. The reconfiguration library then replaces the DataSource bean with one configured from this information.

The net effect is an application that, without modification, will "just work" both locally and in the cloud.