cf-services

cf-services

Simple node package to look up bound services in Cloud Foundry

Background

Cloud Foundry provides an application with the credentials of bound service instances via environment variable VCAP_SERVICES.

Notice that VCAP_SERVICES object uses service names as keys. Since multiple instances of the same service can be bound to one application, the property values are arrays of service bindings. This makes it inconvenient for applications to look up required service bindings in a reliable way.

See this presentation for more details.

Install

npm install --save cf-services

Usage

If you bind a service to your app like this:

cf create-service redis small my-redis
cf bind-service my-app my-redis

You can get this binding in your app like this:

var cfServices = require('cf-services');

var redis = cfServices('my-redis');
// redis = { label: '...', name: 'my-redis', credentials: {...}, ... }

Unfortunately the instance name is rarely known in advance, so you may pass it as a separate environment variable:

cf set-env my-app REDIS_SERVICE_NAME my-redis

Then grab it in your app like this:

var redis = cfServices(process.env.REDIS_SERVICE_NAME);

You can also look up service bindings with matching properties:

var matches = cfServices({ label: 'redis', plan: 'large' });
var redis = matches[i];

or get bindings with a certain tag:

var matches = cfServices({ tags: ['store'] }); 

or use a custom function to filter the bindings:

var matches = cfServices(binding => 
  binding.label === 'redis' || binding.tags.includes('redis')); 

Finally, if called without arguments, it will return all bindings keyed by their names:

var bindings = cfServices();
// bindings = { 'my-redis1': {...}, 'my-redis2': {...}, ... }

Local execution

The ability to test your application locally outside Cloud Foundry is important as it improves turnaround time and hence developer productivity.

One option is to use a tool like dotenv that mocks the process environment. The problem with solutions like this is that they pollute your productive code with code that is used only during testing.

A better approach is to setup the process environment (VCAP_SERVICES) in a similar way to Cloud Foundry. Then it is completely transparent to your app if it is running locally or in Cloud Foundry. You can do this in a shell script or using some tool like fireup which supports multiline environment variables.

API

cfServices([query])

Parses VCAP_SERVICES environment variable and returns matching service bindings.

• if query argument is not provided, returns a flat object of service bindings using instance names as keys
• if query is a string, returns the binding with the same instance name or undefined if there is no match
• if query is an object or function, returns an array of service bindings matching the given query as implemented in _.filter.
• throws an error if VCAP_SERVICES is not defined or its value is not a valid JSON string

Alternatives

Instead of this package, you can use lodash (which you probably already require in your code):

const _ = require('lodash');

var vcapServices = JSON.parse(process.env.VCAP_SERVICES);
var svc = _.keyBy(_.flatMap(vcapServices), 'name');
var redis = svc.redis1;
var postgres = _.filter(svc, {tags: ['sql']})[0];

Actually this is what this package is using internally. So why remember those APIs, when you can just use this simple package.

This package is similar to cfenv but is simpler as it is focused only on service bindings. Also this package provides easy filtering of service bindings powered by lodash filter.

License

MIT

See Also

Proposal for named service bindings