Improve documentation across many documents (#1863)

* Improve documentation - formatting - make some formatting compatible with mkdocs - broken links - implement learnings and add new content * Fix spelling * Add note about modular daemons for libvirt in troubleshooting * Use different naming for Fedora + EL * Add additional option to run without foreman gem * Another simplification * More word formatting
theforeman · Nov 4, 2024 · 5108816 · 5108816
1 parent 695c225
commit 5108816
Show file tree

Hide file tree

Showing 10 changed files with 326 additions and 281 deletions.
diff --git a/docs/development.md b/docs/development.md
diff --git a/docs/library.md b/docs/library.md
@@ -4,13 +4,15 @@ Instead of writing a plugin, Forklift can be used as a library to gain more cont
 
 First, make our example directory and clone Forklift:
 
-    mkdir example
-    cd example
-    git clone https://github.com/theforeman/forklift.git
+```sh
+mkdir example
+cd example
+git clone https://github.com/theforeman/forklift.git
+```
 
 First, add an `ansible.cfg` file:
 
-```
+```ini
 [defaults]
 nocows = 1
 host_key_checking = False
@@ -22,13 +24,17 @@ inventory = forklift/playbooks/inventory/vagrant.py
 
 Now, make directories for playbooks and roles:
 
-    mkdir playbooks
-    mkdir roles
-    mkdir pipelines
+```sh
+mkdir playbooks
+mkdir roles
+mkdir pipelines
+```
 
 Deploy a file with the base set of boxes the plugin requires:
 
-    vim base_boxes.yaml
+```sh
+vim base_boxes.yaml
+```
 
 ```yaml
 centos9-stream:

diff --git a/docs/production.md b/docs/production.md
@@ -2,99 +2,111 @@
 
 This covers how you can use the tooling provided by Forklift to spin up a production environment for real deployments or evaluation purposes. The tooling can spin up deployments automatically using Vagrant or be used on your virtual or bare metal machines.
 
- * [Vagrant](#vagrant)
- * [Bring Your Own Box (BYOB)](#byob)
-
+* [Vagrant](#vagrant)
+* [Bring Your Own Box (BYOB)](#byob)
 
 ## Vagrant
 
 The Vagrant configuration can currently run pointing at either a Libvirt or Virtualbox setup.
 
-### Using VirtualBox (Windows, OS X)
+### Using VirtualBox (Windows, macOS)
 
-If you're using Linux, we recommend [Libvirt](#libvirt). The default setup in the Vagrantfile is for VirtualBox. It has been tested against VirtualBox 4.2.18.  To use Install VirtualBox from [the 4.2 downloads
-page](https://www.virtualbox.org/wiki/Download_Old_Builds_4_2). Vagrant 1.6.5+ can be downloaded and installed from [Vagrant Downloads](http://www.vagrantup.com/downloads.html)
+If you're using Linux, we recommend [Libvirt](#libvirt-linux). The default setup in the Vagrantfile is for VirtualBox. It has been tested against VirtualBox 4.2.18. To use Install VirtualBox from [the 4.2 downloads
+page](https://www.virtualbox.org/wiki/Download_Old_Builds_4_2). Vagrant 1.6.5+ can be downloaded and installed from [Vagrant Downloads](https://developer.hashicorp.com/vagrant/install)
 
 ### Libvirt (Linux)
 
 The Vagrantfile provides default setup and boxes for use with the `vagrant-libvirt` provider. To set this up:
 
 1. Ensure you have Vagrant installed
-   * For **libvirt**:
-     1. Ensure you have the prerequisites installed `sudo yum install ruby rubygems ruby-devel gcc gcc-c++`
-1. Install libvirt. On CentOS/Fedora/RHEL, run `sudo yum install @virtualization libvirt-devel`
-1. Install the libvirt plugin for Vagrant (see [vagrant-libvirt page](https://github.com/vagrant-libvirt/vagrant-libvirt) for more information) `vagrant plugin install vagrant-libvirt`
-1. Make sure your user is in the `qemu` group. (e.g. `[[ ! "$(groups $(whoami))" =~ "qemu" ]] && sudo usermod -aG qemu $(whoami)`)
-1. Set the libvirt environment variable in your `.bashrc` or for your current session - `export VAGRANT_DEFAULT_PROVIDER=libvirt`
-1. If you are asked to provide your password for every command, follow [these policykit steps](https://developer.fedoraproject.org/tools/vagrant/vagrant-libvirt.html).
+    * For **libvirt**:
+        1. Ensure you have the prerequisites installed `sudo dnf install ruby rubygems ruby-devel gcc gcc-c++`
+2. Install libvirt. On CentOS/Fedora/RHEL, run `sudo dnf install @virtualization libvirt-devel`
+3. Install the libvirt plugin for Vagrant (see [vagrant-libvirt page](https://github.com/vagrant-libvirt/vagrant-libvirt) for more information) `vagrant plugin install vagrant-libvirt`
+4. Make sure your user is in the `qemu` group. (e.g. `[[ ! "$(groups $(whoami))" =~ "qemu" ]] && sudo usermod -aG qemu $(whoami)`)
+5. Set the libvirt environment variable in your `.bashrc` or for your current session - `export VAGRANT_DEFAULT_PROVIDER=libvirt`
+6. If you are asked to provide your password for every command, follow [these policykit steps](https://developer.fedoraproject.org/tools/vagrant/vagrant-libvirt.html).
 
 ### Vagrant Box Installation
 
 The available versions and types of installs varies as new releases are made and older releases are deprecated. The most accurate way to see the list of available installations is to run the status command:
 
-```
+```sh
 vagrant status
 ```
 
-This will show a list of boxes by type and OS. For example, at the time of this documentation both Foreman 1.12 and Katello 3.1 had been released. Thus, when doing a status I see, for example:
+This will show a list of boxes by type and OS. For example, at the time of this documentation both Foreman 3.11 and Katello 4.13 had been released. Thus, when doing a status I see, for example:
 
-```
+```text
 centos9-stream-foreman-nightly                 not created (libvirt)
 centos9-stream-katello-nightly                 not created (libvirt)
 centos9-stream-foreman-proxy-nightly           not created (libvirt)
 centos9-stream-foreman-3.11                    not created (libvirt)
-centos9-stream-katello-4.13                     not created (libvirt)
+centos9-stream-katello-4.13                    not created (libvirt)
 ```
 
-This indicates that both Foreman and Katello nightly (our unstable releases) are available as well as production installations on Centos 9 boxes of Foreman, Katello and a Foreman Proxy. To fire up a Katello 4.13:
+This indicates that both Foreman and Katello nightly (our unstable releases) are available as well as production installations on CentOS Stream 9 boxes of Foreman, Katello and a Foreman Proxy. To fire up a Katello 4.13:
 
-Start the installation for CentOS 9:
+Start the installation for CentOS Stream 9:
 
-    vagrant up centos9-stream-katello-4.13
+```sh
+vagrant up centos9-stream-katello-4.13
+```
 
-This will create a libvirt based virtual machine running the Katello server on CentOS.
+This will create a libvirt-based virtual machine running the Katello server on CentOS.
 
 ## BYOB
 
-This setup assumes you are either deploying on a non-VM environment or you already have a Virtual machine setup. The deployment can be done either locally on the box or via SSH using an [Ansible inventory](http://docs.ansible.com/ansible/intro_inventory.html) script with proper access.
+This setup assumes you are either deploying on a non-VM environment or you already have a virtual machine setup. The deployment can be done either locally on the box or via SSH using an [Ansible inventory](https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html) script with proper access.
 
 ### Remote Deployment
 
 This use case assumes that you are on a box that has SSH access to the target box for installation and that Ansible can properly realize the target host via an inventory script.
 
-1. Ensure Ansible is installed
+1. Ensure Ansible is installed - `dnf install ansible-core`
 2. Clone this repository - `git clone https://github.com/theforeman/forklift.git`
 3. Enter the repository - `cd forklift`
-4. [Create an inventory file](https://docs.ansible.com/ansible/latest/intro_inventory.html) with your hosts in the `inventories` subfolder. You can also pass a different inventory to `ansible-playbook` using `--inventory` or `-i`.
-5. Change the variable remote_user in ./ansible.cfg to the appropriate value (the user that will log into the remote machine)
-6. Determine the compatible versions of Foreman and Katello you want to install based on the Katello install instructions at https://github.com/theforeman/forklift/blob/master/vagrant/config/versions.yaml. Replace the 3.16 in the URL with whatever version of Katello you want to install.
+4. Install required Ansible modules - `ansible-galaxy collection install -r requirements-prod.yml`
+5. [Create an inventory file](https://docs.ansible.com/ansible/latest/intro_inventory.html) with your hosts in the `inventories` subfolder. You can also pass a different inventory to `ansible-playbook` using `--inventory` or `-i`.
+6. Change the variable remote_user in ./ansible.cfg to the appropriate value (the user that will log into the remote machine)
+7. Determine the compatible versions of Foreman and Katello you want to install based on the Katello install instructions at [./config/versions.yaml](https://github.com/theforeman/forklift/blob/master/vagrant/config/versions.yaml).
 
 For a release version in production:
 
-    ansible-playbook -l <target-host> playbooks/katello.yml -e foreman_repositories_version=WANTED_FOREMAN_VERSION -e katello_repositories_version=WANTED_KATELLO_VERSION
+```sh
+ansible-playbook -l <target-host> playbooks/katello.yml -e foreman_repositories_version=WANTED_FOREMAN_VERSION -e katello_repositories_version=WANTED_KATELLO_VERSION
+```
 
 For nightly production:
 
-    ansible-playbook -l <target-host> playbooks/katello.yml
-
+```sh
+ansible-playbook -l <target-host> playbooks/katello.yml
+```
 
-After installing a Katello server, you could then spin up a Capsule with the assumption the Katello server can talk to the Capsule and vice versa.
+After installing a Katello server, you could then spin up a Smart Proxy (Capsule) with the assumption the Katello server can talk to the Smart Proxy and vice versa.
 
-    ansible-playbook -l <target-capsule-host> playbooks/capsule_31.yml
+```sh
+ansible-playbook -l <target-capsule-host> playbooks/foreman_proxy_content.yml
+```
 
 ### Local Deployment
 
 1. ssh to target machine **as root**
-2. Install Ansible -- `yum install ansible` (for example from the EPEL repo)
+2. Install Ansible - `dnf install ansible-core`
 3. Clone this repository - `git clone https://github.com/theforeman/forklift.git`
 4. Enter the repository - `cd forklift`
-5. Make sure DNS is set up properly. This is a Foreman requirement, not an Ansible requirement.
-6. Determine the compatible versions of Foreman and Katello you want to install based on the Katello install instructions at https://github.com/theforeman/forklift/blob/master/vagrant/config/versions.yaml.
+5. Install required Ansible modules - `ansible-galaxy collection install -r requirements-prod.yml`
+6. Make sure DNS is set up properly. This is a Foreman requirement, not an Ansible requirement.
+7. Determine the compatible versions of Foreman and Katello you want to install based on the Katello install instructions at [./config/versions.yaml](https://github.com/theforeman/forklift/blob/master/vagrant/config/versions.yaml).
 
 For a release version in production:
 
-    ansible-playbook -l localhost playbooks/katello.yml -e foreman_repositories_version=WANTED_FOREMAN_VERSION -e katello_repositories_version=WANTED_KATELLO_VERSION
+```sh
+ansible-playbook -l localhost playbooks/katello.yml -e foreman_repositories_version=WANTED_FOREMAN_VERSION -e katello_repositories_version=WANTED_KATELLO_VERSION
+```
 
 For nightly production:
 
-    ansible-playbook -l localhost playbooks/katello.yml
+```sh
+ansible-playbook -l localhost playbooks/katello.yml
+```
diff --git a/docs/provision.md b/docs/provision.md
@@ -7,47 +7,43 @@ host.
 
 ## How to configure
 
-1. Enable nested virt on your phyiscal box.  See http://www.rdoxenham.com/?p=275
-comments for more details.  Essentially, add this line to kvm-intel.conf and
-reboot:
+1. If necessary, enable nested virt on your phyiscal box (see in [Checking if nested virtualization is supported](https://docs.fedoraproject.org/en-US/quick-docs/using-nested-virtualization-in-kvm)). Essentially, add this line to kvm-intel.conf and reboot:
 
-        echo "options kvm-intel nested=1" | sudo tee /etc/modprobe.d/kvm-intel.conf
+    ```
+    echo "options kvm-intel nested=1" | sudo tee /etc/modprobe.d/kvm-intel.conf
+    ```
 
 2. Build a box
-
-    - Option 1: Use the `centos9-provision-nightly` box.
-
-    - Option 2: Use an existing katello box (e.g. centos9-katello-p7-nightly) and run the provisioning playbook (it takes a while, as it syncs (on-demand) centos9, puppet 7).   ***Note*: If you are using puppet 7, you need to increase the ram on the box, to something like 8096 otherwise candlepin crashes with OOM.**
-        `ansible-playbook -l centos9-katello-p7-nightly playbooks/katello_provisioning.yml`
-
-4. Login and create a compute profile, because this isn't possible with hammer or the API.
-
-   - Click Infrastructure / Compute Resources
-   - Click "libvirt"
-   - Click Compute profiles
-   - Click 2-Medium
-        - increse ram to 2048MB (required for centos 9)
-        - change network type to NAT, network name = provision
-   - Click Submit
-
-5.  Configure Activation Key
-
-  - Content/ Activation Keys
-  - Assign all available subscriptions to the activation key
-
-6. Configure / Host groups
-
-    - Edit Forklift CentOS 9
-    - Set Compute profile to be "2-Medium"
-    - Assign the `CentOS 9` activation key to the host group
-
-7. You're good to go! Let's provision a box!
-
-     - Click Hosts/ New Host
-     - Fill in:
-                - org, location, host group
-                - deploy on = libvirt
-
-     DONE! Click submit :tada:
-
-7. If you want to view the console while it boots, make sure to trust the CA certificate in your browser, it's hosted at https://centos9-steam-katello-nightly.example.com/pub/katello-server-ca.crt, and you'll need to make sure you're accessing the katello via it's proper hostname (add an entry to /etc/hosts)
+    * Option 1: Use the `centos9-provision-nightly` box.
+
+    * Option 2: Use an existing Katello box (e.g. centos9-stream-katello-nightly) and run the provisioning playbook (it takes a while, as it syncs (on-demand) CentOS Stream 9, Puppet 7).  
+    NOTE: If you are using Puppet 7 or higher, you need to increase the ram on the box, to something like 8096 otherwise candlepin crashes with OOM.
+
+        ```
+        ansible-playbook -l centos9-stream-katello-nightly playbooks/katello_provisioning.yml
+        ```
+
+3. Login and create a compute profile, because this isn't possible with hammer or the API.
+    * Click Infrastructure / Compute Resources
+    * Click "libvirt"
+    * Click Compute profiles
+    * Click 2-Medium
+        * increse ram to 2048MB (required for CentOS Stream 9)
+        * change network type to NAT, network name = provision
+    * Click Submit
+4. Configure Activation Key
+    * Content / Activation Keys
+    * Assign all available subscriptions to the activation key
+5. Configure / Host groups
+    * Edit Forklift CentOS 9
+    * Set Compute profile to be "2-Medium"
+    * Assign the `CentOS 9` activation key to the host group
+6. You're good to go! Let's provision a box!
+    * Click Hosts / New Host
+    * Fill in:
+        * org, location, host group
+        * deploy on = libvirt
+
+    DONE! Click submit :tada:
+
+7. If you want to view the console while it boots, make sure to trust the CA certificate in your browser, it's hosted at [https://centos9-stream-katello-nightly.example.com/pub/katello-server-ca.crt](https://centos9-stream-katello-nightly.example.com/pub/katello-server-ca.crt), and you'll need to make sure you're accessing the katello via it's proper hostname (add an entry to /etc/hosts).