Using the Rackspace DNS provider

Zone
- Model
- APIs
Record
- Model
- APIs

Creating a client is straight-forward:

  // Rackspace Cloud DNS is a global service, so no region is required

  var rackspace = pkgcloud.dns.createClient({
    provider: 'rackspace', // required
    username: 'your-user-name', // required
    apiKey: 'your-api-key', // required
    useInternal: false // optional, use to talk to serviceNet from a Rackspace machine
  });

Learn about more options for creating clients in the Rackspace dns provider.

Zone Model

A Zone for Rackspace DNS has following properties:

{
  id: 12345678, // Rackspace ID of your dns zone
  name: 'example.com', // the domain name for the zone
  nameservers: [
    {
      name: 'dns1.stabletransit.com'
    },
    {
      name: 'dns2.stabletransit.com'
    }
  ], // the nameservers for the zone
  emailAddress: 'hostmaster@example.com', // the SOA contact email address
  created: '2013-07-31T16:21:33.000Z',
  updated: '2013-07-31T16:21:33.000Z'
}

Record Model

A Record for Rackspace DNS has the following properties:

{
    id: 'A-12345', // The Rackspace ID for the record
    name: 'www.example.com', // The DNS record
    type: 'A', // The type of record
    ttl: 3600, // TTL of the record, in seconds
    data: '192.168.10.10', // Data for the record
    created: '2013-07-31T16:21:33.000Z',
    updated: '2013-07-31T16:21:33.000Z'
}

Zone APIs

client.getZones(details, function(err, zones) { })
client.getZone(zone, function(err, zone) { })
client.createZone(zone, function(err, zone) { })
client.createZones(zones, function(err, zones) { })
client.importZone(details, function(err, zone) { })
client.exportZone(zone, function(err, result) { })
client.updateZone(zone, function(err) { })
client.updateZones(zones, function(err) { })
client.deleteZone(zone, function(err) { })
client.deleteZones(zones, function(err) { })
client.getZoneChanges(zone, options, function(err, changes) { })
client.cloneZone(zone, options, function(err, zone) { })
client.getSubZones(zone, function(err, zones) { })

Zone API Details

For all of the zone methods that require a zone, you can pass either an instance of a zone or the zone id as zone. For example:

client.getZone(12345678, function(err, zone) { ... });

This call is functionally equivalent to:

var myZone = new Zone({ id: 12345 });

client.getZone(myZone, function(err, zone) { ... });

client.getZones(details, function(err, zones) { })

Retrieves the zones for the current client instance as an array of zone

client.getZone(zone, function(err, zone) { })

Retrieves the specified zone from the current client instance.

client.createZone(zone, function(err, zone) { })

Creates a new zone with attributes from the argument zone:

client.createZone({
 name: 'example.org', // required
 email: 'hostmaster@example.org', // required, contact email for SOA
 ttl: 300, // optional, default ttl in seconds for records on this domain
 comment: 'my domain for examples' // optional comment
 }, function(err, zone) {
  // ...
 })

client.createZones(zones, function(err, zone) { })

Batch creates multiple zones from any array of zones. Each zone should have the same properties as referenced in createZone.

client.createZones([{
 name: 'example.org', // required
 email: 'hostmaster@example.org', // required, contact email for SOA
 ttl: 300, // optional, default ttl in seconds for records on this domain
 comment: 'my domain for examples' // optional comment
 }], function(err, zones) {
  // ...
 })

client.destroyContainer(container, function(err, result) { })

Removes the container from the storage account. If there are any files within the container, they will be deleted before removing the container on the client. result will be true on success.

client.updateContainerMetadata(container, function(err, container) { })

Updates the metadata on the provided container . Currently, the updateContainer method only adds new metadata fields. If you need to remove specific metadata properties, you should call client.removeContainerMetadata(...).

container.metadata.color = 'red';
client.updateContainerMetadata(container, function(err, container) {
  // ...
})

