This chapter contains many useful &PRODUCT; recipes. While a solid understanding of the toolset is always preferred this chapter is meant to be the user's reference manual.

Virtualization is by no means a requirement to make use of the &PRODUCT; tooling, though it is the more common than "bare metal" provisioning. The machine used to host virtual machines is called the Cloud Appliance. As the name suggests, there can be one-to-many physical machines. The first goal of this machine is to provide and environment to host virtual machines and for that reason are always provisioned on "bare metal". The second is to provide an effective way to manage resources amongst underutilized commodity hardware. Since virtualization plays such a key role in the &PRODUCT; environment these machines amongst the first that users of the &PRODUCT; tooling desire to get up and running quickly. One of the main goals of the current Cloud machine tooling is to Do the simplest thing that could possibly work. This functionality, implemented through Func modules, will most likely be entirely replaced with ovirt.

The first step is to install the genome-replace-self RPM. You can do this by running one of the following commands: rpm -Uvh --force http://ftp.redhat.com/pub/redhat/genome/yum/Fedora-9-genome-noarch/genome-replace-self-1.0.0-2.fc9.noarch.rpm If you want to install the RPM from your local Genome server, the format would be: rpm -Uvh --force http://$GENOME_MACHINE/cobbler/repo_mirror/Fedora-9-genome-noarch/genome-replace-self-1.0.0-2.fc9.noarch.rpm Cloud Appliances use genome-replace-self to get up and running quickly. The key to using genome-replace-self to provision a Cloud Appliance is to: Use a Cloud profile. Set the -m (metadata) flag appropriately. The value for this flag varies depending if it is the certmaster or a minion in func parlance. For the master set -m to certmaster=localhost For the minion set -m to certmaster=[Any previously created Cloud master]

The Repo Appliance provisioning story is fairly straight forward: install the &REPORPM; (either via kickstart or manually) Replicate cobbler to pull down the bits and kickstarts Syncronize the git repositories from another Repo Appliance. Define access controls

There are several options on how to go about this step. If another Repo Appliance is already available genome-replace-self or koan based options are generally preferred since they require fewer manual steps.

# See what profiles are available koan -s [remote Repo Appliance] --list=profiles # If choosing a virtual machine koan -s [remote Repo Appliance] --virt --virt-name=[Any name] --profile=[Profile from first step] --virt-path=[Usually a Volume Group or path to a file]

The only step needed for this is to use genome-replace-self and pass in a Repo profile.

If installing this on a machine that already has an operating system (OS) installed simply yum install genome-repo. In case the &REPORPM; is not available in the stock yum repositories for your OS you can grab the RPMs from any other &PRODUCT; Repo Appliance at http://[hostname]/cobbler/repo_mirror/[distro]-genome-noarch. Whenever installing the &REPORPM; manually there is one other step that needs to happen to properly configure a Repo Appliance. /sbin/service genome-repo-bootstrap start This step is designed to work "offline" since all the external dependencies are pulled down via the &REPORPM;. That being said there are external factors than can cause it to fail. If you suspect a Repo Appliance is not configured correctly it is always safe to run this command multiple times as puppet will only perform outstanding tasks.

The simplest way to do this is to use cobbler's replicate functionality. cobbler replicate --master=[remote Genome Repo machine] --full-data-sync For more advanced usage see the cobbler manpage. Currently the use of cobbler replicate requires the user to know the root password on the master cobbler server (the remote Repo machine). This is less than desirable but for now the default password is &GENOMEPASSWORD;. Technically it is also possible to configure cobbler by hand. This obviously requires a more in depth understanding of cobbler and is outside the scope of this document.

Since this is a newly provisioned Repo Appliance the fastest way to get up and running is to run: # "reset --hard" to all the git repositories on a remote Repo genome-sync start quick --repo=[remote Repo Appliance] # Push all the repos where they need to go on the new Repo Appliance genome-sync save If any new puppet modules are saved the puppetmaster will have to be restarted for them to be available.

All machines in the &PRODUCT; environment have a default root password set as detailed in the appendix. By default Repo Appliances have a local user named &GENOMEUSER; who owns all content under /pub/git. Out of the box there is no password set and users of Repo Appliances should feel free to use whatever method of authentication they choose. Typical methods of authentication are: Setting a password Using SSH public key authentication There is a good chance &PRODUCT; will make use of FreeIPA someday.

