Assisted Installer Agent

Contents

This project contains several executables that are intended to work with the OpenShift Assisted Installer Service:

• agent - This is the entry point of an assisted installation on the host side. It registers a host with the assisted installer service and starts next_step_runner.
• next_step_runner - Polls the assisted installer service for next steps of an installation, and executes them.
• inventory - Provides information about the host's inventory (CPU, memory, disk, network interfaces, etc.).
• connectivity_check - Tests connectivity via NICs provided in the argument.
• free_addresses - Detects free addresses in a subnet provided in the argument.
• logs_sender - Packages system logs and uploads them to the server for troubleshooting.
• dhcp_lease_allocate - Allocates IP addresses in DHCP. An assisted cluster needs several reserved IPs such as API VIP and ingress VIP.
• apivip_check - Tests connectivity to the API VIP of the assisted cluster.

The project uses the ghw library to collect the inventory and generate a unique identifier (UUID) of the host that the agent is running on.

Agent Flags

• --url: The URL of an assisted installer server, includes a schema and optionally a port.
• --cluster-id: ID of the cluster the host will be connected to.
• --agent-version: Version (full image reference) of the agent being run, used for diagnostic and upgrade purposes.
• --interval: Interval in seconds between consecutive requests that the agent sends to the server. Default is 60.
• --with-text-logging: Enable writing the agent logs to /var/log/agent.log. Default is true.
• --with-journal-logging: Enable writing logs to systemd journal. Default is true.
• --insecure: Skip certificate validation in case of HTTPS transport. Should be used only for testing. Default is false.
• --cacert: Path to a custom CA certificate file in PEM format.
• --help: Print help message and exit.

Inventory Flags

[!WARNING] The inventory process is typically executed during the agent provisioning workflow. Therefore, the inventory configuration must be set before reaching the step of calling the inventory binary.

• --gpu-config-file: Path to a configuration file to filter the GPU discovery process.

The GPU configuration file is in YAML format with 3 elements:

• classes. PCI class (base + subclass) allowed.
• vendors. Combination of PCI class + PCI vendor-id
• models. Combination od PCI class + PCI vendor-id + PCI device-id

The idea for filtering devices is to go from the most generic (PCI Class) to the most specific (Hardware model). If any hardware matches a generic filter it will be added to the list of GPUs. We discard the use of a single element, for example the vendor-id, because it can cause false positives. For example, Intel hardware (0x8086) can be a VGA display controller but also a sound controller. For this reason, for a vendor-id we should add a PCI class to be more precise.

Example:

---
# Include all Display controllers, VGA compatible (0x0300)
classes:
  - '0300'
# Include Nvidia (0x10de) 3D controllers (0x302)
vendors:
  - '0302 10de'
# Include Habana labs (0x1da3) Gaudi2 (0x1020) AI accelerator (0x1200)
models:
  - '1200 1da3 1020'

Example filtering only Nvidia (0x10de) display controllers:

---
# Include Nvidia (0x10de) 3D controllers (0x302)
vendors:
  - '0300 10de'
  - '0302 10de'

By default, the PCI classes discovered will be:

• VGA compatible display controllers (0x0300)
• 3D display controllers (0x0302)
• Display controllers (0x0380)
• Processing accelerators (0x1200)

Packaging

By default, the executables are packaged in a container image quay.io/ocpmetal/assisted-installer-agent:latest. The executables inside the image reside under /usr/bin/.

Running

Since the agent is a statically linked go executable, it can be copied and run outside a container. If running outside a container, the agent must run as root. If running in a Podman container, the podman run command should be invoked with --net=host and --privileged.

The other tools can be invoked using podman run <flags> quay.io/ocpmetal/assisted-installer-agent:latest <executable>.

Dependencies

• Docker (including Docker Compose) is used for subsystem testing, and is not required in runtime.
• Skipper is used for building and testing. Can be installed with pip install strato-skipper.
• Podman is the preferred container runtime to run the executables.

Building

To build the executables run: skipper make To build the container image run: skipper make build-image

Testing

For unit tests, run skipper make unit-test.

The subsystem tests use Docker Compose to run the agent and Wiremock stubs that simulate the assisted installer service. To perform the subsystem tests run skipper make subsystem.

WARNING: The subsystem tests can only run with the default image name and tag. You can build it locally just for this purpose.

To run selected system tests use a regular expression: skipper make subsystem FOCUS=register.

Publishing

To publish the container image run skipper make push. You can override the image name and tag via the ASSISTED_INSTALLER_AGENT variable.