How I Replaced K3s with Openshift 4.20 in My Homelab

Learn why OpenShift and OKD are excellent choices for your homelab Kubernetes cluster. Also, learn how to install OKD with a complete step-by-step guide to installing a single node OKD 4.20 cluster with DNS setup, authentication, and security features.

Why and How I Run OpenShift in My Homelab: A Complete Guide

Links For Future reference

• OKD Site
• OKD Product Docs

I recently made a significant change to my homelab infrastructure. My setup was running k3s nodes via podman containers on an AlmaLinux 10 host, but I decided to convert everything to an OpenShift Cluster 4.20. More specifically, I transformed my k3s cluster into a single node OKD cluster. If you’re curious about what I mean by running K3s via podman containers, check out my repository here and here (bottom of readme on second link).

So what exactly is OKD? It’s the community distribution of Kubernetes that powers Red Hat OpenShift. Think of it as the equivalent of CentOS Stream to Red Hat Enterprise Linux, but for the container orchestration world. While the release history suggests it’s closer to a sibling model rather than a true upstream/downstream relationship, the practical difference is straightforward: OKD is essentially OpenShift with CentOS Stream base images instead of RHEL UBI base images.

In this post, I’ll cover the key reasons behind my switch and explain why you might want to consider OKD for your own homelab, even if you’re not planning to use it in production.

For reference, here’s the repository where I documented my single node OKD cluster setup: OKD 4.20 SNO REPO

We’ll dive into the installation details later in this post.

Why Choose OpenShift or OKD to Begin With?

The short answer: it makes Kubernetes significantly easier to use on a daily basis and is more secure by default than vanilla Kubernetes. Let me break down the main features that influenced my decision and what specifically drew me to this conclusion:

1. A Powerful Web Console

OpenShift ships with an intuitive web console that lets you manage your cluster without constantly relying on kubectl/oc commands. While I still use the CLI for many tasks, I increasingly find myself turning to the web console for everyday operations. Whether I’m using the topology view to visualize how applications are running in a namespace, examining resource specs, reviewing Helm releases, or quickly spinning up a resource through the create wizard, the web console provides a welcome alternative. It’s particularly useful when you don’t want to write kubectl/oc commands, Ansible playbooks, Terraform configurations, or Argo applications for a quick task or proof of concept.

Here is a quick glance at the topology ui (this looks really bad ass once you have like 4 applications and a bunch of services within an application)

Here’s a look at the Helm release interface:

2. Seamless Authentication Integration

OpenShift makes it straightforward to integrate with authentication providers like LDAP/AD or OAuth providers such as GitHub, GitLab, and Google. This capability simplifies user and team management in a homelab environment, eliminating the need to create local users on cluster nodes or manage individual kubeconfigs.

Without going into extensive detail about my setup, I’ll mention that I created an Entra ID app registration that allows users in my organization to authenticate using their work accounts.

The setup was simple and works as expected.

3. Projects: Enhanced Namespaces with Built-in Security

Projects represent one of OpenShift’s most practical innovations. Think of them as Namespaces with additional capabilities and security features.

In standard Kubernetes, cluster admins face a binary choice: either users can see all namespaces or none at all. OpenShift takes a more nuanced approach. By default, non-admin users can create and view their own projects while remaining unable to see other users’ projects unless explicitly granted access.

Here’s what the projects view looks like for me as a cluster admin:

Compare that to the view for a non-admin user:

When a non-admin user creates a new project, they’re essentially creating a new namespace:

The creator automatically receives admin permissions for that project/namespace. This design enables users to manage their own projects without requiring cluster admin intervention for routine tasks. For platform teams, this self-service model is invaluable, allowing developers to work independently without creating bottlenecks.

While non-admin users cannot see namespaces directly, they can fully manage their own projects, which have a one-to-one mapping with namespaces. Here’s what the oc CLI output looks like for a non-admin user viewing their projects:

Beyond self-service capabilities, the OpenShift API includes additional security features to prevent privilege escalation and other common vulnerabilities. Namespaces created through Projects automatically have pod security standard labels set to “restricted” by default, the most secure configuration available. This ensures workloads cannot run with privileged access or other insecure settings. Cluster admins can adjust these settings when necessary, but having secure defaults out of the box is a significant advantage.

For more information, check out these resources:

• Pod Security Standards in Kubernetes
• OKD Projects Documentation

In summary, OpenShift Projects provide a more secure and user-friendly approach to namespace management in multi-tenant environments. This straightforward abstraction addresses critical security needs while enabling self-service for developers and teams.

