[readme] initial version of "Quick start" and reasons to use salt-ami-cloud-builder
authorArthur Lutz <arthur.lutz@logilab.fr>
Fri, 07 Jun 2013 17:26:49 +0200
changeset 153 df8956d7881b
parent 152 bed8cb177dce
child 154 b3695cbb8757
[readme] initial version of "Quick start" and reasons to use salt-ami-cloud-builder
readme.rst
user_data.cfg.sample
--- a/readme.rst	Fri May 31 18:12:55 2013 +0200
+++ b/readme.rst	Fri Jun 07 17:26:49 2013 +0200
@@ -1,23 +1,98 @@
 
 Objective
-=========
+---------
 
-Automatically create variations of virtual machines images for a cloud
-infrastructure (OpensStack or Amazon are currently supported) using
-SaltStack_ based configuration files availables in a given Mercurial_
-repository, eg.:
+The goal is to automatically create variations of virtual machines
+images for a cloud infrastructure (OpenStack or Amazon are currently
+supported) using SaltStack_ based configuration files available in a
+given Mercurial_ repository.
 
-  http://hg.logilab.org/users/ptonelli/salt-ami-cloud-builder/variation
+The AMI builder tool can be used in two ways:
 
-The AMI creator tool consist in a properly configured AMI to be
-instanciated with proper parameters passed as user data. This instance
-(which creation itself is described below) by default also updates
-itself from the base configuration repository (stored in the following
-Mercurial_ repository):
+* a simple developper mode, which will create new AMIs from your
+  workstation (it requires root credentials on a the machine)
 
-  http://hg.logilab.org/master/salt-ami-cloud-builder/
+* a production mode, in which the special cloud-builder AMI is used to
+  build a preconfigured deployable AMI.
 
 .. _SaltStack: http://docs.saltstack.com/
 .. _Mercurial: http://mercurial.selenic.com/
 
 
+Why you need salt-ami-cloud-builder
+-----------------------------------
+
+ .. or why we build it.
+
+For a virtual machine in the cloud (private or Amazon), having a
+preconfigured AMI_ helps you gain setup time and execution time.
+
+Instead of having an "install and configure each instantiation of a
+machine" we go for a "install once, run multiple times" approach.
+
+Another benefit of this approach is that you have a repeatable
+environnement.
+
+If you're already using SaltStack_, you can easily reuse your `salt
+states`_ to setup a custom AMI.
+
+.. _AMI: http://en.wikipedia.org/wiki/Amazon_Machine_Image
+.. _`salt states`: http://docs.saltstack.com/topics/tutorials/starting_states.html
+
+
+Quick start
+-----------
+
+To create your first working image, follow these instructions:
+
+1. Get the code ::
+
+    hg clone http://hg.logilab.org/master/salt-ami-cloud-builder/
+
+2. Install `salt-minion` and dependencies (as root) ::
+
+    sudo apt-get install salt-minion python-apt
+
+3. Configure salt (edit `/etc/salt/minion`):
+
+    * set to masterless mode ::
+
+       file_client: local
+
+    * set state and modules source as local folder ::
+
+       file_roots:
+         base:
+          - /home/user/src/salt-ami-cloud-builder/
+
+4. Edit your configuration file ::
+
+    cd salt-ami-cloud-builder
+    cp user_data.cfg.sample user_data.cfg
+    vim user_data.cfg
+
+   You should remove the unsed parts.
+
+5. Set the environment variables by `sourcing` the config file ::
+
+    sudo python others/ec2_ami_parser.py user_data.cfg
+
+6. Run salt ::
+
+    sudo salt-call saltutil.sync_modules
+    sudo salt-call saltutil.sync_states
+    sudo salt-call state.sls ami_builder
+
+If you got only green and blue outputs, everything should be ok.
+
+You are now the proud owner of a variation.img file containing your
+dear AMI, in `/mnt/output`.
+
+
+Documentation
+-------------
+
+For further documentation (installation, deployment, examples, etc) see
+the docs/ folder.
+
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/user_data.cfg.sample	Fri Jun 07 17:26:49 2013 +0200
@@ -0,0 +1,44 @@
+#salt-grains #interpreter flag
+### necessary unless you want the standard image ###
+ami.hg_address_variation: http://hg.logilab.org/users/ptonelli/salt-ami-cloud-builder/variation
+ami.hg_rev_variation: 9ed741a55f17 #optionnal
+ami.name: my_variation
+ami.type: ubuntu #or debian
+
+ami.source_address: http://cloud-images.ubuntu.com/precise/current/precise-server-cloudimg-amd64.tar.gz
+ami.source_hash: md5=1d72ed9c56abb899be02e7cae0822f1d
+
+### optionnal if your image uses existing kernel/ramdisk id in openstack ###
+kernel_id:a5b900bd-c009-40b2-a763-32b32996b1ee
+initrd_id:b953e40a-2605-402b-8663-c8556a5899f2
+
+### optionnal (ami_creation code update) ###
+ami.hg_address_server: http://hg.logilab.org/master/salt-ami-cloud-builder/
+
+### optionnal (necessary to upload to openstack) ###
+keystone.user: username
+keystone.password: password
+keystone.tenant: tenant
+keystone.tenant_id: 00000000000000000000000000000000
+keystone.auth_url: 'http://control.example.com:5000/v2.0'
+keystone.insecure: False   #(optional)
+
+### optionnal (necessary to upload to amazon aws) ###
+### remove the BEGIN and END statements found in the files ###
+### do not forget the ' ' at each newline for ConfigParser ###
+aws.region: eu-west-1
+aws.private_key: 0000000000000000000000000000000000000000000000000000000000000000
+ 0000000000000000000000000000000000000000000000000000000000000000
+ 0000000000000000000000000000000000000000000000000000000000000000
+ 0000000000000000000000000000000000000000000000000000000000000000
+ 0000000000000000000000000000000000000000000000000000000000000000
+ 0000000000000000000000000000000000000000000000000000000000000000
+ 0000000000000000000000000000000000000000000000000000000000000000
+aws.certificate: 0000000000000000000000000000000000000000000000000000000000000000
+ 0000000000000000000000000000000000000000000000000000000000000000
+ 0000000000000000000000000000000000000000000000000000000000000000
+ 0000000000000000000000000000000000000000000000000000000000000000
+ 0000000000000000000000000000000000000000000000000000000000000000
+ 0000000000000000000000000000000000000000000000000000000000000000
+ 0000000000000000000000000000000000000000000000000000000000000000
+