title: Getting started

## Installation ##

Libcloud is [available on PyPi](http://pypi.python.org/pypi/apache-libcloud) and can be installed using pip:

    ::bash
    pip install apache-libcloud

## Upgrading ##

If you used pip to install the library you can also use it to upgrade it:

    ::bash
    pip install --upgrade apache-libcloud

## Documentation ##

Available at [https://libcloud.readthedocs.org/en/latest/](https://libcloud.readthedocs.org/en/latest/).

## Example: Connecting with a Driver ##

    ::python
    from libcloud.compute.types import Provider
    from libcloud.compute.providers import get_driver

    EC2_ACCESS_ID = 'your access id'
    EC2_SECRET_KEY = 'your secret key'

    Driver = get_driver(Provider.EC2)
    conn = Driver(EC2_ACCESS_ID, EC2_SECRET_KEY)

    nodes = conn.list_nodes()
    # [<Node: uuid=..., state=3, public_ip=['1.1.1.1'], provider=EC2 ...>, ...]

## Example: Creating a Node ##

    ::python
    from libcloud.compute.types import Provider
    from libcloud.compute.providers import get_driver

    RACKSPACE_USER = 'your username'
    RACKSPACE_KEY = 'your key'

    Driver = get_driver(Provider.RACKSPACE)
    conn = Driver(RACKSPACE_USER, RACKSPACE_KEY)

    # retrieve available images and sizes
    images = conn.list_images()
    # [<NodeImage: id=3, name=Gentoo 2008.0, driver=Rackspace  ...>, ...]
    sizes = conn.list_sizes()
    # [<NodeSize: id=1, name=256 server, ram=256 ... driver=Rackspace ...>, ...]

    # create node with first image and first size
    node = conn.create_node(name='test', image=images[0], size=sizes[0])
    # <Node: uuid=..., name=test, state=3, public_ip=['1.1.1.1'], provider=Rackspace ...>

## Example: List Nodes Across Multiple Providers ##

The following example will list servers across Amazon EC2, Slicehost, and Rackspace Cloud Servers using the same API call. The servers will be represented in a standard Node object.

    ::python
    from libcloud.compute.types import Provider
    from libcloud.compute.providers import get_driver

    EC2_ACCESS_ID    = 'your access id'
    EC2_SECRET_KEY    = 'your secret key'
    RACKSPACE_USER    = 'your username'
    RACKSPACE_KEY    = 'your key'

    EC2Driver     = get_driver(Provider.EC2)
    RackspaceDriver = get_driver(Provider.RACKSPACE)

    drivers = [EC2Driver(EC2_ACCESS_ID, EC2_SECRET_KEY),
               RackspaceDriver(RACKSPACE_USER, RACKSPACE_KEY)]

    nodes = []
    for driver in drivers:
        nodes += driver.list_nodes()
    print nodes
    # [ <Node: provider=Amazon, status=RUNNING, name=bob, ip=1.2.3.4.5>,
    #   <Node: provider=Slicehost, status=REBOOT, name=korine, ip=6.7.8.9>, ... ]

    # Reboot all nodes named 'test'
    [node.reboot() for node in nodes if node.name == 'test']

## Example: Bootstrapping Puppet on a Node ##

Just creating a node isn't that helpful because each cloud gives you
back nodes in different states. The deploy_node API lets
you do more complex actions in cross-cloud portable manner. It works by
calling create_node, and then SSHing into the node to run a script
or install an SSH Key.

    ::python
    from libcloud.compute.types import Provider
    from libcloud.compute.providers import get_driver
    from libcloud.compute.deployment import MultiStepDeployment, ScriptDeployment, SSHKeyDeployment
    import os

    RACKSPACE_USER = 'your username'
    RACKSPACE_KEY = 'your key'

    Driver = get_driver(Provider.RACKSPACE)
    conn = Driver(RACKSPACE_USER, RACKSPACE_KEY)

    # read your public key in
    # Note: This key will be added to the authorized keys for the root user
    # (/root/.ssh/authorized_keys)
    sd = SSHKeyDeployment(open(os.path.expanduser("~/.ssh/id_rsa.pub")).read())
    # a simple script to install puppet post boot, can be much more complicated.
    script = ScriptDeployment("apt-get -y install puppet")
    # a task that first installs the ssh key, and then runs the script
    msd = MultiStepDeployment([sd, script])

    images = conn.list_images()
    sizes = conn.list_sizes()

    # deploy_node takes the same base keyword arguments as create_node.
    node = conn.deploy_node(name='test', image=images[0], size=sizes[0], deploy=msd)
    # <Node: uuid=..., name=test, state=3, public_ip=['1.1.1.1'], provider=Rackspace ...>
    # the node is now booted, with your ssh key and puppet installed.