Automatically install and configure Foreman, the open source infrastructure lifecycle management tool, and multiple Puppet Agent VMs using Vagrant and VirtualBox.
Introduction
In the last post, Installing Puppet Master and Agents on Multiple VM Using Vagrant and VirtualBox, we installed Puppet Master/Agent on VirtualBox VMs using Vagrant. Puppet Master is an excellent tool, but lacks the ease-of-use of Puppet Enterprise or Foreman. In this post, we will build an almost identical environment, substituting Foreman for Puppet Master.
According to Foreman’s website, “Foreman is an open source project that helps system administrators manage servers throughout their lifecycle, from provisioning and configuration to orchestration and monitoring. Using Puppet or Chef and Foreman’s smart proxy architecture, you can easily automate repetitive tasks, quickly deploy applications, and proactively manage change, both on-premise with VMs and bare-metal or in the cloud.”
Combined with Puppet Labs’ Open Source Puppet, Foreman is an effective solution to manage infrastructure and system configuration. Again, according to Foreman’s website, the Foreman installer is a collection of Puppet modules that installs everything required for a full working Foreman setup. The installer uses native OS packaging and adds necessary configuration for the complete installation. By default, the Foreman installer will configure:
- Apache HTTP with SSL (using a Puppet-signed certificate)
- Foreman running under mod_passenger
- Smart Proxy configured for Puppet, TFTP and SSL
- Puppet master running under mod_passenger
- Puppet agent configured
- TFTP server (under xinetd on Red Hat platforms)
For the average Systems Engineer or Software Developer, installing and configuring Foreman, Puppet Master, Apache, Puppet Agent, and the other associated software packages listed above, is daunting. If the installation doesn’t work properly, you must troubleshooting, or trying to remove and reinstall some or all the components.
A better solution is to automate the installation of Foreman into a Docker container, or on to a VM using Vagrant. Automating the installation process guarantees accuracy and consistency. The Vagrant VirtualBox VM can be snapshotted, moved to another host, or simply destroyed and recreated, if needed.
All code for this post is available on GitHub. However, it been updated as of 8/23/2015. Changes were required to fix compatibility issues with the latest versions of Puppet 4.x and Foreman. Additionally, the version of CentOS on all VMs was updated from 6.6 to 7.1 and the version of Foreman was updated from 1.7 to 1.9.
The Post’s Example
In this post, we will use Vagrant and VirtualBox to create three VMs. The VMs in this post will be build from a standard CentOS 6.5 x64 base Vagrant Box, located on Atlas. We will use a single JSON-format configuration file to automatically build all three VMs with Vagrant. As part of the provisioning process, using Vagrant’s shell provisioner, we will execute a bootstrap shell script. The script will install Foreman and it’s associated software on the first VM, and Puppet Agent on the two remaining VMs (aka Puppet ‘agent nodes’ or Foreman ‘hosts’).
Foreman does have the ability to provision on bare-metal infrastructure and public or private clouds. However, this example would simulate an environment where you have existing nodes you want to manage with Foreman.
The Foreman bootstrap script will also download several Puppet modules. To test Foreman once the provisioning is complete, import those module’s classes into Foreman and assign the classes to the hosts. The hosts will fetch and apply the configurations. You can then test for the installed instances of those module’s components on the puppet agent hosts.
Vagrant
To begin the process, we will use the JSON-format configuration file to create the three VMs, using Vagrant and VirtualBox.
{ "nodes": { "theforeman.example.com": { ":ip": "192.168.35.5", "ports": [], ":memory": 1024, ":bootstrap": "bootstrap-foreman.sh" }, "agent01.example.com": { ":ip": "192.168.35.10", "ports": [], ":memory": 1024, ":bootstrap": "bootstrap-node.sh" }, "agent02.example.com": { ":ip": "192.168.35.20", "ports": [], ":memory": 1024, ":bootstrap": "bootstrap-node.sh" } } }
The Vagrantfile
uses the JSON-format configuration file, to provision the three VMs, using a single ‘vagrant up
‘ command. That’s it, less than 30 lines of actual code in the Vagrantfile
to create as many VMs as you want. For this post’s example, we will not need to add any VirtualBox port mappings. However, that can also done from the JSON configuration file (see the READM.md for more directions).
If you have not used the CentOS Vagrant Box, it will take a few minutes the first time for Vagrant to download the it to the local Vagrant Box repository.
# -*- mode: ruby -*- # vi: set ft=ruby : # Builds single Foreman server and # multiple Puppet Agent Nodes using JSON config file # Gary A. Stafford - 01/15/2015 # read vm and chef configurations from JSON files nodes_config = (JSON.parse(File.read("nodes.json")))['nodes'] VAGRANTFILE_API_VERSION = "2" Vagrant.configure(VAGRANTFILE_API_VERSION) do |config| config.vm.box = "chef/centos-6.5" nodes_config.each do |node| node_name = node[0] # name of node node_values = node[1] # content of node config.vm.define node_name do |config| # configures all forwarding ports in JSON array ports = node_values['ports'] ports.each do |port| config.vm.network :forwarded_port, host: port[':host'], guest: port[':guest'], id: port[':id'] end config.vm.hostname = node_name config.vm.network :private_network, ip: node_values[':ip'] config.vm.provider :virtualbox do |vb| vb.customize ["modifyvm", :id, "--memory", node_values[':memory']] vb.customize ["modifyvm", :id, "--name", node_name] end config.vm.provision :shell, :path => node_values[':bootstrap'] end end end
Once provisioned, the three VMs, also called ‘Machines’ by Vagrant, should appear in Oracle VM VirtualBox Manager.
The name of the VMs, referenced in Vagrant commands, is the parent node name in the JSON configuration file (node_name
), such as, ‘vagrant ssh theforeman.example.com
‘.
Bootstrapping Foreman
As part of the Vagrant provisioning process (‘vagrant up
‘ command), a bootstrap script is executed on the VMs (shown below). This script will do almost of the installation and configuration work. Below is script for bootstrapping the Foreman VM.
#!/bin/sh # Run on VM to bootstrap Foreman server # Gary A. Stafford - 01/15/2015 if ps aux | grep "/usr/share/foreman" | grep -v grep 2> /dev/null then echo "Foreman appears to all already be installed. Exiting..." else # Configure /etc/hosts file echo "" | sudo tee --append /etc/hosts 2> /dev/null && \ echo "192.168.35.5 theforeman.example.com theforeman" | sudo tee --append /etc/hosts 2> /dev/null # Update system first sudo yum update -y # Install Foreman for CentOS 6 sudo rpm -ivh http://yum.puppetlabs.com/puppetlabs-release-el-6.noarch.rpm && \ sudo yum -y install epel-release http://yum.theforeman.org/releases/1.7/el6/x86_64/foreman-release.rpm && \ sudo yum -y install foreman-installer && \ sudo foreman-installer # First run the Puppet agent on the Foreman host which will send the first Puppet report to Foreman, # automatically creating the host in Foreman's database sudo puppet agent --test --waitforcert=60 # Install some optional puppet modules on Foreman server to get started... sudo puppet module install -i /etc/puppet/environments/production/modules puppetlabs-ntp sudo puppet module install -i /etc/puppet/environments/production/modules puppetlabs-git sudo puppet module install -i /etc/puppet/environments/production/modules puppetlabs-docker fi
Bootstrapping Puppet Agent Nodes
Below is script for bootstrapping the puppet agent nodes. The agent node bootstrap script was executed as part of the Vagrant provisioning process.
#!/bin/sh # Run on VM to bootstrap Puppet Agent nodes # Gary A. Stafford - 01/15/2015 if ps aux | grep "puppet agent" | grep -v grep 2> /dev/null then echo "Puppet Agent is already installed. Moving on..." else # Update system first sudo yum update -y # Install Puppet for CentOS 6 sudo rpm -ivh http://yum.puppetlabs.com/puppetlabs-release-el-6.noarch.rpm && \ sudo yum -y install puppet # Configure /etc/hosts file echo "" | sudo tee --append /etc/hosts 2> /dev/null && \ echo "192.168.35.5 theforeman.example.com theforeman" | sudo tee --append /etc/hosts 2> /dev/null # Add agent section to /etc/puppet/puppet.conf (sets run interval to 120 seconds) echo "" | sudo tee --append /etc/puppet/puppet.conf 2> /dev/null && \ echo " server = theforeman.example.com" | sudo tee --append /etc/puppet/puppet.conf 2> /dev/null && \ echo " runinterval = 120" | sudo tee --append /etc/puppet/puppet.conf 2> /dev/null sudo service puppet stop sudo service puppet start sudo puppet resource service puppet ensure=running enable=true sudo puppet agent --enable fi
Now that the Foreman is running, use the command, ‘vagrant ssh agent01.example.com
‘, to ssh into the first puppet agent node. Run the command below.
sudo puppet agent --test --waitforcert=60
The command above manually starts Puppet’s Certificate Signing Request (CSR) process, to generate the certificates and security credentials (private and public keys) generated by Puppet’s built-in certificate authority (CA). Each puppet agent node must have it certificate signed by the Foreman, first. According to Puppet’s website, “Before puppet agent nodes can retrieve their configuration catalogs, they need a signed certificate from the local Puppet certificate authority (CA). When using Puppet’s built-in CA (that is, not using an external CA), agents will submit a certificate signing request (CSR) to the CA Puppet Master (Foreman) and will retrieve a signed certificate once one is available.”
Open the Foreman browser-based interface, running at https://theforeman.example.com. Proceed to the ‘Infrastructure’ -> ‘Smart Proxies’ tab. Sign the certificate(s) from the agent nodes (shown below). The agent node will wait for the Foreman to sign the certificate, before continuing with the initial configuration.
Once the certificate signing process is complete, the host retrieves the client configuration from the Foreman and applies it to the hosts.
That’s it, you should now have one host running Foreman and two puppet agent nodes.
Testing Foreman
To test Foreman, import the classes from the Puppet modules installed with the Foreman bootstrap script.
Next, apply ntp, git, and Docker classes to both agent nodes (aka, Foreman ‘hosts’), as well as the Foreman node, itself.
Every two minutes, the two agent node hosts should fetch their latest configuration from Foreman and apply it. In a few minutes, check the times reported in the ‘Last report’ column on the ‘All Hosts’ tab. If the times are two minutes or less, Foreman and Puppet Agent are working. Note we changed the runinterval
to 120 seconds (‘120s’) in the bootstrap script to speed up the Puppet Agent updates for the sake of the demo. The normal default interval is 30 minutes. I recommend changing the agent node’s runinterval
back to 30 minutes (’30m’) on the hosts, once everything is working to save unnecessary use of resources.
Finally, to verify that the configuration was successfully applied to the hosts, check if ntp, git, and Docker are now running on the hosts.
Helpful Links
All the source code this project is on Github.
Foreman:
http://theforeman.org
Atlas – Discover Vagrant Boxes:
https://atlas.hashicorp.com/boxes/search
Learning Puppet – Basic Agent/Master Puppet
https://docs.puppetlabs.com/learning/agent_master_basic.html
Puppet Glossary (of terms):
https://docs.puppetlabs.com/references/glossary.html
#1 by wb on July 9, 2015 - 2:08 pm
This is a great article! Great work.
#2 by test on September 9, 2015 - 2:26 pm
Excellent writeup!!! Can you do one which integrates the foreman with the openstack
#3 by eiser on September 30, 2015 - 6:32 pm
Great article, thanks. Quick question, Is it possible to install foreman without the puppet server? I mean, I already have a puppet server running in a different vm, I would like to
#4 by Jon on February 3, 2016 - 4:16 pm
During foreman vargrant up you get prompted for a password when touching /etc/hosts, what is this password?
#5 by Gary A. Stafford on February 4, 2016 - 12:11 am
vagrant
#6 by chris on February 6, 2016 - 9:59 pm
Hey Gary,
this seems like a really good howto, except you’ve missed the ID10T’s guide section .
(Which I need) 😉
Basically I know Linux well and some basic puppet, but none of Vagrant/Foreman/Virtualbox/github/json …. (I’m really old school…)
Can you provide instructions on how to actually get all the SW onto my Centos 6.7 box and install/set it up?
Obviously I have root; I don’t bother with sudo.
Incidentally I’d like to stick with the Centos 6 version of the install please.
Feel free to email me if you need more info.
thx a lot,
Chris
#7 by Helper 1000 on September 27, 2016 - 8:03 am
Gary,
I am seeing the following issue. Please could you suggest whether some thing has been changed.
theforeman.example.com: SSH address: 127.0.0.1:2200
theforeman.example.com: SSH username: vagrant
theforeman.example.com: SSH auth method: private key
theforeman.example.com:
theforeman.example.com: Vagrant insecure key detected. Vagrant will automatically replace
theforeman.example.com: this with a newly generated keypair for better security.
theforeman.example.com:
theforeman.example.com: Inserting generated public key within guest…
theforeman.example.com: Removing insecure key from the guest if it’s present…
theforeman.example.com: Key inserted! Disconnecting and reconnecting using new SSH key…
#8 by Student on October 15, 2016 - 10:21 am
Gary,
Do you have any solution to this issue.
#9 by Kunalsing Thakur on August 17, 2017 - 5:27 am
Getting Error:-
Downloading VirtualBox Guest Additions ISO from http://download.virtualbox.org/virtualbox/5.1.26/VBoxGuestAdditions_5.1.26.iso
Progress: 100% (Rate: 116k/s, Estimated time remaining: –:–:–)
Copy iso file C:/Users/kunalsingt/.vagrant.d/tmp/VBoxGuestAdditions_5.1.26.iso into the box /tmp/VBoxGuestAdditions.iso
mount: /dev/loop0 is write-protected, mounting read-only
Installing Virtualbox Guest Additions 5.1.26 – guest version is 4.3.22
Verifying archive integrity… All good.
Uncompressing VirtualBox 5.1.26 Guest Additions for Linux………..
VirtualBox Guest Additions installer
Removing installed version 4.3.22 of VirtualBox Guest Additions…
Copying additional installer modules …
Installing additional modules …
vboxadd.sh: Starting the VirtualBox Guest Additions.
Could not find the X.Org or XFree86 Window System, skipping.
An error occurred during installation of VirtualBox Guest Additions 5.1.26. Some functionality may not work as intended.
In most cases it is OK that the “Window System drivers” installation failed.
Redirecting to /bin/systemctl start vboxadd.service
Cleaning up downloaded VirtualBox Guest Additions ISO…
FAILED: Permission denied @ unlink_internal – C:/Users/kunalsingt/.vagrant.d/tmp/VBoxGuestAdditions_5.1.26.iso
You might want to delete this file manually: C:/Users/kunalsingt/.vagrant.d/tmp/VBoxGuestAdditions_5.1.26.iso
Got different reports about installed GuestAdditions version:
Virtualbox on your host claims: 4.3.22
VBoxService inside the vm claims: 5.1.26
Going on, assuming VBoxService is correct…
Got different reports about installed GuestAdditions version:
Virtualbox on your host claims: 4.3.22
VBoxService inside the vm claims: 5.1.26
Going on, assuming VBoxService is correct…
Got different reports about installed GuestAdditions version:
Virtualbox on your host claims: 4.3.22
VBoxService inside the vm claims: 5.1.26
Going on, assuming VBoxService is correct…
Restarting VM to apply changes…