Open Stack

Hi Tom,



You asked me to write "what else you'd like to see", and I'm really pleased if I can help :) !



Premise: I'm actually working in a research center in Munich, Germany, and my aim is to provide an Openstack+quantum Cloud platform to researchers to test new algorithms to orchestrate and manage a Software Defined Networks (SDN), I guess that this leads to face problems that are of general interest, so I guess and hope that all my issues and needs could be useful, at least as stimulus for the documentation roadmap



These are the main issues that I'm facing:



1) quickly get your system working:

You need an installation guide, in our case that was a problem because we DO NEED an installation WITH quantum and an openflow-compatible plugin AND, ad I mentioned to the mailing list in a previous post there is no trace of this in the actual documentation!

The "general interest" point here is that it's always more common for the user the need to create a "real world" datacenter, with complex network structure, so it starts to be mandatory to have a clear openstack+quantum installation guide...I found very useful this guides, that a user in openstack list did gave me:

https://github.com/mseknibilel/OpenStack-Grizzly-Install-Guide

NOTE: often you need to first install and try openstack even with few resources...and then apply for more....this means that the initial guides should always involve the less possible number of servers and (real) NICs/subnets, honestly a "startup" guide that do involve 3 servers and three subnets is out of scope for a beginner

My personal suggestion is to start from this drafts to build new official installation guides

Note: don't you forget a comprehensive collections of example configuration files, each file with with ALL the parameters (even the default one, to let user have an overall control)



2) provide a brief guide for most common operations

In my opinion this exists but should be improved: this is a list of thing a common user should be lead to normally do:

->Create his/her own user

->create his/her own tenant

->establish correct user role for what he/she has to do

->create and modify networks/subnets/routers + modifying routers to reach a real network (WITH simple example of floating IP)

->creating and modifying security groups (at least to ping and ssh)

->finally boot a machine, access that and (why not) interact with another VM

NOTE: I saw the web interface (horizon) has really increased in terms of functionalities, so examples should me made either with prompt commands and on web interface

NOTE: all the commands should be coherent with item 1: ideally the user should start operation guide just after finishing installing



3) provide a brief guide for API access (python + java)

Once you have your system working and users starts to get in touch you are immediately asked by users to access system via API, and they want just CLEAR and SIMPLE CODE  examples to do via code/API what they learned to do via API, particularly:

-> create and modify networks/subnets/routers + modifying routers to reach a real network (WITH simple example of floating IP)

-> boot VMs, access those and un customized scripts

NOTE: In my personal experience the most used languages are Python and Java, personally I would recommend these languages for the documentation examples, but the important point is that all the examples should be made in at least a couple of languages

NOTE: personally I like very much the API structure in openstack because it only deals with URL (endpoint) and http/POST calls sending json files, SO I add a very personal suggestion: wouldn't it be possible to always START from examples that use curl in linux (AND something similar in Win or mac) to do things???, in this way we will be educating the user to "call" openstack API "DIRECTLY", without any "logical connection" to a specific development language

For this we should first provide json files examples, usable either with curl, python, java or whatever...



4) Extend your system

Finally, when everything works, you will surely need to "extend" your system, for instance adding compute nodes, splitting the controller services on more servers, or even adding the object storage (swift) that you did not use in first steps.

In my opinion the "advanced" installation guides should start from this assumptions: in these cases you never start from the scratch, you are just extending a system SO we should simply add some Appendixes to the main installation guides to explain this by examples too (i.e.: appendix 1: "adding a compute node", appendix 2 "empowering controller" etc etc).





NOTE: HOPE I HAVE BEEN USEFUL AND DID NOT BOTHER ANYONE



Best Regards



Marco



-----Original Message-----
From: Tom Fifield [mailto:tom at openstack.org]
Sent: den 7 oktober 2013 12:37
To: Marco Fornaro; openstack-docs at lists.openstack.org
Subject: Re: [Openstack-docs] HELP! guide "openstack-compute-api-with-shell-and-python"



Thanks Marco, really appreciate the feedback - I think it's very valid.



Do you have a moment to write what else you'd like to see? I think we're

planning to make a new book/make some updates specifically for the kind

of adventure you're on now ...



On 07/10/13 20:23, Marco Fornaro wrote:

> Hi Tom,

>

> Thanks very much for your help and for the URL

>

> I will take in count your considerations about the not-up-to-date guide

>

> BUT..in general I could not find another simple tutorial that could lead to create/boot/destroy a VM...the quick start guide IS NOT in my opinion: because only the CLI commands are used in the example...I mean not even an example for booting a machine using a json file and curl and/or python script or whatever...

>

> If you have some alternative tutorial to suggest you're welcome!

>

> BR

>

> Marco

>

> -----Original Message-----

> From: Tom Fifield [mailto:tom at openstack.org]

> Sent: den 7 oktober 2013 09:15

> To: openstack-docs at lists.openstack.org

> Subject: Re: [Openstack-docs] HELP! guide "openstack-compute-api-with-shell-and-python"

>

> If you really still want it -- and do take care: it's probably going to

> cause a lot of pain if you try to use it -- you can find it at:



> https://github.com/openstack/api-site/blob/7ff099be64ab58bce13a10f7dd7ca5807ce4618b/openstack-api-programming/openstack-api-programming.md

>

>

> Regards,

>

> Tom

>

> On 07/10/13 18:12, Tom Fifield wrote:

>> Hi,

>>

>> That guide was very outdated and in many cases simply wrong for the

>> current releases of OpenStack - especially the examples.

>>

>> Do you really still want it?

>>

>>

>> Regards,

>>

>> Tom

>>

>> On 07/10/13 18:09, Marco Fornaro wrote:

>>> Hi All,

>>>

>>> To get practice in interfacing to Openstack API I read a manual that was

>>> linked from openstack official documentation main page, this was the

>>> link:

>>>

>>> http://docs.openstack.org/api/openstack-compute/programmer/content/programming-openstack-compute-api-with-shell-and-python-1st-ed..html

>>>

>>>

>>> I found that guide very useful especially for the many practical

>>> examples in there, either for shell or for python

>>>

>>> now, clicking that page I am redirected to:

>>>

>>> http://docs.openstack.org/api/quick-start/content/

>>>

>>> Does anyone know WHY that link is now redirected to the quick start

>>> guide (a different document)?

>>>

>>> Is it still possible to access the original guide?

>>>

>>> Best Regards

>>>

>>> Marco

>>>

>>>

>>>

>>> _______________________________________________

>>> Openstack-docs mailing list

>>> Openstack-docs at lists.openstack.org

>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

>>>

>>

>>

>> _______________________________________________

>> Openstack-docs mailing list

>> Openstack-docs at lists.openstack.org

>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

>

>

> _______________________________________________

> Openstack-docs mailing list

> Openstack-docs at lists.openstack.org

> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

>


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131009/5ebb793f/attachment-0001.html>