Assisted Installer Based Installation

The Assisted Installer (AI for short in this doc) is yet another method DCI OCP agent can use to install OpenShift clusters. If you're curious about the Assisted Installer you can read several resources already out there. This document will focus on explaining how the AI can be used to install an OpenShift cluster through the DCI agent.

Requirements

You can consult the upstream documentation on the prerequisites needed for a cluster, but they are basically the same as with any other OCP cluster you intend to run, to summarize, for a baremetal cluster you will need:

3 nodes minimum with:
8 CPU cores
16G RAM
100GB Storage

AI does not use a dedicated bootstrap node, instead it re-purposes the bootstrap node into a control plane node when it completes the installation.

!!! note Due to the nature of when Agent Based installer got released, installation through ABI is only available on version 4.12 and up. If you want to test versions < 4.12 using Assisted Installer it is still possible, but you will need to use the On-Prem method

For the DCI Jumpbox you will need:

A RHEL 8 server with:
100G of available disk in the location where you configure the service to store the ISO files. Keep in mind that you will require more disk space if you plan on using a disconnected environment for the local cache
8G of RAM

An explanation of the process

Process starts, the agent creates a new job in the DCI dashboard
Some checks are performed to make sure the installation can proceed
NTP server is installed/configured
HTTP server is created/configured
If this is a disconnected / restricted network environment:
1. The OCP release artifacts are downloaded
2. A container registry is created
3. Container/operator images are mirrored to the local registry
4. Configuration is put in place so the Assisted Installer uses the locally cached resources
VM are created if defined in the inventory file
DNS server is installed/configured
Sushy tools service is configured (if using local VMs)
A Discovery ISO file is created and mounted on all nodes in the cluster via redfish API / virtual media over HTTP
The AI installation is triggered
Installation process is monitored until completion
The KUBECONFIG file is fetched and used to perform some connectivity checks on the OCP cluster
Process ends, the job status is set to complete in the DCI dashboard

Configuration

Before anything else you will need to set install_method: assisted in your inventory or pipeline ansible extra variables. We do this because AI is not the default install method in the DCI OCP Agent.

The first change you will notice right away is that the inventory file has a completely different format: instead of the INI-style format default configuration shows, it is a YAML file. The YAML file offers more capabilities to represent more comples variables (e.g. dicts, lists) then INI files, so familiarize yourself with it.

The following variables control where in the jumpbox the different pieces will store their data, make sure you have enough space (at least 200G) to hold your cached files, and routinely monitor for disk consumption:

downloads_path where the OCP files (ISO files, RAW images, client tools, etc) will be downloaded
assisted_installer_dir (for on-prem method only) where the data needed by the Assisted Installer service(s) will be stored such as database files, etc
registry_dir where the locally configured container registry layers will be stored
sushy_dir (for a virtual environment only) stores the files needed by the sushy service, this directory may grow indiscriminately if left unchecked
http_dir will store the files served over HTTP e.g. the discovery ISO
vm_create_scripts_dir (for a virtual environment only): holds the shell scripts that tell libvirt how to create the VMs
images_dir (for a virtual environment only): where the generated libvirt OS images will be stored

Vendors

Under the nodes section where each member of the control/compute planes is defined you will see a vendor variable. If it's not specified at the node level it's probably specified at the parent and inherited.

Types of vendors:

KVM
PXE
DELL
HPE
LENOVO
SUPERMICRO
ZT

KVM will generate virtual hosts in libvirt and PXE will setup dhcp and tftpboot so that your systems can netboot. All the other types are vendor specific and use redfish to attach virtual media for discovery.

Disconnected environment

This setup is a little bit different from the regular disconnected environment from the IPI method mainly because of the changes in the underlying mechanism that performs the installation and the inventory format change.

If you need to setup a disconnected environment, there's a couple more things you'll have to adjust:

Set dci_disconnected to true, this can be done in the inventory file or the settings.yml file
Turn on the following variables:
setup_registry_service: Creates a container registry in the jumpbox
use_local_registry: Tells the Assisted Installer to use the previously configured container registry
setup_ntp_service (if needed): Configures an NTP server so the cluster can synchronize with. This is turned on by default in the libvirt template
setup_dns_service (if needed): Configures a DNS server so the cluster can resolve names. This is turned on by default in the libvirt template

Virtual Lab Quick Start

If you want to get started quickly with the OCP Agent to test the Assisted Installer the path is fairly easy, assuming you have a jumpbox that meets the requirements. Here's a quick step by step list of what you need to do:

Create (if there is none) an SSH key for the dci-openshift-agent user and add it to its own ~/.ssh/authorized_keys
Generate the libvirt test inventory file from the sample template, there are 3 templates to choose from: sno (single node openshift), controlplane (only 3 control plane nodes), and split (3+3 control and compute plane nodes). To generate the inventory file, login to your jumpbox and execute the following as the dci-openshift-agent user:

bash CONFIG=sno # or 'controlplane' or 'split' cd ~/samples/assisted_on_libvirt ansible-playbook -i $PWD/dev/$CONFIG parse-template.yml
Inspect the generated ~dci-openshift-agent/hosts file and adjust as needed
Copy the generated file from ~dci-openshift-agent/hosts to /etc/dci-openshift-agent/hosts
Start the agent

That's it, after the process is complete, you should be left with a ~dci-openshift-agent/clusterconfigs-dciokd/kubeconfig file which you can use to interact with your OCP cluster.

!!! note The name of the cluster is prepended to the clusterconfigs directory, if you change the cluster name then the path to the kubeconfig file will need to be adjusted

Single Node Openshift

If you followed the libvirt quickstart above, you can see right away there's a few notable differences between SNO and the other cluster configurations:

There are no nodes defined in the compute plane section
There is a single node defined in the control plane section
Both the api_vip and ingress_vip values are pointed to the same IP address you gave the single node
Because SNO requires a minimum of 8 cores, make sure your vm_spec in your vm_nodes section for your control plane has cpu_cores: 8 (it is possible to adjust the memory and disk size in this section too)

That should be all that is required to install in SNO mode, the playbooks will install a SNO cluster and leave you with a kubeconfig/access to the cluster once finished.

On Premise Assisted Installer

There is a way for you to use an alternate method to install using Assisted Installer, this is by installing the AI service/API on premise on the jumpbox itself. This method is currently achievable by setting the inventory variable use_agent_based_installer to false. This method should only be used if you need to install a cluster < 4.12. The rest of the configuration should behave the same, disconnected environment, local cache paths and etc, should be adjusted according to your needs.