USER.md - cloudstack-ec2stack - Git at Google

 <!---
 # Licensed to the Apache Software Foundation (ASF) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
 # regarding copyright ownership.  The ASF licenses this file
 # to you under the Apache License, Version 2.0 (the
 # "License"); you may not use this file except in compliance
 # with the License.  You may obtain a copy of the License at
 #
 #   http://www.apache.org/licenses/LICENSE-2.0
 #
 # Unless required by applicable law or agreed to in writing,
 # software distributed under the License is distributed on an
 # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
 --->
 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
 ```
	<!---
	# Licensed to the Apache Software Foundation (ASF) under one
	# or more contributor license agreements. See the NOTICE file
	# distributed with this work for additional information
	# regarding copyright ownership. The ASF licenses this file
	# to you under the Apache License, Version 2.0 (the
	# "License"); you may not use this file except in compliance
	# with the License. You may obtain a copy of the License at
	#
	# http://www.apache.org/licenses/LICENSE-2.0
	#
	# Unless required by applicable law or agreed to in writing,
	# software distributed under the License is distributed on an
	# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	# KIND, either express or implied. See the License for the
	# specific language governing permissions and limitations
	# under the License.
	--->
	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
	```