Documentation Networking issue

[Ron Wheeler <rw...@artifact-software.com>]

http://docs.cloudstack.apache.org/en/latest/concepts.html#deployment-architecture-overview 
Network section is really unclear.

In about Physical Networking there are 4 Traffic types defined
Guest, Management, Public and Storage.

Later on the term "Direct IP range" is used but never defined. "These 
IPs are in the same VLAN as the hosts." is added without any explanation 
of what this means or how this relates to various traffic types or any 
statement about what VLAN the hosts are in or where their addresses come 
from.

In Advanced Networking it says "The hosts in a pod are assigned private 
IP addresses. These are typically RFC1918 addresses."
Is this different than in Basic Networking? Why is it important in 
Advanced Networking but not required in Basic. Is it not true for both?

In the next paragraph it says:
"For zones with advanced networking, we recommend provisioning enough 
private IPs for your total number of customers, plus enough for the 
required CloudStack System VMs.
Typically, about 10 additional IPs are required for the System VMs."

How is this different in Basic Network?

What has the importance of "customers"? They are never defined or 
mentioned earlier and has no relationship to physical hosts as near as I 
can tell from my understanding of "customers" and "hosts".

I am not sure how one decides if you are "typical" or what would make 
your situation require more or less.
Perhaps it should be a bit more definite "Allow at least 10 IPS for the 
SYSTEM VMs unless you xxx xxx xxx in which case you will need on for 
each yyy"

System VMs are very poorly defined earlier in the Traffic type section.
"system VMs (VMs used by CloudStack to perform various tasks in the 
cloud), and any other component that communicates directly with the 
CloudStack Management Server. You must configure the IP range for the 
system VMs to use."
"Various tasks " could hardly be more vague. Surely someone must have a 
list or a count with a link to the reference section.
The last sentence about assigning IP addresses System VMs is confusing 
in a paragraph about Traffic Types and should be omitted since it will 
be discussed later when IP addresses are discussed.

It seems to me that there should be a reorganization of this section 
with a clear statement of all the things that are true for both Basic 
and Advanced with careful attention paid to vocabulary and proper 
definition of new buzzwords as they are added.
Then differentiate the handling of Basic vs Advanced in 2 sections that 
are clearly written in a parallel structure and sequence so it is easy 
to see what the difference is.

This is an important section and should be an overview.
There are too many references to exceptions related to specific hardware 
or hypervisors.
If these have to be in the overview, they should be as footnotes or 
special sections at the end of the overview.

Some simple diagrams should be included to make the network topology and 
IP address assignments clearer.
Networking is an important part of Cloudstack and is the source of a lot 
more confusion that the hierarchy of hosts to region which include 4 
diagrams.


I hope that this helps.

Ron

-- 
Ron Wheeler
President
Artifact Software Inc
email: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102