In the previous blog post, Cloud Foundry Now Supports Auto-Reconfiguration for Node.js Applications, we saw that Node.js applications deployed to CloudFoundry.com can be automatically reconfigured to connect to Cloud Foundry services. However, there may be situations where you want to opt-out of that feature to have finer control over service connections or to overcome its limitations. In those cases, your applications would be required to parse JSON-formatted environment variables to perform that same function. While this is not overly complex given that JSON is trivial to parse with JavaScript, you will be required to understand the environment variable names and their payload schema. The new cf-runtime module introduced in this blog simplifies this by providing a way to obtain application information and service connection objects. This module moves Cloud Foundry’s Node.js support forward to the match the support for Java and Ruby applications.
Installation
Cf-runtime is available in the npm registry and can be easily installed with the Node Package Manager (npm). Run the following command in the base directory of your Node.js application.
npm install cf-runtime
Usage
This node module provides access to two types of objects. The first is a preconfigured object named CloudApp that contains application information. This includes the application’s host and port configured by Cloud Foundry, list of services bound to the application and their properties.
Additionally, each service that is bound to the application can be accessed via <ServiceName>Client object (i.e. RedisClient, MysqlClient). This object provides a convenient way to obtain the corresponding service connection with just a single function call. You can either create a service connection by the name used to create the service instance or by providing a general service name (e.g. redis or mongo) if there is only one service of this type that is bound to your application. This function may also accept additional parameters depending on the node module it uses (see details below in Service Clients section).
var cf = require('cf-runtime')
var app = cf.CloudApp
// Check if application is running in Cloud Foundry
app.runningInCloud
// Get application properties
app.host
app.port
// Get the list of application service names
app.serviceNames
// Obtain connection properties for single service of type Redis
app.serviceProps.redis
// Obtain connection properties for service named 'redis-service-name'
app.serviceProps['redis-service-name']
// Obtain the list of service names of specific type
app.serviceNamesOfType.redis
// Check if service of the given type is available
cf.RedisClient !== undefined
// Connect to a single service of type Redis
var redisClient = cf.RedisClient.create()
// Connect to redis service named 'redis-service-name'
var redisClient = cf.RedisClient.createFromSvc('redis-service-name')
Service Properties
All services have the following common properties:
- name: specific name of the service
- label: name of service type, for example “redis”, “mysql”
- version: software version of the service type
- host
- port
- username
- password
- url: service connection url
Additionally, PostgreSQL, MySQL and Redis include this service property:
- database: the name of the database that is provided by the service
RabbitMQ provides access to these additional properties:
- vhost: the name of the virtual host
MongoDB provides access to these additional properties:
- db: the database name
Service Clients
The following table shows the available methods and parameters for each service type:
| Node module | Returns | Functions | Parameters |
|---|---|---|---|
| MongoDB | |||
| mongodb | null | cf.MongoClient.create([options], callback) cf.MongoClient.createFromSvc(name, [options], callback) |
name- the name of a service bound to the appoptions- optional {object} non-connection related optionscallback – {function} connection callback |
| MySQL | |||
| mysql | Mysql client instance | cf.MysqlClient.create([options]) cf.MysqlClient.createFromSvc(name, [options]) |
name- the name of a service bound to the appoptions – optional {object} non-connection related options |
| PostgreSQL | |||
| pg | {boolean} | cf.PGClient.create(callback) cf.PGClient.createFromSvc(name, callback) |
name- the name of a service bound to the appcallback – {function} connection callback |
| RabbitMQ | |||
| amqp | AMQP client instance | cf.AMQPClient.create([implOptions]) cf.AMQPClient.createFromSvc(name, [implOptions]) |
name- the name of a service bound to the appimplOptions – optional {object} non-connection related implementation options |
| Redis | |||
| redis | Redis client instance | cf.RedisClient.create([options]) cf.RedisClient.createFromSvc(name, [options]) |
name- the name of a service bound to the appoptions – optional {object} non-connection related options |
Summary
The main purpose of cf-runtime is to make your Node.js applications understand their cloud better, retrieve the environment properties, find the available services, and connect to them easily. If you are writing Node.js applications, cf-runtime just made it easier to deploy your applications to Cloud Foundry.
- Maria Shaldibina
The Cloud Foundry Team
Don’t have a Cloud Foundry account yet? Sign up for free today
