There are some simple problems with the documentation.
Some of these have been raised in the past but never fixed.
http://docs.cloudstack.apache.org/en/latest/concepts.html is the first
technical page that a new user will read.
*Loose text.*
At the top of the page under Concepts and Terminology there is a
sentence that looks out of place.
"Primary storage is associated with a cluster"
*DIAGRAMS too simple and possibly wrong
*
The diagrams for Zones, Pods,Clusters should show at least 2 of the next
lower level. The diagram for Regions looks much clearer as it show 3
zones that make up the Region. The Pod diagram looks like the Primary
storage is inside the Cluster which is different from what the text
says. "A pod consists of one or more clusters of hosts and one or more
primary storage servers"
*Clusters must have identical hardware*
The text says "The hosts in a cluster all have identical hardware, run
the same hypervisor, are on the same subnet, and access the same shared
primary storage." Is it true that the hardware must be "identical".That
seems to an overstatement of the requirement.
*Redundant t**ext**in Cluster*
This sentence should be removed. It is clear from the whole discussion
of the hierarchy.
"A cluster is the fourth-largest organizational unit within a CloudStack
deployment. Clusters are contained within pods, and pods are contained
within zones."
*Cluster Size*
" Size of the cluster is limited by the underlying hypervisor, although
the CloudStack recommends less in most cases; see Best Practices."
What doe this actually mean? Is it true? Would an example make it clearer?
The hyperlink to Best Practices is missing.
*Host question*
The description says
* May reside in multiple data centers across different geographic location
This contradicts previous statements that hosts exist inside clusters
which are inside pods and zones which can only be in one datacenter.
This section also says that host in a cluster must be homogeneous which
is different from identical but in no place is either identical or
homogeneous ever defined and these are not commonly used in Computer
Science with the definitions which I think are meant here.
*
**Primary Storage section contradicts Pod definitions and the entire
previous hierachy*
The Pod section says that a pod consists of clusters and primary
storage. This section says that Primary storage is "associated" with a
cluster not a pod.
It then goes on to recommend that Primary storage should be at the Zone
level.
Can someone make up a consistent definition of the relationship of
Primary Storage to the rest of the structures and fix the diagrams to
match the actual reality.
*Redundant Network Traffic Type definitions*
Not sure why the definitions are associated with both Basic and Advanced
Network Traffic Types. The definitions appear to be the same and the
fact that they appear twice is confusing.
*Basic Zone Network Traffic Type only requires Guest Network**
*The description of Basic Zone Network configuration says that you only
need to define a Guest network. It makes no comments about the other
traffic types.
*Accounts and Customers never defined*
In the discussion about Advanced Zone Guest IP Addresses, the concept of
Accounts is used with no definition of what accounts.
There is also a mention of "Customers" without any description of what
"Customers" means in a Cloudstack context.
*
**General Comment on exceptions
*My personal view is that there are too many references to specific
product exceptions. These add too many confusing and conflicting**ideas
for an introductory article. This is supposed to be an introduction to
the concepts and terminology that will be used in the rest of the
documentation.*
*
--
Ron Wheeler
President
Artifact Software Inc
email: rwhee...@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102
