More doc updates

3 files changed, 178 insertions, 21 deletions

diff --git a/everest-docs/everest-docs-1.0.0/en-US/Koan.xml b/everest-docs/everest-docs-1.0.0/en-US/Koan.xml
index f7a4cd0..1e2f5ee 100644
--- a/everest-docs/everest-docs-1.0.0/en-US/Koan.xml
+++ b/everest-docs/everest-docs-1.0.0/en-US/Koan.xml
@@ -17,12 +17,16 @@
 				documentation</ulink>.  
 		</para>
 
-		<para>
-			Most provisioning in with &PRODUCT; can be done without
-			having to work with Koan directly.  The main exception
-			is <link linkend="everest-Koan-HostProvisioning">Host
-				Provisioning</link>
-		</para>
+		<note>
+			<title>Note</title>
+			<para>
+				Most provisioning with the &PRODUCT; tools
+				can be done without having to work with Koan
+				directly.  However, a good understanding of its
+				basic operation is useful for advanced usage of
+				the &PRODUCT; tooling.
+			</para>
+		</note>
 	</section>
 
 	<section id="everest-Koan-Installation">
@@ -30,7 +34,7 @@
 		<para> RPMs exist for both Fedora and RHEL (through <ulink
 				url="http://fedoraproject.org/wiki/EPEL">EPEL</ulink>).
 			If your repositories are configured correctly you should simply
-			be able to '*yum install koan*'. Koan doesn't have many
+			be able to <userinput>yum install koan</userinput>. Koan doesn't have many
 			dependencies so if you don't feel like adding the EPEL repo to
 			your RHEL machine you can simply install the RPM.  
 		</para>
@@ -44,21 +48,114 @@ koan -s everest-repo.usersys.redhat.com --list-systems
 		</para>
 	</section>
 
-	<section id="everest-Koan-HostProvisioning">
-		<title>Host Provisioning</title>
-		<screen> 
-koan -s everest-repo.usersys.redhat.com --replace-self --system=[hostname of your system]
-		</screen>
+	<section id="everest-hypervisor-setup">
+		<title>Setting up an environment to host virtual machines</title>
+		<para>
+		     Virtualization is by no means a requirement to make use of
+		     the &PRODUCT; tooling, though it is the more common than
+		     "bare metal" provisioning.
+		</para>
+
+		<para>
+			The two main types of machines used to host virtual
+			machines are called the Host and Cloud machine types.
+			These machine types, like Repo machines, are typically
+			amongst the first machines that users of the &PRODUCT;
+			tooling desire to get up and running quickly.  These
+			machines use virtualization to host other machines and
+			for that reason are <emphasis>always</emphasis>
+			provisioned on "bare metal".
+		</para>
+
+		<note>
+			<title>Note</title>
+			<para>
+				The <emphasis>Host</emphasis> machine type,
+				while arguably poorly named, is named so based
+				on historical reasons.  In reality there are
+				very few differences between Host and Cloud
+				machines so eventually they will probably go
+				away.
+			</para>
+		</note>
+
+                <section id="everest-host-machines">
+			<title>Host machines</title>
+
+			<para>
+				The quickest way to get a Host machine up and running
+				is to use the <link
+					linkend="everest-replace-self">everest-replace-self</link> tool
+				with a <emphasis>Host</emphasis> profile.
+			</para>
+
+		</section>
+
+                <section id="everest-cloud-machines">
+			<title>Cloud machines</title>
+			<para>
+			     The &PRODUCT; Cloud machine is an effective way to
+			     manage resources amongst underutilized commodity
+			     hardware. 
+			</para>
+
+			<note>
+				<title>Note</title>
+				<para>
+					One of the main goals of the current
+					Cloud machine tooling is to
+					<emphasis>Do the simplest thing that
+						could possibly work</emphasis>.
+					This functionality, implemented through
+					<ulink
+						url="https://fedorahosted.org/func">Func</ulink>
+					modules, will most likely be entirely
+					replaced with <ulink
+						url="http://ovirt.org/">ovirt</ulink>.
+				</para>
+			</note>
+
+			<para>
+				Like Hosts, Cloud machines use <link
+					linkend="everest-replace-self">everest-replace-self</link>
+				to get up and running quickly.  The main
+				different is that a <emphasis>Cloud</emphasis>
+				profile should be used and the
+				<emphasis>-m</emphasis> (metadata) flag must
+				be set.  The value for this flag varies
+				depending it is the
+				<emphasis>certmaster</emphasis> or if it is a
+				<emphasis>minion</emphasis> in
+				<application>func</application> parlance.  
+			</para>
+
+			<para>
+				For the master set <emphasis>-m</emphasis> to
+				<emphasis>certmaster=localhost</emphasis>
+			</para>
+
+			<para>
+				For the minion set <emphasis>-m</emphasis> to
+				<emphasis>certmaster=[Any previously created Cloud master]</emphasis>
+			</para>
+
+			<note>
+				<title>Important</title>
+				<para>
+					It's typically a good idea to create a
+					standalone Cloud machine instead of a
+					Host machine since there is so little
+					difference between the two.
+				</para>
+			</note>
+		</section>
+	</section>
+
+	<section id="everest-Koan-CloudProvisioning">
+		<title>Cloud Provisioning</title>
 		<para>
