1. Documentation
×

Installing OpenShift on a single node

Installing single-node OKD using the Assisted Service

To install single-node OKD with the Assisted Service, please refer to the following documentation: * 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

Installing OKD on a single node requires an installation ISO, which you can generate with the following procedure.

Prerequisites

  • Install podman.

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

  1. Set the OKD version:

    $ OKD_VERSION=<okd_version> (1)
    1 Replace <okd_version> with the current version, for example, 4.14.0-0.okd-2024-01-26-175629

  2. Set the host architecture:

    $ export ARCH=<architecture> (1)
    1 Replace <architecture> with the target host architecture, for example, aarch64 or x86_64.

  3. 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

  4. 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

  5. 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)

  6. Download the FCOS ISO:

    $ curl -L $ISO_URL -o fcos-live.iso

  7. Prepare the install-config.yaml file:

    apiVersion: v1
baseDomain: <domain> (1)
compute:
- name: worker
  replicas: 0 (2)
controlPlane:
  name: master
  replicas: 1 (3)
metadata:
  name: <name> (4)
networking: (5)
  clusterNetwork:
  - cidr: 10.128.0.0/14
    hostPrefix: 23
  machineNetwork:
  - cidr: 10.0.0.0/16 (6)
  networkType: OVNKubernetes
  serviceNetwork:
  - 172.30.0.0/16
platform:
  none: {}
bootstrapInPlace:
  installationDisk: /dev/disk/by-id/<disk_id> (7)
pullSecret: '<pull_secret>' (8)
sshKey: |
  <ssh_key> (9)
    1 Add the cluster domain name.
    2 Set the compute replicas to 0. This makes the control plane node schedulable.
    3 Set the controlPlane replicas to 1. In conjunction with the previous compute setting, this setting ensures the cluster runs on a single node.
    4 Set the metadata name to the cluster name.
    5 Set the networking details. OVN-Kubernetes is the only allowed network plugin type for single-node clusters.
    6 Set the cidr value to match the subnet of the single-node OKD cluster.
    7 Set the path to the installation disk drive, for example, /dev/disk/by-id/wwn-0x64cd98f04fde100024684cf3034da5c2.
    8 Copy the pull secret from Red Hat OpenShift Cluster Manager and add the contents to this configuration setting.
    9 Add the public SSH key from the administration host so that you can log in to the cluster after installation.

  8. Generate OKD assets by running the following commands:

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

  9. 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 openshift-install 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

  1. Attach the discovery ISO image to the target host.

  2. 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.

  3. On the administration host, monitor the installation by running the following command:

    $ ./openshift-install --dir=sno wait-for install-complete

  4. 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

Installing single-node OKD on cloud providers

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

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 8 vCPU cores and 120GB of storage.

  • 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.

Supported cloud providers for single-node OKD

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 Platform (GCP)

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 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 single-node OKD on GCP

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

Additional resources

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

  1. On the administration host, insert a USB drive into a USB port.

  2. 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.