❤No Packages Misplaced

    npm

    Sign UpSign In

    pkgcloud
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/pkgcloud package

    2.2.0 • Public • Published

    pkgcloud Build Status NPM version

    Join the chat at https://gitter.im/pkgcloud/pkgcloud

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

    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:

    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.

    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

    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) {
        // success, file will be a File model
      });
     
      readStream.pipe(writeStream);

    Download a File

      var pkgcloud = require('pkgcloud'),
          fs = require('fs');
     
      var client = pkgcloud.storage.createClient({ /* ... */ });
     
      client.download({
        container: 'a-container',
        remote: 'remote-file-name.txt'
      }).pipe(fs.createWriteStream('a-file.txt'));

    Databases

    The pkgcloud.database service is designed to consistently work with a variety of Database-as-a-Service (DBaaS) providers.

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

      var client = require('pkgcloud').database.createClient({
        //
        // The name of the provider (e.g. "openstack")
        //
        provider: 'provider-name',
     
        //
        // ... Provider specific credentials
        //
      });

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

    Due to the various differences in how these DBaaS providers provision databases only a small surface area of the API for instances of pkgcloud.database.Client returned from pkgcloud.database.createClient is consistent across all providers:

    • client.create(options, callback)

    All of the individual methods are documented for each DBaaS provider listed above.

    DNS -- Beta

    Note: DNS is considered Beta until there are multiple providers; presently only Rackspace are supported.

    The pkgcloud.dns service is designed to make it easy to manage DNS zones and records on various infrastructure providers. Special attention has been paid so that methods are streams and pipe-capable.

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

      var client = require('pkgcloud').dns.createClient({
        //
        // The name of the provider (e.g. "rackspace")
        //
        provider: 'provider-name',
     
        //
        // ... Provider specific credentials
        //
      });

    Providers

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

    Zone

    • client.getZones(details, function (err, zones) { })
    • client.getZone(zone, function (err, zone) { })
    • client.createZone(details, function (err, zone) { })
    • client.updateZone(zone, function (err) { })
    • client.deleteZone(zone, function (err) { })

    Record

    • client.getRecords(zone, function (err, records) { })
    • client.getRecord(zone, record, function (err, record) { })
    • client.createRecord(zone, record, function (err, record) { })
    • client.updateRecord(zone, record, function (err, record) { })
    • client.deleteRecord(zone, record, function (err) { })

    Block Storage -- Beta

    Note: Block Storage is considered Beta until there are multiple providers; presently only Openstack and Rackspace are supported.

    The pkgcloud.blockstorage service is designed to make it easy to create and manage block storage volumes and snapshots.

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

      var client = require('pkgcloud').blockstorage.createClient({
        //
        // The name of the provider (e.g. "rackspace")
        //
        provider: 'provider-name',
     
        //
        // ... Provider specific credentials
        //
      });

    Providers

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

    Volume

    • client.getVolumes(options, function (err, volumes) { })
    • client.getVolume(volume, function (err, volume) { })
    • client.createVolume(details, function (err, volume) { })
    • client.updateVolume(volume, function (err, volume) { })
    • client.deleteVolume(volume, function (err) { })

    Snapshot

    • client.getSnapshots(options, function (err, snapshots) { })
    • client.getSnapshot(snapshot, function (err, snapshot) { })
    • client.createSnapshot(details, function (err, snapshot) { })
    • client.updateSnapshot(snapshot, function (err, snapshot) { })
    • client.deleteSnapshot(snapshot, function (err) { })

    Load Balancers -- Beta

    Note: Load Balancers is considered Beta until there are multiple providers; presently only Rackspace are supported.

    The pkgcloud.loadbalancer service is designed to make it easy to create and manage block storage volumes and snapshots.

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

      var client = require('pkgcloud').loadbalancer.createClient({
        //
        // The name of the provider (e.g. "rackspace")
        //
        provider: 'provider-name',
     
        //
        // ... Provider specific credentials
        //
      });

    Providers

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

    LoadBalancers

    • client.getLoadBalancers(options, function (err, loadBalancers) { })
    • client.getLoadBalancer(loadBalancer, function (err, loadBalancer) { })
    • client.createLoadBalancer(details, function (err, loadBalancer) { })
    • client.updateLoadBalancer(loadBalancer, function (err) { })
    • client.deleteLoadBalancer(loadBalancer, function (err) { })

    Nodes

    • client.getNodes(loadBalancer, function (err, nodes) { })
    • client.addNodes(loadBalancer, nodes, function (err, nodes) { })
    • client.updateNode(loadBalancer, node, function (err) { })
    • client.removeNode(loadBalancer, node, function (err) { })

    Network -- Beta

    Note: Network is considered Beta until there are multiple providers; presently only HP & Openstack providers are supported.

    The pkgcloud.network service is designed to make it easy to create and manage networks.

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

      var client = require('pkgcloud').network.createClient({
        //
        // The name of the provider (e.g. "openstack")
        //
        provider: 'provider-name',
     
        //
        // ... Provider specific credentials
        //
      });

    Providers

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

    Networks

    • client.getNetworks(options, function (err, networks) { })
    • client.getNetwork(network, function (err, network) { })
    • client.createNetwork(options, function (err, network) { })
    • client.updateNetwork(network, function (err, network) { })
    • client.deleteNetwork(network, function (err, networkId) { })

    Subnets

    • client.getSubnets(options, function (err, subnets) { })
    • client.getSubnet(subnet, function (err, subnet) { })
    • client.createSubnet(options, function (err, subnet) { })
    • client.updateSubnet(subnet, function (err, subnet) { })
    • client.deleteSubnet(subnet, function (err, subnetId) { })

    Ports

    • client.getPorts(options, function (err, ports) { })
    • client.getPort(port, function (err, port) { })
    • client.createPort(options, function (err, port) { })
    • client.updatePort(port, function (err, port) { })
    • client.deletePort(port, function (err, portId) { })

    Orchestration -- Beta

    Note: Orchestration is considered Beta until there are multiple providers; presently only Openstack are supported.

    The pkgcloud.orchestration service is designed to allow you to access Openstack Heat via node.js. You can manage stacks and resources from within any node.js application.

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

      var client = require('pkgcloud').orchestration.createClient({
        //
        // The name of the provider (e.g. "openstack")
        //
        provider: 'provider-name',
     
        //
        // ... Provider specific credentials
        //
      });

    Providers

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

    Stack

    • client.getStack(stack, function (err, stack) { })
    • client.getStacks(options, function (err, stacks) { })
    • client.createStack(details, function (err, stack) { })
    • client.previewStack(details, function (err, stack) { })
    • client.adoptStack(details, function (err, stack) { })
    • client.updateStack(stack, function (err, stack) { })
    • client.deleteStack(stack, function (err) { })
    • client.abandonStack(stack, function (err, abandonedStack) { })
    • client.getTemplate(stack, function (err, template) { })

    Resources

    • client.getResource(stack, resource, function (err, resource) { })
    • client.getResources(stack, function (err, resources) { })
    • client.getResourceTypes(function (err, resourceTypes) { })
    • client.getResourceSchema(resourceType, function (err, resourceSchema) { })
    • client.getResourceTemplate(resourceType, function (err, resourceTemplate) { })

    Events

    • client.getEvent(stack, resource, eventId, function (err, event) { })
    • client.getEvents(stack, function (err, events) { })
    • client.getResourceEvents(stack, resource, function (err, events) { })

    Templates

    • client.validateTemplate(template, function (err, template) { })

    CDN -- Beta

    Note: CDN is considered Beta until there are multiple providers; presently only Openstack and Rackspace are supported.

    The pkgcloud.cdn service is designed to allow you to access Openstack Poppy via node.js. You can manage services and flavors from within any node.js application.

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

      var client = require('pkgcloud').cdn.createClient({
        //
        // The name of the provider (e.g. "openstack")
        //
        provider: 'provider-name',
     
        //
        // ... Provider specific credentials
        //
      });

    Providers

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

    Base

    • client.getHomeDocument(function (err, homeDocument) { })
    • client.getPing(function (err) { })

    Service

    • client.getService(service, function (err, service) { })
    • client.getServices(options, function (err, services) { })
    • client.createService(details, function (err, service) { })
    • client.updateService(service, function (err, service) { })
    • client.deleteService(service, function (err) { })

    Service Assets

    • client.deleteServiceCachedAssets(service, assetUrl, function(err) { })

    Flavors

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

    Installation

      $ npm install pkgcloud

    Tests

    To run the tests you will need mocha@1.9.x or higher. You may install all the requirements with:

     $ npm install

    Then run the tests:

     $ npm test

    The tests use the hock library for mock up the response of providers, so the tests run without do any connection to the providers, there is a notorius advantage of speed on that, also you can run the tests without Internet connection and also can highlight a change of API just disabling hock.

    Running tests without mocks

    By default the npm test command run the tests enabling hock. And sometimes you will want to test against the live provider, so you need to do this steps, in order to test without mocks.

    1. Copy a provider config file from test/configs/mock to test/configs
    2. Fill in with your own credentials for the provider.
    3. (Optional) The compute test suite run the common tests for all providers listed on test/configs/providers.json, there you can enable or disable providers.
    4. Run the tests using mocha.
    Mocha installed globally
     $ mocha -R spec test/*/*/*-test.js test/*/*/*/*-test.js
     
    Linux/Mac - Mocha installed locally
     $ ./node_modules/.bin/mocha -R spec test/*/*/*-test.js test/*/*/*/*-test.js
     
    Windows - Mocha installed locally:
     $ node_modules\.bin\mocha.cmd -R spec test/*/*/*-test.js test/*/*/*/*-test.js
     

    Other ways to run the tests

    Also you can run the tests directly using mocha with hock enabled:

    Linux/Mac - Mocha installed globally:
     $ MOCK=on mocha -R spec test/*/*/*-test.js test/*/*/*/*-test.js
     
    Linux/Mac - Mocha installed locally:
     $ MOCK=on node_modules/.bin/mocha -R spec test/*/*/*-test.js test/*/*/*/*-test.js
     
    Windows - Mocha installed globally:
     $ set MOCK=on&mocha -R spec test/*/*/*-test.js test/*/*/*/*-test.js
     
    Windows - Mocha installed locally:
     $ set MOCK=on&node_modules\.bin\mocha.cmd -R spec test/*/*/*-test.js test/*/*/*/*-test.js

    Even better, you can run the tests for some specific provider:

    Linux/Mac - Mocha installed globally:
     $ MOCK=on mocha -R spec test/openstack/*/*-test.js
     
    Linux/Mac - Mocha installed locally:
     $ MOCK=on ./node_modules/.bin/mocha -R spec test/openstack/*/*-test.js
     
    Windows - Mocha installed globally:
     $ set MOCK=on&mocha -R spec test/openstack/*/*-test.js
     
    Windows - Mocha installed locally:
     $ set MOCK=on&node_modules\.bin\mocha.cmd -R spec test/openstack/*/*-test.js
     

    Logging

    Any client you create with createClient can emit logging events. If you're interested in more detail from the internals of pkgcloud, you can wire up an event handler for log events.

    var client = pkgcloud.compute.createClient(options);
     
    client.on('log::*', function(message, object) {
      if (object) {
       console.log(this.event.split('::')[1] + ' ' + message);
       console.dir(object);
      }
      else {
        console.log(this.event.split('::')[1]  + ' ' + message);
      }
    });
     

    The valid log events raised are log::debug, log::verbose, log::info, log::warn, and log::error. There is also a more detailed logging example using pkgcloud with Winston.

    Code Coverage

    Run Coverage locally and send to coveralls.io

    Travis takes care of coveralls, so this shouldn't be necessary unless you're troubleshooting a problem with Travis / Coveralls. You'll need to have access to the coveralls repo_token, which should only be visible to pkgcloud/pkgcloud admins.

    1. Create a .coveralls.yml containing the repo_token from https://coveralls.io/r/pkgcloud/pkgcloud
    2. Run the following:
    npm test
npm run coverage

    Contribute!

    We welcome contribution to pkgcloud by any and all individuals or organizations. Before contributing please take a look at the Contribution Guidelines in CONTRIBUTING.md.

    We are pretty flexible about these guidelines, but the closer you follow them the more likely we are to merge your pull-request.

    Author: Charlie Robbins

    Contributors: Ross Kukulinski, Jarrett Cruger, Ken Perkins

    License: MIT

    Keywords

    Install

    npm i pkgcloud

    Repository

    Gitgithub.com/pkgcloud/pkgcloud

    Homepage

    github.com/pkgcloud/pkgcloud#readme

    DownloadsWeekly Downloads

    20,616

    Version

    2.2.0

    License

    none

    Unpacked Size

    886 kB

    Total Files

    321

    Last publish

    Collaborators

    • cronopio
    • indexzero
    • jcrugzz
    • kperkins
    • mmalecki
    • rosskukulinski
    Try on RunKit
    Report malware