Skip to content
Permalink
Browse files
Make use of wiki for user/developer guides
  • Loading branch information
brogand93 committed Jun 25, 2014
1 parent ce55f96 commit d225502f24ec7be01293204488f07140f0e4e58a
Showing 1 changed file with 7 additions and 195 deletions.
@@ -12,205 +12,17 @@ A Google Compute Engine Interface For Cloudstack
.. image:: https://coveralls.io/repos/NOPping/gstack/badge.png?branch=master
:target: https://coveralls.io/r/NOPping/gstack

Description

Apache Cloudstack is open source software designed to deploy and manage large networks of virtual machines, as highly available, highly scalable Infrastructure as a Service(laaS) cloud computing platform. Apache Cloudstack is used by a number of service providers to offer public cloud services, and by many companies to provide an on-premises (private) cloud offering.

Proposal
_________
Users can manage their Apache Cloudstack cloud with an easy to use web interface, command line tools and/or a full featured RESTful API.

This project aims to provide a new compute API interface for Apache Cloudstack that is compatible with Google Compute Engine `GCE <https://cloud.google.com/products/compute-engine>`_, GCE is Google's Infrastructure-as-a-Service (IaaS) compute service that competes with Amazon Web Services EC2. In short, this is a mapping of the `GCE API <https://developers.google.com/compute/docs/reference/latest/>`_ and the `CloudStack API <http://cloudstack.apache.org/docs/api/index.html>`_
Google Compute Engine is the Infrastructure as a Service (IaaS) component of Google Cloud Platform which is built on the global infrastructure that runs Google's search engine, Gmail, YouTube and other services. Google Compute Engine enables users to launch virtual machines on demand.

Implementation
______________

The GCE APIs for Cloudstack is supplied as a layer over the current Cloudstack API. The given application will take in a GCE based API request, pass it over to the Cloudstack API, get the required data and return it in a suitable format.

It is written in Python, using `Flask <http://flask.pocoo.org/>`_ to expose a GCE compliant REST API. Requests, Pycrypto, Pyopenssl and Flask-sqlachemy are dependencies. A custom version of pyoauth2 is included in the source.

- Disks
- listdisks
- getdisk
- Firewalls
- addfirewall
- deletefirewall
- listfirewalls
- getfirewall
- Images
- listimages
- getimage
- Instances
- addinstance
- deleteinstance
- listinstances
- getinstance
- Machinetypes
- listmachinetypes
- getmachinetype
- Project
- getproject
- Zones
- listzones
- getzone


Installation
############

Developers
__________

Clone the repository

$ git clone https://github.com/NOPping/gstack.git

Install the package

$ python ./setup.py install

Users
_____

Users can grab the package from Pypi

$ pip install gstack

Configuration
#############

Before running gstack you must configure it. To do so run

$ gstack-configure

You can configure a profile of your choice with the optional ``-p`` or ``--profile`` flag

$ gstack-configure -p exampleprofile

If you don't specify a profile, ``gstack-configure`` will default to ``initial``

Enter your configuration information as prompted.

Install the stand alone `gcutil <https://developers.google.com/compute/docs/gcutil/#gcutilupgrade/>`_

gstack comes with a self-signed certificate for the local endpoint ``gstack/data/server.crt``, copy the certificate to the gcutil certificates file ``gcutil/lib/httplib2/httplib2/cacerts.txt``

At this stage your CloudStack apikey and secretkey need to be entered in the gcutil auth_helper.py file at ``gcutil/lib/google_compute_engine/gcutil/auth_helper.py``

This is far from ideal and we opened a feature request with google to pass the ``client_id`` and ``client_secret`` as options to gcutil, hopefully future release of gcutil will allow us to do so.

Create a cached parameters file for gcutil:

- Make a flagfile to store required flags, something like ``~/.gcutil_params``

- An example of what to put in here would be:

`--auth_local_webserver`

`--auth_host_port=9999`

`--dump_request_response`

`--authorization_uri_base=https://localhost:5000/oauth2`

`--ssh_user=root`

`--fetch_discovery`

`--auth_host_name=localhost`

`--api_host=https://localhost:5000/`

`--nocheck_for_new_version`

`--permit_root_ssh`

gcutil will issue auth requests to the local Flask application, get an OAuth token and then issue requests to the CloudStack endpoint you specified when cofiguring gstack.
Bridging Apache Cloudstack with existing public cloud providers APIs is needed in order to help users work across clouds. Our project’s aim is to create an application that will sit above the Apache Cloudstack API. The application will take in common Google Compute Engine requests, execute the necessary Cloudstack Calls and parse the responses as required. This would allow utilities created for the Google Compute Engine API to be used against Apache Cloudstack.

Usage
#####

Start gstack:

$ gstack

You can launch gstack using a configuration profile created earlier using the optional ``-p`` or ``--profile`` flag

$ gstack -p exampleprofile

If you don't specify a profile, gstack will default to ``initial``

You can start gstack in debug mode using the optional ``-d`` or ``--debug`` flag

$ gstack -d True

You can now start issuing standard gcutil commands to gstack.

$ ./gcutil --flag_file=~/.gcutil_params --project=brogand93@darrenbrogan.ie listzones


================== ======== ====================
name status next-maintenance
================== ======== ====================
Sandbox-simulator UP None scheduled
================== ======== ====================

Running The Tests
#################

To run the included tests the following software is required:

pep8

pylint

nose

mock

coverage

These can be installed via the Python Package Index:

$ pip install pep8 pylint nose mock coverage

Tests can be executed from the root of the code base as follows:

Style Check
___________

$ pep8 --ignore=E501 *.py gstack
Lint
____

$ pylint --rcfile=pylint.rc *.py gstack
Unit Tests
__________

$ nosetests --with-coverage --cover-erase --cover-package=gstack --cover-html

A HTML base coverage report will be placed in ./cover

Trouble shooting
################

CertificateHostnameMismatch
___________________________

- Ensure that the addresses you entered for ``authorization_uri_base``, ``api_host`` and ``auth_host_name`` are the exact same as the address you binded ``gstack`` to earlier when configuring with ``gstack-configure``.

Authentication/authorization issues
___________________________________

- Clean up your gcutil authentication information ``rm -rf ~/.gcutil_auth``.
- Ensure that you set your ``client_id`` and ``client_secret`` in ``gcutil/lib/google_compute_engine/gcutil/auth_helper.py``.



Apache CloudStack
#################

For more information about CloudStack check the official `<website http://cloudstack.apache.org>`_

Copyright © 2013 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
"Apache", "CloudStack", "Apache CloudStack", and the Apache feather logos are registered trademarks or trademarks of The Apache Software Foundation.
=====

Please see the project wiki for usage instructions (`<https://github.com/NOPping/gstack/wiki>`_)

0 comments on commit d225502

Please sign in to comment.