Skip to content

Latest commit

 

History

History
253 lines (178 loc) · 6.39 KB

USER.md

File metadata and controls

253 lines (178 loc) · 6.39 KB
Raw

Abstract

This document is the Software Manual for EC2Stack. The Software user manual instructs how to install and use the EC2Stack from a user's perspective.

Glossary

Amazon EC2 - A web service that provides resizable compute capacity in the cloud.

Apache Cloudstack - Open source cloud computing software for creating, managing, and deploying infrastructure cloud services.

Puppet: - IT automation software that helps system administrators manage infrastructure throughout its lifecycle, from provisioning and configuration to orchestration and reporting.

Python package index - Official third-party software repository for the Python Programming language.

Vagrant - Tool for building complete development environments.

1 Introduction

1.1 Intended readership

This document covers the use for the following users of EC2Stack:

  • The User.

1.2 Applicability

This software user manual applies to EC2Stack, version 0.7.

1.3 Purpose

The purpose of the software user manual is to assist:

  • Users installing and configuring EC2Stack.

1.4 How to use this document

Section 2 includes an overview of EC2Stack from a user perspective. This covers installation of EC2Stack, its configuration and starting it.

Section 3 includes information for a developer. This covers installation for development purposes, git repository location, test execution and the automated vagrant development environment.

2 User Information

2.1 Overview

EC2Stack implements an API layer that sits on top of the Apache Cloudstack API. This API layer attempts to handle requests designed for the Amazon Web Services (AWS) Elastic Compute (EC2) API. It achieves this by retrieving EC2 requests, converting them to Apache Cloudstack requests and parsing the Apache Cloudstack responses into EC2 responses.

2.2 Required dependencies

In order to run EC2Stack your machine will need Python 2.7 installed. EC2Stack will run best on a Linux or BSD based operating system.

2.3 Installing the software

EC2Stack is available on the python package index (pip). If your machine has pip installed you can install EC2Stack by executing:

$ pip install ec2stack

Alternatively, you may install EC2Stack via a tar.gz archive:

$ wget https://pypi.python.org/packages/source/e/ec2stack/ec2stack-0.1.tar.gz

$ tar xf ec2stack-0.1.tar.gz && cd ec2stack-0.1.tar.gz

$ python setup.py install

2.4 Configuration

Before you can start EC2Stack it must be configured. To so do run:

$ ec2stack-configure

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

$ ec2stack-configure -p exampleprofile

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

You can configure an advanced profile with

$ ec2stack-configure -a True

Launching ec2stack-configure will prompt you for various configuration options.

EC2Stack bind address [0.0.0.0]:

Binds EC2Stack to the supplied IP address. If left unset EC2Stack will bind to all IP addresses assigned to the machine.

EC2Stack bind port [5000]:

Binds EC2stack to the supplied port. If left unset EC2Stack will port to port 5000.

Cloudstack host [localhost]:

This is the hostname of the Apache Cloudstack server you wish to run EC2Stack on-top off. If left unset EC2Stack will use localhost.

Cloudstack port [8080]:

This is the port of the Apache Cloudstack server you wish to run EC2Stack on-top off. If left unset EC2Stack will use 8080.

Cloudstack protocol [http]:

This is the protocol EC2Stack should use for connecting to the specified Apache Cloudstack API. If left unset EC2Stack will use http.

Cloudstack path [/client/api]:

This is the path of the Apache Cloudstack API that EC2Stack should query. If left unset EC2Stack will use /client/api

Cloudstack custom disk offering name [Custom]:

This is the name of a disk offering configured on your Apache Cloudstack server that allows for custom disk sizes to set by the user. If left unset EC2Stack will use Custom.

Cloudstack default zone name:

This is the zone you wish EC2Stack to use on your Apache Cloudstack infrastructure should the end user not of set a zone within their request. This field is required.

Do you wish to input instance type mappings? (Yes/No): y

Insert the AWS EC2 instance type you wish to map: m1.small

Insert the name of the instance type you wish to map this to: micro

This allows you to map EC2 instance types to Apache Cloudstack service offerings.

Do you wish to input resource type mappings for tag support? (Yes/No): y

Insert the Cloudstack resource id you wish to map: examplevirtualmachineid

Insert the Cloudstack resource type you wish to map this to: UserVm

This allows you to use tag related actions.

2.5 Running

To run EC2stack execute the following command:

$ ec2stack

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

$ ec2stack -p exampleprofile

EC2Stack will start up and bind to the supplied IP address and port.

2.6 Initial user registration

Before EC2Stack can handle user requests the user must register their API Key and Secret Key.

To register a secert key execute ec2stack-register:

$ ec2stack-register ec2stack_server_address api_key secret_key

To remove a secret key execute ec2stack-remove:

$ ec2stack-remove ec2stack_server_address api_key secret_key