Forklift: lifting Foreman into your environment

Forklift provides tools to create Foreman/Katello environments for development, testing and production configurations. Whether you are a developer wanting an environment to write code, or a user wanting to spin up the latest production environment for deployment or evaluation Forklift has you covered.

Using Forklift
Production Environments
Development Environments
Stable Boxes
Testing Environments
Provisioning environment
Plugins
Using Forklift as a Library
Troubleshooting
Vagrant
Packer

Using Forklift

Requirements

Vagrant - 2.2+ - Both the VirtualBox and Libvirt providers are tested
Ansible - 2.13+
Vagrant Libvirt provider plugin (if using Libvirt)
Virtualization enabled in BIOS

See Installing Vagrant for installation instructions.

Quickstart

The quickstart guide covers the basic steps to install Forklift so that you can quickly spin up a production test environment of the latest bleeding edge nightly Foreman or Katello build.

It assumes you have already Vagrant and libvirt installed, as well as the vagrant-libvirt and vagrant-hostmanager plugins. You also need Ansible, although if you don't have it or aren't sure if your version is compatible, you can simply create and activate a Python virtual environment and then pip install ansible-galaxy

Start by cloning the Forklift repository:

git clone https://github.com/theforeman/forklift.git
cd forklift

Then install the Ansible collections which are needed by Forklift:

ansible-galaxy collection install -r requirements.yml

When this is complete, simply follow the next section of this README to try out the latest nightly Foreman build using Forklift.

Foreman Nightly Box

Spin up your box and start using the latest nightly build of Foreman:

vagrant up centos9-stream-foreman-nightly

Access the CLI by first connecting to the box via SSH:

vagrant ssh centos9-stream-foreman-nightly

To access the WebUI, it's helpful to have the vagrant-hostmanager plugin installed, so that your Workstation will automatically be able to resolve the hostname of the box to its IP address.

Then you can simply open your browser and navigate to https://centos9-stream-foreman-nightly.<HOSTNAME>.example.com where <HOSTNAME> is replaced by the shortname of your workstation. The first time you do this you will need to accept the self-signed certificate.

By default, forklift deploys Foreman with admin/changeme as username and password.

Katello Nightly Box

Katello nightly boxes are available as well; simply change centos9-stream-foreman-nightly to centos9-stream-katello-nightly and the steps are otherwise exactly the same as above.

Additional Documentation

The remainder of this README contains helpful notes on additional topics that are likely to be of interest to users. For the most thorough and complete guides however, please refer to the docs page.

Katello Development Environment

If you want a Katello development environment, substitute your GitHub username for GITHUB_NICK and run:

cp vagrant/boxes.d/99-local.yaml{.example,}
sed -i "s/<REPLACE ME>/GITHUB_NICK/g" vagrant/boxes.d/99-local.yaml

Bring up the Katello Development Box:

vagrant up centos9-katello-devel

Once the box is running, you can access the shell via SSH and modify the source code in the ~/foreman and ~/katello directories. Then start the application to preview your changes:

cd ~/foreman
bundle exec foreman start

Before you can access the WebUI, you must first accept the self-signed certificate on port 3808 by visiting https://centos9-katello-devel.<HOSTNAME>.example.com:3808 in your browser.

Then, navigate to https://centos9-katello-devel.<HOSTNAME>.example.com/ to access the WebUI and preview your changes.

As above, <HOSTNAME> refers to the shortname of your hypervisor.

There is a much more detailed guide to the development environments in the full documentation.

See the developer documentation within the Foreman and Katello repositories for instructions on running the test suites, submitting pull requests, etc.

Using Playbooks and Roles without Vagrant

In case using Vagrant is not desired, ansible playbooks and roles from this repo can be used separately. This is useful if an existing host should be used for the installation, e.g. a beaker machine. In order to deploy the devel environment on host test.example.com, the following needs to be done:

on test.example.com machine, where the dev env should be deployed

useradd vagrant
echo "vagrant	ALL=(ALL)	NOPASSWD: ALL" >> /etc/sudoers.d/vagrant

in forklift checkout

echo -e "[devel]\ntest.example.com" > inventories/local_inventory
ansible-playbook --private-key=~/.ssh/id_rsa --user root --inventory inventories/local_inventory --extra-vars katello_devel_github_username=katello playbooks/devel.yml

In an example above, ansible was instructed to use specific private key (overriding the value from ansible.cfg), root user was set as ssh user and playbook variable was set, so that checkout will be made from katello user.

Other playbooks from playbooks/ directory can be used similarly, though some might need more variables and investigating their parameters is recommended first.

Credentials

By default forklift deploys Foreman with admin/changeme as username and password, please change this on production installs (either after the install, or by setting foreman_installer_admin_password during the initial deployment).

Poor man's DNS a.k.a /etc/hosts

For the multi-host setup, one of the easiest way of making the name resolution working with vagrant is using vagrant-hostmanager. Forklift supports this plugin by default. The only thing one needs to do is install the vagrant-hostmanager plugin:

vagrant plugin install vagrant-hostmanager

By default, the boxes are set with example.com domain.

If you're using NetworkManager, this advanced DNS configuration allows completely automated dns resolution using dnsmasq from host to guest and guest to guest.

You can disable hostmanager in vagrant/settings.yaml by setting hostmanager_enabled option.

When using a bridged network or with multiple network interfaces, the hostmanager would resolve the internal ip from the ssh-info, you can choose an ip of a particular network interface in vagrant/settings.yaml by setting hostmanager_ip_resolver_device option with the device name.

hostmanager_ip_resolver_device: 'eth1'

Adding Custom Boxes

Sometimes you want to spin up the same box type (e.g. centos9-katello-devel) from within the forklift directory. While this can be added to the Vagrantfile directly, updates to the forklift repository could wipe out your local changes. To help with this, you can define a custom box re-using the configuration within the Vagrantfile. To do so, create a 99-local.yaml file in vagrant/boxes.d/. For example, to create a custom box on CentOS 9 Stream with nightly and run the installers reset command:

my-nightly-staging:
  box: centos9-stream
  ansible:
    playbook: playbooks/katello.yml
    variables:
      katello_repositories_environment: staging
    verbose: vvv

Options:

| Option | Description | |:-------------------------|:----------------------------------------------------------------------| | box | the ':name' one of the defined boxes in the Vagrantfile | | bridged | deploy on Libvirt with a bridged networking configuration, value of this parameter should be the interface of the host (e.g. em1) | | memory | set the amount of memory (in megabytes) this box will consume | | cpus | set the number of cpus this box will use | | hostname | hostname to set on the box | | networks | custom networks to use in addition to the management network | | disk_size | spec

Forklift

Install / Use

README