Soon, all Red Hat OpenShift documentation will only be available on docs.redhat.com, the official location of all Red Hat product documentation. Get familiar with the updated experience today!
  1. Documentation
×

Understanding image-based installation and deployment for single-node OpenShift

Image-based installations significantly reduce the deployment time of single-node OpenShift clusters by streamlining the installation process.

This approach enables the preinstallation of configured and validated instances of single-node OpenShift on target hosts. These preinstalled hosts can be rapidly reconfigured and deployed at the far edge of the network, including in disconnected environments, with minimal intervention.

To deploy a managed cluster using an imaged-based approach in combination with GitOps Zero Touch Provisioning (ZTP), you can use the SiteConfig operator. For more information, see SiteConfig operator.

Overview of image-based installation and deployment for single-node OpenShift clusters

Deploying infrastructure at the far edge of the network presents challenges for service providers with low bandwidth, high latency, and disconnected environments. It is also costly and time-consuming to install and deploy single-node OpenShift clusters.

An image-based approach to installing and deploying single-node OpenShift clusters at the far edge of the network overcomes these challenges by separating the installation and deployment stages.

Overview of an image-based installation and deployment
Figure 1. Overview of an image-based installation and deployment for managed single-node OpenShift clusters
Imaged-based installation

Preinstall multiple hosts with single-node OpenShift at a central site, such as a service depot or a factory. Then, validate the base configuration for these hosts and leverage the image-based approach to perform reproducible factory installs at scale by using a single live installation ISO.

Image-based deployment

Ship the preinstalled and validated hosts to a remote site and rapidly reconfigure and deploy the clusters in a matter of minutes by using a configuration ISO.

You can choose from two methods to preinstall and configure your SNO clusters.

Using the openshift-install program

For a single-node OpenShift cluster, use the openshift-install program only to manually create the live installation ISO that is common to all hosts. Then, use the program again to create the configuration ISO which ensures that the host is unique. For more information, see “Deploying managed single-node OpenShift using the openshift-install program”.

Using the IBI Operator

For managed single-node OpenShift clusters, you can use the openshift-install with the Image Based Install (IBI) Operator to scale up the operations. The program creates the live installation ISO and then the IBI Operator creates one configuration ISO for each host. For more information, see “Deploying single-node OpenShift using the IBI Operator”.

Image-based installation for single-node OpenShift clusters

Using the Lifecycle Agent, you can generate an OCI container image that encapsulates an instance of a single-node OpenShift cluster. This image is derived from a dedicated cluster that you can configure with the target OKD version.

You can reference this image in a live installation ISO to consistently preinstall configured and validated instances of single-node OpenShift to multiple hosts. This approach enables the preparation of hosts at a central location, for example in a factory or service depot, before shipping the preinstalled hosts to a remote site for rapid reconfiguration and deployment. The instructions for preinstalling a host are the same whether you deploy the host by using only the openshift-install program or using the program with the IBI Operator.

The following is a high-level overview of the image-based installation process:

  1. Generate an image from a single-node OpenShift cluster.

  2. Use the openshift-install program to embed the seed image URL, and other installation artifacts, in a live installation ISO.

  3. Start the host using the live installation ISO to preinstall the host.

    During this process, the openshift-install program installs Fedora CoreOS (FCOS) to the disk, pulls the image you generated, and precaches release container images to the disk.

  4. When the installation completes, the host is ready to ship to the remote site for rapid reconfiguration and deployment.

Image-based deployment for single-node OpenShift clusters

You can use the openshift-install program or the IBI Operator to configure and deploy a host that you preinstalled with an image-based installation.

Single-node OpenShift cluster deployment

To configure the target host with site-specific details by using the openshift-install program, you must create the following resources:

  • The install-config.yaml installation manifest

  • The image-based-config.yaml manifest

The openshift-install program uses these resources to generate a configuration ISO that you attach to the preinstalled target host to complete the deployment.

