path: root/genome-docs/genome-docs-1.0.0/en-US/Tooling.xml

<?xml version='1.0'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<chapter id="genome-Tooling">
	<title>Tooling</title>
	<para>
		One of the goals of &PRODUCT; is not to event new tools but
		rather to leverage and contribute to existing Open Source
		projects.  This section presents the user with links to many
		technologies that can be considered prerequisites for
		contributing to &PRODUCT;.
	</para>

	<section id="genome-replace-self">
		<title>genome-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>genome-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 set up via
				<application>genome-replace-self</application>
				are not always controlled by
				<application>puppet</application>.  They tend to be treated
				more like appliances.
			</para>
		</important>

		<section id="genome-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> 
genome-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
genome-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="genome-GenomeBootstrap">
		<title>genome-bootstrap</title> 

		<section id="genome-GenomeBootstrap-Background">
			<title>Background</title> 
			<para>   
				With the introduction of virtualization, we are able to
				easily rebuild entire environments quickly; however
				there is a fair amount of complexity involved in doing
				so. We've created a tool called
				<application>genome-bootstrap</application> that
				automates the process of wiring a machine up to puppet. 
			</para>

			<para>
				There are essentially two ways of using
				<application>genome-bootstrap</application>.  One way,
				which does not require root privileges, is to run with
				the <emphasis>--config-only</emphasis> option.  This configures everything
				on &PRODUCT; repo to prepare for an installation.
				Obvously this can also be used to update a machine's
				configuration.
			</para>

			<para> 
				The second way to use the tool requires root privileges
				since it kicks off a <application>Koan</application>
				process.  
			</para>

			<note>
				<title>Note</title>
				<para>
					The <emphasis>--config-only</emphasis> option
					is especially useful for bootstrapping Host
					machines.  Quite often a machine that will be
					turned into a Host does not even have
					<application>genome-bootstrap</application>
					installed.  It's easy to run
					<application>genome-bootstrap</application>
					with <emphasis>--config-only</emphasis> from
					another machine and then procede with Koan on
					the soon-to-be Host.
				</para>
			</note>
		</section>

		<section id="genome-GenomeBootstrap-features">
			<title>Features</title>
			<orderedlist>
				<listitem>
					<para>
						Creates DDNS entries for your
						machines during the bootstrap
						process
					</para>
				</listitem>
				<listitem>
					<para>
						Creates a
						<application>Cobbler</application>
						system record for provisioning
					</para>
				</listitem>
				<listitem>
					<para>
						Guides the user through the
						process of setting parameters
						to be used by
						<application>Puppet</application>
						for configuration
					</para>
				</listitem>
				<listitem>
					<para>
						Optionally starts the
						<application>Koan</application>
						process
					</para>
				</listitem>
			</orderedlist>

			<important>
				<title>Important</title>
				<para>
					As of version 0.4.0 we are no longer tied to using
					Red Hat's internal DDNS solution.  This is great for users with stricter
					networking requirements.
				</para>
			</important>

		</section>

		<section id="genome-GenomeBootstrap-installation">
			<title>Installation</title>
			<para>
				The required RPMs should already be installed
				on any machine already bootstrapped in the
				&PRODUCT; environment.  This is useful for the
				<emphasis>--config-only</emphasis> mode.  If
				you want to install &PRODUCT; machines in a
				virtualized environment you will need to setup
				a <link linkend="genome-cloud-appliance">Cloud
					Appliance </link>.  That machine 
				comes with
				<application>genome-bootstrap</application>
				already installed.
			</para>
			<para>
				If you are installing genome-bootstrap on a separate
				machine, like a laptop, you can easily add the Genome
				yum repositories and install genome-bootstrap on any
				machine you like.  Run the following commands to create
				the Genome yum repository file:
				<screen>
# Switch to root
su -

echo """
[genome-noarch]
name=Genome (noarch)
baseurl=http://ftp.redhat.com/pub/redhat/genome/yum/Fedora-9-genome-noarch
enabled=1
gpgcheck=0

[genome-i386]
name=Genome (i386)
baseurl=http://ftp.redhat.com/pub/redhat/genome/yum/Fedora-9-genome-i386
enabled=1
gpgcheck=0
""" > /etc/yum.repos.d/genome.repo

# Install genome-bootstrap
yum install rubygem-genome-bootstrap
				</screen>
			</para>
			<para>
				Should you need to install
				<application>genome-bootstrap</application> manually,
				yum can be configured to point to the
				<application>Cobbler</application> server running on
				your &PRODUCT; Repo.  Once yum is properly setup you
				can run:
				<screen>