These highlights represent just a fraction of what motivated my switch to OpenShift. While the platform offers many additional features and benefits, these stood out as practical improvements that genuinely enhance the Kubernetes experience without sounding like marketing jargon. OpenShift streamlines security and cluster management in ways that benefit both administrators and users. To be clear, OpenShift remains Kubernetes at its core. It simply adds APIs and features through aggregate API servers and custom controllers, making the platform easier to use and more secure by default than a vanilla Kubernetes installation.

Installing OpenShift in Your Homelab

Now that I’ve covered the reasons behind my decision, let’s walk through the actual installation process.

First, an important caveat: deploying an OpenShift Cluster requires more effort than setting up K3s, MicroK8s, or even using Kubeadm. OpenShift is tightly coupled with Red Hat CoreOS (RHCOS), a minimal operating system purpose-built for running OpenShift. RHCOS is based on Fedora CoreOS, and while OKD previously used Fedora CoreOS, it now uses CentOS Stream CoreOS 10.

The practical implication is that you cannot install OpenShift on top of an existing operating system like you can with other Kubernetes distributions. Instead, you must create boot media containing RHCOS and the OpenShift installer, then boot your nodes from that media. For bare metal servers, the most straightforward approach is creating a bootable USB drive with a tool like Balena Etcher. This is exactly what I did for my homelab.

Here’s a high-level overview of the installation process for my single node OKD cluster:

Prerequisites

Before starting, ensure these prerequisites are in place, as the installation will fail without them:

A separate server or VM functioning as a DNS server with records for cluster nodes, the cluster API, and wildcard records for applications. I used a Pi-hole instance in my homelab for this purpose.

# OKD Cluster DNS records
# This file is used by dnsmasq to resolve cluster hostnames to IP addresses.
# If you don't have this setup on your local DNS server, then the OKD Cluster will not work at all.

# API server - external clients and internal cluster nodes
address=/api.okd.kubesoar.com/192.168.1.9

# Internal API - internal cluster nodes only
address=/api-int.okd.kubesoar.com/192.168.1.9

# Apps wildcard - external clients and internal cluster nodes
address=/.apps.okd.kubesoar.com/192.168.1.9

# Node hostname - single control plane node
address=/control-plane0.okd.kubesoar.com/192.168.1.9

# PTR record for the control plane node
ptr-record=9.1.168.192.in-addr.arpa,control-plane0.okd.kubesoar.com

Since this is a single node cluster, I only have one node address. Multi-node clusters require records for each master and worker node. For my homelab needs, a single node cluster on a capable server is more than sufficient.

With prerequisites in place, the installation is fairly straightforward. Start by cloning the repository:

git clone git@github.com:josephaw1022/okd-sno-manual-install.git
cd okd-sno-manual-install/okd
code .

This repository automates the installation process for a single node OKD cluster. I created it by working through the official OKD installation documentation and packaging the steps into a makefile.

Next, modify the variables at the top of the makefile to match your environment:

Finding the newest version of OKD

Find available versions on the OKD releases page

Finding the WWN

After selecting your version, you’ll need to determine the WWN (World Wide Name) for your target disk. Here’s my approach:

1. Prepare two USB drives: one with an AlmaLinux 10 ISO, and one empty

2. Boot your future OKD server using the AlmaLinux USB

3. Install AlmaLinux to the empty USB drive

4. During software selection, choose “Minimal Install” and add “Graphical Administration Tools” (this includes Cockpit)

Once the installation completes:

1. Power off the server and remove the AlmaLinux ISO USB

2. Boot from the newly created AlmaLinux USB

3. Access Cockpit at https://<server-ip>:9090/

4. Navigate to Storage and wipe all SSDs the OKD node will use

5. Select your target boot drive and locate the WWN in the details view

Here’s an example of the WWN displayed in Cockpit:

In this example, the WWN is “0x5001b444a766a652”. Configure your makefile accordingly:

DISK_ID ?= wwn-0x5001b444a766a652

After recording the WWN, shut down the server and remove the AlmaLinux USB.

Configuring the Domain

Use either a non-public TLD or a domain you own. I used okd.kubesoar.com since I own kubesoar.com:

CLUSTER_NAME ?= okd
BASE_DOMAIN ?= kubesoar.com

Pull Secret Configuration

Since we’re using OKD rather than Red Hat OpenShift, pull secrets and subscriptions aren’t required. I used the placeholder value from the OKD documentation:

For Red Hat OpenShift, you would need to create an account on the Red Hat Customer Portal and generate a proper pull secret.

Running the Installation

With all variables configured, execute:

make oc
make installer

This downloads the oc and openshift-install binaries to the okd directory.

Then run make build, which performs five operations:

1. Downloads the CentOS Stream CoreOS ISO

2. Creates the install-config file

3. Generates ignition files from the install-config

4. Formats the ignition files

