Open Stack

Marco,

Thanks again for your brilliant feedback. It's not often we get such 
detailed advice on how to make things better. Your problems are 
definitely of general interest, and please feel free to write to us at 
any time!

To try and offer some ideas on what we're working on on your points, 
some in-line comments below.

On 09/10/13 19:24, Marco Fornaro wrote:
> *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

Very good points.
Though ... guess what? We should have this for you within a couple of weeks!

Anne managed to rope in documentation legend Shaun McCance, who is 
leading the effort to create an install guide that I think will very 
much look like this.

The new guide starts with a very, very basic install, then allows you to 
"choose-your-own-adventure" in terms of which components you can bolt on.

The basic outline of it have just appeared on the 'trunk' site under the 
Install guide. http://docs.openstack.org/trunk/

It's not yet complete, so maybe we can ask you to take a look at the 
overview in a couple of weeks to see if it's doing better than the old 
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)

When I was running OpenStack clouds, this was one of my pet peeves. It 
was so difficult to find out all of the configuration options, so I 
absolutely agree with you here.

So this release cycle we started a new book: the configuration 
reference. It's supposed to be terse descriptions of particular features 
or drivers, followed by comprehensive (automatically generated from the 
code so 100% complete/correct) lists of the options.

So you should be able to go through a path like:
Config Reference -> Block Storage -> Volume Drivers -> NetApp

(http://docs.openstack.org/trunk/config-reference/content/netapp-volume-driver.html)

and it will have everything you need to to know to configure the NetApp 
driver.


That's at:
http://docs.openstack.org/trunk/config-reference/content/

but again, it probably needs a couple of weeks before it's worth looking at.


> *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

Yes, as you've noted this there there for:

Admins:
http://docs.openstack.org/admin-guide-cloud/content/

Regular Users:
http://docs.openstack.org/user-guide/content/

I've been happy to note that there's many more references to horizon 
than there was last release.

Though, perhaps the problem with these is that they're aiming to be 
comprehensive manuals and potentially have too much in them to flow 
naturally ... we could maybe add a getting started bit for those who've 
just completed the install?


Also, query - have you seen the Operations Guide? 
(http://docs.openstack.org/ops/) Particularly from Chapter 9 "Lay of the 
Land" onwards, I'd be very interested in your feedback. We're planning 
to make a new version of this book.

> *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…

Yeah, this is one of the areas that makes me most sad right now :(

We did have a guide that did this, as you found, but it was neglected 
and fell out of date.

Partially to address this, I notice Everett Toews has submitted a design 
summit talk: http://summit.openstack.org/cfp/details/185

At least we do have a good API reference at 
http://api.openstack.org/api-ref.html - but yeah, need something to 
combine that with, like your curl commands to make it the most useful it 
can be :)

> *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).


All I can say is: Yes :)

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

This is extremely useful Marco. Thank you so much for all of your time!!

> 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
>
>  >
>