# <userinput>yum install rubygem-genome-bootstrap</userinput>
				</screen>
			</para>
		</section>

		<section>
			<title>Usage</title>
			<para>
				<application>genome-bootstrap</application> does not
				need any parameters.  Simply run the program and you
				will be guided through the bootstrap process.
				<note>
					<title>Note</title>
					<para>
						Originally
						<application>genome-bootstrap</application>
						had all sorts of complicated command
						line flags.  While this was nice for
						scripting it was not a very pleasant
						UI.  Switching to a wizard was the
						simplist way to keep the documentation
						up to speed with the tool.  For
						scripting be sure to checkout the <link
							linkend="genome-GenomeBootstrap-Advanced">Advanced
							Mode</link> for
						<application>genome-bootstrap</application>.
					</para>
				</note>
			</para>
		</section>

		<section id="genome-GenomeBootstrap-Advanced">
			<title>Advanced Mode</title>
			<important>
				<title>Important</title>
				<para>
					Most casual users of the
					<application>genome-bootstrap</application> tool will
					not require this feature and can simply skip this
					section.
				</para>
			</important>

			<para>
				The advanced mode is most useful for scripting.  It
				also allows for more complicated use cases which
				operate outside of a normal Red Hat internal network.
				The only required input are the
				<emphasis>--fqdn</emphasis> and
				<emphasis>--repo</emphasis> flags.  The yaml
				configuration can either be specified as another flag
				or it can be piped to stdin.  If a
				<emphasis>--virt-path</emphasis> is provided then a
				<application>Koan</application> process will be
				started. See the <emphasis>--help</emphasis> for more
				information.
			</para>

			<screen>
