OSDir

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Documentation issues


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: rwheeler@xxxxxxxxxxxxxxxxxxxxx
skype: ronaldmwheeler
phone: 866-970-2435, ext 102