Genesis

Genesis is a tool for data center automation. The primary motivation for developing Genesis at Tumblr was to streamline the process of discovering new machines and reporting their hardware details to Collins, our inventory management system, without having to do a bunch of data entry by hand. In addition, we've also extended Genesis to be a convenient way to do hardware configuration such as altering BIOS settings and configuring RAID cards before provisioning an operating system on to the host.

From a high-level point of view, Genesis consists of a stripped down linux image suitable to boot over PXE and a ruby DSL for describing tasks to be executed on the host.

This repository also includes a test environment which is suitable for building the linux image.

genesis_framework

genesis_retryingfetcher

genesis_promptcli

The Genesis framework and supporting gem can be found in src

Tasks are created using the Genesis DSL which makes it easy to run commands, install packages, etc. in the stripped down environment.

Examples of tasks are the TimedBurnin task, which performs a stress test on the system to rule out hardware errors before putting it into production, and BiosConfigrR720, which sets up the BIOS on Dell R720s just the way we want it.

There are a couple of systems apart from Genesis that need to be in place for a successful deployment. These are

• a DHCP server,
• a TFTP server,
• and a file server (serving static files over HTTP)

More detail on setting these up is documented in INSTALL.md.

When a machine boots, the DHCP server tells the PXE firmware to chain boot into iPXE. We then use iPXE to present a list of menu choices, fetched from a remote server. When the user makes a choice we load the Genesis kernel and initrd (from the file server) along with parameters on the kernel command line. Once the Genesis OS has loaded, the genesis-bootloader fetches and executes a ruby script describing a second stage where we install gems, a few base RPMs, and fetch our tasks from a remote server. Finally, we execute the relevant tasks.

For a real world example; consider a brand new server that boots up. It makes a DHCP request and loads the iPXE menu. In this case, we know that we haven't seen this MAC address before, so it must be a new machine. We boot Genesis in to discovery mode, where the tasks it runs are written to fetch all the hardware information we need and report it back to the Collins. In our setup this includes information such as hard drives and their capacity and the number of CPUs, but also more detailed information such as service tags, which memory banks are in use, and even the name of the switchports all interfaces are connected to. We then follow this up with 48 hours of hardware stress-test using the TimedBurnin task.

To avoid testing Genesis in production, we've set up a virtual test environment based on VirtualBox. This allows for end-to-end testing of changes to the framework, new tasks, etc.

More information about the test environment and setting it up can be found in testenv/README.md.

To make it easy to get started with genesis, we have included a Dockerfile that will allow you to compile a bootable live image without needing a lot of client side configuration. If you have docker running on your machine and just want to build the latest images:

# mkdir output
# docker run --privileged=true -v $(pwd)/output:/output tumblr/genesis-builder
# ls output

It is possible to customize the image with extra content specific to your site, such as adding iptables rules. To do so, create a directory and put your custom code into one or more files named <something>.content. Bind mount this directory, read-only, as /conf when running genesis-builder. Any file with the .content extension under /conf will be added to the build. See bootcd/iptable.content.sample for an example.

# docker run --privileged=true -v $(pwd)/bootcd:/conf:ro -v $(pwd)/output:/output tumblr/genesis-builder
# ls output

To build a custom image, if you have tweaked something about genesis, you can present build a custom builder image:

# docker build -f Dockerfile -t genesis-builder .
# docker run --privileged=true -v $(pwd)/output:/output genesis-builder
# ls output

NOTE: the genesis-builder uses livecd-creator which depends on loopback mounts. These don't currently (2016-08-25) work with Docker for Mac. On linux you should make sure you have at least 2 spare /dev/loop* devices, losetup -a will show which ones are busy and mknod /dev/loop# -m0600 b 7 # a couple if needed. Also you may need to cleanup/free (losetup -d) devices after this has run.

Please feel free to open issues on GitHub for any feedback or problems you might run in to. We also actively encourage pull requests. Please also make sure to check CONTRIBUTING.md.

Copyright 2016 Tumblr Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.