openstack team mailing list archive

[Rick Jones <rick.jones2@xxxxxx>]

On 05/10/2012 07:33 AM, Atul Jha wrote:
> Suggestion/criticism would be highly appreciated.

Tried a few times to send this directly to Atul and the 
css.ossbooks@xxxxxxxxxxx  address in the paper, but was getting rejected 
content for Atul's email destination and no such user for the 
css.ossbooks email.  So, some feedback, mostly little things, 
wording/format/etc:


11th Page - List of Tables - "This is a tutorial style beginner’s guide
for OpenStackTM on Ubuntu 12.04, Precise Pangolin. The aim is to help
the reader in setting up a minimal installation of OpenStack." doesn't
seem like a list of tables.

13th page, section 1.1 - since it is a beginners guide, a short sentence
describing IaaS, PaaS and SaaS would be a good thing to include.


13th page, section 1.2 - similar to previous, a short sentence
describing what a Compute, Storage, Imaging, Identity and UI service
are/do would be goodness.


14th page - Perhaps a dialect thing but should it be "The diagram below"
rather than "The below diagram?" Also, I would put the overall diagram
before the Nova-specific one and then call them "Overall Architecture"
and "Nova Architecture" respectively.  Show the beginner the overall 
first before hitting him with the complex :)

Also, in the overall diagram, should Glance be called "STORE" or should
that be "IMAGE" to maintain consistency with previous discussion -
someone seeing Glance:Store and Swift:Storage will wonder about the
difference.

15th page - section 1.2.1.2.2 - I think that should start with
"OpenStack components communicate"

section 1.2.1.2.3 - "Compute workers deal with the instance management
life cycle..." and I might add "based on the scheduling algorithm used
by nova-scheduler."

Section 1.2.1.2.4 - security groups are mentioned without prior definition.

16th page - section 1.2.1.2.6 - previously, it was said that OpenStack
Nova provides EC2 apis and the native was mentioned just as an aside.
Now though we read "The scheduler maps the nova-API calls to the ..." -
what has become of EC2?

section 1.2.2 - might it be worthwhile to include the "Swift" project
name along with "Open Stack Object Store" in the second bullet item?

22nd page - section 2.2.2 - should there be some sort of caveat about
using IP addresses appropriate for the admin's specific situation?

Section 2.2.3 - the NTP gods are quite adamant about configuring at
least four sources of time. That allows the bad clock detection
heuristics to operate even if one of the time sources is unavailable.

"IP addresses of the servers are resolvable" sounds like asking for PTR
records to go from IP to name, but I think you mean to verify that the
names can be resolved to IPs no? Perhaps "Ensure that the hostnames can
be resolved to their respective IP addresses. If they are not
resolvable via DNS, you can add entries to the /etc/hosts file."

Some discussion of how long it will take Server1 to get its time
synchronized and so be willing to serve time to others is probably in order.

27th page - it might be an artifact of document viewer, but it isn't
possible to cut-and-paste the keystone commands from the document. And
even if it was, where I'd expect to find a backslash '\' there is an
arrow with a curled shaft - is that something bash et all will recognize
and deal with properly as a "continued on the next line" indication?


40th page - why is "Server2" a child of "Server1" section 2.2 instead of
its own section 2.3? Also, the interfaces file seems to be the first
indication that Server2 needs to have two NICs.

42nd page - same sort of question about Client1

56th page - 5.2.1 Instances - the text is on this page, but the image is
on the 57th page. And that continues with the other sections.
Something should be done to force the text and image to be on the same page.

58th page - section 5.2.3 - Flavors as a term just sort of magically
appears for the first time here.

80th page - section 8.1 - not an issue with the document per-se but with
the terms nova chose. To someone with much knowledge of TCP "From Port"
sounds like the source port number and "To Port" sounds like the
destination port number. That is very different from what they are in
this context, which are the Beginning and Ending port numbers of an
instance-local range of ports being opened. Some verbiage about that
might be goodness.

Also the example description for adding port 22 is incomplete - it isn't
allowing tcp traffic traffic generally. It is allowing ssh/scp traffic
specifically

hope that helps,

rick jones