Installing OpenShift on a single node - Installing on a single node | Installing

Installing single-node OKD using the Assisted Service
Installing single-node OKD manually
- Generating the installation ISO with coreos-installer
- Monitoring the cluster installation using openshift-install
Additional requirements for installing single-node OKD on a cloud provider
Supported cloud providers for single-node OKD
Installing single-node OpenShift on AWS
Installing single-node OKD on Azure
Installing single-node OKD on Google Cloud
Creating a bootable ISO image on a USB drive

You can install single-node OKD using the Assisted Service or you can generate an installation ISO using openshift-installer.

Installing single-node OKD using the Assisted Service

You can install install single-node OKD with the Assisted Service.

For more information, see "Install OKD using Assisted Service".

Additional resources

Installing single-node OKD manually

To install OKD on a single node, first generate the installation ISO, and then boot the server from the ISO. You can monitor the installation using the openshift-install installation program.

Additional resources

Generating the installation ISO with coreos-installer

You can install OKD on a single node by generating an installation ISO.

Prerequisites

Install podman.

See "Requirements for installing OpenShift on a single node" for networking requirements, including dns records.

Procedure

Set the OKD version:
```
$ OKD_VERSION=<okd_version>
```
Replace <okd_version> with the current version, for example, 4.14.0-0.okd-2024-01-26-175629
Set the target cluster architecture:
```
$ export ARCH=<architecture>
```
Replace <architecture> with the target host architecture, for example, aarch64 or x86_64.
Set the installation host architecture:
```
$ export HOST_ARCH=$(uname -m)
```
This command detects the architecture of the installation host. If the installation host architecture differs from the target cluster architecture, the downloaded binaries must match the installation host. For example, if you are installing an aarch64 cluster from an x86_64 bastion host, HOST_ARCH is x86_64.

Download the OKD client (oc) and make it available for use by entering the following commands:

$ curl -L https://github.com/okd-project/okd/releases/download/$OKD_VERSION/openshift-client-linux-$OKD_VERSION.tar.gz -o oc.tar.gz

$ tar zxf oc.tar.gz

$ chmod +x oc

Download the OKD installer and make it available for use by entering the following commands:

$ curl -L https://github.com/okd-project/okd/releases/download/$OKD_VERSION/openshift-install-linux-$OKD_VERSION.tar.gz -o openshift-install-linux.tar.gz

$ tar zxvf openshift-install-linux.tar.gz

$ chmod +x openshift-install

Retrieve the FCOS ISO URL by running the following command:

$ export ISO_URL=$(./openshift-install coreos print-stream-json | grep location | grep $ARCH | grep iso | cut -d\" -f4)

Download the FCOS ISO:
```
$ curl -L $ISO_URL -o fcos-live.iso
```
Prepare the install-config.yaml file:
```
apiVersion: v1
baseDomain: <domain>
compute:
- name: worker
  replicas: 0
controlPlane:
  name: master
  replicas: 1
metadata:
  name: <name>
networking:
  clusterNetwork:
  - cidr: 10.128.0.0/14
    hostPrefix: 23
  machineNetwork:
  - cidr: 10.0.0.0/16
  networkType: OVNKubernetes
  serviceNetwork:
  - 172.30.0.0/16
platform:
  none: {}
bootstrapInPlace:
  installationDisk: /dev/disk/by-id/<disk_id>
pullSecret: '<pull_secret>'
sshKey: |
  <ssh_key>
```
where:

baseDomain

Specifies the cluster domain name.

compute.replicas

Specifies the value of compute.replicas as 0. This makes the control plane node schedulable.

controlPlane.replicas

Specifies the value of controlPlane.replicas as 1. In conjunction with the previous compute setting, this setting ensures the cluster runs on a single node.

metadata.name

Specifies the metadata name to the cluster name.

networking

Specifies the networking details. OVN-Kubernetes is the only allowed network plugin type for single-node clusters.

machineNetwork.cidr

Specifies the cidr value to match the subnet of the cluster.

installationDisk

Specifies the path to the installation disk drive, for example, /dev/disk/by-id/wwn-0x64cd98f04fde100024684cf3034da5c2.

pullSecret

Specifies the pullSecret parameter. Copy the pull secret from Red Hat OpenShift Cluster Manager and add the contents to this configuration setting.

sshKey

Specifies the sshKey parameter. Add the public SSH key from the administration host so that you can log in to the cluster after installation.

Generate OKD assets by running the following commands:

$ mkdir sno

$ cp install-config.yaml sno

$ ./openshift-install --dir=sno create single-node-ignition-config

Embed the ignition data into the FCOS ISO by running the following commands:

$ alias coreos-installer='podman run --privileged --pull always --rm \
        -v /dev:/dev -v /run/udev:/run/udev -v $PWD:/data \
        -w /data quay.io/coreos/coreos-installer:release'

$ coreos-installer iso ignition embed -fi sno/bootstrap-in-place-for-live-iso.ign fcos-live.iso

Additional resources

Monitoring the cluster installation using openshift-install

Use the openshift-install binary to monitor the progress of the single-node cluster installation.

Prerequisites

Ensure that the boot drive order in the server BIOS settings defaults to booting the server from the target installation disk.

Procedure

Attach the discovery ISO image to the target host.
Boot the server from the discovery ISO image. The discovery ISO image writes the system configuration to the target installation disk and automatically triggers a server restart.
On the administration host, monitor the installation by running the following command:
```
$ ./openshift-install --dir=sno wait-for install-complete
```
Optional: Remove the discovery ISO image.

The server restarts several times while deploying the control plane.

Verification

After the installation is complete, check the environment by running the following command:

$ export KUBECONFIG=sno/auth/kubeconfig

$ oc get nodes

Example output

NAME                         STATUS   ROLES           AGE     VERSION
control-plane.example.com    Ready    master,worker   10m     v1.27.9+e36e183

Additional resources

Additional requirements for installing single-node OKD on a cloud provider

Compared to installing a high-availability cluster, there are additional requirements for installing single-node OKD.

The documentation for installer-provisioned installation on cloud providers is based on a high availability cluster consisting of three control plane nodes. When referring to the documentation, consider the differences between the requirements for a single-node OKD cluster and a high availability cluster.

A high availability cluster requires a temporary bootstrap machine, three control plane machines, and at least two compute machines. For a single-node OKD cluster, you need only a temporary bootstrap machine and one cloud instance for the control plane node and no worker nodes.

The minimum resource requirements for high availability cluster installation include a control plane node with 4 vCPUs and 100GB of storage. For a single-node OKD cluster, you must have a minimum of 4 vCPU cores and 120GB of storage.

Running single-node OKD on 4 vCPUs leaves very little "headroom" for user applications, and creates a high risk of resource contention and performance degradation.

To ensure cluster stability at this threshold, you must take steps to minimize the total resource footprint of the cluster, such as limiting the amount of workloads running on the cluster or limiting cluster capabilities. For more information, see "Cluster capabilities".

Otherwise, it is recommended to provide more compute resources to the cluster.

The controlPlane.replicas setting in the install-config.yaml file should be set to 1.
The compute.replicas setting in the install-config.yaml file should be set to 0. This makes the control plane node schedulable.

Additional resources

Cluster capabilities

Supported cloud providers for single-node OKD

You can install a single-node cluster on several supported cloud providers.

The following table contains a list of supported cloud providers and CPU architectures.

Table 1. Supported cloud providers
Cloud provider	CPU architecture
Amazon Web Service (AWS)	x86_64 and AArch64
Microsoft Azure	x86_64
Google Cloud	x86_64 and AArch64

Installing single-node OpenShift on AWS

Installing a single-node cluster on AWS requires installer-provisioned installation using the "Installing a cluster on AWS with customizations" procedure.

Additional resources

Installing a cluster on AWS with customizations

Installing single-node OKD on Azure

Installing a single-node cluster on Azure requires installer-provisioned installation using the "Installing a cluster on Azure with customizations" procedure.

Additional resources

Installing a cluster on Azure with customizations

Installing single-node OKD on Google Cloud

Installing a single-node cluster on Google Cloud requires installer-provisioned installation using the "Installing a cluster on Google Cloud with customizations" procedure.

Additional resources

Installing a cluster on Google Cloud with customizations

Creating a bootable ISO image on a USB drive

You can install software using a bootable USB drive that contains an ISO image. Booting the server with the USB drive prepares the server for the software installation.

Procedure

On the administration host, insert a USB drive into a USB port.
Create a bootable USB drive, for example:
```
# dd if=<path_to_iso> of=<path_to_usb> status=progress
```
where:

<path_to_iso>

is the relative path to the downloaded ISO file, for example, fcos-live.iso.

<path_to_usb>

is the location of the connected USB drive, for example, /dev/sdb.

After the ISO is copied to the USB drive, you can use the USB drive to install software on the server.