1. Introduction to provisioning
Provisioning is a process that starts with a bare physical or virtual machine and ends with a fully configured, ready-to-use operating system. Using Foreman, you can define and automate fine-grained provisioning for a large number of hosts.
1.1. Provisioning methods in Foreman
With Foreman, you can provision hosts by using multiple methods.
- Bare-Metal Provisioning
-
Foreman provisions bare-metal hosts primarily by using PXE boot and MAC address identification. When provisioning bare-metal hosts with Foreman, you can do the following:
-
Create host entries and specify the MAC address of the physical host to provision.
-
Boot blank hosts to use the Foreman Discovery service, which creates a pool of hosts that are ready to be provisioned.
-
Boot and provision hosts by using PXE-less methods.
-
- Cloud Providers
-
Foreman connects to private and public cloud providers to provision instances of hosts from images that are stored with the cloud environment. When provisioning from cloud with Foreman, you can do the following:
-
Select which hardware profile or flavor to use.
-
Provision cloud instances from specific providers by using their APIs.
-
- Virtualization Infrastructure
-
Foreman connects to virtualization infrastructure services, such as oVirt and VMware. When provisioning virtual machines with Foreman, you can do the following:
-
Provision virtual machines from virtual image templates.
-
Use the same PXE-based boot methods as bare-metal providers.
-
1.2. Supported cloud providers
You can connect the following cloud providers as compute resources to Foreman:
-
OpenStack
-
Amazon EC2
-
Google Compute Engine
-
Microsoft Azure
1.3. Supported virtualization infrastructures
You can connect the following virtualization infrastructures as compute resources to Foreman:
-
KVM (libvirt)
-
oVirt
-
VMware
-
KubeVirt
-
Proxmox
1.4. Network boot provisioning workflow
The provisioning process follows a basic PXE workflow:
-
You create a host and select a domain and subnet. Foreman requests an available IP address from the DHCP Smart Proxy server that is associated with the subnet or from the PostgreSQL database in Foreman. Foreman loads this IP address into the IP address field in the Create Host window. When you complete all the options for the new host, submit the new host request.
-
Depending on the configuration specifications of the host and its domain and subnet, Foreman creates the following settings:
-
A DHCP record on Smart Proxy server that is associated with the subnet.
-
A forward DNS record on Smart Proxy server that is associated with the domain.
-
A reverse DNS record on the DNS Smart Proxy server that is associated with the subnet.
-
PXELinux, Grub, Grub2, and iPXE configuration files for the host in the TFTP Smart Proxy server that is associated with the subnet.
-
A Puppet certificate on the associated Puppet server.
-
A realm on the associated identity server.
-
-
The host is configured to boot from the network as the first device and HDD as the second device.
-
The new host requests a DHCP reservation from the DHCP server.
-
The DHCP server responds to the reservation request and returns TFTP
next-server
andfilename
options. -
The host requests the boot loader and menu from the TFTP server according to the PXELoader setting.
-
A boot loader is returned over TFTP.
-
The boot loader fetches configuration for the host through its provisioning interface MAC address.
-
The boot loader fetches the operating system installer kernel, init RAM disk, and boot parameters.
-
The installer requests the provisioning template from Foreman.
-
Foreman renders the provision template and returns the result to the host.
-
The installer performs installation of the operating system.
-
The installer registers the host to Foreman using Subscription Manager.
-
The installer notifies Foreman of a successful build in the
postinstall
script.
-
-
The PXE configuration files revert to a local boot template.
-
The host reboots.
-
The new host requests a DHCP reservation from the DHCP server.
-
The DHCP server responds to the reservation request and returns TFTP
next-server
andfilename
options. -
The host requests the bootloader and menu from the TFTP server according to the PXELoader setting.
-
A boot loader is returned over TFTP.
-
The boot loader fetches the configuration for the host through its provision interface MAC address.
-
The boot loader initiates boot from the local drive.
-
If you configured the host to use any Puppet classes, the host configures itself using the modules.
The fully provisioned host performs the following workflow:
-
The host is configured to boot from the network as the first device and HDD as the second device.
-
The new host requests a DHCP reservation from the DHCP server.
-
The DHCP server responds to the reservation request and returns TFTP
next-server
andfilename
options. -
The host requests the boot loader and menu from the TFTP server according to the PXELoader setting.
-
A boot loader is returned over TFTP.
-
The boot loader fetches the configuration settings for the host through its provisioning interface MAC address.
-
For BIOS hosts:
-
The boot loader returns non-bootable device so BIOS skips to the next device (boot from HDD).
-
-
For EFI hosts:
-
The boot loader finds Grub2 on a ESP partition and chainboots it.
-
-
If the host is unknown to Foreman, a default bootloader configuration is provided. When Discovery service is enabled, it boots into discovery, otherwise it boots from HDD.
This workflow differs depending on custom options. For example:
- Discovery
-
If you use the discovery service, Foreman automatically detects the MAC address of the new host and restarts the host after you submit a request. Note that TCP port 8443 must be reachable by the Smart Proxy to which the host is attached for Foreman to restart the host.
- PXE-less Provisioning
-
After you submit a new host request, you must boot the specific host with the boot disk that you download from Foreman and transfer using a USB port of the host.
- Compute Resources
-
Foreman creates the virtual machine and retrieves the MAC address and stores the MAC address in Foreman. If you use image-based provisioning, the host does not follow the standard PXE boot and operating system installation. The compute resource creates a copy of the image for the host to use. Depending on image settings in Foreman, seed data can be passed in for initial configuration, for example using
cloud-init
. Foreman can connect using SSH to the host and execute a template to finish the customization.
1.5. Required boot order for network boot
- For physical or virtual BIOS hosts
-
-
Set the first booting device as boot configuration with network.
-
Set the second booting device as boot from hard drive. Foreman manages TFTP boot configuration files, so hosts can be easily provisioned just by rebooting.
-
- For physical or virtual EFI hosts
-
-
Set the first booting device as boot configuration with network.
-
Depending on the EFI firmware type and configuration, the OS installer typically configures the OS boot loader as the first entry.
-
To reboot into installer again, use the
efibootmgr
utility to switch back to boot from network.
-
2. Configuring provisioning resources
2.1. Provisioning contexts
A provisioning context is the combination of an organization and location that you specify for Foreman components. The organization and location that a component belongs to sets the ownership and access for that component.
Organizations divide Foreman components into logical groups based on ownership, purpose, content, security level, and other divisions. You can create and manage multiple organizations through Foreman and assign components to each individual organization. This ensures Foreman server provisions hosts within a certain organization and only uses components that are assigned to that organization. For more information about organizations, see Managing Organizations in Managing organizations and locations in Foreman.
Locations function similar to organizations. The difference is that locations are based on physical or geographical setting. Users can nest locations in a hierarchy. For more information about locations, see Managing Locations in Managing organizations and locations in Foreman.
2.2. Setting the provisioning context
When you set a provisioning context, you define which organization and location to use for provisioning hosts.
The organization and location menus are located in the menu bar, on the upper left of the Foreman web UI. If you have not selected an organization and location to use, the menu displays: Any Organization and Any Location.
-
Click Any Organization and select the organization.
-
Click Any Location and select the location to use.
Each user can set their default provisioning context in their account settings. Click the user name in the upper right of the Foreman web UI and select My account to edit your user account settings.
-
When using the CLI, include either
--organization
or--organization-label
and--location
or--location-id
as an option. For example:# hammer host list --organization "My_Organization" --location "My_Location"
This command outputs hosts allocated to
My_Organization
andMy_Location
.
2.3. Creating operating systems
An operating system is a collection of resources that define how Foreman server installs a base operating system on a host. Operating system entries combine previously defined resources, such as installation media, partition tables, provisioning templates, and others.
Importing operating systems from Red Hat’s CDN creates new entries on the Hosts > Provisioning Setup > Operating Systems page. To import operating systems from Red Hat’s CDN, enable the Red Hat repositories of the operating systems and synchronize the repositories to Foreman. For more information, see Enabling Red Hat Repositories and Synchronizing Repositories in Managing content.
You can also add custom operating systems using the following procedure. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > Operating systems and click New Operating system.
-
In the Name field, enter a name to represent the operating system entry.
-
In the Major field, enter the number that corresponds to the major version of the operating system.
-
In the Minor field, enter the number that corresponds to the minor version of the operating system.
-
In the Description field, enter a description of the operating system.
-
From the Family list, select the operating system’s family.
-
From the Root Password Hash list, select the encoding method for the root password.
-
From the Architectures list, select the architectures that the operating system uses.
-
Click the Partition table tab and select the possible partition tables that apply to this operating system.
-
Click the Installation Media tab and enter the information for the installation media source. For more information, see Adding Installation Media to Foreman.
-
Click the Templates tab and select a PXELinux template, a Provisioning template, and a Finish template for your operating system to use. You can select other templates, for example an iPXE template, if you plan to use iPXE for provisioning.
-
Click Submit to save your provisioning template.
-
Create the operating system using the
hammer os create
command:# hammer os create \ --architectures "x86_64" \ --description "My_Operating_System" \ --family "Redhat" \ --major 8 \ --media "Red Hat" \ --minor 8 \ --name "Enterprise Linux" \ --partition-tables "My_Partition_Table" \ --provisioning-templates "My_Provisioning_Template"
2.4. Creating an operating system for Debian 12
Create an operating system in Foreman to provision hosts running Debian 12. This example creates an operating system entry for Debian 12.
-
In the Foreman web UI, navigate to Hosts > Provisioning Setup > Operating Systems.
-
Click Create Operating System to create an operating system entry for Debian.
-
Enter
Debian 12
as Name for the operating system. Choose a name as reported by Ansible, Puppet, or Salt as fact. -
Set the Major Version to
12
. -
Leave the Minor Version field empty.
-
Set the Release Name to
bookworm
for Debian 12. -
On the Partition Table tab, select the
Preseed
partition table.For more information, see Creating partition tables.
-
On the Templates tab, select the
Preseed Finish
template as Finish template, thePreseed
template as Provisioning Template, and thePreseed PXELinux
template as PXELinux template.For more information, see Creating provisioning templates.
-
Click Submit to save the operating system entry for Debian.
2.5. Creating an operating system for Debian 11
Create an operating system in Foreman to provision hosts running Debian 11. This example creates an operating system entry for Debian 11.
-
In the Foreman web UI, navigate to Hosts > Provisioning Setup > Operating Systems.
-
Click Create Operating System to create an operating system entry for Debian.
-
Enter
Debian 11
as Name for the operating system. Choose a name as reported by Ansible, Puppet, or Salt as fact. -
Set the Major Version to
11
. -
Leave the Minor Version field empty.
-
Set the Release Name to
bullseye
for Debian 11. -
On the Partition Table tab, select the
Preseed
partition table.For more information, see Creating partition tables.
-
On the Templates tab, select the
Preseed Finish
template as Finish template, thePreseed
template as Provisioning Template, and thePreseed PXELinux
template as PXELinux template.For more information, see Creating provisioning templates.
-
Click Submit to save the operating system entry for Debian.
2.6. Creating an operating system for Ubuntu 24.04
Create an operating system in Foreman to provision hosts running Ubuntu 24.04. This example creates an operating system entry for Ubuntu 24.04.
-
In the Foreman web UI, navigate to Hosts > Provisioning Setup > Operating Systems.
-
Click Create Operating System to create an operating system entry for Ubuntu.
-
Enter
Ubuntu 24.04
as Name for the operating system. Choose a name as reported by Ansible, Puppet, or Salt as fact. -
Set the Major Version to
24.04
. -
Leave the Minor Version field empty.
-
Set the Release Name to
noble
for Ubuntu 24.04. -
On the Partition Table tab, select the
Preseed
partition table.For more information, see Creating partition tables.
-
On the Templates tab, select the
Preseed Finish
template as Finish template, thePreseed
template as Provisioning Template, and thePreseed PXELinux
template as PXELinux template.For more information, see Creating provisioning templates.
-
Click Submit to save the operating system entry for Ubuntu.
2.7. Creating an operating system for Ubuntu 22.04
Create an operating system in Foreman to provision hosts running Ubuntu 22.04. This example creates an operating system entry for Ubuntu 22.04.
-
In the Foreman web UI, navigate to Hosts > Provisioning Setup > Operating Systems.
-
Click Create Operating System to create an operating system entry for Ubuntu.
-
Enter
Ubuntu 22.04
as Name for the operating system. Choose a name as reported by Ansible, Puppet, or Salt as fact. -
Set the Major Version to
22.04
. -
Leave the Minor Version field empty.
-
Set the Release Name to
jammy
for Ubuntu 22.04. -
On the Partition Table tab, select the
Preseed
partition table.For more information, see Creating partition tables.
-
On the Templates tab, select the
Preseed Finish
template as Finish template, thePreseed
template as Provisioning Template, and thePreseed PXELinux
template as PXELinux template.For more information, see Creating provisioning templates.
-
Click Submit to save the operating system entry for Ubuntu.
2.8. Updating the details of multiple operating systems
Use this procedure to update the details of multiple operating systems.
This example shows you how to assign each operating system a partition table called Kickstart default
, a configuration template called Kickstart default PXELinux
, and a provisioning template called Kickstart Default
.
-
On Foreman server, run the following Bash script:
PARTID=$(hammer --csv partition-table list | grep "Kickstart default," | cut -d, -f1) PXEID=$(hammer --csv template list --per-page=1000 | grep "Kickstart default PXELinux" | cut -d, -f1) SATID=$(hammer --csv template list --per-page=1000 | grep "provision" | grep ",Kickstart default" | cut -d, -f1) for i in $(hammer --no-headers --csv os list | awk -F, {'print $1'}) do hammer partition-table add-operatingsystem --id="${PARTID}" --operatingsystem-id="${i}" hammer template add-operatingsystem --id="${PXEID}" --operatingsystem-id="${i}" hammer os set-default-template --id="${i}" --config-template-id=${PXEID} hammer os add-config-template --id="${i}" --config-template-id=${SATID} hammer os set-default-template --id="${i}" --config-template-id=${SATID} done
-
Display information about the updated operating system to verify that the operating system is updated correctly:
# hammer os info --id 1
2.9. Creating architectures
An architecture in Foreman represents a logical grouping of hosts and operating systems. Architectures are created by Foreman automatically when hosts check in with Puppet. The x86_64 architecture is already preset in Foreman.
Use this procedure to create an architecture in Foreman.
-
In the Foreman web UI, navigate to Hosts > Provisioning Setup > Architectures.
-
Click Create Architecture.
-
In the Name field, enter a name for the architecture.
-
From the Operating Systems list, select an operating system. If none are available, you can create and assign them under Hosts > Provisioning Setup > Operating Systems.
-
Click Submit.
-
Enter the
hammer architecture create
command to create an architecture. Specify its name and operating systems that include this architecture:# hammer architecture create \ --name "My_Architecture" \ --operatingsystems "My_Operating_System"
2.10. Creating hardware models
Use this procedure to create a hardware model in Foreman so that you can specify which hardware model a host uses.
-
In the Foreman web UI, navigate to Hosts > Provisioning Setup > Hardware Models.
-
Click Create Model.
-
In the Name field, enter a name for the hardware model.
-
Optionally, in the Hardware Model and Vendor Class fields, you can enter corresponding information for your system.
-
In the Info field, enter a description of the hardware model.
-
Click Submit to save your hardware model.
-
Create a hardware model using the
hammer model create
command. The only required parameter is--name
. Optionally, enter the hardware model with the--hardware-model
option, a vendor class with the--vendor-class
option, and a description with the--info
option:# hammer model create \ --hardware-model "My_Hardware_Model" \ --info "My_Description" \ --name "My_Hardware_Model_Name" \ --vendor-class "My_Vendor_Class"
2.11. Using a synchronized Kickstart repository for a host’s operating system
The following feature is provided by the Katello plugin.
Foreman contains a set of synchronized Kickstart repositories that you use to install the provisioned host’s operating system. For more information about adding repositories, see Syncing Repositories in Managing content.
Use this procedure to set up a Kickstart repository.
You must enable both BaseOS and Appstream Kickstart before provisioning.
-
Add the synchronized Kickstart repository that you want to use to the existing content view, or create a new content view and add the kickstart repository.
For Red Hat Enterprise Linux 8, ensure that you add both Red Hat Enterprise Linux 8 for x86_64 - AppStream Kickstart x86_64 8 and Red Hat Enterprise Linux 8 for x86_64 - BaseOS Kickstart x86_64 8 repositories.
-
Publish a new version of the content view where the Kickstart repository is added and promote it to a required lifecycle environment. For more information, see Managing content views in Managing content.
-
When you create a host, in the Operating System tab, for Media Selection, select the Synced Content checkbox.
To view the Kickstart tree, enter the following command:
# hammer medium list --organization "My_Organization"
2.12. Adding installation media to Foreman
Installation media are sources of packages that Foreman server uses to install a base operating system on a machine from an external repository. When you install the Katello plugin, you can download packages from a Pulp mirror. In this case, installation media are ignored.
You can view installation media by navigating to Hosts > Provisioning Setup > Installation Media.
Installation media must be in the format of an operating system installation tree and must be accessible from the machine hosting the installer through an HTTP URL.
Note
|
Other protocols, such as HTTPS or NFS, are known to work but have not been tested. Foreman community recommends using HTTP. You can hypothetically use NFS share for PXE-based provisioning in a semi-automated way by copying the |
By default, Foreman includes installation media for some official Linux distributions. Note that some of those installation media are targeted for a specific version of an operating system. For example CentOS mirror (7.x) must be used for CentOS 7 or earlier, and CentOS mirror (8.x) must be used for CentOS 8 or later.
If you want to improve download performance when using installation media to install operating systems on multiple hosts, you must modify the Path of the installation medium to point to the closest mirror or a local copy.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > Provisioning Setup > Installation Media.
-
Click Create Medium.
-
In the Name field, enter a name to represent the installation media entry.
-
In the Path enter the URL that contains the installation tree. You can use following variables in the path to represent multiple different system architectures and versions:
-
$arch
– The system architecture. -
$version
– The operating system version. -
$major
– The operating system major version. -
$minor
– The operating system minor version.Example HTTP path:
http://download.example.com/centos/$version/Server/$arch/os/
Example NFS path:
nfs://download.example.com/centos/$version/Server/$arch/os/
Synchronized content on Smart Proxy servers always uses an HTTP path. Smart Proxy server managed content does not support NFS paths.
-
-
From the Operating system family list, select the distribution or family of the installation medium. For example, CentOS and Fedora are in the
Red Hat
family. Debian and Ubuntu belong to theDebian
family. -
Click the Organizations and Locations tabs, to change the provisioning context. Foreman server adds the installation medium to the set provisioning context.
-
Click Submit to save your installation medium.
-
Create the installation medium using the
hammer medium create
command:# hammer medium create \ --locations "My_Location" \ --name "My_Operating_System" \ --organizations "My_Organization" \ --os-family "Redhat" \ --path "http://download.example.com/centos/$version/Server/$arch/os/"
2.13. Creating an installation medium for Debian/Ubuntu
Create an installation medium in Foreman to provision hosts running Debian/Ubuntu.
-
In the Foreman web UI, navigate to Hosts > Provisioning Setup > Installation Media.
-
Click Create Medium to create an installation medium entry.
-
Enter a Name for the installation medium.
-
Set the Path to the upstream URL
http://deb.debian.org/debian/
.Alternatively, you can also use a Debian/Ubuntu Mirror. Note that synchronized content from Foreman does not work for two reasons: first, the
linux
andinitrd.gz
files are not synchronized; second, theRelease
file is not signed with the official Debian/Ubuntu GPG private key. -
Set the Operating System Family to
Debian
. -
Click Submit to save the installation medium to Foreman.
2.14. Creating an installation medium for Ubuntu 22.04
To provision Ubuntu 22.04, you need to provide both the ISO image and the extracted ISO image on your Foreman server.
-
Connect to your Foreman server using SSH:
# ssh root@foreman.example.com
-
Download the ISO image:
# cd /tmp/ # wget https://releases.ubuntu.com/22.04/ubuntu-22.04.3-live-server-amd64.iso
-
Mount the ISO image:
# mount ubuntu-22.04.3-live-server-amd64.iso /mnt
-
Provide the ISO image and the extracted directory under foreman.example.com/pub:
# mkdir -p /var/www/html/pub/installation_media/ubuntu/22.04-x86_64/ # cp ubuntu-22.04.3-live-server-amd64.iso /var/www/html/pub/installation_media/ubuntu/22.04-x86_64.iso # cp -a /mnt/* /var/www/html/pub/installation_media/ubuntu/22.04-x86_64/
Ensure the path in
/pub/
matches the path in your Preseed default PXELinux Autoinstall template. -
Unmount and delete the ISO image:
# umount /mnt/ # rm -f ubuntu-22.04.3-live-server-amd64.iso
Use http://foreman.example.com/pub/installation_media/ubuntu/22.04-x86_64/
to set up your installation media entry in Foreman.
For more information, see Adding installation media to Foreman.
2.15. Provisioning Ubuntu autoinstall through Smart Proxies
Perform these steps to provision hosts running Ubuntu 20.04.3+ or Ubuntu 22.04.
-
Ensure you have configured your Smart Proxy servers for provisioning. For more information, see Configuring Smart Proxy for Host Registration and Provisioning in Installing a Smart Proxy Server 3.11 on Enterprise Linux.
-
Provide the extracted ISO and ISO image itself on each Smart Proxy server. For more information, see Creating an installation medium for Ubuntu 22.04.
-
In the Foreman web UI, navigate to Hosts > Provisioning Setup > Installation Media.
-
Create an installation medium. Set the Path to the extracted ISO image on your Smart Proxy server.
-
In the Foreman web UI, navigate to Hosts > Provisioning Setup > Operating Systems.
-
Assign the installation medium to your operating system entry for Ubuntu 22.04.
-
In the Foreman web UI, navigate to Configure > Host Groups.
-
Select the host group that you use to deploy Ubuntu 22.04 through a Smart Proxy server and set the installation medium entry accordingly.
2.16. Creating partition tables
A partition table is a type of template that defines the way Foreman server configures the disks available on a new host.
A Partition table uses the same ERB syntax as provisioning templates.
Foreman contains a set of default partition tables to use, including a Kickstart default
.
You can also edit partition table entries to configure the preferred partitioning scheme, or create a partition table entry and add it to the operating system entry.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > Templates > Partition Tables.
-
Click Create Partition Table.
-
In the Name field, enter a name for the partition table.
-
Select the Default checkbox if you want to set the template to automatically associate with new organizations or locations.
-
Select the Snippet checkbox if you want to identify the template as a reusable snippet for other partition tables.
-
From the Operating System Family list, select the distribution or family of the partitioning layout. For example, Red Hat Enterprise Linux, CentOS, and Fedora are in the Red Hat family.
-
In the Template editor field, enter the layout for the disk partition.
The format of the layout must match that for the intended operating system. For example, Enterprise Linux requires a layout that matches a Kickstart file, such as:
zerombr clearpart --all --initlabel autopart
For more information, see Dynamic partition example.
You can also use the file browser in the template editor to import the layout from a file.
-
In the Audit Comment field, add a summary of changes to the partition layout.
-
Click the Organizations and Locations tabs to add any other provisioning contexts that you want to associate with the partition table. Foreman adds the partition table to the current provisioning context.
-
Click Submit to save your partition table.
-
Create a plain text file, such as
~/My_Partition_Table
, that contains the partition layout.The format of the layout must match that for the intended operating system. For example, Enterprise Linux requires a layout that matches a Kickstart file, such as:
zerombr clearpart --all --initlabel autopart
For more information, see Dynamic partition example.
-
Create the installation medium using the
hammer partition-table create
command:# hammer partition-table create \ --file "~/My_Partition_Table" \ --locations "My_Location" \ --name "My_Partition_Table" \ --organizations "My_Organization" \ --os-family "Redhat" \ --snippet false
2.17. Associating partition tables with disk encryption
Foreman contains partition tables that encrypt the disk of your host by using Linux Unified Key Setup (LUKS) during host provisioning. Encrypted disks on hosts protect data at rest. Optionally, you can also bind the disk to a Tang server through Clevis for decryption during boot.
Associate the partition table with your operating system entry. Then, you assign the partition table to your host group or select it manually during provisioning.
-
Your host has access to the
AppStream
repository to installclevis
during provisioning.
-
In the Foreman web UI, navigate to Hosts > Provisioning Setup > Operating Systems.
-
Select your Enterprise Linux entry.
-
On the Partition Table tab, associate
Kickstart default encrypted
with your operating system entry. -
Create a host group that uses the
Kickstart default encrypted
partition table. For more information, see Creating a host group in Managing hosts. -
Decrypt the disk of your host during boot time by using one of the following options:
-
LUKS encryption: Add the host parameter
disk_enc_passphrase
as type string and your cleartext passphrase of the LUKS container as the value. -
Clevis and Tang: Add the host parameter
disk_enc_tang_servers
as type array and your list of Tang servers (example:["1.2.3.4"]
or["server.example.com", "5.6.7.8"]
).If you set
disk_enc_tang_servers
, do not setdisk_enc_passphrase
because the passphrase slot is removed from the LUKS container after provisioning.
-
2.18. Dynamic partition example
Using an Anaconda kickstart template, the following section instructs Anaconda to erase the whole disk, automatically partition, enlarge one partition to maximum size, and then proceed to the next sequence of events in the provisioning process:
zerombr clearpart --all --initlabel autopart <%= host_param('autopart_options') %>
Dynamic partitioning is executed by the installation program. Therefore, you can write your own rules to specify how you want to partition disks according to runtime information from the node, for example, disk sizes, number of drives, vendor, or manufacturer.
If you want to provision servers and use dynamic partitioning, add the following example as a template.
When the #Dynamic
entry is included, the content of the template loads into a %pre
shell scriplet and creates a /tmp/diskpart.cfg
that is then included into the Kickstart partitioning section.
#Dynamic (do not remove this line) MEMORY=$((`grep MemTotal: /proc/meminfo | sed 's/^MemTotal: *//'|sed 's/ .*//'` / 1024)) if [ "$MEMORY" -lt 2048 ]; then SWAP_MEMORY=$(($MEMORY * 2)) elif [ "$MEMORY" -lt 8192 ]; then SWAP_MEMORY=$MEMORY elif [ "$MEMORY" -lt 65536 ]; then SWAP_MEMORY=$(($MEMORY / 2)) else SWAP_MEMORY=32768 fi cat <<EOF > /tmp/diskpart.cfg zerombr clearpart --all --initlabel part /boot --fstype ext4 --size 200 --asprimary part swap --size "$SWAP_MEMORY" part / --fstype ext4 --size 1024 --grow EOF
2.19. Provisioning templates
A provisioning template defines the way Foreman server installs an operating system on a host.
Foreman includes many template examples. In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates to view them. You can create a template or clone a template and edit the clone. For help with templates, navigate to Hosts > Templates > Provisioning Templates > Create Template > Help.
Templates accept the Embedded Ruby (ERB) syntax. For more information, see Template Writing Reference in Managing hosts.
You can download provisioning templates. Before you can download the template, you must create a debug certificate. For more information, see Creating an Organization Debug Certificate in Managing organizations and locations in Foreman.
You can synchronize templates between Foreman server and a Git repository or a local directory. For more information, see Synchronizing Templates Repositories in Managing hosts.
To view the history of changes applied to a template, navigate to Hosts > Templates > Provisioning Templates, select one of the templates, and click History. Click Revert to override the content with the previous version. You can also revert to an earlier change. Click Show Diff to see information about a specific change:
-
The Template Diff tab displays changes in the body of a provisioning template.
-
The Details tab displays changes in the template description.
-
The History tab displays the user who made a change to the template and date of the change.
2.20. Kinds of provisioning templates
There are various kinds of provisioning templates:
- Provision
-
The main template for the provisioning process. For example, a Kickstart template. For more information about Kickstart syntax and commands, see the following resources:
-
Kickstart references in Performing an advanced RHEL 9 installation
-
Kickstart references in Performing an advanced RHEL 8 installation
-
Kickstart Syntax Reference in the Red Hat Enterprise Linux 7 Installation Guide
-
- PXELinux, PXEGrub, PXEGrub2
-
PXE-based templates that deploy to the template Smart Proxy associated with a subnet to ensure that the host uses the installer with the correct kernel options. For BIOS provisioning, select PXELinux template. For UEFI provisioning, select PXEGrub2.
- Finish
-
Post-configuration scripts to execute using an SSH connection when the main provisioning process completes. You can use Finish templates only for image-based provisioning in virtual or cloud environments that do not support user_data. Do not confuse an image with a foreman discovery ISO, which is sometimes called a Foreman discovery image. An image in this context is an install image in a virtualized environment for easy deployment.
When a finish script successfully exits with the return code
0
, Foreman treats the code as a success and the host exits the build mode.Note that there are a few finish scripts with a build mode that uses a call back HTTP call. These scripts are not used for image-based provisioning, but for post configuration of operating-system installations such as Debian, Ubuntu, and BSD.
- user_data
-
Post-configuration scripts for providers that accept custom data, also known as seed data. You can use the user_data template to provision virtual machines in cloud or virtualised environments only. This template does not require Foreman to be able to reach the host; the cloud or virtualization platform is responsible for delivering the data to the image.
Ensure that the image that you want to provision has the software to read the data installed and set to start during boot. For example,
cloud-init
, which expects YAML input, orignition
, which expects JSON input. - cloud_init
-
Some environments, such as VMWare, either do not support custom data or have their own data format that limits what can be done during customization. In this case, you can configure a cloud-init client with the
foreman
plugin, which attempts to download the template directly from Foreman over HTTP or HTTPS. This technique can be used in any environment, preferably virtualized.Ensure that you meet the following requirements to use the
cloud_init
template:-
Ensure that the image that you want to provision has the software to read the data installed and set to start during boot.
-
A provisioned host is able to reach Foreman from the IP address that matches the host’s provisioning interface IP.
Note that cloud-init does not work behind NAT.
-
- Bootdisk
-
Templates for PXE-less boot methods.
- Kernel Execution (kexec)
-
Kernel execution templates for PXE-less boot methods.
- Script
-
An arbitrary script not used by default but useful for custom tasks.
- ZTP
-
Zero Touch Provisioning templates.
- POAP
-
PowerOn Auto Provisioning templates.
- iPXE
-
Templates for
iPXE
orgPXE
environments to use instead of PXELinux.
2.21. Creating provisioning templates
A provisioning template defines the way Foreman server installs an operating system on a host. Use this procedure to create a new provisioning template.
-
In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates and click Create Template.
-
In the Name field, enter a name for the provisioning template.
-
Fill in the rest of the fields as required. The Help tab provides information about the template syntax and details the available functions, variables, and methods that can be called on different types of objects within the template.
-
Before you create a template with the CLI, create a plain text file that contains the template. This example uses the
~/my-template
file. -
Create the template using the
hammer template create
command and specify the type with the--type
option:# hammer template create \ --file ~/my-template \ --locations "My_Location" \ --name "My_Provisioning_Template" \ --organizations "My_Organization" \ --type provision
2.22. Cloning provisioning templates
A provisioning template defines the way Foreman server installs an operating system on a host. Use this procedure to clone a template and add your updates to the clone.
-
In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates.
-
Find the template that you want to use.
-
Click Clone to duplicate the template.
-
In the Name field, enter a name for the provisioning template.
-
Select the Default checkbox to set the template to associate automatically with new organizations or locations.
-
In the Template editor field, enter the body of the provisioning template. You can also use the Template file browser to upload a template file.
-
In the Audit Comment field, enter a summary of changes to the provisioning template for auditing purposes.
-
Click the Type tab and if your template is a snippet, select the Snippet checkbox. A snippet is not a standalone provisioning template, but a part of a provisioning template that can be inserted into other provisioning templates.
-
From the Type list, select the type of the template. For example, Provisioning template.
-
Click the Association tab and from the Applicable Operating Systems list, select the names of the operating systems that you want to associate with the provisioning template.
-
Optionally, click Add combination and select a host group from the Host Group list or an environment from the Environment list to associate provisioning template with the host groups and environments.
-
Click the Organizations and Locations tabs to add any additional contexts to the template.
-
Click Submit to save your provisioning template.
2.23. Creating custom provisioning snippets
Custom provisioning snippets allow you to execute custom code during host provisioning. You can run code before and/or after the provisioning process.
-
Depending on your provisioning template, multiple custom snippet hooks exist which you can use to include custom provisioning snippets. Ensure that you check your provisioning template first to verify which custom snippets you can use.
-
In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates and click Create Template.
-
In the Name field, enter a name for your custom provisioning snippet. The name has to start with the name of a provisioning template that supports including custom provisioning snippets:
-
Append ` custom pre` to the name of a provisioning template to run code before provisioning a host.
-
Append ` custom post` to the name of a provisioning template to run code after provisioning a host.
-
-
On the Type tab, select Snippet.
-
Click Submit to create your custom provisioning snippet.
-
Before you create a template with the CLI, create a plain text file that contains your custom snippet.
-
Create the template using
hammer
:# hammer template create \ --file "/path/to/My_Snippet" \ --locations "My_Location" \ --name "My_Template_Name_custom_pre" \ --organizations "_My_Organization" \ --type snippet
2.24. Custom provisioning snippet example for Debian
You can use Custom Post
snippets to call external APIs from within the provisioning template directly after provisioning a host.
Preseed default custom post
Example for Debian/Ubuntuecho "Calling API to report successful host deployment" apt install -y curl ca-certificates curl -X POST \ -H "Content-Type: application/json" \ -d '{"name": "<%= @host.name %>", "operating_system": "<%= @host.operatingsystem.name %>", "status": "provisioned",}' \ "https://api.example.com/"
2.25. Custom provisioning snippet example for Enterprise Linux
You can use Custom Post
snippets to call external APIs from within the provisioning template directly after provisioning a host.
Kickstart default finish custom post
Example for Enterprise Linuxecho "Calling API to report successful host deployment" yum install -y curl ca-certificates curl -X POST \ -H "Content-Type: application/json" \ -d '{"name": "<%= @host.name %>", "operating_system": "<%= @host.operatingsystem.name %>", "status": "provisioned",}' \ "https://api.example.com/"
2.26. Associating templates with operating systems
You can associate templates with operating systems in Foreman. The following example adds a provisioning template to an operating system entry.
-
In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates.
-
Select a provisioning template.
-
On the Association tab, select all applicable operating systems.
-
Click Submit to save your changes.
-
Optional: View all templates:
# hammer template list
-
Optional: View all operating systems:
# hammer os list
-
Associate a template with an operating system:
# hammer template add-operatingsystem \ --id My_Template_ID \ --operatingsystem-id My_Operating_System_ID
2.27. Creating compute profiles
You can use compute profiles to predefine virtual machine hardware details such as CPUs, memory, and storage.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
A default installation of Foreman contains three predefined profiles:
-
1-Small
-
2-Medium
-
3-Large
You can apply compute profiles to all supported compute resources:
-
In the Foreman web UI, navigate to Infrastructure > Compute Profiles and click Create Compute Profile.
-
In the Name field, enter a name for the profile.
-
Click Submit. A new window opens with the name of the compute profile.
-
In the new window, click the name of each compute resource and edit the attributes you want to set for this compute profile.
-
Create a new compute profile:
# hammer compute-profile create --name "My_Compute_Profile"
-
Set attributes for the compute profile:
# hammer compute-profile values create \ --compute-attributes "flavor=m1.small,cpus=2,memory=4GB,cpu_mode=default \ --compute-resource "My_Compute_Resource" \ --compute-profile "My_Compute_Profile" \ --volume size=40GB
-
Optional: To update the attributes of a compute profile, specify the attributes you want to change. For example, to change the number of CPUs and memory size:
# hammer compute-profile values update \ --compute-resource "My_Compute_Resource" \ --compute-profile "My_Compute_Profile" \ --attributes "cpus=2,memory=4GB" \ --interface "type=network,bridge=br1,index=1" \ --volume "size=40GB"
-
Optional: To change the name of the compute profile, use the
--new-name
attribute:# hammer compute-profile update \ --name "My_Compute_Profile" \ --new-name "My_New_Compute_Profile"
-
For more information about creating compute profiles by using Hammer, enter
hammer compute-profile --help
.
2.28. Setting a default encrypted root password for hosts
If you do not want to set a plain text default root password for the hosts that you provision, you can use a default encrypted password.
The default root password can be inherited by a host group and consequentially by hosts in that group.
If you change the password and reprovision the hosts in the group that inherits the password, the password will be overwritten on the hosts.
-
Generate an encrypted password:
$ python3 -c 'import crypt,getpass;pw=getpass.getpass(); print(crypt.crypt(pw)) if (pw==getpass.getpass("Confirm: ")) else exit()'
-
Copy the password for later use.
-
In the Foreman web UI, navigate to Administer > Settings.
-
On the Settings page, select the Provisioning tab.
-
In the Name column, navigate to Root password, and click Click to edit.
-
Paste the encrypted password, and click Save.
2.29. Using noVNC to access virtual machines
You can use your browser to access the VNC console of VMs created by Foreman.
Foreman supports using noVNC on the following virtualization platforms:
-
VMware
-
Libvirt
-
oVirt
-
You must have a virtual machine created by Foreman.
-
For existing virtual machines, ensure that the Display type in the Compute Resource settings is VNC.
-
You must import the Katello root CA certificate into your Foreman server. Adding a security exception in the browser is not enough for using noVNC. For more information, see Installing the Katello Root CA Certificate in Administering Foreman.
-
On your Foreman server, configure the firewall to allow VNC service on ports 5900 to 5930.
-
On operating systems with the
iptables
command:# iptables -A INPUT -p tcp --dport 5900:5930 -j ACCEPT # service iptables save
-
On operating systems with the
firewalld
service:# firewall-cmd --add-port=5900-5930/tcp # firewall-cmd --add-port=5900-5930/tcp --permanent
If you do not use
firewall-cmd
to configure the Linux firewall, implement using the command of your choice.
-
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources and select the name of a compute resource.
-
In the Virtual Machines tab, select the name of your virtual machine. Ensure the machine is powered on and then select Console.
2.30. Removing a virtual machine upon host deletion
By default, when you delete a host provisioned by Foreman, Foreman does not remove the actual VM on the compute resource. You can configure Foreman to remove the VM when deleting the host entry on Foreman.
Note
|
If you do not remove the associated VM and attempt to create a new VM with the same FQDN later, it will fail because that VM already exists in the compute resource. You can still re-register the existing VM to Foreman. |
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
Your Foreman account has a role that grants the
view_settings
andedit_settings
permissions.
-
In the Foreman web UI, navigate to Administer > Settings > Provisioning.
-
Change the value of the Destroy associated VM on host delete setting to Yes.
-
Configure Foreman to remove a VM upon host deletion by using Hammer:
# hammer settings set \ --name destroy_vm_on_host_delete \ --value true \ --location "My_Location" \ --organization "My_Organization"
-
You can delete a host and Foreman removes its associated VM in the compute resource.
3. Configuring networking
Each provisioning type requires some network configuration. Use this chapter to configure network services in your integrated Smart Proxy on Foreman server.
New hosts must have access to your Smart Proxy server. Smart Proxy server can be either your integrated Smart Proxy on Foreman server or an external Smart Proxy server. You might want to provision hosts from an external Smart Proxy server when the hosts are on isolated networks and cannot connect to Foreman server directly, or when the content is synchronized with Smart Proxy server. Provisioning using the external Smart Proxy server can save on network bandwidth.
Configuring Smart Proxy server has two basic requirements:
-
Configuring network services. This includes:
-
Content delivery services
-
Network services (DHCP, DNS, and TFTP)
-
Puppet configuration
-
-
Defining network resource data in Foreman server to help configure network interfaces on new hosts.
The following instructions have similar applications to configuring standalone Smart Proxies managing a specific network. To configure Foreman to use external DHCP, DNS, and TFTP services, see Configuring External Services in Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux.
3.1. Facts and NIC filtering
Facts describe aspects such as total memory, operating system version, or architecture as reported by the host. You can find facts in Monitor > Facts and search hosts through facts or use facts in templates.
Foreman collects facts from multiple sources:
-
subscription manager
-
ansible
-
puppet
Foreman is an inventory system for hosts and network interfaces. For hypervisors or container hosts, adding thousands of interfaces per host and updating the inventory every few minutes is inadequate. For each individual NIC reported, Foreman creates a NIC entry and those entries are never removed from the database. Parsing all the facts and comparing all records in the database makes Foreman extremely slow and unusable. To optimize the performance of various actions, most importantly fact import, you can use the options available on the Facts tab under Administer > Settings.
3.2. Optimizing performance by removing NICs from database
Filter and exclude the connections using the Exclude pattern for facts stored in Foreman
and Ignore interfaces with matching identifier
option.
By default, these options are set to most common hypervisors.
If you name the virtual interfaces differently, you can update this filter to use it according to your requirements.
-
In the Foreman web UI, navigate to Administer > Settings and select the Facts tab.
-
To filter out all interfaces starting with specific names, for example,
blu
, addblu*
to theIgnore interfaces with matching identifier
option. -
To prevent databases from storing facts related to interfaces starting with specific names, for example,
blu
, addblu*
to theExclude pattern for facts stored in Foreman
option.By default, it contains the same list as the
Ignore interfaces with matching identifier
option. You can override it based on the your requirements. This filters out facts completely without storing them. -
To remove facts from the database, enter the following command:
# foreman-rake facts:clean
This command removes all facts matching with the filter added in Administer > Settings > Facts > the
Exclude pattern for facts stored in Foreman
option. -
To remove interfaces from the database, enter the following command:
# foreman-rake interfaces:clean
This command removes all interfaces matching with the filter added in Administer > Settings > Facts > the
Ignore interfaces with matching identifier
option.
3.3. Network resources
Foreman contains networking resources that you must set up and configure to create a host. It includes the following networking resources:
- Domain
-
You must assign every host that is managed by Foreman to a domain. Using the domain, Foreman can manage A, AAAA, and PTR records. Even if you do not want Foreman to manage your DNS servers, you still must create and associate at least one domain. Domains are included in the naming conventions Foreman hosts, for example, a host with the name
test123
in theexample.com
domain has the fully qualified domain nametest123.example.com
. - Subnet
-
You must assign every host managed by Foreman to a subnet. Using subnets, Foreman can then manage IPv4 reservations. If there are no reservation integrations, you still must create and associate at least one subnet. When you manage a subnet in Foreman, you cannot create DHCP records for that subnet outside of Foreman. In Foreman, you can use IP Address Management (IPAM) to manage IP addresses with one of the following options:
-
DHCP: DHCP Smart Proxy manages the assignment of IP addresses by finding the next available IP address starting from the first address of the range and skipping all addresses that are reserved. Before assigning an IP address, Smart Proxy sends an ICMP and TCP pings to check whether the IP address is in use. Note that if a host is powered off, or has a firewall configured to disable connections, Foreman makes a false assumption that the IP address is available. This check does not work for hosts that are turned off, therefore, the DHCP option can only be used with subnets that Foreman controls and that do not have any hosts created externally.
The Smart Proxy DHCP module retains the offered IP addresses for a short period of time to prevent collisions during concurrent access, so some IP addresses in the IP range might remain temporarily unused.
-
Internal DB: Foreman finds the next available IP address from the Subnet range by excluding all IP addresses from the Foreman database in sequence. The primary source of data is the database, not DHCP reservations. This IPAM is not safe when multiple hosts are being created in parallel; in that case, use DHCP or Random DB IPAM instead.
-
Random DB: Foreman finds the next available IP address from the Subnet range by excluding all IP addresses from the Foreman database randomly. The primary source of data is the database, not DHCP reservations. This IPAM is safe to use with concurrent host creation as IP addresses are returned in random order, minimizing the chance of a conflict.
-
EUI-64: Extended Unique Identifier (EUI) 64bit IPv6 address generation, as per RFC2373, is obtained through the 48-bit MAC address.
-
External IPAM: Delegates IPAM to an external system through Smart Proxy feature. Foreman currently does not ship with any external IPAM implementations, but several plugins are in development.
-
None: IP address for each host must be entered manually.
Options DHCP, Internal DB and Random DB can lead to DHCP conflicts on subnets with records created externally. These subnets must be under exclusive Foreman control.
For more information about adding a subnet, see Adding a subnet to Foreman server.
-
- DHCP Ranges
-
You can define the same DHCP range in Foreman server for both discovered and provisioned systems, but use a separate range for each service within the same subnet.
3.4. Foreman and DHCP options
Foreman manages DHCP reservations through a DHCP Smart Proxy.
Foreman also sets the next-server
and filename
DHCP options.
The next-server
option provides the IP address of the TFTP server to boot from.
This option is not set by default and must be set for each TFTP Smart Proxy.
You can use the foreman-installer
command with the --foreman-proxy-tftp-servername
option to set the TFTP server in the /etc/foreman-proxy/settings.d/tftp.yml
file:
# foreman-installer --foreman-proxy-tftp-servername 1.2.3.4
Each TFTP Smart Proxy then reports this setting through the API and Foreman can retrieve the configuration information when it creates the DHCP record.
When the PXE loader is set to none
, Foreman does not populate the next-server
option into the DHCP record.
If the next-server
option remains undefined, Foreman uses reverse DNS search to find a TFTP server address to assign, but you might encounter the following problems:
-
DNS timeouts during provisioning
-
Querying of incorrect DNS server. For example, authoritative rather than caching
-
Errors about incorrect IP address for the TFTP server. For example,
PTR record was invalid
If you encounter these problems, check the DNS setup on both Foreman and Smart Proxy, specifically the PTR record resolution.
The filename
option contains the full path to the file that downloads and executes during provisioning.
The PXE loader that you select for the host or host group defines which filename
option to use.
When the PXE loader is set to none
, Foreman does not populate the filename
option into the DHCP record.
Depending on the PXE loader option, the filename
changes as follows:
PXE loader option | filename entry | Notes |
---|---|---|
PXELinux BIOS |
|
|
PXELinux UEFI |
|
|
iPXE Chain BIOS |
|
|
PXEGrub2 UEFI |
|
x64 can differ depending on architecture |
iPXE UEFI HTTP |
|
Requires the |
Grub2 UEFI HTTP |
|
Requires the |
3.5. Troubleshooting DHCP problems in Foreman
Foreman can manage an ISC DHCP server on internal or external DHCP Smart Proxy. Foreman can list, create, and delete DHCP reservations and leases. However, there are a number of problems that you might encounter on occasions.
When an error occurs during DHCP orchestration, DHCP records in the Foreman database and the DHCP server might not match. To fix this, you must add missing DHCP records from the Foreman database to the DHCP server and then remove unwanted records from the DHCP server as per the following steps:
-
To preview the DHCP records that are going to be added to the DHCP server, enter the following command:
# foreman-rake orchestration:dhcp:add_missing subnet_name=NAME
-
If you are satisfied by the preview changes in the previous step, apply them by entering the above command with the
perform=1
argument:# foreman-rake orchestration:dhcp:add_missing subnet_name=NAME perform=1
-
To keep DHCP records in Foreman and in the DHCP server synchronized, you can remove unwanted DHCP records from the DHCP server. Note that Foreman assumes that all managed DHCP servers do not contain third-party records, therefore, this step might delete those unexpected records. To preview what records are going to be removed from the DHCP server, enter the following command:
# foreman-rake orchestration:dhcp:remove_offending subnet_name=NAME
-
If you are satisfied by the preview changes in the previous step, apply them by entering the above command with the
perform=1
argument:# foreman-rake orchestration:dhcp:remove_offending subnet_name=NAME perform=1
When the PXE loader option is changed for an existing host, this causes a DHCP conflict. The only workaround is to overwrite the DHCP entry.
This is a known issue. Until Issue 27877 is fixed, the only workaround is to overwrite the DHCP entry.
An operating system update can update the dhcpd
package.
This causes the permissions of important directories and files to reset so that the DHCP Smart Proxy cannot read the required information.
For more information, see ERF12-6899 - Unable to set DHCP entry.
Foreman manages DHCP records only for hosts that are assigned to subnets with a DHCP Smart Proxy set. If you create a host and then clear or change the DHCP Smart Proxy, when you attempt to delete the host, the action fails.
If you create a host without setting the DHCP Smart Proxy and then try to set the DHCP Smart Proxy, this causes DHCP conflicts.
Any changes to a DHCP lease are appended to the end of the dhcpd.leases
file.
Because entries are appended to the file, it is possible that two or more entries of the same lease can exist in the dhcpd.leases
file at the same time.
When there are two or more entries of the same lease, the last entry in the file takes precedence.
Group, subgroup and host declarations in the lease file are processed in the same manner.
If a lease is deleted, { deleted; }
is appended to the declaration.
3.6. Prerequisites for image-based provisioning
Images that use the finish
post-boot configuration scripts require a managed DHCP server, such as Foreman’s integrated Smart Proxy or an external Smart Proxy.
The host must be created with a subnet associated with a DHCP Smart Proxy, and the IP address of the host must be a valid IP address from the DHCP range.
It is possible to use an external DHCP service, but IP addresses must be entered manually. The SSH credentials corresponding to the configuration in the image must be configured in Foreman to enable the post-boot configuration to be made.
Check the following items when troubleshooting a virtual machine booted from an image that depends on post-configuration scripts:
-
The host has a subnet assigned in Foreman server.
-
The subnet has a DHCP Smart Proxy assigned in Foreman server.
-
The host has a valid IP address assigned in Foreman server.
-
The IP address acquired by the virtual machine using DHCP matches the address configured in Foreman server.
-
The virtual machine created from an image responds to SSH requests.
-
The virtual machine created from an image authorizes the user and password, over SSH, which is associated with the image being deployed.
-
Foreman server has access to the virtual machine via SSH keys. This is required for the virtual machine to receive post-configuration scripts from Foreman server.
Images that use the cloud-init
scripts require a DHCP server to avoid having to include the IP address in the image.
A managed DHCP Smart Proxy is preferred.
The image must have the cloud-init
service configured to start when the system boots and fetch a script or configuration data to use in completing the configuration.
Check the following items when troubleshooting a virtual machine booted from an image that depends on initialization scripts included in the image:
-
There is a DHCP server on the subnet.
-
The virtual machine has the
cloud-init
service installed and enabled.
3.7. Configuring network services
Some provisioning methods use Smart Proxy server services. For example, a network might require Smart Proxy server to act as a DHCP server. A network can also use PXE boot services to install the operating system on new hosts. This requires configuring Smart Proxy server to use the main PXE boot services: DHCP, DNS, and TFTP.
Use the foreman-installer
command with the options to configure these services on Foreman server.
-
Enter the
foreman-installer
command to configure the required network services:# foreman-installer --foreman-proxy-dhcp true \ --foreman-proxy-dhcp-gateway "192.168.140.1" \ --foreman-proxy-dhcp-managed true \ --foreman-proxy-dhcp-nameservers "192.168.140.2" \ --foreman-proxy-dhcp-range "192.168.140.10 192.168.140.110" \ --foreman-proxy-dhcp-server "192.168.140.2" \ --foreman-proxy-dns true \ --foreman-proxy-dns-forwarders "8.8.8.8" \ --foreman-proxy-dns-forwarders "8.8.4.4" \ --foreman-proxy-dns-managed true \ --foreman-proxy-dns-reverse "140.168.192.in-addr.arpa" \ --foreman-proxy-dns-server "127.0.0.1" \ --foreman-proxy-dns-zone "example.com" \ --foreman-proxy-tftp true \ --foreman-proxy-tftp-managed true
-
Find Smart Proxy server that you configure:
# hammer proxy list
-
Refresh features of Smart Proxy server to view the changes:
# hammer proxy refresh-features --name "foreman.example.com"
-
Verify the services configured on Smart Proxy server:
# hammer proxy info --name "foreman.example.com"
3.7.1. Multiple subnets or domains using installer
The foreman-installer
options allow only for a single DHCP subnet or DNS domain.
One way to define more than one subnet is by using a custom configuration file.
For every additional subnet or domain, create an entry in /etc/foreman-installer/custom-hiera.yaml
file:
dhcp::pools: isolated.lan: network: 192.168.99.0 mask: 255.255.255.0 gateway: 192.168.99.1 range: 192.168.99.5 192.168.99.49 dns::zones: # creates @ SOA $::fqdn root.example.com. # creates $::fqdn A $::ipaddress example.com: {} # creates @ SOA test.example.net. hostmaster.example.com. # creates test.example.net A 192.0.2.100 example.net: soa: test.example.net soaip: 192.0.2.100 contact: hostmaster.example.com. # creates @ SOA $::fqdn root.example.org. # does NOT create an A record example.org: reverse: true # creates @ SOA $::fqdn hostmaster.example.com. 2.0.192.in-addr.arpa: reverse: true contact: hostmaster.example.com.
Execute foreman-installer
to perform the changes and verify that the /etc/dhcp/dhcpd.conf
contains appropriate entries.
Subnets must be then defined in Foreman database.
3.7.2. DHCP options for network configuration
- --foreman-proxy-dhcp
-
Enables the DHCP service. You can set this option to
true
orfalse
. - --foreman-proxy-dhcp-managed
-
Enables Foreman to manage the DHCP service. You can set this option to
true
orfalse
. - --foreman-proxy-dhcp-gateway
-
The DHCP pool gateway. Set this to the address of the external gateway for hosts on your private network.
- --foreman-proxy-dhcp-interface
-
Sets the interface for the DHCP service to listen for requests. Set this to
eth1
. - --foreman-proxy-dhcp-nameservers
-
Sets the addresses of the nameservers provided to clients through DHCP. Set this to the address for Foreman server on
eth1
. - --foreman-proxy-dhcp-range
-
A space-separated DHCP pool range for Discovered and Unmanaged services.
- --foreman-proxy-dhcp-server
-
Sets the address of the DHCP server to manage.
Run foreman-installer --help
to view more options related to DHCP and other Smart Proxy services.
3.7.3. DNS options for network configuration
- --foreman-proxy-dns
-
Enables the DNS feature. You can set this option to
true
orfalse
. - --foreman-proxy-dns-provider
-
Selects the provider to be used.
- --foreman-proxy-dns-managed
-
Let the installer manage ISC BIND. This is only relevant when using the
nsupdate
andnsupdate_gss
providers. You can set this option totrue
orfalse
. - --foreman-proxy-dns-forwarders
-
Sets the DNS forwarders. Only used when ISC BIND is managed by the installer. Set this to your DNS recursors.
- --foreman-proxy-dns-interface
-
Sets the interface to listen for DNS requests. Only used when ISC BIND is managed by the installer. Set this to
eth1
. - --foreman-proxy-dns-reverse
-
The DNS reverse zone name. Only used when ISC BIND is managed by the installer.
- --foreman-proxy-dns-server
-
Sets the address of the DNS server. Only used by the
nsupdate
,nsupdate_gss
, andinfoblox
providers. - --foreman-proxy-dns-zone
-
Sets the DNS zone name. Only used when ISC BIND is managed by the installer.
Run foreman-installer --help
to view more options related to DNS and other Smart Proxy services.
3.7.4. TFTP options for network configuration
- --foreman-proxy-tftp
-
Enables TFTP service. You can set this option to
true
orfalse
. - --foreman-proxy-tftp-managed
-
Enables Foreman to manage the TFTP service. You can set this option to
true
orfalse
. - --foreman-proxy-tftp-servername
-
Sets the TFTP server to use. Ensure that you use Smart Proxy’s IP address.
Run foreman-installer --help
to view more options related to TFTP and other Smart Proxy services.
3.7.5. Using TFTP services through NAT
You can use Foreman TFTP services through NAT. To do this, on all NAT routers or firewalls, you must enable a TFTP service on UDP port 69 and enable the TFTP state tracking feature. For more information, see the documentation for your NAT device.
firewalld
:-
Allow the TFTP service in the firewall configuration:
# firewall-cmd --add-service=tftp
-
Make the changes persistent:
# firewall-cmd --runtime-to-permanent
iptables
:-
Configure the firewall to allow TFTP service UDP on port 69:
# iptables \ --sport 69 \ --state ESTABLISHED \ -A OUTPUT \ -i eth0 \ -j ACCEPT \ -m state \ -p udp # service iptables save
-
Load the
ip_conntrack_tftp
kernel TFTP state module. In the/etc/sysconfig/iptables-config
file, locateIPTABLES_MODULES
and addip_conntrack_tftp
as follows:IPTABLES_MODULES="ip_conntrack_tftp"
3.8. Adding a domain to Foreman server
Foreman server defines domain names for each host on the network. Foreman server must have information about the domain and Smart Proxy server responsible for domain name assignment.
Foreman server might already have the relevant domain created as part of Foreman server installation.
Switch the context to Any Organization
and Any Location
then check the domain list to see if it exists.
During the DNS record creation, Foreman performs conflict DNS lookups to verify that the host name is not in active use. This check runs against one of the following DNS servers:
-
The system-wide resolver if Administer > Settings > Query local nameservers is set to true.
-
The nameservers that are defined in the subnet associated with the host.
-
The authoritative NS-Records that are queried from the SOA from the domain name associated with the host.
If you experience timeouts during DNS conflict resolution, check the following settings:
-
The subnet nameservers must be reachable from Foreman server.
-
The domain name must have a Start of Authority (SOA) record available from Foreman server.
-
The system resolver in the
/etc/resolv.conf
file must have a valid and working configuration.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Domains and click Create Domain.
-
In the DNS Domain field, enter the full DNS domain name.
-
In the Fullname field, enter the plain text name of the domain.
-
Click the Parameters tab and configure any domain level parameters to apply to hosts attached to this domain. For example, user defined Boolean or string parameters to use in templates.
-
Click Add Parameter and fill in the Name and Value fields.
-
Click the Locations tab, and add the location where the domain resides.
-
Click the Organizations tab, and add the organization that the domain belongs to.
-
Click Submit to save the changes.
-
Use the
hammer domain create
command to create a domain:# hammer domain create \ --description "My_Domain" \ --dns-id My_DNS_ID \ --locations "My_Location" \ --name "my-domain.tld" \ --organizations "My_Organization"
In this example, the --dns-id
option uses 1
, which is the ID of your integrated Smart Proxy on Foreman server.
3.9. Adding a subnet to Foreman server
You must add information for each of your subnets to Foreman server because Foreman configures interfaces for new hosts. To configure interfaces, Foreman server must have all the information about the network that connects these interfaces.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Subnets, and in the Subnets window, click Create Subnet.
-
In the Name field, enter a name for the subnet.
-
In the Description field, enter a description for the subnet.
-
In the Network address field, enter the network address for the subnet.
-
In the Network prefix field, enter the network prefix for the subnet.
-
In the Network mask field, enter the network mask for the subnet.
-
In the Gateway address field, enter the external gateway for the subnet.
-
In the Primary DNS server field, enter a primary DNS for the subnet.
-
In the Secondary DNS server, enter a secondary DNS for the subnet.
-
From the IPAM list, select the method that you want to use for IP address management (IPAM). For more information about IPAM, see Configuring networking.
-
Enter the information for the IPAM method that you select.
-
If you use the remote execution plugin, click the Remote Execution tab and select the Smart Proxy that controls the remote execution.
-
Click the Domains tab and select the domains that apply to this subnet.
-
Click the Smart Proxies tab and select the Smart Proxy that applies to each service in the subnet, including DHCP, TFTP, and reverse DNS services.
-
Click the Parameters tab and configure any subnet level parameters to apply to hosts attached to this subnet. For example, user defined Boolean or string parameters to use in templates.
-
Click the Locations tab and select the locations that use this Smart Proxy.
-
Click the Organizations tab and select the organizations that use this Smart Proxy.
-
Click Submit to save the subnet information.
-
Create the subnet with the following command:
# hammer subnet create \ --boot-mode "DHCP" \ --description "My_Description" \ --dhcp-id My_DHCP_ID \ --dns-id My_DNS_ID \ --dns-primary "192.168.140.2" \ --dns-secondary "8.8.8.8" \ --domains "my-domain.tld" \ --from "192.168.140.111" \ --gateway "192.168.140.1" \ --ipam "DHCP" \ --locations "_My_Location" \ --mask "255.255.255.0" \ --name "My_Network" \ --network "192.168.140.0" \ --organizations "My_Organization" \ --tftp-id My_TFTP_ID \ --to "192.168.140.250"
Note
|
In this example, the |
4. Using Infoblox as DHCP and DNS providers
You can use Smart Proxy server to connect to your Infoblox application to create and manage DHCP and DNS records, and to reserve IP addresses.
The supported Infoblox version is NIOS 8.0 or higher.
4.1. Infoblox limitations
All DHCP and DNS records can be managed only in a single Network or DNS view.
After you install the Infoblox modules on Smart Proxy and set up the view using the foreman-installer
command, you cannot edit the view.
Smart Proxy server communicates with a single Infoblox node using the standard HTTPS web API. If you want to configure clustering and High Availability, make the configurations in Infoblox.
Hosting PXE-related files using Infoblox’s TFTP functionality is not supported. You must use Smart Proxy as a TFTP server for PXE provisioning. For more information, see Configuring networking.
Foreman IPAM feature cannot be integrated with Infoblox.
4.2. Infoblox prerequisites
-
You must have Infoblox account credentials to manage DHCP and DNS entries in Foreman.
-
Ensure that you have Infoblox administration roles with the names:
DHCP Admin
andDNS Admin
. -
The administration roles must have permissions or belong to an admin group that permits the accounts to perform tasks through the Infoblox API.
4.3. Installing the Infoblox CA certificate on Smart Proxy server
You must install Infoblox HTTPS CA certificate on the base system for all Smart Proxies that you want to integrate with Infoblox applications.
You can download the certificate from the Infoblox web UI, or you can use the following OpenSSL commands to download the certificate:
# update-ca-trust enable # openssl s_client -showcerts -connect infoblox.example.com:443 </dev/null | \ openssl x509 -text >/etc/pki/ca-trust/source/anchors/infoblox.crt # update-ca-trust extract
-
The
infoblox.example.com
entry must match the host name for the Infoblox application in the X509 certificate.
To test the CA certificate, use a CURL query:
# curl -u admin:password https://infoblox.example.com/wapi/v2.0/network
Example positive response:
[ { "_ref": "network/ZG5zLm5ldHdvcmskMTkyLjE2OC4yMDIuMC8yNC8w:infoblox.example.com/24/default", "network": "192.168.202.0/24", "network_view": "default" } ]
4.4. Installing the DHCP Infoblox module
Use this procedure to install the DHCP Infoblox module on Smart Proxy. Note that you cannot manage records in separate views.
You can also install DHCP and DNS Infoblox modules simultaneously by combining this procedure and Installing the DNS Infoblox module.
If you want to use the DHCP and DNS Infoblox modules together, configure the DHCP Infoblox module with the fixedaddress
record type only.
The host
record type causes DNS conflicts and is not supported.
If you configure the DHCP Infoblox module with the host
record type, you have to unset both DNS Smart Proxy and Reverse DNS Smart Proxy options on your Infoblox-managed subnets, because Infoblox does DNS management by itself.
Using the host
record type leads to creating conflicts and being unable to rename hosts in Foreman.
-
On Smart Proxy, enter the following command:
# foreman-installer --enable-foreman-proxy-plugin-dhcp-infoblox \ --foreman-proxy-dhcp true \ --foreman-proxy-dhcp-provider infoblox \ --foreman-proxy-dhcp-server infoblox.example.com \ --foreman-proxy-plugin-dhcp-infoblox-username admin \ --foreman-proxy-plugin-dhcp-infoblox-password infoblox \ --foreman-proxy-plugin-dhcp-infoblox-record-type fixedaddress \ --foreman-proxy-plugin-dhcp-infoblox-dns-view default \ --foreman-proxy-plugin-dhcp-infoblox-network-view default
-
Optional: In the Foreman web UI, navigate to Infrastructure > Smart Proxies, select the Smart Proxy with the DHCP Infoblox module, and ensure that the dhcp feature is listed.
-
In the Foreman web UI, navigate to Infrastructure > Subnets.
-
For all subnets managed through Infoblox, ensure that the IP address management (IPAM) method of the subnet is set to
DHCP
.
4.5. Installing the DNS Infoblox module
Use this procedure to install the DNS Infoblox module on Smart Proxy. You can also install DHCP and DNS Infoblox modules simultaneously by combining this procedure and Installing the DHCP Infoblox module.
-
On Smart Proxy, enter the following command to configure the Infoblox module:
# foreman-installer --enable-foreman-proxy-plugin-dns-infoblox \ --foreman-proxy-dns true \ --foreman-proxy-dns-provider infoblox \ --foreman-proxy-plugin-dns-infoblox-dns-server infoblox.example.com \ --foreman-proxy-plugin-dns-infoblox-username admin \ --foreman-proxy-plugin-dns-infoblox-password infoblox \ --foreman-proxy-plugin-dns-infoblox-dns-view default
Optionally, you can change the value of the
--foreman-proxy-plugin-dns-infoblox-dns-view
option to specify an Infoblox DNS view other than the default view. -
Optional: In the Foreman web UI, navigate to Infrastructure > Smart Proxies, select the Smart Proxy with the Infoblox DNS module, and ensure that the dns feature is listed.
-
In the Foreman web UI, navigate to Infrastructure > Domains.
-
For all domains managed through Infoblox, ensure that the DNS Proxy is set for those domains.
-
In the Foreman web UI, navigate to Infrastructure > Subnets.
-
For all subnets managed through Infoblox, ensure that the DNS Smart Proxy and Reverse DNS Smart Proxy are set for those subnets.
5. Using PXE to provision hosts
You can provision bare-metal instances with Foreman using one of the following methods:
- Unattended Provisioning
-
New hosts are identified by a MAC address and Foreman server provisions the host using a PXE boot process.
- Unattended Provisioning with Discovery
-
New hosts use PXE boot to load the Foreman Discovery service. This service identifies hardware information about the host and lists it as an available host to provision. For more information, see Configuring the Discovery service.
- PXE-less Provisioning
-
New hosts are provisioned with a boot disk or PXE-less discovery image that Foreman server generates.
- PXE-less Provisioning with Discovery
-
New hosts use an ISO boot disk that loads the Foreman Discovery service. This service identifies hardware information about the host and lists it as an available host to provision. For more information, see Implementing PXE-less Discovery.
Note
|
Discovery workflows are only available when the Discovery plugin is installed. For more information, see Configuring the Discovery service. |
With Foreman, you can perform both BIOS and UEFI based PXE provisioning. Both BIOS and UEFI interfaces work as interpreters between the operating system and firmware of a computer, initializing hardware components and starting the operating system at boot time.
In Foreman provisioning, the PXE loader option defines the DHCP filename
option to use during provisioning.
-
For BIOS systems, use the PXELinux BIOS option to enable a provisioned host to download the
pxelinux.0
file over TFTP. -
For UEFI systems, use the PXEGrub2 UEFI option to enable a TFTP client to download
grub2/grubx64.efi
file, or use the PXEGrub2 UEFI HTTP option to enable an UEFI HTTP client to downloadgrubx64.efi
from Smart Proxy with the HTTP Boot feature.
Foreman supports UEFI Secure Boot.
SecureBoot PXE loaders enable a client to download the shim.efi
bootstrap boot loader that then loads the signed grubx64.efi
.
Use the Grub2 UEFI SecureBoot PXE loader for PXE-boot provisioning or Grub2 UEFI HTTPS SecureBoot for HTTP-boot provisioning.
Important
|
You can only use Secure Boot to provision hosts with the same operating system version, major and minor, that runs on your TFTP Smart Proxy. |
Other PXE loaders, such as PXELinux UEFI, Grub2 ELF, or iPXE Chain, require additional configuration. These workflows are not documented.
For BIOS provisioning, you must associate a PXELinux template with the operating system. For UEFI provisioning, you must associate a PXEGrub2 template with the operating system. If you associate both PXELinux and PXEGrub2 templates, Foreman can deploy configuration files for both on a TFTP server, so that you can switch between PXE loaders easily.
5.1. Prerequisites for bare-metal provisioning
The requirements for bare-metal provisioning include:
-
A Smart Proxy server managing the network for bare-metal hosts. For unattended provisioning and discovery-based provisioning, Foreman server requires PXE server settings.
For more information about networking requirements, see Configuring networking.
For more information about the Discovery service, Configuring the Discovery service.
-
A bare-metal host or a blank VM.
-
Provide the installation medium for the operating systems that you want to use to provision hosts. If the Katello plugin is installed, you can use synchronized content repositories for Red Hat Enterprise Linux. For more information, see Syncing Repositories in Managing content.
-
If the Katello plugin is installed, provide an activation key for host registration. For more information, see Creating An Activation Key in Managing content.
For information about the security token for unattended and PXE-less provisioning, see Configuring the security token validity duration.
5.2. Configuring the security token validity duration
When performing any kind of provisioning, as a security measure, Foreman automatically generates a unique token and adds this token to the OS installer recipe URL in the PXE configuration file (PXELinux, Grub2). By default, the token is valid for 360 minutes. When you provision a host, ensure that you reboot the host within this time frame. If the token expires, it is no longer valid and you receive a 404 error and the operating system installer download fails.
-
In the Foreman web UI, navigate to Administer > Settings, and click the Provisioning tab.
-
Find the Token duration option and click the edit icon and edit the duration, or enter
0
to disable token generation. If token generation is disabled, an attacker can spoof client IP address and download OS installer recipe from Foreman server, including the encrypted root password.
5.3. Creating hosts with unattended provisioning
Unattended provisioning is the simplest form of host provisioning. You enter the host details on Foreman server and boot your host. Foreman server automatically manages the PXE configuration, organizes networking services, and provides the operating system and configuration for the host.
This method of provisioning hosts uses minimal interaction during the process.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
In the Name field, enter a name for the host.
-
Optional: Click the Organization tab and change the organization context to match your requirement.
-
Optional: Click the Location tab and change the location context to match your requirement.
-
From the Host Group list, select a host group that you want to assign your host to. That host group will populate the form.
-
Click the Interfaces tab, and on the interface of the host, click Edit.
-
Verify that the fields are populated with values. Note in particular:
-
Foreman automatically assigns an IP address for the new host.
-
In the MAC address field, enter a MAC address of the provisioning interface of the host. This ensures the identification of the host during the PXE boot process.
-
The Name from the Host tab becomes the DNS name.
-
Ensure that Foreman automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
-
-
Click OK to save. To add another interface, click Add Interface. You can select only one interface for Provision and Primary.
-
Click the Operating System tab, and verify that all fields contain values. Confirm each aspect of the operating system.
-
Optional: Click Resolve in Provisioning template to check the new host can identify the right provisioning templates to use.
For more information about associating provisioning templates, see Provisioning templates.
-
Click the Parameters tab, and ensure that a parameter exists that provides an activation key. If not, add an activation key.
-
Click Submit to save the host details.
For more information about network interfaces, see Adding network interfaces in Managing hosts.
This creates the host entry and the relevant provisioning settings. This also includes creating the necessary directories and files for PXE booting the bare-metal host. If you start the physical host and set its boot mode to PXE, the host detects the DHCP service of Foreman server’s integrated Smart Proxy, receives HTTP endpoint of the Kickstart tree and installs the operating system.
When the installation completes, the host also registers to Foreman server using the activation key and installs the necessary configuration and management tools from the Foreman Client repository.
-
Create the host with the
hammer host create
command:# hammer host create \ --build true \ --enabled true \ --hostgroup "My_Host_Group" \ --location "My_Location" \ --mac "My_MAC_Address" \ --managed true \ --name "My_Host_Name" \ --organization "My_Organization"
-
Ensure the network interface options are set using the
hammer host interface update
command:# hammer host interface update \ --host "_My_Host_Name_" \ --managed true \ --primary true \ --provision true
5.4. Creating hosts with PXE-less provisioning
Some hardware does not provide a PXE boot interface. In Foreman, you can provision a host without PXE boot. This is also known as PXE-less provisioning and involves generating a boot ISO that hosts can use. Using this ISO, the host can connect to Foreman server, boot the installation media, and install the operating system.
Foreman also provides a PXE-less discovery service that operates without PXE-based services, such as DHCP and TFTP. For more information, see Implementing PXE-less Discovery.
There are the following types of boot ISOs:
- Host image
-
A boot ISO for the specific host. This image contains only the boot files that are necessary to access the installation media on Foreman server. The user defines the subnet data in Foreman and the image is created with static networking. The image is based on iPXE boot firmware, only a limited number of network cards is supported.
- Full host image
-
A boot ISO that contains the kernel and initial RAM disk image for the specific host. This image is useful if the host fails to chainload correctly. The provisioning template still downloads from Foreman server.
- Generic image
-
A boot ISO that is not associated with a specific host. The ISO sends the host’s MAC address to Foreman server, which matches it against the host entry. The image does not store IP address details and requires access to a DHCP server on the network to bootstrap. This image is also available from the
/disks/generic
URL on your Foreman server, for example,https://foreman.example.com/disks/generic
. - Subnet image
-
A boot ISO that is not associated with a specific host. The ISO sends the host’s MAC address to Smart Proxy server, which matches it against the host entry. The image does not store IP address details and requires access to a DHCP server on the network to bootstrap. This image is generic to all hosts with a provisioning NIC on the same subnet. The image is based on iPXE boot firmware, only a limited number of network cards is supported.
Note
|
The Full host image is based on SYSLINUX and Grub and works with most network cards. When using a Host image, Generic image, or Subnet image, see supported hardware on ipxe.org for a list of network card drivers expected to work with an iPXE-based boot disk. |
Host image and Full host image contain provisioning tokens, therefore the generated image has limited lifespan. For more information about configuring security tokens, read Configuring the security token validity duration.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
In the Name field, enter a name for the host.
-
Optional: Click the Organization tab and change the organization context to match your requirement.
-
Optional: Click the Location tab and change the location context to match your requirement.
-
From the Host Group list, select a host group that you want to assign your host to. That host group will populate the form.
-
Click the Interfaces tab, and on the interface of the host, click Edit.
-
Verify that the fields are populated with values. Note in particular:
-
Foreman automatically assigns an IP address for the new host.
-
In the MAC address field, enter a MAC address of the provisioning interface of the host. This ensures the identification of the host during the PXE boot process.
-
The Name from the Host tab becomes the DNS name.
-
Ensure that Foreman automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
-
-
Click OK to save. To add another interface, click Add Interface. You can select only one interface for Provision and Primary.
-
Click the Operating System tab, and verify that all fields contain values. Confirm each aspect of the operating system.
-
Click Resolve in Provisioning Templates to check the new host can identify the right provisioning templates to use.
For more information about associating provisioning templates, see Provisioning templates.
-
Click the Parameters tab, and ensure that a parameter exists that provides an activation key. If not, add an activation key.
-
Click Submit to save the host details. This creates a host entry and the host details page appears.
-
Download the boot disk from Foreman server.
-
For Host image, on the host details page, click the vertical ellipsis and select Host 'My_Host_Name' image.
-
For Full host image, on the host details page, click the vertical ellipsis and select Full host 'My_Host_Name' image.
-
For Generic image, navigate to Infrastructure > Subnets, click Boot disk and select Generic image.
-
For Subnet image, navigate to Infrastructure > Subnets, click the dropdown menu in the Actions column of the required subnet and select Subnet generic image.
-
-
Write the ISO to a USB storage device using the
dd
utility orlivecd-tools
if required. -
When you start the host and boot from the ISO or the USB storage device, the host connects to Foreman server and starts installing operating system from its kickstart tree.
When the installation completes, the host also registers to Foreman server using the activation key and installs the necessary configuration and management tools from the Foreman Client repository.
-
Create the host using the
hammer host create
command.# hammer host create \ --build true \ --enabled true \ --hostgroup "My_Host_Group" \ --location "My_Location" \ --mac "My_MAC_Address" \ --managed true \ --name "My_Host_Name" \ --organization "My_Organization"
-
Ensure that your network interface options are set using the
hammer host interface update
command.# hammer host interface update \ --host "My_Host_Name" \ --managed true \ --primary true \ --provision true
-
Download the boot disk from Foreman server using the
hammer bootdisk
command:-
For Host image:
# hammer bootdisk host --host My_Host_Name
-
For Full host image:
# hammer bootdisk host \ --full true \ --host My_Host_Name
-
For Generic image:
# hammer bootdisk generic
-
For Subnet image:
# hammer bootdisk subnet --subnet My_Subnet_Name
This creates a boot ISO for your host to use.
-
-
Write the ISO to a USB storage device using the
dd
utility orlivecd-tools
if required. -
When you start the physical host and boot from the ISO or the USB storage device, the host connects to Foreman server and starts installing operating system from its kickstart tree.
When the installation completes, the host also registers to Foreman server using the activation key and installs the necessary configuration and management tools from the Foreman Client repository.
5.5. Creating hosts with UEFI HTTP boot provisioning
You can provision hosts from Foreman using the UEFI HTTP Boot. This is the only method with which you can provision hosts in IPv6 network.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
Ensure that you meet the requirements for HTTP booting. For more information, see HTTP Booting Requirements in Planning for Foreman.
-
On Smart Proxy that you use for provisioning, update the
grub2-efi
package to the latest version:# dnf upgrade grub2-efi
-
Enable
foreman-proxy-http
,foreman-proxy-httpboot
, andforeman-proxy-tftp
features.# foreman-installer \ --foreman-proxy-http true \ --foreman-proxy-httpboot true \ --foreman-proxy-tftp true
-
Ensure that the Smart Proxy has TFTP and HTTPBoot features recognized. In the Foreman web UI, navigate to Infrastructure > Smart Proxies and click on Smart Proxy to see the list of recognized features. Click Refresh Features if any of the features are missing.
-
Ensure that Smart Proxy is associated with the provisioning subnet. In the Foreman web UI, navigate to Infrastructure > Subnets > Edit Subnet > Smart Proxies and select the Smart Proxy for both TFTP and HTTPBoot options.
-
Click OK to save.
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
In the Name field, enter a name for the host.
-
Optional: Click the Organization tab and change the organization context to match your requirement.
-
Optional: Click the Location tab and change the location context to match your requirement.
-
From the Host Group list, select a host group that you want to assign your host to. That host group will populate the form.
-
Click the Interfaces tab, and on the interface of the host, click Edit.
-
Verify that the fields are populated with values. Note in particular:
-
Foreman automatically assigns an IP address for the new host.
-
In the MAC address field, enter a MAC address of the provisioning interface of the host. This ensures the identification of the host during the PXE boot process.
-
The Name from the Host tab becomes the DNS name.
-
Ensure that Foreman automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
-
-
Click OK to save. To add another interface, click Add Interface. You can select only one interface for Provision and Primary.
-
Click the Operating System tab, and verify that all fields contain values. Confirm each aspect of the operating system.
-
From the PXE Loader list, select Grub2 UEFI HTTP.
-
Optional: Click Resolve in Provisioning template to check the new host can identify the right provisioning templates to use.
For more information about associating provisioning templates, see Creating provisioning templates.
-
Click the Parameters tab, and ensure that a parameter exists that provides an activation key. If not, add an activation key.
-
Click Submit to save the host details.
For more information about network interfaces, see Adding network interfaces in Managing hosts.
-
Set the host to boot in UEFI mode from network.
-
Start the host.
-
From the boot menu, select Kickstart default PXEGrub2.
This creates the host entry and the relevant provisioning settings. This also includes creating the necessary directories and files for UEFI booting the bare-metal host. When you start the physical host and set its boot mode to UEFI HTTP, the host detects the defined DHCP service, receives HTTP endpoint of Smart Proxy with the Kickstart tree and installs the operating system.
When the installation completes, the host also registers to Foreman server using the activation key and installs the necessary configuration and management tools from the Foreman Client repository.
-
On Smart Proxy that you use for provisioning, update the
grub2-efi
package to the latest version:# dnf upgrade grub2-efi
-
Enable
foreman-proxy-http
,foreman-proxy-httpboot
, andforeman-proxy-tftp true
features:# foreman-installer \ --foreman-proxy-http true \ --foreman-proxy-httpboot true \ --foreman-proxy-tftp true
-
Create the host with the
hammer host create
command.# hammer host create \ --build true \ --enabled true \ --hostgroup "My_Host_Group" \ --location "My_Location" \ --mac "My_MAC_Address" \ --managed true \ --name "My_Host_Name" \ --organization "My_Organization" \ --pxe-loader "Grub2 UEFI HTTP"
-
Ensure the network interface options are set using the
hammer host interface update
command:# hammer host interface update \ --host "My_Host_Name" \ --managed true \ --primary true \ --provision true
-
Set the host to boot in UEFI mode from network.
-
Start the host.
-
From the boot menu, select Kickstart default PXEGrub2.
This creates the host entry and the relevant provisioning settings. This also includes creating the necessary directories and files for UEFI booting the bare-metal host. When you start the physical host and set its boot mode to UEFI HTTP, the host detects the defined DHCP service, receives HTTP endpoint of Smart Proxy with the Kickstart tree and installs the operating system.
When the installation completes, the host also registers to Foreman server using the activation key and installs the necessary configuration and management tools from the Foreman Client repository.
5.6. Deploying SSH keys during provisioning
Use this procedure to deploy SSH keys added to a user during provisioning. For information on adding SSH keys to a user, see Managing SSH Keys for a User in Administering Foreman.
-
In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates.
-
Create a provisioning template, or clone and edit an existing template. For more information, see Creating provisioning templates.
-
In the template, click the Template tab.
-
In the Template editor field, add the
create_users
snippet to the%post
section:<%= snippet('create_users') %>
-
Select the Default checkbox.
-
Click the Association tab.
-
From the Application Operating Systems list, select an operating system.
-
Click Submit to save the provisioning template.
-
Create a host that is associated with the provisioning template or rebuild a host using the OS associated with the modified template. For more information, see Creating a Host in Managing hosts.
The SSH keys of the Owned by user are added automatically when the
create_users
snippet is executed during the provisioning process. You can set Owned by to an individual user or a user group. If you set Owned by to a user group, the SSH keys of all users in the user group are added automatically.
6. Using iPXE to reduce provisioning times
iPXE is an open-source network-boot firmware. It provides a full PXE implementation enhanced with additional features, such as booting from an HTTP server. For more information about iPXE, see iPXE website.
You can use iPXE if the following restrictions prevent you from using PXE:
-
A network with unmanaged DHCP servers.
-
A PXE service that is unreachable because of, for example, a firewall restriction.
-
A TFTP UDP-based protocol that is unreliable because of, for example, a low-bandwidth network.
6.1. Prerequisites for using iPXE
You can use iPXE to boot virtual machines in the following cases:
-
Your virtual machines run on a hypervisor that uses iPXE as primary firmware.
-
Your virtual machines are in BIOS mode. In this case, you can configure PXELinux to chainboot iPXE and boot by using the HTTP protocol.
For booting virtual machines in UEFI mode by using HTTP, you can follow Creating hosts with UEFI HTTP boot provisioning instead.
Only BIOS systems are known to work reliably. For configuring iPXE with some EFI hosts, read a separate tutorial.
-
The MAC address of the provisioning interface matches the host configuration.
-
The provisioning interface of the host has a valid DHCP reservation.
-
The NIC is capable of PXE booting. For more information, see supported hardware on ipxe.org for a list of hardware drivers expected to work with an iPXE-based boot disk.
-
The NIC is compatible with iPXE.
6.2. Configuring iPXE environment
Configure an iPXE environment on all Smart Proxies that you want to use for iPXE provisioning.
Important
|
In Enterprise Linux, security-related features of iPXE are not supported and the iPXE binary is built without security features. For this reason, you can only use HTTP but not HTTPS. You can recompile iPXE from source to use security features such as HTTPS. |
-
If you want to use Smart Proxy servers instead of your Foreman server, ensure that you have configured your Smart Proxy servers accordingly. For more information, see Configuring Smart Proxy for Host Registration and Provisioning in Installing a Smart Proxy Server 3.11 on Enterprise Linux.
-
Enable the TFTP and HTTPboot services on your Smart Proxy:
# foreman-installer \ --foreman-proxy-httpboot true \ --foreman-proxy-tftp true
-
Install the
ipxe-bootimgs
package on your Smart Proxy:# dnf install ipxe-bootimgs
-
Copy iPXE firmware to the TFTP directory.
-
Copy the iPXE firmware with the Linux kernel header:
# cp /usr/share/ipxe/ipxe.lkrn /var/lib/tftpboot/
-
Copy the UNDI iPXE firmware:
# cp /usr/share/ipxe/undionly.kpxe /var/lib/tftpboot/undionly-ipxe.0
-
-
Correct the SELinux file contexts:
# restorecon -RvF /var/lib/tftpboot/
-
Set the HTTP URL.
-
If you want to use Foreman server for booting, run the following command on Foreman server:
# foreman-installer \ --foreman-proxy-dhcp-ipxefilename "http://foreman.example.com/unattended/iPXE?bootstrap=1"
-
If you want to use Smart Proxy server for booting, run the following command on Smart Proxy server:
# foreman-installer --foreman-proxy-dhcp-ipxe-bootstrap true
-
6.3. Booting virtual machines
Some virtualization hypervisors use iPXE as primary firmware for PXE booting. If you use such a hypervisor, you can boot virtual machines without TFTP and PXELinux.
Booting a virtual machine has the following workflow:
-
Virtual machine starts.
-
iPXE retrieves the network credentials, including an HTTP URL, by using DHCP.
-
iPXE loads the iPXE bootstrap template from Smart Proxy.
-
iPXE loads the iPXE template with MAC as a URL parameter from Smart Proxy.
-
iPXE loads the kernel and initial RAM disk of the installer.
-
Your hypervisor must support iPXE. The following virtualization hypervisors support iPXE:
-
libvirt
-
oVirt (deprecated)
-
VMWare (via custom firmware)
-
-
You have configured your iPXE environment. For more information, see Configuring iPXE environment.
Note
|
You can use the original templates shipped in Foreman as described below. If you require modification to an original template, clone the template, edit the clone, and associate the clone instead of the original template. For more information, see Cloning provisioning templates. |
-
In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates.
-
Search for the required template:
-
The
AutoYaST default iPXE
template for SUSE Linux Enterprise Server hosts. -
The
Kickstart default iPXE
template for Enterprise Linux hosts. -
The
Preseed default iPXE
template for Debian/Ubuntu hosts.
-
-
Click the name of the template.
-
Click the Association tab and select the operating systems that your host uses.
-
Click the Locations tab and add the location where the host resides.
-
Click the Organizations tab and add the organization that the host belongs to.
-
Click Submit to save the changes.
-
In the Foreman web UI, navigate to Hosts > Operating systems and select the operating system of your host.
-
Click the Templates tab.
-
From the iPXE template list, select the required template:
-
The
AutoYaST default iPXE
template for SUSE Linux Enterprise Server hosts. -
The
Kickstart default iPXE
template for Enterprise Linux hosts. -
The
Preseed default iPXE
template for Debian/Ubuntu hosts.
-
-
Click Submit to save the changes.
-
In the Foreman web UI, navigate to Hosts > All Hosts.
-
In the Hosts page, select the host that you want to use.
-
Select the Operating System tab.
-
Set PXE Loader to
iPXE Embedded
. -
Select the Templates tab.
-
In Provisioning Templates, click Resolve and verify that the iPXE template resolves to the required template.
-
Click Submit to save host settings.
6.4. Chainbooting iPXE from PXELinux
You can set up iPXE to use a built-in driver for network communication (ipxe.lkrn
) or Universal Network Device Interface (UNDI) (undionly-ipxe.0
).
You can choose to load either file depending on the networking hardware capabilities and iPXE driver availability.
UNDI is a minimalistic UDP/IP stack that implements TFTP client.
However, UNDI cannot support other protocols like HTTP.
To use HTTP with iPXE, use the iPXE build with built-in drivers (ipxe.lkrn
).
Chainbooting iPXE has the following workflow:
-
Host powers on.
-
PXE driver retrieves the network credentials by using DHCP.
-
PXE driver retrieves the PXELinux firmware
pxelinux.0
by using TFTP. -
PXELinux searches for the configuration file on the TFTP server.
-
PXELinux chainloads iPXE
ipxe.lkrn
orundionly-ipxe.0
. -
iPXE retrieves the network credentials, including an HTTP URL, by using DHCP again.
-
iPXE chainloads the iPXE template from your Templates Smart Proxy.
-
iPXE loads the kernel and initial RAM disk of the installer.
-
You have configured your iPXE environment. For more information, see Configuring iPXE environment.
Note
|
You can use the original templates shipped in Foreman as described below. If you require modification to an original template, clone the template, edit the clone, and associate the clone instead of the original template. For more information, see Cloning provisioning templates. |
-
In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates.
-
Search for the required PXELinux template:
-
PXELinux chain iPXE
to useipxe.lkrn
-
PXELinux chain iPXE UNDI
to useundionly-ipxe.0
-
-
Click the name of the template you want to use.
-
Click the Association tab and select the operating systems that your host uses.
-
Click the Locations tab and add the location where the host resides.
-
Click the Organizations tab and add the organization that the host belongs to.
-
Click Submit to save the changes.
-
On the Provisioning Templates page, search for the required template:
-
The
AutoYaST default iPXE
template for SUSE Linux Enterprise Server hosts. -
The
Kickstart default iPXE
template for Enterprise Linux hosts. -
The
Preseed default iPXE
template for Debian/Ubuntu hosts.
-
-
Click the name of the template.
-
Click the Association tab and associate the template with the operating system that your host uses.
-
Click the Locations tab and add the location where the host resides.
-
Click the Organizations tab and add the organization that the host belongs to.
-
Click Submit to save the changes.
-
In the Foreman web UI, navigate to Hosts > Operating systems and select the operating system of your host.
-
Click the Templates tab.
-
From the PXELinux template list, select the template you want to use.
-
From the iPXE template list, select the required template:
-
The
AutoYaST default iPXE
template for SUSE Linux Enterprise Server hosts. -
The
Kickstart default iPXE
template for Enterprise Linux hosts. -
The
Preseed default iPXE
template for Debian/Ubuntu hosts.
-
-
Click Submit to save the changes.
-
In the Foreman web UI, navigate to Configure > Host Groups, and select the host group you want to configure.
-
Select the Operating System tab.
-
Select the Architecture and Operating system.
-
Set the PXE Loader:
-
Select
PXELinux BIOS
to chainboot iPXE (ipxe.lkrn
) from PXELinux. -
Select
iPXE Chain BIOS
to loadundionly-ipxe.0
directly.
-
7. Configuring the Discovery service
Foreman can detect hosts on a network that are not in your Foreman inventory. These hosts boot the discovery image that performs hardware detection and relays this information back to Foreman server. This method creates a list of ready-to-provision hosts in Foreman server without needing to enter the MAC address of each host.
When you boot a blank bare-metal host, the boot menu has two options: local
and discovery
.
If you select discovery
to boot the Discovery image, after a few minutes, the Discovery image completes booting and a status screen is displayed.
The Discovery service is enabled by default on Foreman server. However, the default setting of the global templates is to boot from the local hard drive. To change the default setting, in the Foreman web UI, navigate to Administer > Settings, and click the Provisioning tab. Locate the Default PXE global template entry row, and in the Value column, enter discovery. Then build the PXE default configuration. Navigate to Hosts > Templates > Provisioning Templates and click Build PXE Default. Foreman distributes the PXE configuration to any TFTP Proxies.
Ensure that the DHCP range of all subnets that you plan to use for discovery do not intersect with the DHCP lease pool configured for the managed DHCP service.
The DHCP range is set in the Foreman web UI, while the lease pool range is set using the foreman-installer
command.
For example, in a 10.1.0.0/16 network range 10.1.0.0 to 10.1.127.255 could be allocated for leases and 10.1.128.0 to 10.1.255.254 could be allocated for reservations.
Since network interface names are not expected to always be the same between major versions of Red Hat Enterprise Linux,
or any other operating system being provisioned,
hosts or virtual machines can be created with incorrect network configurations. On Dell servers, the new naming scheme can be disabled via biosdevname=1
kernel command line option, for other hardware or virtual machines, the new naming scheme can be completely turned off via net.ifnames=1
.
Note
|
Foreman provides multiple versions of the Foreman Discovery image (FDI):
|
-
Install Discovery on Foreman server:
# foreman-installer \ --enable-foreman-plugin-discovery \ --enable-foreman-proxy-plugin-discovery \ --foreman-proxy-plugin-discovery-install-images=true
This command downloads the latest Discovery image. If you require another version, add the following argument:
--foreman-proxy-plugin-discovery-source-url=https://downloads.theforeman.org/discovery/releases/x.y/
When the installation completes, you can view the new menu option by navigating to Hosts > Discovered Hosts.
7.1. Installing the Discovery service
Complete the following procedure to enable the Discovery service on Smart Proxy server.
-
Enter the following commands on Smart Proxy server:
# foreman-installer \ --enable-foreman-proxy-plugin-discovery \ --foreman-proxy-plugin-discovery-install-images=true
This command downloads the latest Discovery image. If you require another version, add the following argument:
--foreman-proxy-plugin-discovery-source-url=https://downloads.theforeman.org/discovery/releases/x.y/
All subnets with discoverable hosts require an appropriate Smart Proxy server selected to provide the Discovery service.
In the Foreman web UI, navigate to Infrastructure > Subnets, select a subnet, click the Smart Proxies tab, and select the Discovery Proxy that you want to use. Perform this for each subnet that you want to use.
7.2. Provisioning template PXELinux Discovery snippet
For BIOS provisioning, the PXELinux global default
template in the Hosts > Templates > Provisioning Templates window contains the snippet pxelinux_discovery
.
The snippet has the following lines:
LABEL discovery MENU LABEL Foreman Discovery Image KERNEL boot/fdi-image/vmlinuz0 APPEND initrd=boot/fdi-image/initrd0.img rootflags=loop root=live:/fdi.iso rootfstype=auto ro rd.live.image acpi=force rd.luks=0 rd.md=0 rd.dm=0 rd.lvm=0 rd.bootif=0 rd.neednet=0 nomodeset proxy.url=<%= foreman_server_url %> proxy.type=foreman IPAPPEND 2
The KERNEL
and APPEND
options boot the Discovery image and ramdisk.
The APPEND
option contains a proxy.url
parameter, with the foreman_server_url
macro as its argument.
This macro resolves to the full URL of Foreman server.
For UEFI provisioning, the PXEgrub2 global default
template in the Hosts > Templates > Provisioning Templates window contains the snippet pxegrub2_discovery
:
menuentry 'Foreman Discovery Image' --id discovery { linuxefi boot/fdi-image/vmlinuz0 rootflags=loop root=live:/fdi.iso rootfstype=auto ro rd.live.image acpi=force rd.luks=0 rd.md=0 rd.dm=0 rd.lvm=0 rd.bootif=0 rd.neednet=0 nomodeset proxy.url=<%= foreman_server_url %> proxy.type=foreman BOOTIF=01-$mac initrdefi boot/fdi-image/initrd0.img }
To use Smart Proxy to proxy the discovery steps, edit /var/lib/tftpboot/pxelinux.cfg/default
or /var/lib/tftpboot/grub2/grub.cfg
and change the URL to Smart Proxy server FQDN you want to use.
The global template is available on Foreman server and all Smart Proxies that have the TFTP feature enabled.
7.3. Automatic contexts for discovered hosts
Foreman server assigns an organization and location to discovered hosts automatically according to the following sequence of rules:
-
If a discovered host uses a subnet defined in Foreman, the host uses the first organization and location associated with the subnet.
-
If the default location and organization is configured in global settings, the discovered hosts are placed in this organization and location. To configure these settings, navigate to Administer > Settings > Discovery and select values for the Discovery organization and Discovery location settings. Ensure that the subnet of discovered host also belongs to the selected organization and location, otherwise Foreman refuses to set it for security reasons.
-
If none of the previous conditions is met, Foreman assigns the first organization and location ordered by name.
You can change the organization or location manually by using the bulk actions on the Discovered Hosts page. Select the discovered hosts to modify and, from the Select Action menu, select Assign Organization or Assign Location.
7.4. Discovery template and snippet settings
To use the Discovery service, you must configure provisioning settings to set Discovery as the default service and set the templates that you want to use.
For both BIOS and UEFI, to set the Discovery service as the default service that boots for hosts that are not present in your current Foreman inventory, complete the following steps:
-
In the Foreman web UI, navigate to Administer > Settings and click the Provisioning tab.
-
For the Default PXE global template entry, in the Value column, enter
discovery
.
To use a template, in the Foreman web UI, navigate to Administer > Settings and click the Provisioning tab and set the templates that you want to use.
Templates and snippets are locked to prevent changes. If you want to edit a template or snippet, clone it, save it with a unique name, and then edit the clone.
When you change the template or a snippet it includes, the changes must be propagated to Foreman server’s default PXE template.
In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates and click Build PXE Default.
This refreshes the default PXE template on Foreman server.
- The proxy.url argument
-
During the Foreman installation process, if you use the default option
--enable-foreman-plugin-discovery
, you can edit theproxy.url
argument in the template to set the URL of Smart Proxy server that provides the discovery service. You can change theproxy.url
argument to the IP address or FQDN of another provisioning Smart Proxy that you want to use, but ensure that you append the port number, for example,9090
. If you use an alternative port number with the--foreman-proxy-ssl-port
option during Foreman installation, you must add that port number. You can also edit theproxy.url
argument to use a Foreman IP address or FQDN so that the discovered hosts communicate directly with Foreman server. - The proxy.type argument
-
If you use a Smart Proxy server FQDN for the
proxy.url
argument, ensure that you set theproxy.type
argument toproxy
. If you use a Foreman FQDN, update theproxy.type
argument toforeman
.proxy.url=https://smartproxy.example.com:9090 proxy.type=proxy
NoteFor katello scenario deployment, use port 9090.
Foreman deploys the same template to all TFTP Smart Proxies and there is no variable or macro available to render the Smart Proxy’s host name.
The hard-coded proxy.url
does not not work with two or more TFTP Smart Proxies.
As a workaround, every time you click Build PXE Defaults, edit the configuration file in the TFTP directory using SSH, or use a common DNS alias for appropriate subnets.
If you want to use tagged VLAN provisioning, and you want the discovery service to send a discovery request, add the following information to the KERNEL
option in the discovery template:
fdi.vlan.primary=example_VLAN_ID
7.5. Creating hosts from discovered hosts
Provisioning discovered hosts follows a provisioning process that is similar to PXE provisioning. The main difference is that instead of manually entering the host’s MAC address, you can select the host to provision from the list of discovered hosts.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
Configure a domain and subnet on Foreman. For more information about networking requirements, see Configuring networking.
-
Configure the discovery service on Foreman. For more information, see Installing the Discovery service.
-
A bare-metal host or a blank VM.
-
Provide the installation medium for the operating systems that you want to use to provision hosts. If the Katello plugin is installed, you can use synchronized content repositories for Red Hat Enterprise Linux. For more information, see Syncing Repositories in Managing content.
-
If the Katello plugin is installed, provide an activation key for host registration. For more information, see Creating An Activation Key in Managing content.
For information about the security tokens, see Configuring the security token validity duration.
-
In the Foreman web UI, navigate to Hosts > Discovered host. Select the host you want to use and click Provision to the right of the list.
-
Select from one of the two following options:
-
To provision a host from a host group, select a host group, organization, and location, and then click Create Host.
-
To provision a host with further customization, click Customize Host and enter the additional details you want to specify for the new host.
-
-
Verify that the fields are populated with values. Note in particular:
-
The Name from the Host tab becomes the DNS name.
-
Foreman server automatically assigns an IP address for the new host.
-
Foreman server automatically populates the MAC address from the Discovery results.
-
-
Ensure that Foreman server automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
-
Click the Operating System tab, and verify that all fields contain values. Confirm each aspect of the operating system.
-
Click Resolve in Provisioning template to check the new host can identify the right provisioning templates to use. The host must resolve to the following provisioning templates:
-
kexec Template:
Discovery Red Hat kexec
-
provision Template:
Foreman Kickstart Default
For more information about associating provisioning templates, see Provisioning templates.
-
-
Click Submit to save the host details.
When the host provisioning is complete, the discovered host becomes a content host. To view the host, navigate to Hosts > Content Hosts.
-
Identify the discovered host to use for provisioning:
# hammer discovery list
-
Select a host and provision it using a host group. Set a new host name with the
--new-name
option:# hammer discovery provision \ --build true \ --enabled true \ --hostgroup "My_Host_Group" \ --location "My_Location" \ --managed true \ --name "My_Host_Name" \ --new-name "My_New_Host_Name" \ --organization "My_Organization"
This removes the host from the discovered host listing and creates a host entry with the provisioning settings. The Discovery image automatically resets the host so that it can boot to PXE. The host detects the DHCP service on Foreman server’s integrated Smart Proxy and starts installing the operating system. The rest of the process is identical to normal PXE workflow described in Creating hosts with unattended provisioning.
7.6. Creating Discovery rules
As a method of automating the provisioning process for discovered hosts, Foreman provides a feature to create discovery rules. These rules define how discovered hosts automatically provision themselves, based on the assigned host group. For example, you can automatically provision hosts with a high CPU count as hypervisors. Likewise, you can provision hosts with large hard disks as storage servers.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
Auto provisioning does not currently allow configuring NICs; all systems are being provisioned with the NIC configuration that was detected during discovery.
However, you can set the NIC in the OS installer recipe
scriplet, using a script, or using configuration management at a later stage.
-
In the Foreman web UI, navigate to Configure > Discovery rules, and select Create Rule.
-
In the Name field, enter a name for the rule.
-
In the Search field, enter the rules to determine whether to provision a host. This field provides suggestions for values you enter and allows operators for multiple rules. For example:
cpu_count > 8
. -
From the Host Group list, select the host group to use as a template for this host.
-
In the Hostname field, enter the pattern to determine host names for multiple hosts. This uses the same ERB syntax that provisioning templates use. The host name can use the
@host
attribute for host-specific values and therand
macro for a random number or thesequence_hostgroup_param_next
macro for incrementing the value. For more information about provisioning templates, see Provisioning templates and the API documentation.-
myhost-<%= sequence_hostgroup_param_next("EL7/MyHostgroup", 10, "discovery_host") %>
-
myhost-<%= rand(99999) %>
-
abc-<%= @host.facts['bios_vendor'] %>-<%= rand(99999) %>
-
xyz-<%= @host.hostgroup.name %>
-
srv-<%= @host.discovery_rule.name %>
-
server-<%= @host.ip.gsub('.','-') + '-' + @host.hostgroup.subnet.name %>
When creating host name patterns, ensure that the resulting host names are unique, do not start with numbers, and do not contain underscores or dots. A good approach is to use unique information provided by Facter, such as the MAC address, BIOS, or serial ID.
-
-
In the Hosts limit field, enter the maximum number of hosts that you can provision with the rule. Enter
0
for unlimited. -
In the Priority field, enter a number to set the precedence the rule has over other rules. Rules with lower values have a higher priority.
-
From the Enabled list, select whether you want to enable the rule.
-
To set a different provisioning context for the rule, click the Organizations and Locations tabs and select the contexts you want to use.
-
Click Submit to save your rule.
-
In the Foreman web UI, navigate to Hosts > Discovered Host and select one of the following two options:
-
From the Discovered hosts list on the right, select Auto-Provision to automatically provisions a single host.
-
On the upper right of the window, click Auto-Provision All to automatically provisions all hosts.
-
-
Create the rule with the
hammer discovery-rule create
command:# hammer discovery-rule create \ --enabled true \ --hostgroup "My_Host_Group" \ --hostname "hypervisor-<%= rand(99999) %>" \ --hosts-limit 5 \ --name "My_Hypervisor" \ --priority 5 \ --search "cpu_count > 8"
-
Automatically provision a host with the
hammer discovery auto-provision
command:# hammer discovery auto-provision --name "macabcdef123456"
7.7. Implementing PXE-less Discovery
Foreman provides a PXE-less Discovery service that operates without the need for PXE-based services (DHCP and TFTP).
You accomplish this using Foreman server’s Discovery image.
Once a discovered node is scheduled for installation, it uses kexec
command to reload Linux kernel with OS installer without rebooting the node.
The console might freeze during the process. On some hardware, you might experience graphical hardware problems.
If you have not yet installed the Discovery service or image, see Building a Discovery image.
-
Copy this media to either a CD, DVD, or a USB stick. For example, to copy to a USB stick at
/dev/sdb
:# dd bs=4M \ if=/usr/share/foreman-discovery-image/foreman-discovery-image-3.4.4-5.iso \ of=/dev/sdb
-
Insert the Discovery boot media into a bare-metal host, start the host, and boot from the media. The Discovery Image displays an option for either Manual network setup or Discovery with DHCP:
If you select Manual network setup, the Discovery image requests a set of network options. This includes the primary network interface that connects to Foreman server. This Discovery image also asks for network interface configuration options, such as an IPv4 Address, IPv4 Gateway, and an IPv4 DNS server.
-
After entering these details, select Next.
-
If you select Discovery with DHCP, the Discovery image requests only the primary network interface that connects to Foreman server. It attempts to automatically configure the network interface using a DHCP server, such as one that a Smart Proxy server provides.
-
After the primary interface configuration, the Discovery image requests the Server URL, which is the URL of Foreman server or Smart Proxy server offering the Discovery service. For example, to use the integrated Smart Proxy on Foreman server, use the following URL:
https://foreman.example.com:9090
-
Set the Connection type to
Proxy
, then select Next. -
Optional: The Discovery image also provides a set of fields to input Custom facts for the Facter tool to relay back to Foreman server. These are entered in a name-value format. Provide any custom facts you require and select Confirm to continue.
Foreman reports a successful communication with Foreman server’s Discovery service. In the Foreman web UI, navigate to Hosts > Discovered Hosts and view the newly discovered host.
For more information about provisioning discovered hosts, see Creating hosts from discovered hosts.
7.8. Building a Discovery image
The Discovery image is a minimal operating system that is PXE-booted on hosts to acquire initial hardware information and to check in with Foreman. Discovered hosts keep running the Discovery image until they are rebooted into Anaconda, which then initiates the provisioning process.
Run the following procedure on Enterprise Linux 8.
The Discovery image is based on CentOS Stream 8.
Use this procedure to build a Foreman discovery image or rebuild an image if you change configuration files.
Do not use this procedure on your production Foreman or Smart Proxy. Use either a dedicated environment or copy the synchronized repositories and a kickstart file to a separate server.
-
Ensure that hardware virtualization is available on your host.
-
Install the following packages:
# dnf install git-core lorax anaconda pykickstart wget qemu-kvm
-
Clone the
foreman-discovery-image
repository:$ git clone https://github.com/theforeman/foreman-discovery-image.git $ cd foreman-discovery-image
-
Replace the contents of the
00-repos-centos8.ks
file with the following:url --mirrorlist=http://mirrorlist.centos.org/?release=8&arch=$basearch&repo=baseos repo --name="AppStream" --mirrorlist=http://mirrorlist.centos.org/?release=8&arch=$basearch&repo=appstream repo --name="foreman-el8" --baseurl=http://yum.theforeman.org/releases/3.11/el8/$basearch/ repo --name="foreman-plugins-el8" --baseurl=http://yum.theforeman.org/plugins/3.11/el8/$basearch/ module --name=ruby --stream=2.7 module --name=postgresql --stream=12 module --name=foreman --stream=el8
-
Prepare the kickstart file:
$ ./build-livecd fdi-centos8.ks
-
Build the ISO image:
$ sudo ./build-livecd-root custom ./result "nomodeset nokaslr"
The options
nomodeset
andnokaslr
instruct the Discovery image kernel to disable mode setting and to disable ASLR (Address Space Layout Randomization). -
Verify that your
./result/fdi-custom-XXXXXXX.iso
file is created:$ ls -h ./result/*.iso
Use the following command to build a fully automated Discovery image with a static network configuration:
$ sudo ./build-livecd-root custom ./result \ "nomodeset nokaslr \ fdi.pxip=192.168.140.20/24 fdi.pxgw=192.168.140.1 \ fdi.pxdns=192.168.140.2 proxy.url=https://foreman.example.com:8443 \ proxy.type=foreman fdi.pxmac=52:54:00:be:8e:8c fdi.pxauto=1"
For more information about configuration options, see Unattended use, customization, and image remastering.
When you create the .iso
file, you can boot the .iso
file over a network or locally.
Complete one of the following procedures.
If you want to boot the .iso
file over a network, complete the following steps:
-
Create a directory to store your boot files:
# mkdir /var/lib/tftpboot/boot/myimage
-
Copy the
./tftpboot/initrd0.img
and./tftpboot/vmlinuz0
files to your new directory. -
Edit the
KERNEL
andAPPEND
entries in the/var/lib/tftpboot/pxelinux.cfg
file to add the information about your own initial ramdisk and kernel files.
If you want to create a hybrid .iso
file for booting locally, complete the following steps:
-
To convert the
.iso
file to an.iso
hybrid file for PXE provisioning, enter the following command:# isohybrid --partok fdi.iso
If you have
grub2
packages installed, you can also use the following command to install agrub2
bootloader:# isohybrid --partok --uefi fdi.iso
-
To add
md5
checksum to the.iso
file so it can pass installation media validation tests in Foreman, enter the following command:# implantisomd5 fdi.iso
7.9. Unattended use, customization, and image remastering
You can create a customized Discovery ISO to automate the image configuration process after booting. The Discovery image uses a Linux kernel for the operating system, which passes kernel parameters to configure the discovery service. These kernel parameters include the following entries:
- fdi.cachefacts
-
Number of fact uploads without caching. By default, Foreman does not cache any uploaded facts.
- fdi.countdown
-
Number of seconds to wait until the text-user interface is refreshed after the initial discovery attempt. This value defaults to 45 seconds. Increase this value if the status page reports the IP address as
N/A
. - fdi.dhcp_timeout
-
NetworkManager DHCP timeout. The default value is 300 seconds.
- fdi.dns_nameserver
-
Nameserver to use for DNS SRV record.
- fdi.dns_ndots
-
ndots
option to use for DNS SRV record. - fdi.dns_search
-
Search domain to use for DNS SRV record.
- fdi.initnet
-
By default, the image initializes all network interfaces (value
all
). When this setting is set tobootif
, only the network interface it was network-booted from will be initialized. - fdi.ipv4.method
-
By default, NetworkManager IPv4 method setting is set to
auto
. This option overrides it, set it toignore
to disable the IPv4 stack. This option works only in DHCP mode. - fdi.ipv6.method
-
By default, NetworkManager IPv6 method setting is set to
auto
. This option overrides it, set it toignore
to disable the IPv6 stack. This option only works in DHCP mode. - fdi.ipwait
-
Duration in seconds to wait for IP to be available in HTTP proxy SSL cert start. By default, Foreman waits for 120 seconds.
- fdi.nmwait
-
nmcli -wait
option for NetworkManager. By default,nmcli
waits for 120 seconds. - fdi.proxy_cert_days
-
Number of days the self-signed HTTPS cert is valid for. By default, the certificate is valid for 999 days.
- fdi.pxauto
-
To set automatic or semi-automatic mode. If set to 0, the image uses semi-automatic mode, which allows you to confirm your choices through a set of dialog options. If set to 1, the image uses automatic mode and proceeds without any confirmation.
- fdi.pxfactname1, fdi.pxfactname2 … fdi.pxfactnameN
-
Use to specify custom fact names.
- fdi.pxfactvalue1, fdi.pxfactvalue2 … fdi.pxfactvalueN
-
The values for each custom fact. Each value corresponds to a fact name. For example,
fdi.pxfactvalue1
sets the value for the fact named withfdi.pxfactname1
. - fdi.pxip, fdi.pxgw, fdi.pxdns
-
Manually configures IP address (
fdi.pxip
), the gateway (fdi.pxgw
), and the DNS (fdi.pxdns
) for the primary network interface. If you omit these parameters, the image uses DHCP to configure the network interface. You can add multiple DNS entries in a comma-separated [1] list, for examplefdi.pxdns=192.168.1.1,192.168.200.1
. - fdi.pxmac
-
The MAC address of the primary interface in the format of
AA:BB:CC:DD:EE:FF
. This is the interface you aim to use for communicating with Smart Proxy server. In automated mode, the first NIC (using network identifiers in alphabetical order) with a link is used. In semi-automated mode, a screen appears and requests you to select the correct interface. - fdi.rootpw
-
By default, the
root
account is locked. Use this option to set a root password. You can enter both clear and encrypted passwords. - fdi.ssh
-
By default, the SSH service is disabled. Set this to
1
ortrue
to enable SSH access. - fdi.uploadsleep
-
Duration in seconds between facter runs. By default, facter runs every 30 seconds.
- fdi.vlan.primary
-
VLAN tagging ID to set for the primary interface.
- fdi.zips
-
Filenames with extensions to be downloaded and started during boot. For more information, see see Extending the Discovery image.
- fdi.zipserver
-
TFTP server to use to download extensions from. For more information, see see Extending the Discovery image.
- proxy.type
-
The proxy type. This is usually set to
proxy
to connect to Smart Proxy server. This parameter also supports a legacyforeman
option, where communication goes directly to Foreman server instead of a Smart Proxy server. - proxy.url
-
The URL of Smart Proxy server or Foreman server providing the Discovery service.
discovery-remaster
tool to remaster an OS imageForeman server provides the discovery-remaster
tool.
This tool remasters the image to include these kernel parameters.
To remaster the image, run the discovery-remaster
tool.
For example:
# discovery-remaster ~/iso/foreman-discovery-image-3.4.4-5.iso \ "fdi.pxip=192.168.140.20/24 fdi.pxgw=192.168.140.1 \ fdi.pxdns=192.168.140.2 proxy.url=https://foreman.example.com:9090 \ proxy.type=proxy fdi.pxfactname1=customhostname fdi.pxfactvalue1=myhost fdi.pxmac=52:54:00:be:8e:8c fdi.pxauto=1"
Copy this media to either a CD, DVD, or a USB stick.
For example, to copy to a USB stick at /dev/sdb
:
# dd bs=4M \ if=/usr/share/foreman-discovery-image/foreman-discovery-image-3.4.4-5.iso \ of=/dev/sdb
Insert the Discovery boot media into a bare-metal host, start the host, and boot from the media.
For more information about provisioning discovered hosts, see Creating hosts from discovered hosts.
7.10. Extending the Discovery image
You can extend the Foreman Discovery image with custom facts, software, or device drivers. You can also provide a compressed archive file containing extra code for the image to use.
-
Create the following directory structure:
. ├── autostart.d │ └── 01_zip.sh ├── bin │ └── ntpdate ├── facts │ └── test.rb └── lib ├── libcrypto.so.1.0.0 └── ruby └── test.rb
-
The
autostart.d
directory contains scripts that are executed in POSIX order by the image when it starts, but before the host is registered to Foreman. -
The
bin
directory is added to the$PATH
variable; you can place binary files in this directory and use them in theautostart
scripts. -
The
facts
directory is added to theFACTERLIB
variable so that custom facts can be configured and sent to Foreman. -
The
lib
directory is added to theLD_LIBRARY_PATH
variable andlib/ruby
is added to theRUBYLIB
variable, so that binary files in/bin
can be executed correctly.
-
-
After creating the directory structure, create a
.zip
file archive with the following command:# zip -r my_extension.zip .
-
To inform the Discovery image of the extensions it must use, place your zip files on your TFTP server with the Discovery image, and then update the
APPEND
line of the PXELinux template with thefdi.zips
option where the paths are relative to the TFTP root. For example, if you have two archives at$TFTP/zip1.zip
and$TFTP/boot/zip2.zip
, use the following syntax:fdi.zips=zip1.zip,boot/zip2.zip
You can append new directives and options to the existing environment variables (PATH
, LD_LIBRARY_PATH
, RUBYLIB
and FACTERLIB
).
If you want to specify the path explicitly in your scripts, the .zip
file contents are extracted to the /opt/extension
directory on the image.
You can create multiple .zip
files but be aware that they are extracted to the same location on the Discovery image.
Files extracted from in later .zip
files overwrite earlier versions if they have the same file name.
7.11. Troubleshooting Discovery
If a machine is not listed in the Foreman web UI in Hosts > Discovered Hosts, inspect the following configuration areas to help isolate the error:
-
In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates.
-
Click Build PXE Default to redeploy the default PXELinux template.
-
-
Verify the
pxelinux.cfg/default
configuration file on the TFTP Smart Proxy. -
Ensure adequate network connectivity between hosts, Smart Proxy server, and Foreman server.
-
Check the PXELinux template in use and determine the PXE discovery snippet it includes. Snippets are named as follows:
pxelinux_discovery
,pxegrub_discovery
, orpxegrub2_discovery
. Verify theproxy.url
andproxy.type
options in the PXE discovery snippet. -
Ensure that DNS is working correctly for the discovered nodes, or use an IP address in the
proxy.url
option in the PXE discovery snippet included in the PXELinux template you are using. -
Ensure that the DHCP server is delivering IP addresses to the booted image correctly.
-
Ensure the discovered host or virtual machine has at least 1200 MB of memory. Less memory can lead to various random kernel panic errors because the image is extracted in-memory.
For gathering important system facts, use the discovery-debug
command.
It prints out system logs, network configuration, list of facts, and other information on the standard output.
The typical use case is to redirect this output and copy it with the scp
command for further investigation.
The first virtual console on the discovered host is reserved for systemd logs. Particularly useful system logs are tagged as follows:
-
discover-host
— initial facts upload -
foreman-discovery
— facts refresh, reboot remote commands -
nm-prepare
— boot script which pre-configures NetworkManager -
NetworkManager
— networking information
Use TTY2 or higher to log in to a discovered host. The root account and SSH access are disabled by default, but you can enable SSH and set the root password using the following kernel command-line options in the Default PXELinux template on the APPEND line:
fdi.ssh=1 fdi.rootpw=My_Password
8. Using a Lorax Composer image for provisioning
In Foreman, you can enable integration with Cockpit to perform actions and monitor your hosts. Using Cockpit, you can access Lorax Composer and build images that you can then upload to an HTTP server and use this image to provision hosts. When you configure Foreman for image provisioning, Anaconda installer partitions disks, downloads and mounts the image and copies files over to a host. The preferred image type is TAR.
Ensure that your blueprint to build the TAR image includes a kernel package.
For more information about integrating Cockpit with Foreman, see Host management and monitoring using Cockpit in Managing hosts.
-
An existing TAR image created using Lorax Composer.
-
On Foreman, create a custom product, add a custom file repository to this product, and upload the image to the repository. For more information, see Importing Individual ISO Images and Files in Managing content.
-
In the Foreman web UI, navigate to Configure > Host Groups, and select the host group that you want to use.
-
Click the Parameters tab, and then click Add Parameter.
-
In the Name field, enter
kickstart_liveimg
. -
From the Type list, select string.
-
In the Value field, enter the absolute path or a relative path in the following format
custom/product/repository/image_name
that points to the exact location where you store the image. -
Click Submit to save your changes.
You can use this image for bare-metal provisioning and provisioning using a compute resource. For more information about bare-metal provisioning, see Using PXE to provision hosts. For more information about provisioning with different compute resources, see the relevant chapter for the compute resource that you want to use.
9. Provisioning virtual machines on KVM (libvirt)
Kernel-based Virtual Machines (KVMs) use an open source virtualization daemon and API called libvirt
running on Red Hat Enterprise Linux.
Foreman can connect to the libvirt
API on a KVM server, provision hosts on the hypervisor, and control certain virtualization functions.
Only Virtual Machines created through Foreman can be managed. Virtual Machines with other than directory storage pool types are unsupported.
You can use KVM provisioning to create hosts over a network connection or from an existing image.
-
Provide the installation medium for the operating systems that you want to use to provision hosts. If the Katello plugin is installed, you can use synchronized content repositories for Red Hat Enterprise Linux. For more information, see Syncing Repositories in Managing content.
-
If the Katello plugin is installed, provide an activation key for host registration. For more information, see Creating An Activation Key in Managing content.
-
A Smart Proxy server managing a network on the KVM server. Ensure no other DHCP services run on this network to avoid conflicts with Smart Proxy server. For more information about network service configuration for Smart Proxy servers, see Configuring Networking in Provisioning hosts.
-
A server running KVM virtualization tools (libvirt daemon).
-
A virtual network running on the libvirt server. Only NAT and isolated virtual networks can be managed through Foreman.
-
An existing virtual machine image if you want to use image-based provisioning. Ensure that this image exists in a storage pool on the KVM host. The
default
storage pool is usually located in/var/lib/libvirt/images
. Only directory pool storage types can be managed through Foreman. -
Optional: The examples in these procedures use the root user for KVM. If you want to use a non-root user on the KVM server, you must add the user to the
libvirt
group on the KVM server:# usermod -a -G libvirt non_root_user
-
For a list of permissions a non-admin user requires to provision hosts, see Permissions required to provision hosts.
-
You can configure Foreman to remove the associated virtual machine when you delete a host. For more information, see Removing a virtual machine upon host deletion.
9.1. Configuring Foreman server for KVM connections
Before adding the KVM connection, create an SSH key pair for the foreman
user to ensure a secure connection between Foreman server and KVM.
-
On Foreman server, switch to the
foreman
user:# su foreman -s /bin/bash
-
Generate the key pair:
$ ssh-keygen
-
Copy the public key to the KVM server:
$ ssh-copy-id root@kvm.example.com
-
Exit the bash shell for the
foreman
user:$ exit
-
Install the
libvirt-client
package:# dnf install libvirt-client
-
Use the following command to test the connection to the KVM server:
# su foreman -s /bin/bash -c 'virsh -c qemu+ssh://root@kvm.example.com/system list'
9.2. Adding a KVM connection to Foreman server
Use this procedure to add KVM as a compute resource in Foreman. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources and click Create Compute Resource.
-
In the Name field, enter a name for the new compute resource.
-
From the Provider list, select Libvirt.
-
In the Description field, enter a description for the compute resource.
-
In the URL field, enter the connection URL to the KVM server. For example:
qemu+ssh://root@kvm.example.com/system
-
From the Display type list, select either VNC or Spice.
-
Optional: To secure console access for new hosts with a randomly generated password, select the Set a randomly generated password on the display connection checkbox. You can retrieve the password for the VNC console to access the guest virtual machine console from the output of the following command executed on the KVM server:
# virsh edit your_VM_name <graphics type='vnc' port='-1' autoport='yes' listen='0.0.0.0' passwd='your_randomly_generated_password'>
The password is randomly generated every time the console for the virtual machine is opened, for example, with virt-manager.
-
Click Test Connection to ensure that Foreman server connects to the KVM server without fault.
-
Verify that the Locations and Organizations tabs are automatically set to your current context. If you want, add additional contexts to these tabs.
-
Click Submit to save the KVM connection.
-
To create a compute resource, enter the
hammer compute-resource create
command:# hammer compute-resource create --name "My_KVM_Server" \ --provider "Libvirt" --description "KVM server at kvm.example.com" \ --url "qemu+ssh://root@kvm.example.com/system" --locations "New York" \ --organizations "My_Organization"
9.3. Adding KVM images to Foreman server
To create hosts using image-based provisioning, you must add information about the image, such as access details and the image location, to your Foreman server.
Note that you can manage only directory pool storage types through Foreman.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources and click the name of the KVM connection.
-
Click Create Image.
-
In the Name field, enter a name for the image.
-
From the Operating System list, select the base operating system of the image.
-
From the Architecture list, select the operating system architecture.
-
In the Username field, enter the SSH user name for image access. This is normally the
root
user. -
In the Password field, enter the SSH password for image access.
-
In the Image path field, enter the full path that points to the image on the KVM server. For example:
/var/lib/libvirt/images/TestImage.qcow2
-
Optional: Select the User Data checkbox if the image supports user data input, such as
cloud-init
data. -
Click Submit to save the image details.
-
Create the image with the
hammer compute-resource image create
command. Use the--uuid
field to store the full path of the image location on the KVM server.# hammer compute-resource image create \ --name "KVM Image" \ --compute-resource "My_KVM_Server" --operatingsystem "RedHat version" \ --architecture "x86_64" \ --username root \ --user-data false \ --uuid "/var/lib/libvirt/images/KVMimage.qcow2" \
9.4. Adding KVM details to a compute profile
Use this procedure to add KVM hardware settings to a compute profile. When you create a host on KVM using this compute profile, these settings are automatically populated.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Profiles.
-
In the Compute Profiles window, click the name of an existing compute profile, or click Create Compute Profile, enter a Name, and click Submit.
-
Click the name of the KVM compute resource.
-
In the CPUs field, enter the number of CPUs to allocate to the new host.
-
In the Memory field, enter the amount of memory to allocate to the new host.
-
From the Image list, select the image to use if performing image-based provisioning.
-
From the Network Interfaces list, select the network parameters for the host’s network interface. You can create multiple network interfaces. However, at least one interface must point to a Smart Proxy-managed network.
-
In the Storage area, enter the storage parameters for the host. You can create multiple volumes for the host.
-
Click Submit to save the settings to the compute profile.
-
To create a compute profile, enter the following command:
# hammer compute-profile create --name "Libvirt CP"
-
To add the values for the compute profile, enter the following command:
# hammer compute-profile values create --compute-profile "Libvirt CP" \ --compute-resource "My_KVM_Server" \ --interface "compute_type=network,compute_model=virtio,compute_network=examplenetwork" \ --volume "pool_name=default,capacity=20G,format_type=qcow2" \ --compute-attributes "cpus=1,memory=1073741824"
9.5. Creating hosts on KVM
In Foreman, you can use KVM provisioning to create hosts over a network connection or from an existing image:
-
If you want to create a host over a network connection, the new host must be able to access either Foreman server’s integrated Smart Proxy or an external Smart Proxy server on a KVM virtual network, so that the host has access to PXE provisioning services. This new host entry triggers the KVM server to create and start a virtual machine. If the virtual machine detects the defined Smart Proxy server through the virtual network, the virtual machine boots to PXE and begins to install the chosen operating system.
-
If you want to create a host with an existing image, the new host entry triggers the KVM server to create the virtual machine using a pre-existing image as a basis for the new volume.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
For network-based provisioning, if you use a virtual network on the KVM server for provisioning, select a network that does not provide DHCP assignments. This causes DHCP conflicts with Foreman server when booting new hosts.
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
In the Name field, enter a name for the host.
-
Optional: Click the Organization tab and change the organization context to match your requirement.
-
Optional: Click the Location tab and change the location context to match your requirement.
-
From the Host Group list, select a host group that you want to assign your host to. That host group will populate the form.
-
From the Deploy on list, select the KVM connection.
-
From the Compute Profile list, select a profile to use to automatically populate virtual machine settings. The KVM-specific fields are populated with settings from your compute profile. Modify these settings if required.
-
Click the Interfaces tab, and on the interface of the host, click Edit.
-
Verify that the fields are populated with values. Note in particular:
-
Foreman automatically assigns an IP address for the new host.
-
Ensure that the MAC address field is blank. KVM assigns a MAC address to the host during provisioning.
-
The Name from the Host tab becomes the DNS name.
-
Ensure that Foreman automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
-
-
Click OK to save. To add another interface, click Add Interface. You can select only one interface for Provision and Primary.
-
Click the Operating System tab, and confirm that all fields automatically contain values.
-
Select the Provisioning Method that you want to use:
-
For network-based provisioning, click Network Based.
-
For image-based provisioning, click Image Based.
-
-
Click Resolve in Provisioning templates to check the new host can identify the right provisioning templates to use.
-
Click the Virtual Machine tab and confirm that these settings are populated with details from the host group and compute profile. Modify these settings to suit your needs.
-
Click the Parameters tab, and ensure that a parameter exists that provides an activation key. If not, add an activation key.
-
Click Submit to save the host entry.
-
To use network-based provisioning, create the host with the
hammer host create
command and include--provision-method build
. Replace the values in the following example with the appropriate values for your environment.# hammer host create \ --build true \ --compute-attributes="cpus=1,memory=1073741824" \ --compute-resource "My_KVM_Server" \ --enabled true \ --hostgroup "My_Host_Group" \ --interface "managed=true,primary=true,provision=true,compute_type=network,compute_network=examplenetwork" \ --location "My_Location" \ --managed true \ --name "My_Host_Name" \ --organization "My_Organization" \ --provision-method "build" \ --root-password "My_Password" \ --volume="pool_name=default,capacity=20G,format_type=qcow2"
-
To use image-based provisioning, create the host with the
hammer host create
command and include--provision-method image
. Replace the values in the following example with the appropriate values for your environment.# hammer host create \ --compute-attributes="cpus=1,memory=1073741824" \ --compute-resource "My_KVM_Server" \ --enabled true \ --hostgroup "My_Host_Group" \ --image "My_KVM_Image" \ --interface "managed=true,primary=true,provision=true,compute_type=network,compute_network=examplenetwork" \ --location "My_Location" \ --managed true \ --name "My_Host_Name" \ --organization "My_Organization" \ --provision-method "image" \ --volume="pool_name=default,capacity=20G,format_type=qcow2"
For more information about additional host creation parameters for this compute resource, enter the hammer host create --help
command.
10. Provisioning virtual machines on oVirt
oVirt is an enterprise-grade server and desktop virtualization platform. In Foreman, you can manage virtualization functions through oVirt’s REST API. This includes creating virtual machines and controlling their power states.
You can use oVirt provisioning to create virtual machines over a network connection or from an existing image.
You can use cloud-init
to configure the virtual machines that you provision.
Using cloud-init
avoids any special configuration on the network, such as a managed DHCP and TFTP, to finish the installation of the virtual machine.
This method does not require Foreman to connect to the provisioned virtual machine using SSH to run the finish script.
-
Provide the installation medium for the operating systems that you want to use to provision hosts. If the Katello plugin is installed, you can use synchronized content repositories for Red Hat Enterprise Linux. For more information, see Syncing Repositories in Managing content.
-
If the Katello plugin is installed, provide an activation key for host registration. For more information, see Creating An Activation Key in Managing content.
-
A Smart Proxy server managing a logical network on the oVirt environment. Ensure no other DHCP services run on this network to avoid conflicts with Smart Proxy server. For more information, see Configuring Networking in Provisioning hosts.
-
An existing template, other than the
blank
template, if you want to use image-based provisioning. For more information about creating templates for virtual machines, see Templates in the oVirt documentation. -
An administration-like user on oVirt for communication with Foreman server. Do not use the
admin@internal
user for this communication. Instead, create a new oVirt user with the following permissions:-
System > Configure System > Login Permissions
-
Network > Configure vNIC Profile > Create
-
Network > Configure vNIC Profile > Edit Properties
-
Network > Configure vNIC Profile > Delete
-
Network > Configure vNIC Profile > Assign vNIC Profile to VM
-
Network > Configure vNIC Profile > Assign vNIC Profile to Template
-
Template > Provisioning Operations > Import/Export
-
VM > Provisioning Operations > Create
-
VM > Provisioning Operations > Delete
-
VM > Provisioning Operations > Import/Export
-
VM > Provisioning Operations > Edit Storage
-
Disk > Provisioning Operations > Create
-
Disk > Disk Profile > Attach Disk Profile
For more information about how to create a user and add permissions in oVirt, see Users and Roles in the oVirt documentation.
-
-
You can configure Foreman to remove the associated virtual machine when you delete a host. For more information, see Removing a virtual machine upon host deletion.
10.1. Installing the oVirt plugin
Install the oVirt plugin to attach an oVirt compute resource provider to Foreman. This allows you to manage and deploy hosts to oVirt.
-
Install the oVirt compute resource provider on your Foreman server:
# foreman-installer --enable-foreman-compute-ovirt
-
Optional: In the Foreman web UI, navigate to Administer > About and select the Compute resources tab to verify the installation of the oVirt plugin.
10.2. Adding the oVirt connection to Foreman server
Use this procedure to add oVirt as a compute resource in Foreman. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources and click Create Compute Resource.
-
In the Name field, enter a name for the new compute resource.
-
From the Provider list, select oVirt.
-
In the Description field, enter a description for the compute resource.
-
In the URL field, enter the connection URL for the oVirt Engine’s API in the following form:
https://ovirt.example.com/ovirt-engine/api/v4
. -
In the User field, enter the name of a user with permissions to access oVirt Engine’s resources.
-
In the Password field, enter the password of the user.
-
Click Load Datacenters to populate the Datacenter list with data centers from your oVirt environment.
-
From the Datacenter list, select a data center.
-
From the Quota ID list, select a quota to limit resources available to Foreman.
-
In the X509 Certification Authorities field, enter the certificate authority for SSL/TLS access. Alternatively, if you leave the field blank, a self-signed certificate is generated on the first API request by the server.
-
Click the Locations tab and select the location you want to use.
-
Click the Organizations tab and select the organization you want to use.
-
Click Submit to save the compute resource.
-
Enter the
hammer compute-resource create
command withOvirt
for--provider
and the name of the data center you want to use for--datacenter
.# hammer compute-resource create \ --name "My_oVirt" --provider "Ovirt" \ --description "oVirt server at ovirt.example.com" \ --url "https://ovirt.example.com/ovirt-engine/api/v4" \ --user "Foreman_User" --password "My_Password" \ --locations "New York" --organizations "My_Organization" \ --datacenter "My_Datacenter"
10.3. Preparing cloud-init images in oVirt
To use cloud-init
during provisioning, you must prepare an image with cloud-init
installed in oVirt, and then import the image to Foreman to use for provisioning.
-
In oVirt, create a virtual machine to use for image-based provisioning in Foreman.
-
On the virtual machine, install
cloud-init
:-
On Debian or Ubuntu:
# apt install cloud-init
-
On Enterprise Linux 8+:
# dnf install cloud-init
-
On Enterprise Linux 7:
# yum install cloud-init
-
On OpenSUSE and SUSE Linux Enterprise Server:
# zypper install cloud-init
-
-
To the
/etc/cloud/cloud.cfg
file, add the following information:datasource_list: ["NoCloud", "ConfigDrive"]
-
In oVirt, create an image from this virtual machine.
When you add this image to Foreman, ensure that you select the User Data checkbox.
10.4. Adding oVirt images to Foreman server
To create hosts using image-based provisioning, you must add information about the image, such as access details and the image location, to your Foreman server.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources and click the name of the oVirt connection.
-
Click Create Image.
-
In the Name field, enter a name for the image.
-
From the Operating System list, select the base operating system of the image.
-
From the Architecture list, select the operating system architecture.
-
In the Username field, enter the SSH user name for image access. This is normally the
root
user. -
In the Password field, enter the SSH password for image access.
-
From the Image list, select an image from the oVirt compute resource.
-
Optional: Select the User Data checkbox if the image supports user data input, such as
cloud-init
data. -
Click Submit to save the image details.
-
Create the image with the
hammer compute-resource image create
command. Use the--uuid
option to store the template UUID on the oVirt server.# hammer compute-resource image create \ --name "oVirt_Image" \ --compute-resource "My_oVirt" --operatingsystem "RedHat version" \ --architecture "x86_64" \ --username root \ --uuid "9788910c-4030-4ae0-bad7-603375dd72b1" \
10.5. Preparing a cloud-init template
-
You must enable the remote execution plugin to use a 'cloud-init' template.
-
In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates, and click Create Template.
-
In the Name field, enter a name for the template.
-
In the Editor field, enter the following template details:
<%# kind: user_data name: Cloud-init -%> #cloud-config hostname: <%= @host.shortname %> <%# Allow user to specify additional SSH key as host parameter -%> <% if @host.params['sshkey'].present? || @host.params['remote_execution_ssh_keys'].present? -%> ssh_authorized_keys: <% if @host.params['sshkey'].present? -%> - <%= @host.params['sshkey'] %> <% end -%> <% if @host.params['remote_execution_ssh_keys'].present? -%> <% @host.params['remote_execution_ssh_keys'].each do |key| -%> - <%= key %> <% end -%> <% end -%> <% end -%> runcmd: - | #!/bin/bash <%= indent 4 do snippet 'subscription_manager_registration' end %> <% if @host.info['parameters']['realm'] && @host.realm && @host.realm.realm_type == 'Red Hat Identity Management' -%> <%= indent 4 do snippet 'freeipa_register' end %> <% end -%> <% unless @host.operatingsystem.atomic? -%> # update all the base packages from the updates repository yum -t -y -e 0 update <% end -%> <% # safemode renderer does not support unary negation non_atomic = @host.operatingsystem.atomic? ? false : true pm_set = @host.puppetmaster.empty? ? false : true puppet_enabled = non_atomic && (pm_set || @host.params['force-puppet']) %> <% if puppet_enabled %> yum install -y puppet cat > /etc/puppet/puppet.conf << EOF <%= indent 4 do snippet 'puppet.conf' end %> EOF # Setup puppet to run on system reboot /sbin/chkconfig --level 345 puppet on /usr/bin/puppet agent --config /etc/puppet/puppet.conf --onetime --tags no_such_tag <%= @host.puppetmaster.blank? ? '' : "--server #{@host.puppetmaster}" %> --no-daemonize /sbin/service puppet start <% end -%> phone_home: url: <%= foreman_url('built') %> post: [] tries: 10pp
-
Click the Type tab and from the Type list, select User data template.
-
Click the Association tab, and from the Applicable Operating Systems list, select the operating system that you want associate with the template.
-
Click the Locations tab, and from the Locations list, select the location that you want to associate with the template.
-
Click the Organizations tab, and from the Organization list, select the organization that you want to associate with the template.
-
Click Submit.
-
In the Foreman web UI, navigate to Hosts > Provisioning Setup > Operating Systems.
-
Select the operating system you want to associate with the template.
-
Click the Templates tab, and from the User data template list, select the name of the new template.
-
Click Submit.
10.6. Adding oVirt details to a compute profile
Use this procedure to add oVirt hardware settings to a compute profile. When you create a host on KVM using this compute profile, these settings are automatically populated.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Profiles.
-
In the Compute Profiles window, click the name of an existing compute profile, or click Create Compute Profile, enter a Name, and click Submit.
-
Click the name of the oVirt compute resource.
-
From the Cluster list, select the target host cluster in the oVirt environment.
-
From the Template list, select the oVirt template to use for the Cores and Memory settings.
-
In the Cores field, enter the number of CPU cores to allocate to the new host.
-
In the Memory field, enter the amount of memory to allocate to the new host.
-
From the Image list, select image to use for image-based provisioning.
-
In the Network Interfaces area, enter the network parameters for the host’s network interface. You can create multiple network interfaces. However, at least one interface must point to a Smart Proxy-managed network. For each network interface, enter the following details:
-
In the Name field, enter the name of the network interface.
-
From the Network list, select The logical network that you want to use.
-
-
In the Storage area, enter the storage parameters for the host. You can create multiple volumes for the host. For each volume, enter the following details:
-
In the Size (GB) enter the size, in GB, for the new volume.
-
From the Storage domain list, select the storage domain for the volume.
-
From the Preallocate disk, select either thin provisioning or preallocation of the full disk.
-
From the Bootable list, select whether you want a bootable or non-bootable volume.
-
-
Click Submit to save the compute profile.
-
To create a compute profile, enter the following command:
# hammer compute-profile create --name "oVirt CP"
-
To set the values for the compute profile, enter the following command:
# hammer compute-profile values create --compute-profile "oVirt CP" \ --compute-resource "My_oVirt" \ --interface "compute_interface=Interface_Type,compute_name=eth0,compute_network=satnetwork" \ --volume "size_gb=20G,storage_domain=Data,bootable=true" \ --compute-attributes "cluster=Default,cores=1,memory=1073741824,start=true""
10.7. Creating hosts on oVirt
In Foreman, you can use oVirt provisioning to create hosts over a network connection or from an existing image:
-
If you want to create a host over a network connection, the new host must be able to access either Foreman server’s integrated Smart Proxy or an external Smart Proxy server on a oVirt virtual network, so that the host has access to PXE provisioning services. This new host entry triggers the oVirt server to create and start a virtual machine. If the virtual machine detects the defined Smart Proxy server through the virtual network, the virtual machine boots to PXE and begins to install the chosen operating system.
-
If you want to create a host with an existing image, the new host entry triggers the oVirt server to create the virtual machine using a pre-existing image as a basis for the new volume.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
For network-based provisioning, if you use a virtual network on the oVirt server for provisioning, select a network that does not provide DHCP assignments. This causes DHCP conflicts with Foreman server when booting new hosts.
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
In the Name field, enter a name for the host.
-
Optional: Click the Organization tab and change the organization context to match your requirement.
-
Optional: Click the Location tab and change the location context to match your requirement.
-
From the Host Group list, select a host group that you want to assign your host to. That host group will populate the form.
-
From the Deploy on list, select the oVirt connection.
-
From the Compute Profile list, select a profile to use to automatically populate virtual machine settings. The oVirt-specific fields are populated with settings from your compute profile. Modify these settings if required.
-
Click the Interfaces tab, and on the interface of the host, click Edit.
-
Verify that the fields are populated with values. Note in particular:
-
Foreman automatically assigns an IP address for the new host.
-
Ensure that the MAC address field is blank. oVirt assigns a MAC address to the host during provisioning.
-
The Name from the Host tab becomes the DNS name.
-
Ensure that Foreman automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
-
-
Click OK to save. To add another interface, click Add Interface. You can select only one interface for Provision and Primary.
-
Click the Operating System tab, and confirm that all fields automatically contain values.
-
Select the Provisioning Method that you want to use:
-
For network-based provisioning, click Network Based.
-
For image-based provisioning, click Image Based.
-
-
Click Resolve in Provisioning templates to check the new host can identify the right provisioning templates to use.
-
Click the Virtual Machine tab and confirm that these settings are populated with details from the host group and compute profile. Modify these settings to suit your needs.
-
Click the Parameters tab, and ensure that a parameter exists that provides an activation key. If not, add an activation key.
-
Click Submit to save the host entry.
-
To use network-based provisioning, create the host with the
hammer host create
command and include--provision-method build
. Replace the values in the following example with the appropriate values for your environment.# hammer host create \ --build true \ --compute-attributes="cluster=Default,cores=1,memory=1073741824,start=true" \ --compute-resource "MyoVirt_" \ --enabled true \ --hostgroup "My_Host_Group" \ --interface "managed=true,primary=true,provision=true,compute_name=eth0,compute_network=satnetwork" \ --location "My_Location" \ --managed true \ --name "My_Host_Name" \ --organization "My_Organization" \ --provision-method build \ --volume="size_gb=20G,storage_domain=Data,bootable=true"
-
To use image-based provisioning, create the host with the
hammer host create
command and include--provision-method image
. Replace the values in the following example with the appropriate values for your environment.# hammer host create \ --compute-attributes="cluster=Default,cores=1,memory=1073741824,start=true" \ --compute-resource "MyoVirt_" \ --enabled true \ --hostgroup "My_Host_Group" \ --image "MyoVirt_Image_" \ --interface "managed=true,primary=true,provision=true,compute_name=eth0,compute_network=satnetwork" \ --location "My_Location" \ --managed true \ --name "My_Host_Name" \ --organization "My_Organization" \ --provision-method "image" \ --volume="size_gb=20G,storage_domain=Data,bootable=true"
For more information about additional host creation parameters for this compute resource, enter the hammer host create --help
command.
11. Provisioning virtual machines in VMware vSphere
VMware vSphere is an enterprise-level virtualization platform from VMware. Foreman can interact with the vSphere platform, including creating new virtual machines and controlling their power management states.
11.1. Installing VMware plugin
Install the VMware plugin to attach the VMware compute resource provider to Foreman. You can use the VMware provider to manage and deploy hosts to VMware.
-
Install the VMware compute resource provider on your Foreman server:
# foreman-installer --enable-foreman-compute-vmware
-
In the Foreman web UI, navigate to Administer > About.
-
On the System Status card, select the Available Providers tab to verify that the VMware provider is installed.
11.2. Prerequisites for VMware provisioning
The requirements for VMware vSphere provisioning include:
-
A supported version of VMware vCenter Server. The following versions have been fully tested with Foreman:
-
vCenter Server 8.0
-
vCenter Server 7.0
-
vCenter Server 6.7 (EOL)
-
vCenter Server 6.5 (EOL)
-
-
A Smart Proxy server managing a network on the vSphere environment. Ensure no other DHCP services run on this network to avoid conflicts with Smart Proxy server. For more information, see Configuring networking.
-
An existing VMware template if you want to use image-based provisioning.
-
Provide the installation medium for the operating systems that you want to use to provision hosts. If the Katello plugin is installed, you can use synchronized content repositories for Red Hat Enterprise Linux. For more information, see Syncing Repositories in Managing content.
-
If the Katello plugin is installed, provide an activation key for host registration. For more information, see Creating An Activation Key in Managing content.
11.3. Creating a VMware user
The VMware vSphere server requires an administration-like user for Foreman server communication.
For security reasons, do not use the administrator
user for such communication.
Instead, create a user with the following permissions:
For VMware vCenter Server version 8.0, 7.0, or 6.7, set the following permissions:
-
All Privileges → Datastore → Allocate Space, Browse datastore, Update Virtual Machine files, Low level file operations
-
All Privileges → Network → Assign Network
-
All Privileges → Resource → Assign virtual machine to resource pool
-
All Privileges → Virtual Machine → Change Config (All)
-
All Privileges → Virtual Machine → Interaction (All)
-
All Privileges → Virtual Machine → Edit Inventory (All)
-
All Privileges → Virtual Machine → Provisioning (All)
-
All Privileges → Virtual Machine → Guest Operations (All)
For VMware vCenter Server version 6.5, set the following permissions:
-
All Privileges → Datastore → Allocate Space, Browse datastore, Update Virtual Machine files, Low level file operations
-
All Privileges → Network → Assign Network
-
All Privileges → Resource → Assign virtual machine to resource pool
-
All Privileges → Virtual Machine → Configuration (All)
-
All Privileges → Virtual Machine → Interaction (All)
-
All Privileges → Virtual Machine → Inventory (All)
-
All Privileges → Virtual Machine → Provisioning (All)
-
All Privileges → Virtual Machine → Guest Operations (All)
11.4. Adding a VMware connection to Foreman server
Use this procedure to add a VMware vSphere connection in Foreman server’s compute resources. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
Ensure that the host and network-based firewalls are configured to allow communication from Foreman server to vCenter on TCP port 443.
-
Verify that Foreman server and vCenter can resolve each other’s host names.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources, and in the Compute Resources window, click Create Compute Resource.
-
In the Name field, enter a name for the resource.
-
From the Provider list, select VMware.
-
In the Description field, enter a description for the resource.
-
In the VCenter/Server field, enter the IP address or host name of the vCenter server.
-
In the User field, enter the user name with permission to access the vCenter’s resources.
-
In the Password field, enter the password for the user.
-
Click Load Datacenters to populate the list of data centers from your VMware vSphere environment.
-
From the Datacenter list, select a specific data center to manage from this list.
-
In the Fingerprint field, ensure that this field is populated with the fingerprint from the data center.
-
From the Display Type list, select a console type, for example, VNC or VMRC. Note that VNC consoles are unsupported on VMware ESXi 6.5 and later.
-
Optional: In the VNC Console Passwords field, select the Set a randomly generated password on the display connection checkbox to secure console access for new hosts with a randomly generated password. You can retrieve the password for the VNC console to access guest virtual machine console from the
libvirtd
host from the output of the following command:# virsh edit your_VM_name <graphics type='vnc' port='-1' autoport='yes' listen='0.0.0.0' passwd='your_randomly_generated_password'>
The password randomly generates every time the console for the virtual machine opens, for example, with virt-manager.
-
From the Enable Caching list, you can select whether to enable caching of compute resources. For more information, see Caching of compute resources.
-
Click the Locations and Organizations tabs and verify that the values are automatically set to your current context. You can also add additional contexts.
-
Click Submit to save the connection.
-
Create the connection with the
hammer compute-resource create
command. SelectVmware
as the--provider
and set the instance UUID of the data center as the--uuid
:# hammer compute-resource create \ --datacenter "My_Datacenter" \ --description "vSphere server at vsphere.example.com" \ --locations "My_Location" \ --name "My_vSphere" \ --organizations "My_Organization" \ --password "My_Password" \ --provider "Vmware" \ --server "vsphere.example.com" \ --user "My_User"
11.5. Adding VMware images to Foreman server
VMware vSphere uses templates as images for creating new virtual machines. If using image-based provisioning to create new hosts, you need to add VMware template details to your Foreman server. This includes access details and the template name.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Select your Vmware compute resource.
-
Click Create Image.
-
In the Name field, enter a name for the image.
-
From the Operating System list, select the base operating system of the image.
-
From the Architecture list, select the operating system architecture.
-
In the Username field, enter the SSH user name for image access. By default, this is set to
root
. -
If your image supports user data input such as
cloud-init
data, click the User data checkbox. -
Optional: In the Password field, enter the SSH password to access the image.
-
From the Image list, select an image from VMware.
-
Click Submit to save the image details.
-
Create the image with the
hammer compute-resource image create
command. Use the--uuid
field to store the relative template path on the vSphere environment:# hammer compute-resource image create \ --architecture "My_Architecture" \ --compute-resource "My_VMware" --name "My_Image" \ --operatingsystem "My_Operating_System" \ --username root \ --uuid "My_UUID"
11.6. Adding VMware details to a compute profile
You can predefine certain hardware settings for virtual machines on VMware vSphere. You achieve this through adding these hardware settings to a compute profile. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Profiles.
-
Select a compute profile.
-
Select a Vmware compute resource.
-
In the CPUs field, enter the number of CPUs to allocate to the host.
-
In the Cores per socket field, enter the number of cores to allocate to each CPU.
-
In the Memory field, enter the amount of memory in MiB to allocate to the host.
-
In the Firmware checkbox, select either BIOS or UEFI as firmware for the host. By default, this is set to automatic.
-
In the Cluster list, select the name of the target host cluster on the VMware environment.
-
From the Resource pool list, select an available resource allocations for the host.
-
In the Folder list, select the folder to organize the host.
-
From the Guest OS list, select the operating system you want to use in VMware vSphere.
-
From the Virtual H/W version list, select the underlying VMware hardware abstraction to use for virtual machines.
-
If you want to add more memory while the virtual machine is powered on, select the Memory hot add checkbox.
-
If you want to add more CPUs while the virtual machine is powered on, select the CPU hot add checkbox.
-
If you want to add a CD-ROM drive, select the CD-ROM drive checkbox.
-
From the Boot order list, define the order in which the virtual machines tried to boot.
-
Optional: In the Annotation Notes field, enter an arbitrary description.
-
If you use image-based provisioning, select the image from the Image list.
-
From the SCSI controller list, select the disk access method for the host.
-
If you want to use eager zero thick provisioning, select the Eager zero checkbox. By default, the disk uses lazy zero thick provisioning.
-
From the Network Interfaces list, select the network parameters for the host’s network interface. At least one interface must point to a Smart Proxy-managed network.
-
Optional: Click Add Interface to create another network interfaces.
-
Click Submit to save the compute profile.
-
Create a compute profile:
# hammer compute-profile create --name "My_Compute_Profile"
-
Set VMware details to a compute profile:
# hammer compute-profile values create \ --compute-attributes "cpus=1,corespersocket=2,memory_mb=1024,cluster=MyCluster,path=MyVMs,start=true" \ --compute-profile "My_Compute_Profile" \ --compute-resource "My_VMware" \ --interface "compute_type=VirtualE1000,compute_network=mynetwork \ --volume "size_gb=20G,datastore=Data,name=myharddisk,thin=true"
11.7. Creating hosts on VMware
The VMware vSphere provisioning process provides the option to create hosts over a network connection or using an existing image.
For network-based provisioning, you must create a host to access either Foreman server’s integrated Smart Proxy or an external Smart Proxy server on a VMware vSphere virtual network, so that the host has access to PXE provisioning services. The new host entry triggers the VMware vSphere server to create the virtual machine. If the virtual machine detects the defined Smart Proxy server through the virtual network, the virtual machine boots to PXE and begins to install the chosen operating system.
If you use a virtual network on the VMware vSphere server for provisioning, ensure that you select a virtual network that does not provide DHCP assignments. This causes DHCP conflicts with Foreman server when booting new hosts.
For image-based provisioning, use the pre-existing image as a basis for the new volume.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
In the Name field, enter a name for the host.
-
Optional: Click the Organization tab and change the organization context to match your requirement.
-
Optional: Click the Location tab and change the location context to match your requirement.
-
From the Host Group list, select a host group that you want to assign your host to. That host group will populate the form.
-
From the Deploy on list, select the VMware vSphere connection.
-
From the Compute Profile list, select a profile to use to automatically populate virtual machine-based settings.
-
Click the Interfaces tab, and on the interface of the host, click Edit.
-
Verify that the fields are populated with values. Note in particular:
-
Foreman automatically assigns an IP address for the new host.
-
Ensure that the MAC address field is blank. VMware assigns a MAC address to the host during provisioning.
-
The Name from the Host tab becomes the DNS name.
-
Ensure that Foreman automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
-
-
In the interface window, review the VMware-specific fields that are populated with settings from our compute profile. Modify these settings to suit your needs.
-
Click OK to save. To add another interface, click Add Interface. You can select only one interface for Provision and Primary.
-
Click the Operating System tab, and confirm that all fields automatically contain values.
-
Select the Provisioning Method that you want:
-
For network-based provisioning, click Network Based.
-
For image-based provisioning, click Image Based.
-
If the
foreman_bootdisk
plugin is installed, and you want to use boot-disk provisioning, click Boot disk based.
-
-
Click Resolve in Provisioning templates to check the new host can identify the right provisioning templates to use.
-
Click the Virtual Machine tab and confirm that these settings are populated with details from the host group and compute profile. Modify these settings to suit your requirements.
-
Click the Parameters tab and ensure that a parameter exists that provides an activation key. If a parameter does not exist, click + Add Parameter. In the field Name, enter kt_activation_keys. In the field Value, enter the name of the activation key used to register the Content Hosts.
-
Click Submit to provision your host on VMware.
-
Create the host from a network with the
hammer host create
command and include--provision-method build
to use network-based provisioning:# hammer host create \ --build true \ --compute-attributes="cpus=1,corespersocket=2,memory_mb=1024,cluster=MyCluster,path=MyVMs,start=true" \ --compute-resource "My_VMware" \ --enabled true \ --hostgroup "My_Host_Group" \ --interface "managed=true,primary=true,provision=true,compute_type=VirtualE1000,compute_network=mynetwork" \ --location "My_Location" \ --managed true \ --name "My_Host" \ --organization "My_Organization" \ --provision-method build \ --volume="size_gb=20G,datastore=Data,name=myharddisk,thin=true"
-
Create the host from an image with the
hammer host create
command and include--provision-method image
to use image-based provisioning:# hammer host create \ --compute-attributes="cpus=1,corespersocket=2,memory_mb=1024,cluster=MyCluster,path=MyVMs,start=true" \ --compute-resource "My_VMware" \ --enabled true \ --hostgroup "My_Host_Group" \ --image "My_VMware_Image" \ --interface "managed=true,primary=true,provision=true,compute_type=VirtualE1000,compute_network=mynetwork" \ --location "My_Location" \ --managed true \ --name "My_Host" \ --organization "My_Organization" \ --provision-method image \ --volume="size_gb=20G,datastore=Data,name=myharddisk,thin=true"
For more information about additional host creation parameters for this compute resource, enter the hammer host create --help
command.
11.8. Using VMware cloud-init and userdata templates for provisioning
You can use VMware with the Cloud-init
and Userdata
templates to insert user data into the new virtual machine, to make further VMware customization, and to enable the VMware-hosted virtual machine to call back to Foreman.
You can use the same procedures to set up a VMware compute resource within Foreman, with a few modifications to the workflow.
When you set up the compute resource and images for VMware provisioning in Foreman, the following sequence of provisioning events occurs:
-
The user provisions one or more virtual machines using the Foreman web UI, API, or hammer
-
Foreman calls the VMware vCenter to clone the virtual machine template
-
Foreman
userdata
provisioning template adds customized identity information -
When provisioning completes, the
Cloud-init
provisioning template instructs the virtual machine to call back to Smart Proxy whencloud-init
runs -
VMware vCenter clones the template to the virtual machine
-
VMware vCenter applies customization for the virtual machine’s identity, including the host name, IP, and DNS
-
The virtual machine builds,
cloud-init
is invoked and calls back Foreman on port80
, which then redirects to443
-
Configure port and firewall settings to open any necessary connections. Because of the
cloud-init
service, the virtual machine always calls back to Foreman even if you register the virtual machine to Smart Proxy. For more information, see Port and firewall requirements in Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux and Port and firewall requirements in Installing a Smart Proxy Server 3.11 on Enterprise Linux. -
If you want to use Smart Proxy servers instead of your Foreman server, ensure that you have configured your Smart Proxy servers accordingly. For more information, see Configuring Smart Proxy for Host Registration and Provisioning in Installing a Smart Proxy Server 3.11 on Enterprise Linux.
-
Back up the following configuration files:
-
/etc/cloud/cloud.cfg.d/01_network.cfg
-
/etc/cloud/cloud.cfg.d/10_datasource.cfg
-
/etc/cloud/cloud.cfg
-
Userdata
and Cloud-init
templates with the operating system-
In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates.
-
Search for the CloudInit default template and click its name.
-
Click the Association tab.
-
Select all operating systems to which the template applies and click Submit.
-
Repeat the steps above for the UserData open-vm-tools template.
-
Navigate to Hosts > Provisioning Setup > Operating Systems.
-
Select the operating system that you want to use for provisioning.
-
Click the Templates tab.
-
From the Cloud-init template list, select CloudInit default.
-
From the User data template list, select UserData open-vm-tools.
-
Click Submit to save the changes.
To prepare an image, you must first configure the settings that you require on a virtual machine that you can then save as an image to use in Foreman.
To use the cloud-init
template for provisioning, you must configure a virtual machine so that cloud-init
is installed, enabled, and configured to call back to Foreman server.
For security purposes, you must install a CA certificate to use HTTPS for all communication. This procedure includes steps to clean the virtual machine so that no unwanted information transfers to the image you use for provisioning.
If you have an image with cloud-init
, you must still follow this procedure to enable cloud-init
to communicate with Foreman because cloud-init
is disabled by default.
These instructions are for Enterprise Linux or Fedora, follow similar steps for other Linux distributions.
-
On the virtual machine that you use to create the image, install the required packages:
# dnf install cloud-init open-vm-tools perl-interpreter perl-File-Temp
-
Disable network configuration by
cloud-init
:# cat << EOM > /etc/cloud/cloud.cfg.d/01_network.cfg network: config: disabled EOM
-
Configure
cloud-init
to fetch data from Foreman:# cat << EOM > /etc/cloud/cloud.cfg.d/10_datasource.cfg datasource_list: [NoCloud] datasource: NoCloud: seedfrom: https://foreman.example.com/userdata/ EOM
If you intend to provision through Smart Proxy server, use the URL of your Smart Proxy server in the
seedfrom
option, such ashttps://smartproxy.example.com:9090/userdata/
. -
Configure modules to use in
cloud-init
:# cat << EOM > /etc/cloud/cloud.cfg cloud_init_modules: - bootcmd - ssh cloud_config_modules: - runcmd cloud_final_modules: - scripts-per-once - scripts-per-boot - scripts-per-instance - scripts-user - phone-home system_info: distro: rhel paths: cloud_dir: /var/lib/cloud templates_dir: /etc/cloud/templates ssh_svcname: sshd EOM
-
Enable the CA certificates for the image:
# update-ca-trust enable
-
Download the
katello-server-ca.crt
file from Foreman server:# wget -O /etc/pki/ca-trust/source/anchors/cloud-init-ca.crt https://foreman.example.com/pub/katello-server-ca.crt
If you intend to provision through Smart Proxy server, download the file from your Smart Proxy server, such as
https://smartproxy.example.com/pub/katello-server-ca.crt
. -
Update the record of certificates:
# update-ca-trust extract
-
Clean the image:
# systemctl stop rsyslog # systemctl stop auditd # package-cleanup --oldkernels --count=1 # dnf clean all
-
Reduce logspace, remove old logs, and truncate logs:
# logrotate -f /etc/logrotate.conf # rm -f /var/log/*-???????? /var/log/*.gz # rm -f /var/log/dmesg.old # rm -rf /var/log/anaconda # cat /dev/null > /var/log/audit/audit.log # cat /dev/null > /var/log/wtmp # cat /dev/null > /var/log/lastlog # cat /dev/null > /var/log/grubby
-
Remove
udev
hardware rules:# rm -f /etc/udev/rules.d/70*
-
Remove the
ifcfg
scripts related to existing network configurations:# rm -f /etc/sysconfig/network-scripts/ifcfg-ens* # rm -f /etc/sysconfig/network-scripts/ifcfg-eth*
-
Remove the SSH host keys:
# rm -f /etc/ssh/ssh_host_*
-
Remove root user’s SSH history:
# rm -rf ~root/.ssh/known_hosts
-
Remove root user’s shell history:
# rm -f ~root/.bash_history # unset HISTFILE
-
Create an image from this virtual machine.
11.9. Deleting a VM on VMware
You can delete VMs running on VMware from within Foreman.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Select your VMware provider.
-
On the Virtual Machines tab, click Delete from the Actions menu. This deletes the virtual machine from the VMware compute resource while retaining any associated hosts within Foreman. If you want to delete the orphaned host, navigate to Hosts > All Hosts and delete the host manually.
-
You can configure Foreman to remove the associated virtual machine when you delete a host. For more information, see Removing a virtual machine upon host deletion.
11.10. Importing a virtual machine from VMware into Foreman
You can import existing virtual machines running on VMware into Foreman.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Select your VMware compute resource.
-
On the Virtual Machines tab, click Import as managed Host or Import as unmanaged Host from the Actions menu. The following page looks identical to creating a host with the compute resource being already selected. For more information, see Creating a host in Foreman in Managing hosts.
-
Click Submit to import the virtual machine into Foreman.
11.11. Caching of compute resources
Caching of compute resources speeds up rendering of VMware information.
11.11.1. Enabling caching of compute resources
To enable or disable caching of compute resources:
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Click the Edit button to the right of the VMware server you want to update.
-
Select the Enable caching checkbox.
11.11.2. Refreshing the compute resources cache
Refresh the cache of compute resources to update compute resources information.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Select a VMware server you want to refresh the compute resources cache for and click Refresh Cache.
-
Use this API call to refresh the compute resources cache:
# curl -H "Accept:application/json" \ -H "Content-Type:application/json" -X PUT \ -u username:password -k \ https://foreman.example.com/api/compute_resources/compute_resource_id/refresh_cache
Use
hammer compute-resource list
to determine the ID of the VMware server you want to refresh the compute resources cache for.
12. Provisioning virtual machines in Proxmox
Proxmox is open source software made for virtualization using KVM hypervisor and LXC containers. Foreman can interact with Proxmox, including creating virtual machines and controlling their power management states.
-
You can configure Foreman to remove the associated virtual machine when you delete a host. For more information, see Removing a virtual machine upon host deletion.
12.1. Installing the Proxmox plugin
Install the Proxmox plugin to attach a Proxmox compute resource provider to Foreman. This allows you to manage and deploy hosts to Proxmox.
-
Install the Proxmox plugin on your Foreman server:
# foreman-installer --enable-foreman-plugin-proxmox
-
Optional: In the Foreman web UI, navigate to Administer > About and select the Compute Resources tab to verify the installation of the Proxmox plugin.
12.2. Adding a Proxmox connection to Foreman server
Use this procedure to add a Proxmox connection to Foreman. If your Proxmox instance consists of multiple nodes, you have to create a Proxmox connection to Foreman for each node.
-
Ensure that the host and network-based firewalls are configured to allow communication from Foreman to Proxmox on TCP port 443.
-
Verify that Foreman server is able to resolve the host name of your Proxmox compute resource and Proxmox is able to resolve the host name of Foreman server.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Click Create Compute Resource.
-
In the Name field, enter a name for the compute resource.
-
From the Provider list, select Proxmox.
-
Optional: In the Description field, enter a description for the compute resource.
-
Optional: In the Authentication method list, select
User token
if you do not want to use access tickets to authenticate on Proxmox. -
In the Url field, enter the IP address or host name of your Proxmox node. Ensure to specify its port and add
/api2/json
to its path. -
In the Username field, enter the user name to access Proxmox.
-
In the Password field, enter the password for the user.
-
Optional: Select the SSL verify peer checkbox to verify the certificate used for the encrypted connection from Foreman to Proxmox.
-
In the X509 Certificate Authorities field, enter a certificate authority or a correctly ordered chain of certificate authorities.
-
Optional: Click Test Connection to verify the URL and its corresponding credentials.
-
Click Submit to save the connection.
12.3. Adding Proxmox images to Foreman server
Proxmox uses templates as images for creating new virtual machines. When you use image-based provisioning to create new hosts, you need to add Proxmox template details to your Foreman server. This includes access details and the template name.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Select your Proxmox compute resource.
-
Click Create Image.
-
In the Name field, enter a name for the image.
-
From the Operating System list, select the base operating system of the image.
-
From the Architecture list, select the operating system architecture.
-
In the Username field, enter the SSH user name for image access. By default, this is set to
root
. This is only necessary if the image has an inbuilt user account. -
From the User data list, select whether you want the images to support user data input, such as
cloud-init
data. -
In the Password field, enter the SSH password for image access.
-
In the Image field, enter the relative path and name of the template on the Proxmox environment. Do not include the data center in the relative path.
-
Click Submit to save the image details.
12.4. Adding Proxmox details to a compute profile
You can predefine certain hardware settings for virtual machines on Proxmox. You achieve this through adding these hardware settings to a compute profile.
Note that this procedure assumes you are using KVM/qemu-based virtualization.
-
In the Foreman web UI, navigate to Infrastructure > Compute Profiles.
-
Select a compute profile.
-
Select a Proxmox compute resource.
-
In the Type list, select the kind of virtualization solution hosts will run on when created using this compute profile. In Proxmox, you may choose between LXC (Linux containers) and KVM/QEMU (kernel-based virtual machines). LXC focuses more on isolating applications and reusing the host kernel. KVM runs its own kernel and lets you boot various guest operating systems.
-
In the Node list, select the Proxmox node you want to deploy your hosts to. This makes sense if you run a Proxmox cluster.
-
If you want to automatically start virtual machines after creation, select the Start after creation? checkbox. You can overwrite this for individual hosts when you create them.
-
In the Image list, select an image that is available on your Proxmox compute resource.
-
In the Pool list, select a resource allocation pool.
-
Optional: You can select the Main options, CPU, Memory, and OS checkboxes to configure the compute profile in more detail.
-
In the Identifier field, enter the name of the network interface of your host. The default value is
net0
. -
From the Card list, select the type of network interface card of your host.
-
Optional: From the Bridge list, select a bridge to assign the host to it.
-
Optional: In the VLAN tag field, you can assign your host to a VLAN. The VLAN tag field lets you input the corresponding VLAN tag which your Proxmox node is part of.
-
Optional: In the Rate limit field, you can limit the network traffic of hosts.
-
Optional: In the Multiqueue field, you can set multiple virtual CPUs to process network packets.
-
Optional: If you want to use the integrated firewall in Proxmox, select the Firewall checkbox.
-
Optional: If you want to disconnect your host from the network, select the Disconnect checkbox.
-
Optional: Click Add Interface to add another network interface.
-
From the Storage list, select the name of the storage pool within Proxmox.
-
In the Controller field, select the type of the disk controller of your host in Proxmox. Foreman community recommends to use either SCSI or VirtIO Block.
-
In the Device field, enter the number of the disk.
-
In the Cache list, select the type of disk cache you want to use on your host in Proxmox. Foreman community does not recommend using caching within Proxmox.
-
In the Size (GB) field, enter the size of the disk.
-
Click Submit to save the compute profile.
12.5. Creating hosts on Proxmox
The Proxmox provisioning process provides the option to create hosts over a network connection or using an existing image.
For network-based provisioning, you must create a host to access either integrated Smart Proxy or an external Smart Proxy server on a Proxmox virtual network, so that the host has access to PXE provisioning services. The new host entry triggers the Proxmox node to create the virtual machine. If the virtual machine detects the defined Smart Proxy server through the virtual network, the virtual machine boots to PXE and begins to install the chosen operating system.
If you use a virtual network on the Proxmox node for provisioning, ensure that you select a virtual network that does not provide DHCP assignments. This causes DHCP conflicts with Foreman server when booting new hosts.
For image-based provisioning, use the pre-existing image as a basis for the new volume.
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
In the Name field, enter a name for the host.
-
Optional: Click the Organization tab and change the organization context to match your requirement.
-
Optional: Click the Location tab and change the location context to match your requirement.
-
From the Host Group list, select a host group that you want to assign your host to. That host group will populate the form.
-
From the Deploy on list, select your Proxmox compute resource.
-
From the Compute Profile list, select a profile to use to automatically populate virtual machine-based settings.
-
Click the Interfaces tab, and on the interface of the host, click Edit.
-
Verify that the fields are populated with values. Note in particular:
-
Foreman automatically assigns an IP address for the new host.
-
Ensure that the MAC address field is blank. Proxmox assigns a MAC address to the host during provisioning.
-
The Name from the Host tab becomes the DNS name.
-
Ensure that Foreman automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
-
-
Click OK to save. To add another interface, click Add Interface. You can select only one interface for Provision and Primary.
-
On the Operating System tab, confirm that all fields automatically contain values.
-
Select the Provisioning Method that you want:
-
For network-based provisioning, click Network Based.
-
For image-based provisioning, click Image Based.
-
If the
foreman_bootdisk
plugin is installed and you want to use boot-disk provisioning, click Boot disk based.
-
-
Click Resolve in Provisioning templates to check the new host can identify the right provisioning templates to use.
-
Click the Virtual Machine tab and confirm that these settings are populated with details from the host group and compute profile. Modify these settings to suit your requirements.
-
On the Parameters tab, ensure that a parameter exists that provides an activation key. If not, add an activation key.
-
Click Submit to provision your host on Proxmox.
12.6. Deleting a virtual machine on Proxmox
You can delete virtual machines running on Proxmox from within Foreman.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Select your Proxmox compute resource.
-
On the Virtual Machines tab, click Delete from the Actions menu. This deletes the virtual machine from your Proxmox compute resource while retaining any associated hosts within Foreman.
-
Optional: If you want to delete the orphaned host, navigate to Hosts > All Hosts and delete the host manually.
-
You can configure Foreman to remove the associated virtual machine when you delete a host. For more information, see Removing a virtual machine upon host deletion.
12.7. Importing a virtual machine from Proxmox into Foreman
You can import existing virtual machines running on Proxmox into Foreman.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Select your Proxmox compute resource.
-
On the Virtual Machines tab, click Import as managed Host or Import as unmanaged Host from the Actions menu. The following page looks identical to creating a host with the compute resource being already selected. For more information, see Creating a host in Foreman in Managing hosts.
-
Click Submit to import the virtual machine into Foreman.
12.8. Adding a remote console connection for a host on Proxmox
Use this procedure to add a remote console connection using VNC for a host on Proxmox.
-
This procedure only works for hosts based on
qemu
. It does not work for LXC container on Proxmox.
-
Ensure that your host has
Standard VGA
selected from the VGA list.
-
On your Proxmox, open the required port for VNC:
# firewall-cmd --add-port=My_Port/tcp --permanent
The port is the sum of
5900
and the VMID of your host. You can view the VMID on the VM tab for your host in the Foreman web UI. For example, if your host has the VMID 142, open port6042
on your Proxmox.To enable a remote console connection for multiple hosts, open a range of ports using
firewall-cmd --add-port=5900-My_Upper_Port_Range_Limit/tcp --permanent
. -
Reload the firewall configuration:
# firewall-cmd --reload
-
On your Proxmox, enable VNC for your host in
/etc/pve/nodes/My_Proxmox_Instance/qemu-server/My_VMID.conf
:args: -vnc 0.0.0.0:_My_VMID_
For more information, see VNC Client Access in the Proxmox documentation.
-
Restart your host on Proxmox.
-
Optional: Verify that the required port for VNC is open:
# netstat -ltunp
-
On your Foreman server, allow the
websockify
capability in SELinux:# setsebool -P foreman_rails_can_connect_all on # setsebool -P websockify_can_connect_all on
-
If you use a SSL certificate, import the SSL certificate from Foreman server into your browser. For more information, see Importing the Katello Root CA Certificate in Administering Foreman.
The remote console connection to your host will fail if you choose to temporarily accept not checking the certificates in your browser.
13. Provisioning virtual machines on KubeVirt
KubeVirt addresses the needs of development teams that have adopted or want to adopt Kubernetes but possess existing virtual machine (VM) workloads that cannot be easily containerized. This technology provides a unified development platform where developers can build, modify, and deploy applications residing in application containers and VMs in a shared environment. These capabilities support rapid application modernization across the open hybrid cloud.
With Foreman, you can create a compute resource for KubeVirt so that you can provision and manage virtual machines in Kubernetes using Foreman.
-
Provide the installation medium for the operating systems that you want to use to provision hosts. If the Katello plugin is installed, you can use synchronized content repositories for Red Hat Enterprise Linux. For more information, see Syncing Repositories in Managing content.
-
If the Katello plugin is installed, provide an activation key for host registration. For more information, see Creating An Activation Key in Managing content.
-
You must have
cluster-admin
permissions for the Kubernetes cluster. -
A Smart Proxy server managing a network on the Kubernetes cluster. Ensure that no other DHCP services run on this network to avoid conflicts with Smart Proxy server. For more information about network service configuration for Smart Proxy servers, see Configuring Networking in Provisioning hosts.
-
For a list of permissions a non-admin user requires to provision hosts, see Permissions required to provision hosts.
-
You can configure Foreman to remove the associated virtual machine when you delete a host. For more information, see Removing a virtual machine upon host deletion.
13.1. Adding a KubeVirt connection to Foreman server
Use this procedure to add KubeVirt as a compute resource in Foreman.
-
Enter the following
foreman-installer
command to enable the KubeVirt plugin for Foreman:# foreman-installer --enable-foreman-plugin-kubevirt
-
Obtain a token to use for HTTP and HTTPs authentication:
-
Log in to the Kubernetes cluster and list the secrets that contain tokens:
$ kubectl get secrets
-
Obtain the token for your secret:
$ kubectl get secrets MY_SECRET -o jsonpath='{.data.token}' | base64 -d | xargs
-
Record the token to use later in this procedure.
-
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources, and click Create Compute Resource.
-
In the Name field, enter a name for the new compute resource.
-
From the Provider list, select KubeVirt.
-
In the Description field, enter a description for the compute resource.
-
In the Hostname field, enter the FQDN, hostname, or IP address of the Kubernetes cluster.
-
In the API Port field, enter the port number that you want to use for provisioning requests from Foreman to KubeVirt.
-
In the Namespace field, enter the user name of the Kubernetes cluster.
-
In the Token field, enter the bearer token for HTTP and HTTPs authentication.
-
Optional: In the X509 Certification Authorities field, enter a certificate to enable client certificate authentication for API server calls.
14. Provisioning cloud instances on OpenStack
OpenStack provides the foundation to build a private or public Infrastructure-as-a-Service (IaaS) cloud. It offers a massively scalable, fault-tolerant platform for the development of cloud-enabled workloads. In Foreman, you can interact with OpenStack REST API to create cloud instances and control their power management states.
-
Provide the installation medium for the operating systems that you want to use to provision hosts. If the Katello plugin is installed, you can use synchronized content repositories for Red Hat Enterprise Linux. For more information, see Syncing Repositories in Managing content.
-
If the Katello plugin is installed, provide an activation key for host registration. For more information, see Creating An Activation Key in Managing content.
-
A Smart Proxy server managing a network in your OpenStack environment. For more information, see Configuring Networking in Provisioning hosts.
-
An image added to OpenStack Image Storage (glance) service for image-based provisioning. For more information, see the OpenStack Instances and Images Guide.
-
You can configure Foreman to remove the associated virtual machine when you delete a host. For more information, see Removing a virtual machine upon host deletion.
14.1. Adding a OpenStack connection to Foreman server
You can add OpenStack as a compute resource in Foreman. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Click Create Compute Resource.
-
In the Name field, enter a name for the new compute resource.
-
From the Provider list, select RHEL OpenStack Platform.
-
Optional: In the Description field, enter a description for the compute resource.
-
In the URL field, enter the URL for the OpenStack Authentication keystone service’s API at the
tokens
resource, such ashttp://openstack.example.com:5000/v2.0/tokens
orhttp://openstack.example.com:5000/v3/auth/tokens
. -
In the Username and Password fields, enter the user authentication for Foreman to access the environment.
-
Optional: In the Project (Tenant) name field, enter the name of your tenant (v2) or project (v3) for Foreman server to manage.
-
In the User domain field, enter the user domain for v3 authentication.
-
In the Project domain name field, enter the project domain name for v3 authentication.
-
In the Project domain ID field, enter the project domain ID for v3 authentication.
-
Optional: Select Allow external network as main network to use external networks as primary networks for hosts.
-
Optional: Click Test Connection to verify that Foreman can connect to your compute resource.
-
Click the Locations and Organizations tabs and verify that the location and organization that you want to use are set to your current context. Add any additional contexts that you want to these tabs.
-
Click Submit to save the OpenStack connection.
-
To create a compute resource, enter the
hammer compute-resource create
command:# hammer compute-resource create --name "My_OpenStack" \ --provider "OpenStack" \ --description "My OpenStack environment at openstack.example.com" \ --url "http://openstack.example.com:5000/v3/auth/tokens" \ --user "My_Username" --password "My_Password" \ --tenant "My_Openstack" --domain "My_User_Domain" \ --project-domain-id "My_Project_Domain_ID" \ --project-domain-name "My_Project_Domain_Name" \ --locations "New York" --organizations "My_Organization"
14.2. Adding OpenStack images to Foreman server
To create hosts using image-based provisioning, you must add information about the image, such as access details and the image location, to your Foreman server.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources and click the name of the OpenStack connection.
-
Click Create Image.
-
In the Name field, enter a name for the image.
-
From the Operating System list, select the base operating system of the image.
-
From the Architecture list, select the operating system architecture.
-
In the Username field, enter the SSH user name for image access. This is normally the
root
user. -
In the Password field, enter the SSH password for image access.
-
From the Image list, select an image from the OpenStack compute resource.
-
Optional: Select the User Data checkbox if the image supports user data input, such as
cloud-init
data. -
Click Submit to save the image details.
-
Create the image with the
hammer compute-resource image create
command. Use the--uuid
field to store the full path of the image location on the OpenStack server.# hammer compute-resource image create \ --name "OpenStack Image" \ --compute-resource "My_OpenStack_Platform" --operatingsystem "RedHat version" \ --architecture "x86_64" \ --username root \ --user-data true \ --uuid "/path/to/OpenstackImage.qcow2"
14.3. Adding OpenStack details to a compute profile
Use this procedure to add OpenStack hardware settings to a compute profile. When you create a host on OpenStack using this compute profile, these settings are automatically populated.
-
In the Foreman web UI, navigate to Infrastructure > Compute Profiles.
-
In the Compute Profiles window, click the name of an existing compute profile, or click Create Compute Profile, enter a Name, and click Submit.
-
Click the name of the OpenStack compute resource.
-
From the Flavor list, select the hardware profile on OpenStack to use for the host.
-
From the Availability zone list, select the target cluster to use within the OpenStack environment.
-
From the Image list, select the image to use for image-based provisioning.
-
From the Tenant list, select the tenant or project for the OpenStack instance.
-
From the Security Group list, select the cloud-based access rules for ports and IP addresses.
-
From the Internal network, select the private networks for the host to join.
-
From the Floating IP network, select the external networks for the host to join and assign a floating IP address.
-
From the Boot from volume, select whether a volume is created from the image. If not selected, the instance boots the image directly.
-
In the New boot volume size (GB) field, enter the size, in GB, of the new boot volume.
-
Click Submit to save the compute profile.
-
Set OpenStack details to a compute profile:
# hammer compute-profile values create --compute-resource "My_Laptop" \ --compute-profile "My_Compute_Profile" \ --compute-attributes "availability_zone=My_Zone,image_ref=My_Image,flavor_ref=m1.small,tenant_id=openstack,security_groups=default,network=My_Network,boot_from_volume=false"
14.4. Creating image-based hosts on OpenStack
In Foreman, you can use OpenStack provisioning to create hosts from an existing image. The new host entry triggers the OpenStack server to create the instance using the pre-existing image as a basis for the new volume.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
In the Name field, enter a name for the host.
-
Optional: Click the Organization tab and change the organization context to match your requirement.
-
Optional: Click the Location tab and change the location context to match your requirement.
-
From the Host Group list, select a host group that you want to assign your host to. That host group will populate the form.
-
From the Deploy on list, select the OpenStack connection.
-
From the Compute Profile list, select a profile to use to automatically populate virtual machine settings.
-
From the Lifecycle Environment list, select the environment.
-
Click the Interfaces tab, and on the interface of the host, click Edit.
-
Verify that the fields are populated with values. Note in particular:
-
Foreman automatically assigns an IP address for the new host.
-
Ensure that the MAC address field is blank. OpenStack assigns a MAC address to the host during provisioning.
-
The Name from the Host tab becomes the DNS name.
-
Ensure that Foreman automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
-
-
Click OK to save. To add another interface, click Add Interface. You can select only one interface for Provision and Primary.
-
Click the Operating System tab, and confirm that all fields automatically contain values.
-
If you want to change the image that populates automatically from your compute profile, from the Images list, select a different image to base the new host’s root volume on.
-
Click Resolve in Provisioning templates to check the new host can identify the right provisioning templates to use.
-
Click the Virtual Machine tab and confirm that these settings are populated with details from the host group and compute profile. Modify these settings to suit your needs.
-
Click the Parameters tab, and ensure that a parameter exists that provides an activation key. If not, add an activation key.
-
Click Submit to save the host entry.
-
Create the host with the
hammer host create
command and include--provision-method image
. Replace the values in the following example with the appropriate values for your environment.# hammer host create \ --compute-attributes="flavor_ref=m1.small,tenant_id=openstack,security_groups=default,network=mynetwork" \ --compute-resource "My_OpenStack_Platform" \ --enabled true \ --hostgroup "My_Host_Group" \ --image "My_OpenStack_Image" \ --interface "managed=true,primary=true,provision=true" \ --location "My_Location" \ --managed true \ --name "My_Host_Name" \ --organization "My_Organization" \ --provision-method image
For more information about additional host creation parameters for this compute resource, enter the hammer host create --help
command.
15. Provisioning cloud instances in Amazon EC2
Amazon Elastic Compute Cloud (Amazon EC2) is a web service that provides public cloud compute resources. Using Foreman, you can interact with Amazon EC2’s public API to create cloud instances and control their power management states. Use the procedures in this chapter to add a connection to an Amazon EC2 account and provision a cloud instance.
15.1. Prerequisites for Amazon EC2 provisioning
The requirements for Amazon EC2 provisioning include:
-
A Smart Proxy server managing a network in your EC2 environment. Use a Virtual Private Cloud (VPC) to ensure a secure network between the hosts and Smart Proxy server.
-
An Amazon Machine Image (AMI) for image-based provisioning.
-
Provide the installation medium for the operating systems that you want to use to provision hosts. If the Katello plugin is installed, you can use synchronized content repositories for Red Hat Enterprise Linux. For more information, see Syncing Repositories in Managing content.
-
If the Katello plugin is installed, provide an activation key for host registration. For more information, see Creating An Activation Key in Managing content.
15.2. Installing Amazon EC2 plugin
Install the Amazon EC2 plugin to attach an EC2 compute resource provider to Foreman. This allows you to manage and deploy hosts to EC2.
-
Install the EC2 compute resource provider on your Foreman server:
# foreman-installer --enable-foreman-compute-ec2
-
Optional: In the Foreman web UI, navigate to Administer > About and select the compute resources tab to verify the installation of the Amazon EC2 plugin.
15.3. Adding an Amazon EC2 connection to the Foreman server
Use this procedure to add the Amazon EC2 connection in Foreman server’s compute resources. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
An AWS EC2 user performing this procedure needs the
AmazonEC2FullAccess
permissions. You can attach these permissions from AWS.
Amazon Web Services uses time settings as part of the authentication process.
Ensure that Foreman server’s time is correctly synchronized.
Ensure that an NTP service, such as ntpd
or chronyd
, is running properly on Foreman server.
Failure to provide the correct time to Amazon Web Services can lead to authentication failures.
For more information about synchronizing time in Foreman, see Synchronizing Time in Installing Foreman Server with Katello 4.13 plugin on Enterprise Linux.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources and in the Compute Resources window, click Create Compute Resource.
-
In the Name field, enter a name to identify the Amazon EC2 compute resource.
-
From the Provider list, select EC2.
-
In the Description field, enter information that helps distinguish the resource for future use.
-
Optional: From the HTTP proxy list, select an HTTP proxy to connect to external API services. You must add HTTP proxies to Foreman before you can select a proxy from this list. For more information, see Using an HTTP proxy with compute resources.
-
In the Access Key and Secret Key fields, enter the access keys for your Amazon EC2 account. For more information, see Managing Access Keys for your AWS Account on the Amazon documentation website.
-
Optional: Click Load Regions to populate the Regions list.
-
From the Region list, select the Amazon EC2 region or data center to use.
-
Click the Locations tab and ensure that the location you want to use is selected, or add a different location.
-
Click the Organizations tab and ensure that the organization you want to use is selected, or add a different organization.
-
Click Submit to save the Amazon EC2 connection.
-
Select the new compute resource and then click the SSH keys tab, and click Download to save a copy of the SSH keys to use for SSH authentication. Until BZ1793138 is resolved, you can download a copy of the SSH keys only immediately after creating the Amazon EC2 compute resource. If you require SSH keys at a later stage, follow the procedure in Connecting to an Amazon EC2 instance using SSH.
-
Create the connection with the
hammer compute-resource create
command. Use--user
and--password
options to add the access key and secret key respectively.# hammer compute-resource create \ --description "Amazon EC2 Public Cloud` \ --locations "My_Location" \ --name "My_EC2_Compute_Resource" \ --organizations "My_Organization" \ --password "My_Secret_Key" \ --provider "EC2" \ --region "My_Region" \ --user "My_User_Name"
15.4. Using an HTTP proxy with compute resources
In some cases, the EC2 compute resource that you use might require a specific HTTP proxy to communicate with Foreman. In Foreman, you can create an HTTP proxy and then assign the HTTP proxy to your EC2 compute resource.
However, if you configure an HTTP proxy for Foreman in Administer > Settings, and then add another HTTP proxy for your compute resource, the HTTP proxy that you define in Administer > Settings takes precedence.
-
In the Foreman web UI, navigate to Infrastructure > HTTP Proxies, and select New HTTP Proxy.
-
In the Name field, enter a name for the HTTP proxy.
-
In the URL field, enter the URL for the HTTP proxy, including the port number.
-
Optional: Enter a username and password to authenticate to the HTTP proxy, if your HTTP proxy requires authentication.
-
Click Test Connection to ensure that you can connect to the HTTP proxy from Foreman.
-
Click the Locations tab and add a location.
-
Click the Organization tab and add an organization.
-
Click Submit.
15.5. Creating an image for Amazon EC2
You can create images for Amazon EC2 from within Foreman.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Select your Amazon EC2 provider.
-
Click Create Image.
-
In the Name field, enter a meaningful and unique name for your EC2 image.
-
From the Operating System list, select an operating system to associate with the image.
-
From the Architecture list, select an architecture to associate with the image.
-
In the Username field, enter the username needed to SSH into the machine.
-
In the Image ID field, enter the image ID provided by Amazon or an operating system vendor. You can find the ID within Amazon AWS or on operating system specific pages such as debian.org or ubuntu.com.
-
Optional: Select the User Data check box to enable support for user data input.
-
Optional: Set an Iam Role for Fog to use when creating this image.
-
Click Submit to save your changes to Foreman.
-
15.6. Adding Amazon EC2 images to Foreman server
Amazon EC2 uses image-based provisioning to create hosts. You must add image details to your Foreman server. This includes access details and image location.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources and select an Amazon EC2 connection.
-
Click the Images tab, and then click Create Image.
-
In the Name field, enter a name to identify the image for future use.
-
From the Operating System list, select the operating system that corresponds with the image you want to add.
-
From the Architecture list, select the operating system’s architecture.
-
In the Username field, enter the SSH user name for image access. This is normally the
root
user. -
In the Password field, enter the SSH password for image access.
-
In the Image ID field, enter the Amazon Machine Image (AMI) ID for the image. This is usually in the following format:
ami-xxxxxxxx
. -
Optional: Select the User Data checkbox if the images support user data input, such as
cloud-init
data. If you enable user data, the Finish scripts are automatically disabled. This also applies in reverse: if you enable the Finish scripts, this disables user data. -
Optional: In the IAM role field, enter the Amazon security role used for creating the image.
-
Click Submit to save the image details.
-
Create the image with the
hammer compute-resource image create
command. Use the--uuid
field to store the full path of the image location on the Amazon EC2 server.# hammer compute-resource image create \ --architecture "My_Architecture" \ --compute-resource "My_EC2_Compute_Resource" \ --name "My_Amazon_EC2_Image" \ --operatingsystem "My_Operating_System" \ --user-data true \ --username root \ --uuid "ami-My_AMI_ID"
15.7. Adding Amazon EC2 details to a compute profile
You can add hardware settings for instances on Amazon EC2 to a compute profile.
-
In the Foreman web UI, navigate to Infrastructure > Compute Profiles and click the name of your profile, then click an EC2 connection.
-
From the Flavor list, select the hardware profile on EC2 to use for the host.
-
From the Image list, select the image to use for image-based provisioning.
-
From the Availability zone list, select the target cluster to use within the chosen EC2 region.
-
From the Subnet list, add the subnet for the EC2 instance. If you have a VPC for provisioning new hosts, use its subnet.
-
From the Security Groups list, select the cloud-based access rules for ports and IP addresses to apply to the host.
-
From the Managed IP list, select either a
Public
IP or aPrivate
IP. -
Click Submit to save the compute profile.
-
Set Amazon EC2 details to a compute profile:
# hammer compute-profile values create --compute-resource "My_Laptop" \ --compute-profile "My_Compute_Profile" \ --compute-attributes "flavor_id=1,availability_zone= My_Zone,subnet_id=1,security_group_ids=1,managed_ip=public_ip"
15.8. Creating image-based hosts on Amazon EC2
The Amazon EC2 provisioning process creates hosts from existing images on the Amazon EC2 server. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
In the Name field, enter a name for the host.
-
Optional: Click the Organization tab and change the organization context to match your requirement.
-
Optional: Click the Location tab and change the location context to match your requirement.
-
From the Host Group list, select a host group that you want to assign your host to. That host group will populate the form.
-
From the Deploy on list, select the EC2 connection.
-
From the Compute Profile list, select a profile to use to automatically populate virtual machine-based settings.
-
Click the Interfaces tab, and on the interface of the host, click Edit.
-
Verify that the fields are populated with values. Note in particular:
-
Foreman automatically assigns an IP address for the new host.
-
Ensure that the MAC address field is blank. EC2 assigns a MAC address to the host during provisioning.
-
The Name from the Host tab becomes the DNS name.
-
Ensure that Foreman automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
-
-
Click OK to save. To add another interface, click Add Interface. You can select only one interface for Provision and Primary.
-
Click the Operating System tab and confirm that all fields are populated with values.
-
Click the Virtual Machine tab and confirm that all fields are populated with values.
-
Click the Parameters tab, and ensure that a parameter exists that provides an activation key. If not, add an activation key.
-
Click Submit to save your changes.
This new host entry triggers the Amazon EC2 server to create the instance, using the pre-existing image as a basis for the new volume.
-
Create the host with the
hammer host create
command and include--provision-method image
to use image-based provisioning.# hammer host create \ --compute-attributes="flavor_id=m1.small,image_id=TestImage,availability_zones=us-east-1a,security_group_ids=Default,managed_ip=Public" \ --compute-resource "My_EC2_Compute_Resource" \ --enabled true \ --hostgroup "My_Host_Group" \ --image "My_Amazon_EC2_Image" \ --interface "managed=true,primary=true,provision=true,subnet_id=EC2" \ --location "My_Location" \ --managed true \ --name "My_Host_Name_" \ --organization "My_Organization" \ --provision-method image
For more information about additional host creation parameters for this compute resource, enter the hammer host create --help
command.
15.9. Connecting to an Amazon EC2 instance using SSH
You can connect remotely to an Amazon EC2 instance from Foreman server using SSH. However, to connect to any Amazon Web Services EC2 instance that you provision through Foreman, you must first access the private key that is associated with the compute resource in the Foreman database, and use this key for authentication.
-
To locate the compute resource list, on your Foreman server base system, enter the following command, and note the ID of the compute resource that you want to use:
# hammer compute-resource list
-
Switch user to the
postgres
user:# su - postgres
-
Initiate the
postgres
shell:$ psql
-
Connect to the Foreman database as the user
postgres
:# postgres=# \c foreman
-
Select the secret from
key_pairs
wherecompute_resource_id = 3
:# select secret from key_pairs where compute_resource_id = 3; secret
-
Copy the key from after
-----BEGIN RSA PRIVATE KEY-----
until-----END RSA PRIVATE KEY-----
. -
Create a
.pem
file and paste your key into the file:# vim Keyname.pem
-
Ensure that you restrict access to the
.pem
file:# chmod 600 Keyname.pem
-
To connect to the Amazon EC2 instance, enter the following command:
ssh -i Keyname.pem ec2-user@example.aws.com
15.10. Configuring a finish template for an Amazon Web Service EC2 environment
You can use Foreman finish templates during the provisioning of Linux instances in an Amazon EC2 environment.
If you want to use a Finish template with SSH, Foreman must reside within the EC2 environment and in the correct security group. Foreman currently performs SSH finish provisioning directly, not using Smart Proxy server. If Foreman server does not reside within EC2, the EC2 virtual machine reports an internal IP rather than the necessary external IP with which it can be reached.
-
In the Foreman web UI, navigate to Hosts > Templates > Provisioning Templates.
-
In the Provisioning Templates page, enter
Kickstart default finish
into the search field and click Search. -
On the Kickstart default finish template, select Clone.
-
In the Name field, enter a unique name for the template.
-
In the template, prefix each command that requires root privileges with
sudo
, except foryum
or equivalent commands, or add the following line to run the entire template as thesudo
user:sudo -s << EOS _Template_ _Body_ EOS
-
Click the Association tab, and associate the template with a Red Hat Enterprise Linux operating system that you want to use.
-
Click the Locations tab, and add the the location where the host resides.
-
Click the Organizations tab, and add the organization that the host belongs to.
-
Make any additional customizations or changes that you require, then click Submit to save your template.
-
In the Foreman web UI, navigate to Hosts > Operating systems and select the operating system that you want for your host.
-
Click the Templates tab, and from the Finish Template list, select your finish template.
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
In the Name field, enter a name for the host.
-
Optional: Click the Organization tab and change the organization context to match your requirement.
-
Optional: Click the Location tab and change the location context to match your requirement.
-
From the Host Group list, select a host group that you want to assign your host to. That host group will populate the form.
-
Click the Parameters tab and navigate to Host parameters.
-
In Host parameters, click Add Parameter two times to add two new parameter fields. Add the following parameters:
-
In the Name field, enter
activation_keys
. In the corresponding Value field, enter your activation key. -
In the Name field, enter
remote_execution_ssh_user
. In the corresponding Value field, enterec2-user
.
-
-
Click Submit to save the changes.
15.11. Deleting a virtual machine on Amazon EC2
You can delete virtual machines running on Amazon EC2 from within Foreman.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Select your Amazon EC2 provider.
-
On the Virtual Machines tab, click Delete from the Actions menu. This deletes the virtual machine from the Amazon EC2 compute resource while retaining any associated hosts within Foreman. If you want to delete an orphaned host, navigate to Hosts > All Hosts and delete the host manually.
-
You can configure Foreman to remove the associated virtual machine when you delete a host. For more information, see Removing a virtual machine upon host deletion.
15.12. Uninstalling Amazon EC2 plugin
If you have previously installed the Amazon EC2 plugin but do not use it anymore to manage and deploy hosts to EC2, you can uninstall it from your Foreman server.
-
Uninstall the EC2 compute resource provider from your Foreman server:
# dnf remove foreman-ec2 # foreman-installer --no-enable-foreman-compute-ec2
-
Optional: In the Foreman web UI, navigate to Administer > About and select the Available Providers tab to verify the removal of the Amazon EC2 plugin.
15.13. More information about Amazon Web Services and Foreman
For information about how to locate Red Hat Gold Images on Amazon Web Services EC2, see How to Locate Red Hat Cloud Access Gold Images on AWS EC2.
For information about how to install and use the Amazon Web Service Client on Linux, see Install the AWS Command Line Interface on Linux in the Amazon Web Services documentation.
For information about importing and exporting virtual machines in Amazon Web Services, see VM Import/Export in the Amazon Web Services documentation.
16. Provisioning cloud instances on Google Compute Engine
Foreman can interact with Google Compute Engine (GCE), including creating new virtual machines and controlling their power management states.
-
Configure a domain and subnet on Foreman. For more information about networking requirements, see Configuring networking.
-
Provide the installation medium for the operating systems that you want to use to provision hosts. If the Katello plugin is installed, you can use synchronized content repositories for Red Hat Enterprise Linux. For more information, see Syncing Repositories in Managing content.
-
If the Katello plugin is installed, provide an activation key for host registration. For more information, see Creating An Activation Key in Managing content.
-
In your GCE project, configure a service account with the necessary IAM Compute role. For more information, see Compute Engine IAM roles in the GCE documentation.
-
In your GCE project-wise metadata, set the
enable-oslogin
toFALSE
. For more information, see Enabling or disabling OS Login in the GCE documentation. -
Optional: If you want to use Puppet with GCE hosts, navigate to Administer > Settings > Puppet and enable the
Use UUID for certificates
setting to configure Puppet to use consistent Puppet certificate IDs. -
Based on your needs, associate a
finish
oruser_data
provisioning template with the operating system you want to use. For more information, see Provisioning Templates in Provisioning hosts.
16.1. Installing Google GCE plugin
Install the Google GCE plugin to attach an GCE compute resource provider to Foreman. This allows you to manage and deploy hosts to GCE.
-
Install the Google GCE compute resource provider on your Foreman server:
# foreman-installer \ --enable-foreman-cli-google \ --enable-foreman-plugin-google
-
Optional: In the Foreman web UI, navigate to Administer > About and select the Compute Resources tab to verify the installation of the Google GCE plugin.
16.2. Adding a Google GCE connection to Foreman server
Use this procedure to add Google Compute Engine (GCE) as a compute resource in Foreman. To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In Google GCE, generate a service account key in JSON format. For more information, see Create and manage service account keys in the GCE documentation.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources and click Create Compute Resource.
-
In the Name field, enter a name for the compute resource.
-
From the Provider list, select Google.
-
Optional: In the Description field, enter a description for the resource.
-
In the JSON key field, click Choose File and locate your service account key for upload from your local machine.
-
Click Load Zones to populate the list of zones from your GCE environment.
-
From the Zone list, select the GCE zone to use.
-
Click Submit.
-
In Google GCE, generate a service account key in JSON format. For more information, see Create and manage service account keys in the GCE documentation.
-
Copy the file from your local machine to Foreman server:
# scp My_GCE_Key.json root@foreman.example.com:/etc/foreman/My_GCE_Key.json
-
On Foreman server, change the owner for your service account key to the
foreman
user:# chown root:foreman /etc/foreman/My_GCE_Key.json
-
On Foreman server, configure permissions for your service account key to ensure that the file is readable:
# chmod 0640 /etc/foreman/My_GCE_Key.json
-
On Foreman server, restore SELinux context for your service account key:
# restorecon -vv /etc/foreman/My_GCE_Key.json
-
Use the
hammer compute-resource create
command to add a GCE compute resource to Foreman:# hammer compute-resource create \ --key-path "/etc/foreman/My_GCE_Key.json" \ --name "My_GCE_Compute_Resource" \ --provider "gce" \ --zone "My_Zone"
16.3. Adding Google Compute Engine images to Foreman server
To create hosts using image-based provisioning, you must add information about the image, such as access details and the image location, to your Foreman server.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources and click the name of the Google Compute Engine connection.
-
Click Create Image.
-
In the Name field, enter a name for the image.
-
From the Operating System list, select the base operating system of the image.
-
From the Architecture list, select the operating system architecture.
-
In the Username field, enter the SSH user name for image access. Specify a user other than
root
, because theroot
user cannot connect to a GCE instance using SSH keys. The username must begin with a letter and consist of lowercase letters and numbers. -
From the Image list, select an image from the Google Compute Engine compute resource.
-
Optional: Select the User Data checkbox if the image supports user data input, such as
cloud-init
data. -
Click Submit to save the image details.
-
Create the image with the
hammer compute-resource image create
command. With the--username
option, specify a user other thanroot
, because theroot
user cannot connect to a GCE instance using SSH keys. The username must begin with a letter and consist of lowercase letters and numbers.# hammer compute-resource image create \ --name 'gce_image_name' \ --compute-resource 'gce_cr' \ --operatingsystem-id 1 \ --architecture-id 1 \ --uuid '3780108136525169178' \ --username 'admin'
16.4. Adding Google GCE details to a compute profile
Use this procedure to add Google GCE hardware settings to a compute profile. When you create a host on Google GCE using this compute profile, these settings are automatically populated.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Profiles.
-
In the Compute Profiles window, click the name of an existing compute profile, or click Create Compute Profile, enter a Name, and click Submit.
-
Click the name of the GCE compute resource.
-
From the Machine Type list, select the machine type to use for provisioning.
-
From the Image list, select the image to use for provisioning.
-
From the Network list, select the Google GCE network to use for provisioning.
-
Optional: Select the Associate Ephemeral External IP checkbox to assign a dynamic ephemeral IP address that Foreman uses to communicate with the host. This public IP address changes when you reboot the host. If you need a permanent IP address, reserve a static public IP address on Google GCE and attach it to the host.
-
In the Size (GB) field, enter the size of the storage to create on the host.
-
Click Submit to save the compute profile.
-
Create a compute profile to use with the Google GCE compute resource:
# hammer compute-profile create --name My_GCE_Compute_Profile
-
Add GCE details to the compute profile:
# hammer compute-profile values create \ --compute-attributes "machine_type=f1-micro,associate_external_ip=true,network=default" \ --compute-profile "My_GCE_Compute_Profile" \ --compute-resource "My_GCE_Compute_Resource" \ --volume "size_gb=20"
16.5. Creating image-based hosts on Google Compute Engine
In Foreman, you can use Google Compute Engine provisioning to create hosts from an existing image. The new host entry triggers the Google Compute Engine server to create the instance using the pre-existing image as a basis for the new volume.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
In the Name field, enter a name for the host.
-
Optional: Click the Organization tab and change the organization context to match your requirement.
-
Optional: Click the Location tab and change the location context to match your requirement.
-
From the Host Group list, select a host group that you want to assign your host to. That host group will populate the form.
-
From the Deploy on list, select the Google Compute Engine connection.
-
From the Compute Profile list, select a profile to use to automatically populate virtual machine settings.
-
From the Lifecycle Environment list, select the environment.
-
Click the Interfaces tab, and on the interface of the host, click Edit.
-
Verify that the fields are populated with values. Note in particular:
-
Foreman automatically assigns an IP address for the new host.
-
Ensure that the MAC address field is blank. Google Compute Engine assigns a MAC address to the host during provisioning.
-
The Name from the Host tab becomes the DNS name.
-
The Domain field is populated with the required domain.
-
Ensure that Foreman automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
-
-
Click OK to save. To add another interface, click Add Interface. You can select only one interface for Provision and Primary.
-
Click the Operating System tab, and confirm that all fields automatically contain values.
-
Click Resolve in Provisioning templates to check the new host can identify the right provisioning templates to use.
-
Click the Virtual Machine tab and confirm that these settings are populated with details from the host group and compute profile. Modify these settings to suit your needs.
-
Click the Parameters tab, and ensure that a parameter exists that provides an activation key. If not, add an activation key.
-
Click Submit to save the host entry.
-
Create the host with the
hammer host create
command and include--provision-method image
. Replace the values in the following example with the appropriate values for your environment.# hammer host create \ --architecture x86_64 \ --compute-profile "My_Compute_Profile" \ --compute-resource "My_Compute_Resource" \ --image "My_GCE_Image" \ --interface "type=interface,domain_id=1,managed=true,primary=true,provision=true" \ --location "My_Location" \ --name "My_Host_Name" \ --operatingsystem "My_Operating_System" \ --organization "My_Organization" \ --provision-method "image" \ --puppet-ca-proxy-id My_Puppet_CA_Proxy_ID \ --puppet-environment-id My_Puppet_Environment_ID \ --puppet-proxy-id My_Puppet_Proxy_ID \ --root-password "My_Root_Password"
For more information about additional host creation parameters for this compute resource, enter the hammer host create --help
command.
16.6. Deleting a VM on Google GCE
You can delete VMs running on Google GCE on your Foreman server.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Select your Google GCE provider.
-
On the Virtual Machines tab, click Delete from the Actions menu. This deletes the virtual machine from the Google GCE compute resource while retaining any associated hosts within Foreman. If you want to delete the orphaned host, navigate to Hosts > All Hosts and delete the host manually.
-
You can configure Foreman to remove the associated virtual machine when you delete a host. For more information, see Removing a virtual machine upon host deletion.
17. Provisioning cloud instances on Microsoft Azure Resource Manager
Foreman can interact with Microsoft Azure Resource Manager, including creating new virtual machines and controlling their power management states. Only image-based provisioning is supported for creating Azure hosts. This includes provisioning using Marketplace images, custom images, and shared image gallery.
For more information about Azure Resource Manager concepts, see Azure Resource Manager documentation.
-
Provide the installation medium for the operating systems that you want to use to provision hosts. If the Katello plugin is installed, you can use synchronized content repositories for Red Hat Enterprise Linux. For more information, see Syncing Repositories in Managing content.
-
If the Katello plugin is installed, provide an activation key for host registration. For more information, see Creating An Activation Key in Managing content.
-
Ensure that you have the correct permissions to create an Azure Active Directory application. For more information, see Check Azure AD permissions in the Microsoft identity platform (Azure Active Directory for developers) documentation.
-
You must create and configure an Azure Active Directory application and service principle to obtain Application or client ID, Directory or tenant ID, and Client Secret. For more information, see Use the portal to create an Azure AD application and service principal that can access resources in the Microsoft identity platform (Azure Active Directory for developers) documentation.
-
Optional: If you want to use Puppet with Azure hosts, navigate to Administer > Settings > Puppet and enable the
Use UUID for certificates
setting to configure Puppet to use consistent Puppet certificate IDs. -
Based on your needs, associate a
finish
oruser_data
provisioning template with the operating system you want to use. For more information about provisioning templates, see Provisioning Templates. -
Optional: If you want the virtual machine to use a static private IP address, create a subnet in Foreman with the Network Address field matching the Azure subnet address.
-
Before creating RHEL BYOS images, you must accept the image terms either in the Azure CLI or Portal so that the image can be used to create and manage virtual machines for your subscription.
17.1. Installing Microsoft Azure plugin
Install the Microsoft Azure plugin to attach an Azure compute resource provider to Foreman. This allows you to manage and deploy hosts to Azure.
-
Install the Azure compute resource provider on your Foreman server:
# foreman-installer --enable-foreman-plugin-azure
-
Optional: In the Foreman web UI, navigate to Administer > About and select the compute resources tab to verify the installation of the Microsoft Azure plugin.
17.2. Adding a Microsoft Azure Resource Manager connection to Foreman server
Use this procedure to add Microsoft Azure as a compute resource in Foreman. Note that you must add a separate compute resource for each Microsoft Azure region that you want to use.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources and click Create Compute Resource.
-
In the Name field, enter a name for the compute resource.
-
From the Provider list, select Azure Resource Manager.
-
Optional: In the Description field, enter a description for the resource.
-
By default, the Cloud is set to Public/Standard. Azure Government Cloud supports the following regions:
-
US Government
-
China
-
Germany
-
-
In the Client ID field, enter your Application or client ID.
-
In the Client Secret field, enter your client secret.
-
In the Subscription ID field, enter your subscription ID.
-
In the Tenant ID field, enter your Directory or tenant ID.
-
Click Load Regions. This tests if your connection to Azure Resource Manager is successful and loads the regions available in your subscription.
-
From the Azure Region list, select the Azure region to use.
-
Click Submit.
-
Use
hammer compute-resource create
to add an Azure compute resource to Foreman.# hammer compute-resource create \ --app-ident My_Client_ID \ --name My_Compute_Resource_Name \ --provider azurerm \ --region "My_Region" \ --secret-key My_Client_Secret \ --sub-id My_Subscription_ID \ --tenant My_Tenant_ID
Note that the value for the
--region
option must be in lowercase and must not contain special characters.
Important
|
If you are using Azure Government Cloud then you must pass in the --cloud parameter.
The values for the cloud parameter are:
|
Name of Azure Government Cloud | Value for hammer --cloud |
---|---|
US Government |
azureusgovernment |
China |
azurechina |
Germany |
azuregermancloud |
17.3. Adding Microsoft Azure Resource Manager images to Foreman server
To create hosts using image-based provisioning, you must add information about the image, such as access details and the image location, to your Foreman server.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources and click the name of the Microsoft Azure Resource Manager connection.
-
Click Create Image.
-
In the Name field, enter a name for the image.
-
From the Operating System list, select the base operating system of the image.
-
From the Architecture list, select the operating system architecture.
-
In the Username field, enter the SSH user name for image access. You cannot use the
root
user. -
Optional: In the Password field, enter a password to authenticate with.
-
In the Azure Image Name field, enter an image name in the format
prefix://UUID
.-
For a custom image, use the prefix
custom
. For example, custom://image-name. -
For a shared gallery image, use the prefix
gallery
. For example, gallery://image-name. -
For public and RHEL Bring Your Own Subscription (BYOS) images, use the prefix
marketplace
. For example, marketplace://OpenLogicCentOS:7.5:latest.For more information, see Find Linux VM images in the Azure Marketplace with the Azure CLI.
-
-
Optional: Select the User Data checkbox if the image supports user data input, such as
cloud-init
data. -
Click Submit to save the image details.
-
Create the image with the
hammer compute-resource image create
command. Note that the username that you enter for the image must be the same that you use when you create a host with this image. The--password
option is optional when creating an image. You cannot use theroot
user.# hammer compute-resource image create \ --name Azure_image_name \ --compute-resource azure_cr_name \ --uuid 'marketplace://RedHat:RHEL:7-RAW:latest' \ --username 'azure_username' \ --user-data no
17.4. Adding Microsoft Azure Resource Manager details to a compute profile
Use this procedure to add Microsoft Azure hardware settings to a compute profile. When you create a host on Microsoft Azure using this compute profile, these settings are automatically populated.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Infrastructure > Compute Profiles.
-
In the Compute Profiles window, click the name of an existing compute profile, or click Create Compute Profile, enter a Name, and click Submit.
-
Click the name of the Azure compute resource.
-
From the Resource group list, select the resource group to provision to.
-
From the VM Size list, select a size of a virtual machine to provision.
-
From the Platform list, select Linux.
-
In the Username field, enter a user name to authenticate with. Note that the username that you enter for compute profile must be the same that you use when creating an image.
-
To authenticate the user, use one of the following options:
-
To authenticate using a password, enter a password in the Password field.
-
To authenticate using an SSH key, enter an SSH key in the SSH Key field.
-
-
Optional: If you want the virtual machine to use a premium virtual machine disk, select the Premium OS Disk checkbox.
-
From the OS Disk Caching list, select the disc caching setting.
-
Optional: In the Custom Script Command field, enter commands to perform on the virtual machine when the virtual machine is provisioned.
-
Optional: If you want to run custom scripts when provisioning finishes, in the Comma separated file URIs field, enter comma-separated file URIs of scripts to use. The scripts must contain
sudo
at the beginning because Foreman downloads files to the/var/lib/waagent/custom-script/download/0/
directory on the host and scripts require sudo privileges to be executed. -
Optional: You can add a NVIDIA Driver by selecting the NVIDIA driver / CUDA checkbox. For more information, refer to the following Microsoft Azure documentation:
-
Optional: If you want to create an additional volume on the VM, click the Add Volume button, enter the Size in GB and select the Data Disk Caching method.
-
Note that the maximum number of these disks depends on the VM Size selected. For more information on Microsoft Azure VM storage requirements, see the Microsoft Azure documentation.
-
-
Click Add Interface.
ImportantThe maximum number of interfaces depends on the VM Size selected. For more information, see the Microsoft Azure documentation link above.
-
From the Azure Subnet list, select the Azure subnet to provision to.
-
From the Public IP list, select the public IP setting.
-
Optional: If you want the virtual machine to use a static private IP, select the Static Private IP checkbox.
-
Click Submit.
-
Create a compute profile to use with the Azure Resource Manager compute resource:
# hammer compute-profile create --name compute_profile_name
-
Add Azure details to the compute profile. With the
username
setting, enter the SSH user name for image access. Note that the username that you enter for compute profile must be the same that you use when creating an image.# hammer compute-profile values create \ --compute-attributes="resource_group=resource_group,vm_size=Standard_B1s,username=azure_user,password=azure_password,platform=Linux,script_command=touch /var/tmp/text.txt" \ --compute-profile "compute_profile_name" \ --compute-resource azure_cr_name \ --interface="compute_public_ip=Dynamic,compute_network=mysubnetID,compute_private_ip=false" \ --volume="disk_size_gb=5,data_disk_caching=None"
Optional: If you want to run scripts on the virtual machine after provisioning, specify the following settings:
-
To enter the script directly, with the
script_command
setting, enter a command to be executed on the provisioned virtual machine. -
To run a script from a URI, with the
script_uris
setting, enter comma-separated file URIs of scripts to use. The scripts must containsudo
at the beginning because Foreman downloads files to the/var/lib/waagent/custom-script/download/0/
directory on the host and therefore scripts require sudo privileges to be executed.
-
17.5. Creating image-based hosts on Microsoft Azure Resource Manager
In Foreman, you can use Microsoft Azure Resource Manager provisioning to create hosts from an existing image. The new host entry triggers the Microsoft Azure Resource Manager server to create the instance using the pre-existing image as a basis for the new volume.
To use the CLI instead of the Foreman web UI, see the CLI procedure.
-
In the Foreman web UI, navigate to Hosts > Create Host.
-
In the Name field, enter a name for the host.
-
Optional: Click the Organization tab and change the organization context to match your requirement.
-
Optional: Click the Location tab and change the location context to match your requirement.
-
From the Host Group list, select a host group that you want to assign your host to. That host group will populate the form.
-
From the Deploy on list, select the Microsoft Azure Resource Manager connection.
-
From the Compute Profile list, select a profile to use to automatically populate virtual machine settings.
-
From the Lifecycle Environment list, select the environment.
-
Click the Interfaces tab, and on the interface of the host, click Edit.
-
Verify that the fields are populated with values. Note in particular:
-
Foreman automatically assigns an IP address for the new host.
-
Ensure that the MAC address field is blank. Microsoft Azure Resource Manager assigns a MAC address to the host during provisioning.
-
The Name from the Host tab becomes the DNS name.
-
The Azure Subnet field is populated with the required Azure subnet.
-
Optional: If you want to use a static private IP address, from the IPv4 Subnet list select the Foreman subnet with the Network Address field matching the Azure subnet address. In the IPv4 Address field, enter an IPv4 address within the range of your Azure subnet.
-
Ensure that Foreman automatically selects the Managed, Primary, and Provision options for the first interface on the host. If not, select them.
-
-
Click OK to save. To add another interface, click Add Interface. You can select only one interface for Provision and Primary.
-
Click the Operating System tab, and confirm that all fields automatically contain values.
-
For Provisioning Method, ensure Image Based is selected.
-
From the Image list, select the Azure Resource Manager image that you want to use for provisioning.
-
In the Root Password field, enter the root password to authenticate with.
-
Click Resolve in Provisioning templates to check the new host can identify the right provisioning templates to use.
-
Click the Virtual Machine tab and confirm that these settings are populated with details from the host group and compute profile. Modify these settings to suit your needs.
-
Click the Parameters tab, and ensure that a parameter exists that provides an activation key. If not, add an activation key.
-
Click Submit to save the host entry.
-
Create the host with the
hammer host create
command and include--provision-method image
. Replace the values in the following example with the appropriate values for your environment.# hammer host create \ --architecture x86_64 \ --compute-profile "My_Compute_Profile" \ --compute-resource "My_Compute_Resource" \ --domain "My_Domain" \ --image "My_Azure_Image" \ --location "My_Location" \ --name "My_Host_Name" \ --operatingsystem "My_Operating_System" \ --organization "My_Organization" \ --provision-method "image"
For more information about additional host creation parameters for this compute resource, enter the hammer host create --help
command.
17.6. Deleting a VM on Microsoft Azure
You can delete VMs running on Microsoft Azure from within Foreman.
-
In the Foreman web UI, navigate to Infrastructure > Compute Resources.
-
Select your Microsoft Azure provider.
-
On the Virtual Machines tab, click Delete from the Actions menu. This deletes the virtual machine from the Microsoft Azure compute resource while retaining any associated hosts within Foreman. If you want to delete the orphaned host, navigate to Hosts > All Hosts and delete the host manually.
-
You can configure Foreman to remove the associated virtual machine when you delete a host. For more information, see Removing a virtual machine upon host deletion.
17.7. Uninstalling Microsoft Azure plugin
If you have previously installed the Microsoft Azure plugin but don’t use it anymore to manage and deploy hosts to Azure, you can uninstall it from your Foreman server.
-
Uninstall the Azure compute resource provider from your Foreman server:
# dnf remove rubygem-foreman_azure_rm rubygem-ms_rest_azure # foreman-installer --no-enable-foreman-plugin-azure
-
Optional: In the Foreman web UI, navigate to Administer > About and select the Available Providers tab to verify the removal of the Microsoft Azure plugin.
Appendix A: Provisioning FIPS-compliant hosts
Foreman supports provisioning hosts that comply with the National Institute of Standards and Technology’s Security Requirements for Cryptographic Modules standard, reference number FIPS 140-2, referred to here as FIPS.
To enable the provisioning of hosts that are FIPS-compliant, complete the following tasks:
-
Change the provisioning password hashing algorithm for the operating system
-
Create a host group and set a host group parameter to enable FIPS
For more information, see Creating a Host Group in Managing hosts.
The provisioned hosts have the FIPS-compliant settings applied. To confirm that these settings are enabled, complete the steps in Verifying FIPS mode is enabled.
A.1. Changing the provisioning password hashing algorithm
To provision FIPS-compliant hosts, you must first set the password hashing algorithm that you use in provisioning to SHA256. This configuration setting must be applied for each operating system you want to deploy as FIPS-compliant.
-
Identify the Operating System IDs:
# hammer os list
-
Update each operating system’s password hash value.
# hammer os update \ --password-hash SHA256 --title "My_Operating_System"
Note that you cannot use a comma-separated list of values.
A.2. Setting the FIPS-enabled parameter
To provision a FIPS-compliant host, you must create a host group and set the host group parameter fips_enabled
to true
.
If this is not set to true
, or is absent, the FIPS-specific changes do not apply to the system.
You can set this parameter when you provision a host or for a host group.
To set this parameter when provisioning a host, append --parameters fips_enabled=true
to the Hammer command.
# hammer hostgroup set-parameter \ --hostgroup "My_Host_Group" \ --name fips_enabled \ --value "true"
For more information, see the output of the command hammer hostgroup set-parameter --help
.
A.3. Verifying FIPS mode is enabled
To verify these FIPS compliance changes have been successful, you must provision a host and check its configuration.
-
Log in to the host as
root
or with an admin-level account. -
Enter the following command:
$ cat /proc/sys/crypto/fips_enabled
A value of
1
confirms that FIPS mode is enabled.
Appendix B: Host parameter hierarchy
You can access host parameters when provisioning hosts. Hosts inherit their parameters from the following locations, in order of increasing precedence:
Parameter Level | Set in Foreman web UI |
---|---|
Globally defined parameters |
Configure > Global parameters |
Organization-level parameters |
Administer > Organizations |
Location-level parameters |
Administer > Locations |
Domain-level parameters |
Infrastructure > Domains |
Subnet-level parameters |
Infrastructure > Subnets |
Operating system-level parameters |
Hosts > Provisioning Setup > Operating Systems |
Host group-level parameters |
Configure > Host Groups |
Host parameters |
Hosts > All Hosts |
Appendix C: Permissions required to provision hosts
The following list provides an overview of the permissions a non-admin user requires to provision hosts.
Resource name | Permissions | Additional details |
---|---|---|
Activation Keys |
view_activation_keys |
|
Ansible role |
view_ansible_roles |
Required if Ansible is used. |
Architecture |
view_architectures |
|
Compute profile |
view_compute_profiles |
|
Compute resource |
view_compute_resources, create_compute_resources, destroy_compute_resources, power_compute_resources |
Required to provision bare-metal hosts. |
view_compute_resources_vms, create_compute_resources_vms, destroy_compute_resources_vms, power_compute_resources_vms |
Required to provision virtual machines. |
|
Content Views |
view_content_views |
|
Domain |
view_domains |
|
Environment |
view_environments |
|
Host |
view_hosts, create_hosts, edit_hosts, destroy_hosts, build_hosts, power_hosts, play_roles_on_host |
|
view_discovered_hosts, submit_discovered_hosts, auto_provision_discovered_hosts, provision_discovered_hosts, edit_discovered_hosts, destroy_discovered_hosts |
Required if the Discovery service is enabled. |
|
Hostgroup |
view_hostgroups, create_hostgroups, edit_hostgroups, play_roles_on_hostgroup |
|
Image |
view_images |
|
Lifecycle environment |
view_lifecycle_environments |
|
Location |
view_locations |
|
Medium |
view_media |
|
Operatingsystem |
view_operatingsystems |
|
Organization |
view_organizations |
|
Parameter |
view_params, create_params, edit_params, destroy_params |
|
Product and Repositories |
view_products |
|
Provisioning template |
view_provisioning_templates |
|
Ptable |
view_ptables |
|
Smart Proxy |
view_smart_proxies, view_smart_proxies_puppetca |
|
view_openscap_proxies |
Required if the OpenSCAP plugin is enabled. |
|
Subnet |
view_subnets |
-
Creating a Role in Administering Foreman
-
Adding Permissions to a Role in Administering Foreman
-
Assigning Roles to a User in Administering Foreman