|
|
@@ -1,82 +1,102 @@
|
|
|
Getting Started
|
|
|
===============
|
|
|
+This getting started guide will provide a quick tour of some Cloudbridge
|
|
|
+features. For more details on individual features, see the
|
|
|
+`Using Cloudbridge <topics/overview.html>`_ section or the
|
|
|
+`API reference <api_docs/ref.html>`_.
|
|
|
|
|
|
-This getting started guide will provide a quick tour of some cloud bridge
|
|
|
-features. You should reach the conceptual structure section to get a quick
|
|
|
-idea of the main types of objects that cloudbridge provides.
|
|
|
+Installation
|
|
|
+------------
|
|
|
+Cloudbridge is available on PyPI so to install the latest available version,
|
|
|
+run::
|
|
|
|
|
|
-Creating a provider
|
|
|
--------------------
|
|
|
-
|
|
|
-To initialize a connection to a cloud and get a provider object, you will
|
|
|
-need to provide the cloud's access credentials to cloudbridge. These may
|
|
|
-be provided in one of two ways.
|
|
|
-
|
|
|
-1. Environment variables
|
|
|
-2. A dictionary
|
|
|
-
|
|
|
-Providing access credentials through environment variables
|
|
|
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
+ pip install cloudbridge
|
|
|
|
|
|
-When initializing a provider through environment variables, you can
|
|
|
-create a connection as follows.
|
|
|
+Create a provider
|
|
|
+-----------------
|
|
|
+To start, you will need to create a reference to a provider object. The
|
|
|
+provider object idetifies the cloud you want to work with and supplies your
|
|
|
+credentials. In this code snippet, we will be using AWS. For the details on
|
|
|
+other providers, take a look at the `Setup page <topics/setup.html>`_.
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
- from cloudbridge.cloud.factory import CloudProviderFactory, ProviderList
|
|
|
-
|
|
|
- provider = CloudProviderFactory().create_provider(ProviderList.OPENSTACK, {})
|
|
|
-
|
|
|
-The following environment variables must be set, depending on the provider in use.
|
|
|
-
|
|
|
-**Amazon**
|
|
|
+ from cloudbridge.cloud.factory import CloudProviderFactory, ProviderList
|
|
|
|
|
|
-*Mandatory variables*::
|
|
|
+ config = {'aws_access_key': 'AKIAJW2XCYO4AF55XFEQ',
|
|
|
+ 'aws_secret_key': 'duBG5EHH5eD9H/wgqF+nNKB1xRjISTVs9L/EsTWA'}
|
|
|
+ provider = CloudProviderFactory().create_provider(ProviderList.AWS, config)
|
|
|
|
|
|
- AWS_ACCESS_KEY
|
|
|
- AWS_SECRET_KEY
|
|
|
-
|
|
|
-**Openstack**
|
|
|
+List some resources
|
|
|
+-------------------
|
|
|
+Once you have a reference to a provider, explore the cloud platform:
|
|
|
|
|
|
-*Mandatory variables*::
|
|
|
+.. code-block:: python
|
|
|
|
|
|
- OS_AUTH_URL
|
|
|
- OS_USERNAME
|
|
|
- OS_PASSWORD
|
|
|
- OS_TENANT_NAME
|
|
|
- OS_REGION_NAME
|
|
|
+ provider.compute.images.list()
|
|
|
+ provider.security.security_groups.list()
|
|
|
+ provider.block_store.snapshots.list()
|
|
|
+ provider.object_store.list()
|
|
|
|
|
|
-*Optional variables*::
|
|
|
+This will demonstrate the fact the library was properly installed and your
|
|
|
+provider object is setup corectly but it is not very interesting. Hence, let's
|
|
|
+create a new instance we can ssh into using a key pair.
|
|
|
|
|
|
- NOVA_SERVICE_NAME
|
|
|
- OS_COMPUTE_API_VERSION
|
|
|
- OS_VOLUME_API_VERSION
|
|
|
+Create a key pair
|
|
|
+-----------------
|
|
|
+We'll create a new key pair and save the private portion of the key to a file
|
|
|
+on disc as a read-only file.
|
|
|
|
|
|
+.. code-block:: python
|
|
|
|
|
|
-Providing access credentials through a dictionary
|
|
|
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
+ kp = provider.security.key_pairs.create('cloudbridge_intro')
|
|
|
+ with open('cloudbridge_intro.pem', 'w') as f:
|
|
|
+ f.write(kp.material)
|
|
|
+ import os
|
|
|
+ os.chmod('cloudbridge_intro.pem', 0400)
|
|
|
|
|
|
-You can initialize a simple config as follows. The key names are the same
|
|
|
-as the environment variables, in lower case. Note that the config dictionary
|
|
|
-will override environment values.
|
|
|
+Create a security group
|
|
|
+-----------------------
|
|
|
+Next, we need to create a security group and add a rule to allow ssh access.
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
- from cloudbridge.cloud.factory import CloudProviderFactory, ProviderList
|
|
|
+ sg = provider.security.security_groups.create(
|
|
|
+ 'cloudbridge_intro', 'A security group used by Cloudbridge')
|
|
|
+ sg.add_rule('tcp', 22, 22, '0.0.0.0/0')
|
|
|
|
|
|
- config = {'aws_access_key' : '<your_access_key>',
|
|
|
- 'aws_secret_key' : '<your_secret_key>'}
|
|
|
- provider = CloudProviderFactory().create_provider(ProviderList.AWS, config)
|
|
|
+Launch an instance
|
|
|
+------------------
|
|
|
+Before we can launch an instance, we need to decide what image to use so let's
|
|
|
+get the default Ubuntu image ``ami-d05e75b8`` and launch an instance.
|
|
|
|
|
|
-Launching a new instance
|
|
|
-________________________
|
|
|
+.. code-block:: python
|
|
|
|
|
|
+ img = provider.compute.images.get('ami-d05e75b8')
|
|
|
+ inst_type = provider.compute.instance_types.list()[34] # c3.large
|
|
|
+ inst = provider.compute.instances.create(
|
|
|
+ name='Cloudbridge-intro', image=img, instance_type=inst_type,
|
|
|
+ keypair=kp, security_groups=[sg])
|
|
|
+ # Refresh the state
|
|
|
+ inst.refresh()
|
|
|
+ inst.state
|
|
|
+ # 'running'
|
|
|
+ inst.public_ips
|
|
|
+ # [u'54.166.125.219']
|
|
|
+
|
|
|
+From the command prompt, we can now ssh into the instance
|
|
|
+``ssh -i cloudbridge_intro.pem ubuntu@54.166.125.219``.
|
|
|
+
|
|
|
+Cleanup
|
|
|
+-------
|
|
|
+To wrap things up, let's clean up all the resources we have created
|
|
|
|
|
|
-Common methods
|
|
|
-______________
|
|
|
+.. code-block:: python
|
|
|
|
|
|
-create
|
|
|
-list
|
|
|
-find
|
|
|
-delete
|
|
|
+ inst.terminate()
|
|
|
+ sg.delete()
|
|
|
+ kp.delete()
|
|
|
|
|
|
+And that's it - a full circle in a few lines of code. For homework, try to do
|
|
|
+the same but with a different provider. All you will need to change is the
|
|
|
+cloud-specific data, namely the provider setup and the image ID.
|
Enis Afgan