Updated Branches: refs/heads/trunk bb5d2ce83 -> 40f4a1ab2
docs: Start working on upgrade notes for the upcoming release. Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/40f4a1ab Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/40f4a1ab Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/40f4a1ab Branch: refs/heads/trunk Commit: 40f4a1ab2f094401b8adbe17f7c96297a08d4ca8 Parents: bb5d2ce Author: Tomaz Muraus <[email protected]> Authored: Sun Oct 13 21:22:49 2013 +0200 Committer: Tomaz Muraus <[email protected]> Committed: Sun Oct 13 21:22:49 2013 +0200 ---------------------------------------------------------------------- docs/compute/pricing.rst | 2 + docs/upgrade_notes.rst | 214 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 216 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/libcloud/blob/40f4a1ab/docs/compute/pricing.rst ---------------------------------------------------------------------- diff --git a/docs/compute/pricing.rst b/docs/compute/pricing.rst index 92699f4..61355e2 100644 --- a/docs/compute/pricing.rst +++ b/docs/compute/pricing.rst @@ -35,6 +35,8 @@ a JSON file (``data/pricing.json``) which is bundled with each release. This pricing data is only updated once you install a new release which means it could be out of date. +.. _using-custom-pricing-file: + Using a custom pricing file --------------------------- http://git-wip-us.apache.org/repos/asf/libcloud/blob/40f4a1ab/docs/upgrade_notes.rst ---------------------------------------------------------------------- diff --git a/docs/upgrade_notes.rst b/docs/upgrade_notes.rst index 33144f2..d9cd24e 100644 --- a/docs/upgrade_notes.rst +++ b/docs/upgrade_notes.rst @@ -5,6 +5,220 @@ This page describes how to upgrade from a previous version to a new version which contains backward incompatible or semi-incompatible changes and how to preserve the old behavior when this is possible. +Libcloud 0.14.0 +--------------- + +To make drivers with multiple regions easier to use, one of the big changes in +this version is move away from the old "one class per region" model to a new +single class plus ``region`` argument model. + +More information on how this affects existing drivers and your code can be +found bellow. + +Amazon EC2 compute driver changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Rackspace compute driver changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Rackspace compute driver has moved to single class plus ``region`` argument. As +such, the following provider constants have been deprecated: + +* ``RACKSPACE`` +* ``RACKSPACE_UK`` +* ``RACKSPACE_AU`` +* ``RACKSPACE_NOVA_BETA`` +* ``RACKSPACE_NOVA_DFW`` +* ``RACKSPACE_NOVA_LON`` +* ``RACKSPACE_NOVA_ORD`` + +And replaced with two new constants: + +* ``RACKSPACE`` +* ``RACKSPACE_FIRST_GEN`` + +Besides that, ``RACKSPACE`` provider constant now defaults to next-generation +OpenStack based servers. Previously it defaulted to first generation cloud +servers. + +If you want to preserve old behavior and use first-gen drivers you need to use +``RACKSPACE_FIRST_GEN`` provider constant. + +Old code (connecting to a first gen provider in the US): + +.. sourcecode:: python + + from libcloud.compute.types import Provider + from libcloud.compute.providers import get_driver + + cls = get_driver(Provider.RACKSPACE) + driver = cls('username', 'api_key') + +New code (connecting to a first gen provider in the US): + +.. sourcecode:: python + + from libcloud.compute.types import Provider + from libcloud.compute.providers import get_driver + + cls = get_driver(Provider.RACKSPACE_FIRST_GEN) + driver = cls('username', 'api_key', region='us') + +Old code (connecting to a first gen provider in the US): + +.. sourcecode:: python + + from libcloud.compute.types import Provider + from libcloud.compute.providers import get_driver + + cls = get_driver(Provider.RACKSPACE_UK) + driver = cls('username', 'api_key') + +New code (connecting to a first-gen provider in the US): + +.. sourcecode:: python + + from libcloud.compute.types import Provider + from libcloud.compute.providers import get_driver + + cls = get_driver(Provider.RACKSPACE_FIRST_GEN) + driver = cls('username', 'api_key', region='uk') + +Old code (connection to a next-gen provider using ``ORD`` region) + +.. sourcecode:: python + + from libcloud.compute.types import Provider + from libcloud.compute.providers import get_driver + + cls = get_driver(Provider.RACKSPACE_NOVA_ORD) + driver = cls('username', 'api_key') + +New code (connection to a next-gen provider using ``ORD`` region) + +.. sourcecode:: python + + from libcloud.compute.types import Provider + from libcloud.compute.providers import get_driver + + cls = get_driver(Provider.RACKSPACE) + driver = cls('username', 'api_key', region='ord') + +CloudFiles Storage driver changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``CLOUDFILES_US`` and ``CLOUDFILES_UK`` provider constants have been deprecated +and a new ``CLOUDFILES`` constant has been added. + +User can now use this single constant and specify which region to use by +passing ``region`` argument to the driver constructor. + +Old code: + +.. sourcecode:: python + + from libcloud.storage.types import Provider + from libcloud.storage.providers import get_driver + + cls1 = get_driver(Provider.CLOUDFILES_US) + cls2 = get_driver(Provider.CLOUDFILES_UK) + + driver1 = cls1('username', 'api_key') + driver2 = cls1('username', 'api_key') + +New code: + +.. sourcecode:: python + + from libcloud.compute.types import Provider + from libcloud.compute.providers import get_driver + + cls = get_driver(Provider.CLOUDFILES) + + driver1 = cls1('username', 'api_key', region='dfw') + driver2 = cls1('username', 'api_key', region='lon') + +CloudStack Compute driver changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CloudStack driver received a lot of changes and additions which will make it +more pleasant to use. Backward incompatible changes are listed bellow: + +* ``CloudStackForwardingRule`` class has been renamed to + ``CloudStackIPForwardingRule`` + + +ScriptDeployment and ScriptFileDeployment constructor now takes args argument +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:class:`libcloud.compute.deployment.ScriptDeployment` and +:class:`libcloud.compute.deployment.ScriptFileDeployment` class constructor now +take ``args`` as a second argument. + +Previously this argument was not present and the second argument was ``name``. + +If you have a code which instantiate those classes directly and passes two or +more arguments (not keyword arguments) to the constructor you need to update +it to preserve the old behavior. + +Old code: + +.. sourcecode:: python + + sd = ScriptDeployment('#!/usr/bin/env bash echo "ponies!"', 'ponies.sh') + +New code: + +.. sourcecode:: python + + sd = ScriptDeployment('#!/usr/bin/env bash echo "ponies!"', None, + 'ponies.sh') + +Even better (using keyword arguments): + +.. sourcecode:: python + + sd = ScriptDeployment(script='#!/usr/bin/env bash echo "ponies!"', + name='ponies.sh') + + +Pricing file changes +~~~~~~~~~~~~~~~~~~~~ + +By default this version of Libcloud tries to read pricing data from the +``~/.libcloud/pricing.json`` file. If this file doesn't exist, Libcloud falls +back to the old behavior and the pricing data is read from the pricing bundle +which is shipped with each release. + +For more information, please see :ref:`using-custom-pricing-file` page. + +RecordType ENUM value is now a string +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:class:`libcloud.dns.types.RecordType` ENUM value used be an integer, but from +this version on, it's now a string. This was done to make it simpler and remove +unnecessary indirection. + +If you use `RecordType` class in your code as recommended no changes are +required, but if you use integer values directly, you need to update your +code to use `RecordType` class otherwise it will break. + +OK: + +.. sourcecode:: python + + # ... + record = driver.create_record(name=www, zone=zone, type=RecordType.A, + data='127.0.0.1') + +Not OK: + +.. sourcecode:: python + + # ... + record = driver.create_record(name=www, zone=zone, type=0, + data='127.0.0.1') + Libcloud 0.8 ------------
