lab_08.adoc

Lab 8 - Binding to Cloud Foundry Services

The Spring Music application was designed to illustrate the ease with which various types of data services can be bound to and utilized by Spring applications running on Cloud Foundry. In this lab, we’ll be binding the application to both PostgreSQL and MongoDB databases.

Cloud Foundry services are managed through two primary types of operations:

Create/Delete

These operations create or delete instances of a service. For a database this could mean creating/deleting a schema in an existing multitenant cluster or creating/deleting a dedicated database cluster.

Bind/Unbind

These operations create or delete unique credential sets for an existing service instance that can then be injected into the environment of an application instance.

A Bit of Review

Your instance of Spring Music should still be running from the end of Lab 7. Visit the application in your browser by hitting the route that was generated by the CLI:

The information dialog in the top right-hand corner indicates that we’re currently running with an in-memory database, and that we’re not bound to any services. Let’s change that.

The Services Marketplace

There are two ways to discover what services are available on Pivotal Web Services. The first is available on any instance of Cloud Foundry: the CLI. Just type:

$ cf marketplace

and you’ll get a list of services, their available plans, and descriptions. On Pivotal Web Services, the “free” tier of plans is normally the first one listed (e.g. turtle for elephansql).

The second way is specific to PWS’s Application Manager UI. If you haven’t already, login to it by visiting http://console.run.pivotal.io.

Click on the “Marketplace” link:

and you’ll see the same service/plan/description listing in the browser:

Creating and Binding to a Service Instance

1. Let’s begin by creating a PostgreSQL instance provided by ElephantSQL. From the CLI, let’s create a free ElephantSQL service instance:

   $ cf create-service elephantsql turtle spring-music-db
   Creating service spring-music-db in org oreilly-class / space instructor as [email protected]...
   OK

2. Next we’ll bind the newly created instance to our spring-music application:

   $ cf bs spring-music spring-music-db
   Binding service spring-music-db to app spring-music in org oreilly-class / space instructor as [email protected]...
   OK
   TIP: Use 'cf restage' to ensure your env variable changes take effect

3. Notice the admonition to Use 'cf restage' to ensure your env variable changes take effect. Let’s take a look at the environment variables for our application to see what’s been done. We can do this by typing:

   $ cf env spring-music

   The subset of the output we’re interested in is located near the very top, titled System-Provided:

   System-Provided:
   {
    "VCAP_SERVICES": { (1)
     "elephantsql": [
      {
       "credentials": {
        "max_conns": "5",
        "uri": "postgres://xnxzdeao:[email protected]:5432/xnxzdeao" (2)
       },
       "label": "elephantsql",
       "name": "spring-music-db",
       "plan": "turtle",
       "tags": [
        "Data Stores",
        "Cloud Databases",
        "Developer Tools",
        "Data Store",
        "postgresql",
        "relational",
        "New Product"
       ]
      }
     ]
    }
   }

   1. VCAP_SERVICES is a special Cloud Foundry environment variable that contains a JSON document containing all of the information for any services bound to an application.

   2. Notice here the unique URI for this instance of PostgreSQL that spring-music has been bound to.

4. Now let’s restage the application, which cycles our application back through the staging/buildpack process before redeploying the application.^[1]

   $ cf restage spring-music

   Once the application is running again, revisit or refresh the browser tab where you have the Spring Music application loaded:

   

   As you can see from the information dialog, the application is now utilizing a PostgreSQL database via the spring-music-db service.

5. Let’s take a direct look at the data in PostgreSQL by utilizing the Manage link in PWS App Manager:

   

6. Click on the Browser link:

   

7. Paste in the query select * from album; and click Execute:

   

Swapping from PostgreSQL to MongoDB

1. Now let’s bind our Spring Music application to MongoDB instead of PostgreSQL. First let’s create ^[2] a MongoDB instance from MongoLab:

   $ cf cs mongolab sandbox spring-music-mongo
   Creating service spring-music-mongo in org oreilly-class / space instructor as [email protected]...
   OK

2. Next we’ll unbind our application from our PostgreSQL instance (Spring Music does not support being bound to multiple datasources at the same time):

   $ cf us spring-music spring-music-db

   If you visit your application now, you’ll see that it still works. If you recall, environment variable changes (such as binding/unbinding of services) don’t actually take effect until a restage or restart.

3. Now let’s bind the application to our MongoDB instance:

   $ cf bs spring-music spring-music-mongo
   Binding service spring-music-mongo to app spring-music in org oreilly-class / space instructor as [email protected]...
   OK
   TIP: Use 'cf restage' to ensure your env variable changes take effect

4. And then do a restage:

   $ cf restage spring-music

   Once the application is running again, revisit or refresh the browser tab where you have the Spring Music application loaded:

   

   As you can see from the information dialog, the application is now utilizing a MongoDB database via the spring-music-mongo service.

5. Let’s take a direct look at the data in MongoDB by utilizing the Manage link in PWS App Manager:

   

   This uses Cloud Foundry service SSO to pass your authentication through to MongoLab’s management UI (you may be asked to authenticate again because your session may have expired with PWS’s login server).

6. Once in MongoLab’s UI, click on your deployment:

   

7. Next, click on your albums collection:

   

8. Now you should be able to see the documents in your collection:

   

Clean Up

Because of the limited PWS quota we have for this course, let’s clean up our application and services to make room for future labs.

1. Delete the spring-music application:

   $ cf d spring-music
   
   Really delete the app spring-music?> y
   Deleting app spring-music in org oreilly-class / space instructor as [email protected]...
   OK

2. Delete the spring-music-mongo service:

   $ cf ds spring-music-mongo
   
   Really delete the service spring-music-mongo?> y
   Deleting service spring-music-mongo in org oreilly-class / space instructor as [email protected]...
   OK

3. Delete the spring-music-db service:

   $ cf ds spring-music-db
   
   Really delete the service spring-music-db?> y
   Deleting service spring-music-db in org oreilly-class / space instructor as [email protected]...
   OK

---

1. In this case, we could accomplish the same goal by only restarting the application via cf restart spring-music. A restage is generally recommended because Cloud Foundry buildpacks also have access to injected environment variables and can install or configure things differently based on their values.

2. Notice in this listing that we’re typing cf cs rather than cf create-service. Most CF CLI commands have a shorthand version to save typing time. You can view these shorthand commands via cf help or cf h (See! More shorthand!).