client.removeContainerMetadata(container, metadataToRemove, function(err, container) { })

Removes the keys in the metadataToRemove object from the stored container metadata.

client.removeContainerMetadata(container, { year: false }, function(err, c) {
  // ...
});

File APIs

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

File API Details

For all of the file methods, you can pass either an instance of container or the container name as container. For example:

client.getFile('my-container', 'my-file', function(err, file) { ... });

This call is functionally equivalent to:

var myContainer = new Container({ name: 'my-container' });

client.getFile(myContainer, 'my-file', function(err, file) { ... });

client.upload(options, function(err, result) { })

Returns a writeable stream. Upload a new file to a container. result will be true on success.

To upload a file, you need to provide an options argument:

var options = {
    // required options
    container: 'my-container', // this can be either the name or an instance of container
    remote: 'my-file', // name of the new file

    // optional, either stream or local
    stream: myStream, // any instance of a readable stream
    local: '/path/to/local/file' // a path to any local file

    // Other optional values
    metadata: { // provide any number of property/values for metadata
      campaign: '2012 magazine'
    },
    headers: { // optionally provide raw headers to send to cloud files
      'content-type': 'application/json'
    }
};

You need not provide either stream or local. client.upload returns a writeable stream, so you can simply pipe directly into it from your stream. For example:

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

var client = pkgcloud.providers.rackspace.storage.createClient({ ... });

var myFile = fs.createReadStream('/my/local/file');

myFile.pipe(client.upload({
    container: 'my-container',
    remote: 'my-file'
}, function(err, result) {
    // handle the upload result
}));

You could also upload a local file via the local property on options:

var pkgcloud = require('pkgcloud');

var client = pkgcloud.providers.rackspace.storage.createClient({ ... });

client.upload({
    container: 'my-container',
    remote: 'my-file',
    local: '/path/to/my/file'
}, function(err, result) {
    // handle the upload result
});

This is functionally equivalent to piping from an fs.createReadStream, but has a simplified calling convention.

client.download(options, function(err, file) { })

Returns a readable stream. Download a file from a container.

To download a file, you need to provide an options argument:

var options = {
    // required options
    container: 'my-container', // this can be either the name or an instance of container
    remote: 'my-file', // name of the new file

    // optional, either stream or local
    stream: myStream, // any instance of a writeable stream
    local: '/path/to/local/file' // the path to a local file to write to
};

You need not provide either stream or local. client.download returns a readable stream, so you can simply pipe it into your writeable stream. For example:

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

var client = pkgcloud.providers.rackspace.storage.createClient({ ... });

var myFile = fs.createWriteStream('/my/local/file');

client.download({
    container: 'my-container',
    remote: 'my-file'
}, function(err, result) {
    // handle the download result
})).pipe(myFile);

You could also download to a local file via the local property on options:

var pkgcloud = require('pkgcloud');

var client = pkgcloud.providers.rackspace.storage.createClient({ ... });

client.download({
    container: 'my-container',
    remote: 'my-file',
    local: '/path/to/my/file'
}, function(err, result) {
    // handle the download result
});

This is functionally equivalent to piping from an fs.createWriteStream, but has a simplified calling convention.

client.getFile(container, file, function(err, file) { })

Retrieves the specified file details in the specified container from the current client instance.

client.getFiles(container, function(err, files) { })

Retreives an array of file for the provided container.

client.removeFile(container, file, function(err, result) { })

Removes the provided file from the provided container.

client.updateFileMetadata(container, file, function(err, file) { })

Updates the file metadata in the the provided container.

File metadata is completely replaced with each callt o updateFileMetadata. This is different than container metadata. To delete a property, just remove it from the metadata attribute on the File and call updateFileMetadata.

file.metadata = {
 campaign = '2011 website'
};

client.updateFileMetadata(file.container, file, function(err, file) {
  // ...
});

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!