Managed single-node OpenShift cluster deployment

Red Hat Advanced Cluster Management (RHACM) and the multicluster engine for Kubernetes Operator (MCE) use a hub-and-spoke architecture to manage and deploy single-node OpenShift clusters across multiple sites. Using this approach, the hub cluster serves as a central control plane that manages the spoke clusters, which are often remote single-node OpenShift clusters deployed at the far edge of the network.

You can define the site-specific configuration resources for an image-based deployment in the hub cluster. The IBI Operator uses these configuration resources to reconfigure the preinstalled host at the remote site and deploy the host as a managed single-node OpenShift cluster. This approach is especially beneficial for telecommunications providers and other service providers with extensive, distributed infrastructures, where an end-to-end installation at the remote site would be time-consuming and costly.

The following is a high-level overview of the image-based deployment process for hosts preinstalled with an imaged-based installation:

  • Define the site-specific configuration resources for the preinstalled host in the hub cluster.

  • Apply these resources in the hub cluster. This initiates the deployment process.

  • The IBI Operator creates a configuration ISO.

  • The IBI Operator boots the target preinstalled host with the configuration ISO attached.

  • The host mounts the configuration ISO and begins the reconfiguration process.

  • When the reconfiguration completes, the single-node OpenShift cluster is ready.

As the host is already preinstalled using an image-based installation, a technician can reconfigure and deploy the host in a matter of minutes.

Image-based installation and deployment components

The following content describes the components in an image-based installation and deployment.

Seed image

OCI container image generated from a dedicated cluster with the target OKD version.

Seed cluster

Dedicated single-node OpenShift cluster that you use to create a seed image and is deployed with the target OKD version.

Lifecycle Agent

Generates the seed image.

Image Based Install (IBI) Operator

When you deploy managed clusters, the IBI Operator creates a configuration ISO from the site-specific resources you define in the hub cluster, and attaches the configuration ISO to the preinstalled host by using a bare-metal provisioning service.

openshift-install program

Creates the installation and configuration ISO, and embeds the seed image URL in the live installation ISO. If the IBI Operator is not used, you must manually attach the configuration ISO to a preinstalled host to complete the deployment.

Additional resources

Cluster guidelines for image-based installation and deployment

For a successful image-based installation and deployment, see the following guidelines.

Cluster guidelines

  • If you are using Red Hat Advanced Cluster Management (RHACM), to avoid including any RHACM resources in your seed image, you need to disable all optional RHACM add-ons before generating the seed image.

Seed cluster guidelines

  • If your cluster deployment at the edge of the network requires a proxy configuration, you must create a seed image from a seed cluster featuring a proxy configuration. The proxy configurations do not have to match.

  • If you set a maximum transmission unit (MTU) in the seed cluster, you must set the same MTU value in the static network configuration for the image-based configuration ISO.

  • Your single-node OpenShift seed cluster must have a shared /var/lib/containers directory for precaching images during an image-based installation. For more information see "Configuring a shared container partition between ostree stateroots".

  • Create a seed image from a single-node OpenShift cluster that uses the same hardware as your target bare-metal host. The seed cluster must reflect your target cluster configuration for the following items:

    • CPU topology

      • CPU architecture

      • Number of CPU cores

      • Tuned performance configuration, such as number of reserved CPUs

    • IP version

      Dual-stack networking is not supported in this release.

    • Disconnected registry

      If the target cluster uses a disconnected registry, your seed cluster must use a disconnected registry. The registries do not have to be the same.

    • FIPS configuration

Additional resources

Software prerequisites for an image-based installation and deployment

An image-based installation and deployment requires the following minimum software versions for these required components.

Table 1. Minimum software requirements
Component Software version

Managed cluster version

4.17

Hub cluster version

4.16

Red Hat Advanced Cluster Management (RHACM)

2.12

Lifecycle Agent

4.16 or later

Image Based Install Operator

4.17

openshift-install program

4.17
Additional resources