-			The most important thing here is
-<emphasis>--replace-self</emphasis>. This puts an entry in
-<filename>/etc/grub.conf</filename> that, on reboot, will kickstart your
-machine appropriately. Replace the value for the <emphasis>--system</emphasis>
-flag with whatever you configure with
-<application>everest-bootstrap</application> (You will want to use the
-<emphasis>--config-only</emphasis> option).
-	        </para>
 
+		</para>
 	</section>
 
 	<section id="everest-Koan-GuestProvisioning">
diff --git a/everest-docs/everest-docs-1.0.0/en-US/Tooling.xml b/everest-docs/everest-docs-1.0.0/en-US/Tooling.xml
index b342d37..e5db3f8 100644
--- a/everest-docs/everest-docs-1.0.0/en-US/Tooling.xml
+++ b/everest-docs/everest-docs-1.0.0/en-US/Tooling.xml
@@ -12,6 +12,66 @@
 		contributing to &PRODUCT;.
 	</para>
 
+	<section id="everest-replace-self">
+		<title>everest-replace-self</title> 
+		<para>
+		      To avoid many "chicken and the egg" sorts of provisioning
+		      problems the &PRODUCT; tooling provides a RPM and script
+		      called <application>everest-replace-self</application>.
+		      As the name suggests this tool is a quick way to
+		      completely replace a machine.  The term
+		      <emphasis>replace-self</emphasis> is borrowed from
+		      <application>koan</application> and under the covers that
+		      is basically all that is really happening.  The script does
+		      includes some helpful logic to properly install koan on
+		      whatever Red Hat based system was previously running on
+		      the system in question.
+		</para>
+
+		<important>
+			<title>Important</title>
+			<para>
+				Machines setup via
+				<application>everest-replace-self</application>
+				are not always controlled by
+				<application>puppet</application>.  They tend to be treated
+				more like appliances.
+			</para>
+		</important>
+
+		<section id="everest-replace-self-usage">
+			<title>Usage</title> 
+			<para>
+				To use this tool the user must know the profile
+				that will be used to
+				<emphasis>replace-self</emphasis>.  This can be
+				obtained easily with
+				<application>koan</application>.
+			</para>
+
+			<screen> 
+everest-replace-self --help
+
+# Select a profile from the list this command returns
+koan -s [Your &PRODUCT; Repo machine] --list-profiles 
+
+# Only certain types of machines require the -m (metadata) flag
+everest-replace-self -c [Your &PRODUCT; Repo machine] -p [Profile selected in previous step]
+		        </screen>
+
+			<note>
+				<title>Note</title>
+				<para>
+					Ideally which profile to select should
+					be obvious based on the names.  A good
+					practice is to have the profiles
+					include both the architecture and
+					operating system in the name.
+				</para>
+			</note>
+		</section>
+	</section>
+
 	<section id="everest-EverestBootstrap">
 		<title>everest-bootstrap</title> 
 
diff --git a/everest-docs/everest-docs.spec b/everest-docs/everest-docs.spec
index 1d081bf..af28c0b 100644
--- a/everest-docs/everest-docs.spec
+++ b/everest-docs/everest-docs.spec
@@ -1,6 +1,6 @@
 Name:           everest-docs
 Version:        1.0.0
-Release:        17%{?dist}
+Release:        18%{?dist}
 Summary:        Everest documentation 
 
 Group:          Applications/System