Katello Containerized Environments with foremanctl

Development Environment Setup

Prerequisites

• vagrant, libvirt, vagrant-libvirt installed
• foremanctl repository cloned

Setup Commands

# Setup
cd foremanctl
./setup-environment
source .venv/bin/activate

# Start the VM(s)
./forge vms start

# Deploy development environment with Katello features to 'quadlet'
# The special Pulp container image lines are related to Pulp blockers as of April 2026
./forge deploy-dev \
  --foreman-development-enabled-plugin foreman_tasks \
  --foreman-development-enabled-plugin foreman_remote_execution \
  --foreman-development-enabled-plugin foreman_ansible \
  --foreman-development-enabled-plugin foreman_rh_cloud \
  --add-feature foreman-proxy \
  --add-feature hammer \
  --extra-vars pulp_container_tag="nightly" \

# Update /etc/hosts to include the hostname of your new box!
# See https://github.com/theforeman/foremanctl/issues/437
sudo vim /etc/hosts

# To use a specific machine, run the following after editing the Vagrantfile:
./forge vms start --vms="katello-devel"
./forge deploy-dev --target-host=katello-devel ...

Once the machine is created, you should be able to use it like a normal forklift katello-devel box.

Hammer CLI Usage in Development

Location: /home/vagrant/hammer-cli

Usage:

cd /home/vagrant/hammer-cli
bundle exec hammer ...

Production Environment Setup

Local Luna Production with Vagrant

# Start VM
./foreman vms start

# Deploy production environment
./foremanctl deploy \
  --foreman-initial-admin-password=changeme \
  --tuning development \
  --add-feature katello \
  --add-feature foreman-proxy \
  --add-feature remote-execution \
  --add-feature hammer

Notes:

• Production deployment currently expects a VM named quadlet (hardcoded requirement).
• Not all features are available yet, like Foreman RH Cloud and Foreman Ansible.

Import/Export Functionality

Issue: theforeman/foremanctl#445 A PR is in-progress: theforeman/foremanctl#455

Testing New Pulp Versions

Using pulp-oci-images Repository

To test upgraded Pulp versions in your foremanctl environment:

1. Use the pulp-oci-images repository to build custom images
2. Include required components:
   • Pulp plugins
   • Most importantly: pulp_smart_proxy installation
3. Reference: pulp-oci-images PR#13

This PR allows testing of:

• New Pulp versions before official release
• Custom Pulp plugin configurations
• Integration testing with specific Pulp builds

---

Miscellaneous Facts and Quirks

Tips

• Pulp settings are no longer set via /etc/pulp/settings.py. Rather, they are set via environment variables in the systemd service files.
• Quadlet systemd service files live in /etc/containers/systemd.
  • Generated files are created in /run/systemd/generator/.
• Need to update a container? Pull the new version and re-run foremanctl. Double check if the service needs to be restarted for the new container to run.
• Restart Pulp containers via systemctl restart pulp* --all.

Parameter Persistence

foremanctl remembers deployment arguments between runs:

• When you provide parameters to alter deployment, the utility stores and reuses them
• Subsequent runs don't require re-specifying the same parameters
• Reference: foremanctl deployment documentation

Known Issues and Workarounds

1. Foreman URL HTTP Prefix Issue

Problem: foreman_url defaults to HTTP prefix, which breaks host registration.

Symptom: Host registration fails due to protocol mismatch.

Solution:

• Manually set the URL to HTTPS via the Foreman UI
• This is an easy fix but must be done manually after deployment

2. Remote Execution (REX) Jobs Incomplete

Problem: Foreman REX jobs start and run but never fully complete in Foreman UI.

https://gist.github.com/ianballou/6aef2991f7885d4bd1d9bac0ea98a9e2

• foreman_ssl_* setting may solve this.

Impact:

• Jobs execute successfully on target hosts
• Foreman UI shows perpetual "running" status
• Job completion status not properly reflected

3. Import/Export

Problem: /var/lib/pulp/exports/ is not an allowed export path.

Symptom: Any export command fails with an error from Pulp.

Solution: Implement support for configuring Pulp import/export paths in foremanctl.

4. Container Gateway

• The container gateway smart proxy plugin is not yet implemented as a feature.
• theforeman/foremanctl#449

---