# genome-bootstrap advanced --help
			</screen>

			<note>
				<title>Note</title>
				<para>
					The yaml fed to
					<application>genome-bootstrap</application>
					must be in the same format the Puppet expects
					for its external nodes.  You must know exactly
					which parameters are required for a given
					&PRODUCT; machine.  The nice thing is that this
					yaml can be obtained from <link
						linkend="genome-Genomed">Genomed</link>.
				</para>
			</note>
		</section>

		<section>
			<title>Bootstrap Parameters</title>
			<para>
				When using the
				<application>genome-bootstrap</application> wizard the
				user will be asked a series of questions.  The answers
				are used as parameters for configuring &PRODUCT;
				machines.  These parameters live server side and are
				accessible via <link
					linkend="genome-Genomed">Genomed</link>
			</para>

			<para>
				The
				nice thing about these parameters is that they can be used
				anywhere a normal variable can be used in Puppet
				manifests and templates. Some values are client
				specific such as:
				<itemizedlist>
					<listitem>
						<para>What cobbler server a node looks to for dependencies</para>
					</listitem>
					<listitem>
						<para>What machines a particular apache will proxy</para>
					</listitem>
					<listitem>
						<para>What server should be considered its upstream git repo</para>
					</listitem>
				</itemizedlist>
			</para>

			<para>
				Often you will want to change a parameter post bootstrap.
				This is usually because you want to point your machine
				at a different Puppetmaster or Cobbler server.  For
				help on this process see <link
					linkend="genome-ChangingAMachineParameter">the
					cookbook</link>.
			</para>
		</section>

		<section id="genome-PostBootstrapping">
			<title>Post bootstrapping</title>
			<para>
				After successfully running
				<application>genome-bootstrap</application> a
				<application>Koan</application> process will be started
				(that is, unless you specify
				<emphasis>--config-only</emphasis>).  You can watch the
				installation the same way you watch any Xen guest.  See
				the <link linkend="genome-Tooling-Xen">Xen
					documentation</link> for more details.
			</para>

			<para>
				Once it's finished start the guest back up to allow the
				<filename>/usr/sbin/genome-firstboot</filename> script
				to run.  This behaves exactly like the normal firstboot
				script on a Red Hat based system.
			</para>

			<note>
				<title>Note</title>
				<para>
					See <link linkend="genome-LoggingIn">the
						appendix</link> for information about
					logging in to koan'ed machines.
				</para>
			</note>

			<important>
				<title>Important</title>
				<para>
					It's also possible to bootstrap a machine that
					already has an OS.  See <link
						linkend="genome-NoKoanBootstrap">the
						cookbook</link> to see how this is
					done.
				</para>
			</important>

			<important>
				<title>Important</title>
				<para>
					Consistent machine provisioning in the
					&PRODUCT; is vital for efficient team
					collaboration.  There should be no post
					provisioning instructions needed to bring up a
					working machine.  The process for creating a
					Jboss ESB machine should be the same as a node
					on the Selenium grid.
				</para>
			</important>
		</section>
	</section>

	<section id="genome-Genomed">
		<title>genomed</title>
		<para> 
			The <application>genomed</application> service is a
			simple web app that serves as the canonical source of
			&PRODUCT; machine information used in compiling
			<application>puppet</application> configurations.  It's
			really quite simple so it's probably best explained by
			simply showing the link: http://[your
			repo hostname]/genome/nodes.html.  From there
			it should be simple to browse find the other features
			by exploration.
		</para>

		<para>
			It's also worth noting that most of the resources (this
			is a RESTful service) have several representations.
			Try changing the urls to end with
			<literal>xml</literal> or <literal>yaml</literal>.
		</para>

		<section id="genomed-configuration">
			<title>Configuration</title>
			<para>
				<application>genomed</application> has two
				configuration files.  One is located at
				<filename>/etc/genomed/config.yml</filename>
				and the other is at
				<filename>/etc/genome/machine_types.rb</filename>.
				The later of the two is the only one that
				deserves special attention.  This file is a
				traditional <emphasis>Domain Specific
					Language</emphasis> that gets executed
				by the <application>ruby</application>
				interpreter.  A documented sample configuration
				ships with the &REPORPM; which should be
				sufficient to get up and running quickly.  If
				changes are made to this file the
				<application>genomed</application> must be
				restarted.
			</para>
		</section>
    </section>

    <section id="genome-Cloudmasterd">
        <title>cloudmasterd</title>
        <para>
            The <application>cloudmasterd</application> is a RESTful
            web service running on a 
            <glossterm linkend="glossary-cloudmaster">cloud master</glossterm>
            that provides cloud computing capabilities across one or more 
            <glossterm linkend="glossary-cloudmember">cloud members</glossterm>.
        </para>
        <para>
            The <application>cloudmasterd</application> service also
            provides a simple status page indicating the current state
            of the cloud members.
        </para>

        <!--section id="cloudmasterd-technologies">
            <title>Technologies</title>
            <para>
                The <application>cloudmasterd</application> service is based on
                several technologies.
            </para>
            <variablelist>
                <varlistentry>
                    <term>ruby</term>
                    <listitem>
                        <para>The </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>func</term>
                    <listitem>
                        <para>Func rocks</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>koan</term>
                    <listitem>
                        <para>Koan rocks</para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </section-->
    </section>


	<section id="genome-sync">
		<title>genome-sync</title>
		<para>
			The goal of
			<application>genome-sync</application> is to
			make the process of syncronizing git
			repositories from one &PRODUCT; Repo to another
			as easy as possible.  The main mode
			<emphasis>start</emphasis> guides the
			user through the process. 
		</para>

		<para> 
			In the <emphasis>start</emphasis> mode work
			will be performed in a working directory.  The
			app will then iterate over each repository,
			asking the user what work to perform.  After
			this process has completed the user can publish
			their changes with the
			<emphasis>save</emphasis> mode.
		</para>

		<section id="genome-sync-usage">
			<title>Usage</title>
			<para>
				The following oneliners are in no particular order.
				<screen>
# Start the syncronization wizard
genome-sync start --repo=[remote Repo machine]
				</screen>

				<screen>
# Hard reset to a given repositories state (This is the fastest way to 
# get up and running with a newly created repo machine).
genome-sync start quick --repo=[remote Repo machine]
				</screen>

				<screen>
# Push content where it needs to go.  If puppet modules are updated the
# puppetmaster may need to be bounced.
genome-sync save
				</screen>

				<screen>
# Remove the working directory  
genome-sync clean
				</screen>

			</para>
			<important>
				<title>Important</title>
				<para>
					<application>genome-sync</application>
					must be run as the
					<emphasis>genome</emphasis>
					user.
				</para>
			</important>

			<note>
				<title>Note</title>
				<para>
					All
					<application>genome-sync</application>
					modes take the
					<emphasis>--help</emphasis>,
					<emphasis>--verbose</emphasis> and
					<emphasis>--workingdir</emphasis>
					flags.
				</para>
			</note>
		</section>
	</section>
</chapter>