lab_04.adoc

Lab 4 - Binding to Cloud Foundry Services

The Guestbook 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 a PostgreSQL database.

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 Guestbook should still be running from the end of Lab 3. Visit the application in your browser by hitting the route that was generated by the CLI:

The Guestbook application is currently running with an in-memory database, and isn’t bound to any services. Let’s change that.

The Services Marketplace

There are two ways to discover what services are available on Pivotal Cloud Foundry. 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. When 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 PCF’s Application Manager UI. If you haven’t already, login to it by visiting http://apps.your-system-domain (e.g. https://apps.system.pcfaws.jagapps.co) When on PWS visit this URL isntead 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 MySQL instance. From the CLI, let’s create a 100mb-dev MySQL service instance:

   $ cf create-service p-mysql 100mb-dev guestbook-db
   Creating service instance guestbook-db in org teamno1 / space development as jaguilar...
   OK

2. Next we’ll bind the newly created instance to our guestbook application:

   $ cf bs guestbook guestbook-db
   Binding service guestbook-db to app guestbook in org teamno1 / space development as jaguilar...
   OK
   TIP: Use 'cf restage guestbook' 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 guestbook

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

   System-Provided:
   {
    "VCAP_SERVICES": {
     "p-mysql": [
      {
       "credentials": {
        "hostname": "10.0.16.63",
        "jdbcUrl": "jdbc:mysql://10.0.16.63:3306/cf_9d2d4585_834e_44fb_aa82_f3fdbce6cdcc?user=64JeFkFjrBYIHume\u0026password=R3nPiIjsTK6TwUZq",
        "name": "cf_9d2d4585_834e_44fb_aa82_f3fdbce6cdcc",
        "password": "R3nPiIjsTK6TwUZq",
        "port": 3306,
        "uri": "mysql://64JeFkFjrBYIHume:[email protected]:3306/cf_9d2d4585_834e_44fb_aa82_f3fdbce6cdcc?reconnect=true",
        "username": "64JeFkFjrBYIHume"
       },
       "label": "p-mysql",
       "name": "guestbook-db",
       "plan": "100mb-dev",
       "provider": null,
       "syslog_drain_url": null,
       "tags": [
        "mysql",
        "relational"
       ]
      }
     ]
    }
   }

   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 MySQL that guestbook 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 guestbook

   Once the application is running again, revisit or refresh the browser tab where you have the Guestbook application loaded. Add a few guestbook messages. The application is now utilizing a MySQL database via the guestbook-db service and the data is now persisted in a service bound database instead of in-memory database:

   

5. (OPTIONAL STEPS) You can also take a look at the Guestbook data directly in the database.

   You can do this by connecting your favorite SQL Client to to the guestbook-db Database: Launch your client, create a new server connection and populate the properties with values from the URI in your VCAP_SERVICES environment variable (remember cf env guestbook!)

   Another alternative is to deploy a SQL client like PHPMyAdmin in Cloud Foundry and use it to connect to the MySQL instances. This is specially usefull with locked-down environments where your workstation can’t acces PCF internal network. In order to do this you can clone this Git Repo and follow the instrations there: https://github.com/dmikusa-pivotal/cf-ex-phpmyadmin

---

1. In this case, we could accomplish the same goal by only restarting the application via cf restart guestbook. 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.