• OpenShift
  • Step-by-Step Guide to Install OKD 4.x on a Linux VM

Here is a detailed step-by-step guide to install OKD (OpenShift Origin) 4.x on a Linux VM, based on the latest official OKD documentation and community best practices:


Step-by-Step Guide to Install OKD 4.x on a Linux VM


Prerequisites

  • A Linux VM host (e.g., CentOS Stream, Fedora, Ubuntu) with:
    • Minimum 16 GB RAM
    • Minimum 4-8 vCPUs
    • At least 120 GB disk space
    • Static IP address and DNS configured
    • Network connectivity to your management workstation
  • Hypervisor installed (KVM/libvirt, VMware, VirtualBox, etc.)
  • Basic Linux command-line knowledge
  • Access to a DNS server where you can create required DNS records (or local DNS override)
  • Internet access to download OKD binaries and container images

Step 1: Download OKD Installer and Client Tools

  1. Set environment variables for the OKD version and architecture (adjust version as needed):

       export OKD_VERSION=4.15.0-0.okd-2024-03-10-010116
       export ARCH=x86_64
  2. Download the OKD client (oc) and installer binaries:

       curl -L https://github.com/okd-project/okd/releases/download/$OKD_VERSION/openshift-client-linux-$OKD_VERSION.tar.gz -o oc.tar.gz
       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
  3. Extract and move binaries to /usr/local/bin:

       tar xvf oc.tar.gz
       sudo mv oc kubectl /usr/local/bin/
       tar xvf openshift-install-linux.tar.gz
       sudo mv openshift-install /usr/local/bin/
  4. Verify installation:

       oc version
       openshift-install version

Step 2: Prepare Fedora CoreOS Images

OKD 4.x uses Fedora CoreOS as the base OS for all nodes.

  1. Obtain the Fedora CoreOS live ISO:

       ISO_URL=$(openshift-install coreos print-stream-json | grep location | grep $ARCH | grep iso | cut -d\" -f4)
       curl -L $ISO_URL -o fcos-live.iso
  2. Use this ISO to boot your VM nodes during installation.


Step 3: Create Installation Configuration

  1. Create a working directory:

       mkdir okd-install
       cd okd-install
  2. Generate the initial install configuration:

       openshift-install create install-config
  3. Edit the generated install-config.yaml to specify:


Step 4: Generate Ignition Configs and Bootstrap ISO

  1. Generate the ignition configs:

       openshift-install create ignition-configs
  2. This creates bootstrap, master, and worker ignition files.

  3. Generate the agent-based installation ISO (for single-node or multi-node agent install):

       openshift-install agent create image --dir .
  4. Copy the generated ISO (agent.x86_64.iso) to your VM host for use as a bootable image.


Step 5: Provision Virtual Machines

  1. Create VMs for:

    • Bootstrap node (1 VM)
    • Control plane nodes (3 VMs recommended)
    • Worker nodes (1 or more VMs)
  2. Attach the Fedora CoreOS live ISO or the generated agent ISO as the boot media.

  3. Attach the ignition files to each VM accordingly:

    • Bootstrap VM: bootstrap.ign

    • Master VMs: master.ign

    • Worker VMs: worker.ign

  4. Boot the bootstrap node first, then the control plane nodes, then the workers.


Step 6: Monitor Installation Progress

  1. The bootstrap node will initialize the cluster and then shut itself down automatically.

  2. Use the following command to monitor cluster status:

       oc get nodes
  3. Wait until all control plane and worker nodes show as Ready.

  4. Access the OpenShift web console at:

       https://console-openshift-console.apps..
  5. Login with credentials generated during installation.


Step 7: Post-Installation Tasks

  • Remove the bootstrap node once installation completes.
  • Configure persistent storage, ingress, and other cluster services as needed.
  • Deploy your applications and start using your OKD cluster.

Additional Notes

  • DNS Setup: You must create DNS A records for the API and wildcard apps subdomain pointing to your load balancer or bootstrap node IP.
  • Networking: Ensure your VM network allows communication between nodes and external access as required.
  • Resources: Allocate sufficient CPU, RAM, and disk space to each VM for smooth operation.
  • Troubleshooting: Use openshift-install gather bootstrap to collect logs if installation fails.

References