Due to the volatile nature of &PRODUCT; machines there occasionally comes a need to clean up SSL certificates. To clean up all Puppet certs you can simply stop the puppetmaster (in the case of a Repo Application) and puppetd services and then remove /var/lib/puppet/ssl. When you start the services back up the certificates will be created anew. Sometimes the Puppetmaster will have a cert that corresponds to a machine previously provisioned with the same hostname. Our bootstrap process cleans this up automatically but it's not hard to get into a state where it will need to be cleaned manually on the Puppetmaster side. Luckily this is easy to do. The error from Puppet even hints at how to do it. Login to your Repo Appliance as the local user (usually genome) and run sudo /usr/sbin/puppetca --clean [your hostname] sudo access to puppetca has been given to the local &PRODUCT; user.

This particular recipe should be considered advanced. There are plenty of ways to make a custom system incompatible with the &PRODUCT; tooling. Be sure you are comfortable with how &FIRSTBOOTFILE; works. In some cases you might not want to reinstall the OS on a system in the &PRODUCT; environment. This happens mostly for laptops where a developer simply wants a build environment so they can work "off the grid". For this recipe the user simply needs to pass the --config-only option to genome-bootstrap to create the needed server-side configuration. Once that is done it's just a matter of installing the genome-firstboot RPM and editing /etc/sysconfig/genome-firstboot. Here's an example config file: RUN_BOOTSTRAP=YES export GENOME_REPO=genome-staging-repo.usersys.redhat.com export FQDN=arch-repo.usersys.redhat.com It's always best to grab the RPMs from the &PRODUCT; Repo you are going to use. That way you can be certain you are using a compatible version.

There are several tools and config files that need to know what types of machines are available for provisioning on a particular Repo machine. To simplify this process &PRODUCT; includes a DSL (Domain Specific Language) for describing the machines available. At a very high level the only thing that needs to be done is edit /etc/genome/machine_types.rb on a Repo Appliance. The comments are the best documentation for the details. The trick is that this file is typically controlled by puppet. genome-sync is a great way to handle moving custom machine types from one Repo Appliance to another.

It's convenient to be able to change bootstrapped parameters. One typical use case is if you would like to point your machine to a different puppet master. To do this simplify access the genomed running on the &PRODUCT; Repo that your machine is subscribed to and update the yaml file. Once the yaml has been updated you probably want to manually run Puppet (puppetd --test) to update the machine's configuration.

Browse to http://[repo]/genome/nodes/[hostname].html and update the yaml file. Edit the &PUPPETCONFFILE; and change any instances of the current puppet master hostname to the hostname of the new puppet master Make sure there exists a machine configuration for this host on the other repo machine. If not simply create a new one using genomed or by using genome-bootstrap --config-only. Remove the &PUPPET_SSL_DIR; directory, this will be recreated with a valid set of certificates and keys Run puppetd --test to make sure everything worked. If all goes well, start the puppet client and you're done.

This recipe involves a situation where you have 4 commits, with 1,2, and 4 being related and commit 3 just in the middle. Ideally, before you submit this, you would like to combine 1,2, and 4 into a single commit and then have commit 3 and a second, isolated commit. Run the following to prime you repository with this scenario: cd ~ mkdir git-test cd git-test git init touch a.txt git add a.txt git-commit -m "Adding one file" touch b.txt git add b.txt git-commit -m "Adding another file" touch different.txt git add different.txt git-commit -m "Commiting something entirely different" touch c.txt git add c.txt git-commit -m "Adding yet another file" Correcting the problem: Look at the log history and get the id of the initial commit revision: git log Start a working branch and check it out to serve as the cleanup branch, starting at the initial commit: git checkout -b cleanup [REVISION] Confirm you are now working on the new branch: git status Confirm the log history only contains the initial commit: git log Now, since we want to add two more things to this commit and re-commit it. First, you need to get the commit revisions from the master branch: git log master Now, you need to cherry pick commits 2 and 4 without commiting: git-cherry-pick -n [REVISION 2] git-cherry-pick -n [REVISION 4] Now you need to revise the current commit comment to include what was done in revisions 2 and 4 git-commit --revise At this point, you have combined 1,2, and 4 into a single commit. The last step is to cherry pick and commit revision 3: git-cherry-pick [REVISION 3] Now you can push the changes from this branch to the desired public repository.