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
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
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
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/
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.
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
Use this ISO to boot your VM nodes during installation.
Step 3: Create Installation Configuration
Create a working directory:
mkdir okd-install cd okd-install
Generate the initial install configuration:
openshift-install create install-config
Edit the generated
install-config.yaml
to specify:Cluster name
Base domain
Pull secret (from https://cloud.redhat.com/openshift/install/pull-secret)
Platform: For bare metal or libvirt, specify
baremetal
ornone
Networking and machine pool details
Control plane and worker node counts
Step 4: Generate Ignition Configs and Bootstrap ISO
Generate the ignition configs:
openshift-install create ignition-configs
This creates bootstrap, master, and worker ignition files.
Generate the agent-based installation ISO (for single-node or multi-node agent install):
openshift-install agent create image --dir .
Copy the generated ISO (
agent.x86_64.iso
) to your VM host for use as a bootable image.
Step 5: Provision Virtual Machines
Create VMs for:
- Bootstrap node (1 VM)
- Control plane nodes (3 VMs recommended)
- Worker nodes (1 or more VMs)
Attach the Fedora CoreOS live ISO or the generated agent ISO as the boot media.
Attach the ignition files to each VM accordingly:
Bootstrap VM:
bootstrap.ign
Master VMs:
master.ign
Worker VMs:
worker.ign
Boot the bootstrap node first, then the control plane nodes, then the workers.
Step 6: Monitor Installation Progress
The bootstrap node will initialize the cluster and then shut itself down automatically.
Use the following command to monitor cluster status:
oc get nodes
Wait until all control plane and worker nodes show as
Ready
.Access the OpenShift web console at:
https://console-openshift-console.apps..
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
- Official OKD Installation Docs: https://docs.okd.io/latest/installing/overview/index.html
- Community Single Node OKD on KVM: https://remote-lab.net/installing-single-node-okd
- OKD 4.5 Home Lab Guide: https://www.redhat.com/en/blog/guide-to-installing-an-okd-4-4-cluster-on-your-home-lab
- Fedora CoreOS ISO and Ignition: https://docs.okd.io/latest/installing/installing_bare_metal/installing-bare-metal.html