pkgcloud

pkgcloud is a standard library for node.js that abstracts away differences among multiple cloud providers.

Getting started
Compute
Storage
- Uploading Files
- Downloading Files
Database
DNS (beta)
Block Storage (beta)
Load Balancers (beta)
Orchestration (beta)
Network (beta)
CDN (beta)
Fine Print
- Installation
- Tests
- Logging
- Code Coverage
- Contribute!
- Roadmap

Getting Started

You can install pkgcloud via npm or add to it to dependencies in your package.json file:

npm install pkgcloud

Currently there are nine service types which are handled by pkgcloud:

Compute
Storage
Database
DNS (beta)
Block Storage (beta)
Load Balancers (beta)
Network (beta)
Orchestration (beta)
CDN (beta)

In our Roadmap, we plan to add support for more services, such as Queueing, Monitoring, and more. Additionally, we plan to implement more providers for the beta services, thus moving them out of beta.

User Agent

By default, all pkgcloud HTTP requests will have a user agent with the library and version: nodejs-pkgcloud/x.y.z where x.y.z is the current version.

You can get this from a client at any time by calling client.getUserAgent();. Some providers may have an additional suffix as a function of the underlying HTTP stacks.

You can also set a custom User Agent prefix:

client.setCustomUserAgent('my-app/1.2.3');

// returns "my-app/1.2.3 nodejs-pkgcloud/1.1.0"
client.getUserAgent();

Basic APIs for pkgcloud

Services provided by pkgcloud are exposed in two ways:

By service type: For example, if you wanted to create an API client to communicate with a compute service you could simply:

  var client = require('pkgcloud').compute.createClient({
    //
    // The name of the provider (e.g. "openstack")
    //
    provider: 'provider-name',

    //
    // ... Provider specific credentials
    //
  });

By provider name: For example, if you knew the name of the provider you wished to communicate with you could do so directly:

  var client = require('pkgcloud').providers.openstack.compute.createClient({
    //
    // ... Provider specific credentials
    //
  });

All API clients exposed by pkgcloud can be instantiated through pkgcloud[serviceType].createClient({ ... }) or pkcloud.providers[provider][serviceType].createClient({ ... }).

Unified Vocabulary

Due to the differences between the vocabulary for each service provider, pkgcloud uses its own unified vocabulary.

Compute: Server, Image, Flavor
Storage: Container, File
DNS: Zone, Record

Note: Unified vocabularies may not yet be defined for beta services.

Supported APIs

Supporting every API for every cloud service provider in Node.js is a huge undertaking, but that is the long-term goal of pkgcloud. Special attention has been made to ensure that each service type has enough providers for a critical mass of portability between providers (i.e. Each service implemented has multiple providers).

If a service does not have at least two providers, it is considered a beta interface; We reserve the right to improve the API as multiple providers will allow generalization to be better determined.

Compute
- Amazon
- Azure
- DigitalOcean
- HP
- Openstack
- Rackspace
Storage
- Amazon
- Azure
- Google
- HP
- Openstack
- Rackspace
Database
- Rackspace
DNS (beta)
- Rackspace
Block Storage (beta)
- Rackspace
- Openstack
Load Balancers (beta)
- Rackspace
Orchestration (beta)
- Openstack
- Rackspace
Network (beta)
- HP
- Openstack
- Rackspace
CDN (beta)
- Openstack
- Rackspace

Compute

The pkgcloud.compute service is designed to make it easy to provision and work with VMs. To get started with a pkgcloud.compute client just create one:

  var client = require('pkgcloud').compute.createClient({
    //
    // The name of the provider (e.g. "openstack")
    //
    provider: 'provider-name',

    //
    // ... Provider specific credentials
    //
  });

Each compute provider takes different credentials to authenticate; these details about each specific provider can be found below:

Each instance of pkgcloud.compute.Client returned from pkgcloud.compute.createClient has a set of uniform APIs:

Server

client.getServers(function (err, servers) { })
client.createServer(options, function (err, server) { })
client.destroyServer(serverId, function (err, server) { })
client.getServer(serverId, function (err, server) { })
client.rebootServer(server, function (err, server) { })

Image

client.getImages(function (err, images) { })
client.getImage(imageId, function (err, image) { })
client.destroyImage(image, function (err, ok) { })
client.createImage(options, function (err, image) { })

Flavor

client.getFlavors(function (err, flavors) { })
client.getFlavor(flavorId, function (err, flavor) { })

Storage

The pkgcloud.storage service is designed to make it easy to upload and download files to various infrastructure providers. Special attention has been paid so that methods are streams and pipe-capable.

To get started with a pkgcloud.storage client just create one:

  var client = require('pkgcloud').storage.createClient({
    //
    // The name of the provider (e.g. "openstack")
    //
    provider: 'provider-name',

    //
    // ... Provider specific credentials
    //
  });

Each storage provider takes different credentials to authenticate; these details about each specific provider can be found below:

Each instance of pkgcloud.storage.Client returned from pkgcloud.storage.createClient has a set of uniform APIs:

Container

client.getContainers(function (err, containers) { })
client.createContainer(options, function (err, container) { })
client.destroyContainer(containerName, function (err) { })
client.getContainer(containerName, function (err, container) { })

File

client.upload(options)
client.download(options, function (err) { })
client.getFiles(container, function (err, files) { })
client.getFile(container, file, function (err, server) { })
client.removeFile(container, file, function (err) { })

Both the .upload(options) and .download(options) have had careful attention paid to make sure they are pipe and stream capable:

Upload a File

  var pkgcloud = require('pkgcloud'),
      fs = require('fs');

  var client = pkgcloud.storage.createClient({ /* ... */ });

  var readStream = fs.createReadStream('a-file.txt');
  var writeStream = client.upload({
    container: 'a-container',
    remote: 'remote-file-name.txt'
  });

  writeStream.on('error', function(err) {
    // handle your error case
  });

  writeStream.on('success', function(file) {

Pkgcloud

Install / Use

README