5. Embeds the ignition files into the iso

To understand how openshift-install provides the url we need for the iso, I would run the following command after running make installer

openshift-install coreos print-stream-json | jq .

This will show all of the urls available for the iso depending on which platform youre planning to run your OKD cluster on.

Flashing and Booting

After running make build completes, you’ll have a new ISO file. Take the USB drive that originally contained the AlmaLinux ISO and wipe it completely. Keep the AlmaLinux installation USB safe for future disk maintenance needs.

Use Balena Etcher to flash the new OKD ISO to the wiped USB.

Then boot your server from this USB and let the installation proceed. This takes time as components are downloaded and installed.

Expect several reboots during installation. Don’t worry if you need to power cycle the server a few times.

Run make use-kubeconfig to copy the generated kubeconfig to ~/.kube/config, enabling kubectl/oc access to your cluster.

You can now interact with your cluster using kubectl, oc, or a UI tool like Headlamp.

Troubleshooting Hostname Issues

If you encounter an error about “hostname is not a non-localhost value,” SSH into the node and set the correct hostname:

ssh -i ~/.ssh/id_ed25519 core@192.168.1.9 #adjust ip based off what your node's ip is

and then run

sudo hostnamectl set-hostname control-plane0.okd.kubesoar.com #adjust okd.kubesoar.com based off what your cluster name and base domain is

Reboot the node for changes to take effect. Afterward, access the web console at https://console-openshift-console.apps.okd.kubesoar.com/ using the kubeadmin credentials.

Find the password in okd-sno-manual-install/okd/sno/auth/kubeadmin-password.

Congratulations! You now have a single node OKD cluster running in your homelab, ready for application deployment and exploration.

Next Steps

To make your cluster fully operational, consider these additional configurations:

• TLS Certificates for Console UI: Replace the self-signed certificate with a valid one. Instructions are in my repository.
• Cluster Authentication: Configure OAuth providers like GitHub, GitLab, Google, or LDAP/AD. Also documented in my repository.
• Persistent Storage: Set up a storage class. I use OpenEBS. Documentation for this is coming to my repository.
• Add OKDerators: In order to install operators like MetalLB, External Secrets Operator, cert-manager, OKD GitOps (Argo CD), and OKD Service Mesh (Istio) you will need to add the official OKD operator catalog source. Follow the instructions in the OKDerators Repository
• Worker Nodes: Expand your cluster by adding worker nodes using the oc adm node-image command.

oc adm node-image create --mac-address=<worker-node-mac-address>

oc adm node-image create --mac-address=00:d8:e7:c7:4b:bb --hostname=worker-1 --ssh-key-path=~/.ssh/id_ed25519.pub

oc adm node-image create --mac-address=00:d8:e7:c7:4b:bb --hostname=worker-1 --root-device-hint=deviceName:/dev/sda

# Remember to add DNS records for new worker nodes before booting them (e.g., address=/worker-1.okd.kubesoar.com/192.168.1.10 ).

• Set Up OKD GitOps: this operator will setup Argocd for you and configure it so that you can use your clusters auth config for the auth setup in argocd

Once youve installed the operator via the OKDerators catalog source, simply click on the Cluster Argo CDbutton in the console ui

Then click on LOG IN VIA OPENSHIFT

and then you just use the same credentials you used to login

And you’ve got ArgoCD up and running

• Install Cert Manager Operator: Install operator and create a cluster issuer that connects to the dns service that is hosting the domain of your cluster
• Install External Secrets Operator: Install operator and create a cluster secret store that connects to an existing Azure Key Vault or to your Secrets from AWS Secrets Manager.

Conclusion

Switching from k3s to OpenShift in my homelab has been a worthwhile investment. Yes, the initial setup requires more effort than lightweight Kubernetes distributions, but the payoff comes in daily operations. The web console, integrated authentication, and secure-by-default Projects have genuinely improved how I interact with my cluster.

If you’re running a homelab and want an environment that more closely mirrors enterprise Kubernetes deployments, or if you simply want a more polished experience, then OKD deserves serious consideration. It’s still Kubernetes under the hood, so everything you know transfers over. You just get a lot of useful tooling and sensible defaults on top.

Feel free to check out my repository for the installation files and reach out if you have questions. Happy homelabbing!

🚨Update: Moving Beyond Single Node

Since publishing this guide, I have expanded my homelab setup to support high availability . While Single Node OpenShift (SNO) is a fantastic starting point, I recently migrated to a full 3-node cluster using virt-manager and libvirt on AlmaLinux 10.

If you are ready to scale your environment or want to see how to automate a multi-node deployment with Ansible, check out my follow-up post:

**Scaling Out: My Journey from SNO to a 3-Node OpenShift Cluster**