DEV Community: Ana Villar

Building an OpenShift 4.18 Cluster from Scratch: Part 3 - The Deployment Lifecycle & Troubleshooting

Ana Villar — Mon, 27 Jul 2026 18:25:55 +0000

Note: This is Part 3 of a multi-part series.

✅ [Part 1: The Network Foundation & Utilities Server] (Published)
✅ [Part 2: Generating Ignition Configs & VM Prep] (Published)
Part 4: Post-Install Hardening & User Management

In Parts 1 and 2, we built the foundation and prepared our Ignition configurations. The utilities server was humming, DHCP and DNS were routing requests correctly, and our VMs were ready to PXE boot. Now comes the moment of truth: actually deploying the cluster.

But here's the thing about bare metal OpenShift deployments—they rarely go perfectly on the first try. In this part, I'll walk through exactly what happened when my first deployment attempt failed, how I recovered, and the critical troubleshooting steps every OpenShift administrator should know.

Review we have all in place

At this point I want you to check that everything is ready to go.

You have created 7 virtual machines, with the specifications indicated in Part 1, under Lab Environment Overview section.
The VMs are called bootstos, masteros01, masteros02, masteros03, workeros01, workeros02 and workeros03.
Those have been created with UEFI (or EFI) firmware.
You have disabled Secured Boot, as explained in Part 2, under the section Disabling Secure Boot on VMs.
And you have noted the MAC Address of the NIC attached.

Then, ensure you have updated the Kea configuration file (/etc/kea/kea-dhcp4.conf) in your utilities server VM with the correct MAC address (hw-address), under reservations.

"reservations": [
          { "hw-address": "AA:BB:CC:DD:EE:01", "ip-address": "192.168.110.100", "hostname": "bootstos.oc41827.internal.local" },

          { "hw-address": "AA:BB:CC:DD:EE:02", "ip-address": "192.168.110.101", "hostname": "masteros01.oc41827.internal.local" },
...

If you have to update the file now, check the syntax using

$ sudo kea-dhcp4 -t /etc/kea/kea-dhcp4.conf

and restart the service.

$ sudo systemctl restart kea-dhcp4

Start the deployment

Boot the 7 virtual machines

Using your Cockpit interface or with the command sudo virsh start (or, if using a different hypervisor, whatever CLI or GUI interface you prefer), start the virtual machines.

Start first with bootstos. When the iPXE menu appears, ensure you select the menu entry called Install OpenShift 4.18.27 Bootstrap. In a few moments, the process will complete and it will automatically reboot.

If, for whatever reason, you had to manually force the VM to boot from network, once the installation is completed, shutdown the VM and change the boot order to boot from its local disk.

Do the same for the other six virtual machines.

For masteros01, masteros02 and masteros03, when the iPXE menu appears, select Install OpenShift 4.18.27 Master Node.
For workeros01, workeros02 and workeros03, when the iPXE menu appears, select Install OpenShift 4.18.27 Worker Node.

Launch and monitor the progress

Now that the 7 VMs are up and running, open two SSH sessions to your utilities server, one for the actual deployment and the second to be able to monitor the progress.

In the first session, start the deployment running the following command:

$ openshift-install --dir=./oc41827upi wait-for bootstrap-complete --log-level debug

In the second session, connect to the bootstrap VM:

$ ssh -i .ssh/oc41827upi core@bootstos

and once there, monitor the deployment from here as well:

$ sudo journalctl -b -f -u release-image.service -u bootkube.service

🚨 Certificate Expiration

If you followed the steps the ignition files (getting the pull secret and updating the install-config.yaml configuration file, as indicated in the section Generating installation configuration file) a few days back, you are most likely to see the deployment failing after a few minutes, and errors similar to those in the bootstrap ssh session:

May 01 13:34:49 bootstos.oc41827.internal.local bootkube.sh[4018]: [#3964] failed to fetch discovery: Get "https://localhost:6443/api?timeout=32s": dial tcp [::1]:6443: connect: connection refused
May 01 13:34:50 bootstos.oc41827.internal.local cluster-bootstrap[4049]: [#3965] failed to fetch discovery: Get "https://localhost:6443/api?timeout=32s": tls: failed to verify certificate: x509: certificate has expired or is not yet valid: current time 2026-05-01T13:34:50Z is after 2026-04-27T18:15:56Z
May 01 13:34:50 bootstos.oc41827.internal.local bootkube.sh[4018]: [#3965] failed to fetch discovery: Get "https://localhost:6443/api?timeout=32s": tls: failed to verify certificate: x509: certificate has expired or is not yet valid: current time 2026-05-01T13:34:50Z is after 2026-04-27T18:15:56Z

What Happened? OpenShift certificates generated during the install-config.yaml creation have a limited validity window (typically 24 hours). My first deployment attempt came four days after configuration generation, causing the certificates to expire before installation began.

The Solution: Regenerate Everything, I am afraid.

As seen in Part 2, those are the steps needed:

Get a fresh pull secret from console.redhat.com
Move old config fiels aside
Recreate the configuration directory:

$ mv oc41827upi oc41827upi.old
$ mkdir oc41827upi
$ cd oc41827upi

Copy the fresh pull secret** and format it properly:

$ python3 -m json.tool pull-secret > pull-secret.json
$ cat pull-secret.json | jq . -c > ~/oc41827upi/pull-secret-online.json

Update install-config.yaml

$ cat <<EOF > ~/oc41827upi/install-config.yaml
apiVersion: v1
baseDomain: internal.local
compute:
- hyperthreading: Enabled
  name: worker
  replicas: 3
controlPlane:
  hyperthreading: Enabled
  name: master
  replicas: 3
metadata:
  name: oc41827
networking:
  clusterNetwork:
  - cidr: 10.128.0.0/14
    hostPrefix: 23
  networkType: OVNKubernetes
  serviceNetwork:
  - 172.30.0.0/16
platform:
  none: {}
fips: false
pullSecret: '$(cat ~/oc41827upi/pull-secret.json)'
sshKey: '$(cat ~/.ssh/oc41827upi.pub)'
EOF

Regenerate manifests and Ignition files:

$ cd ~/oc41827upi
$ openshift-install create manifests --dir=.
$ openshift-install create ignition-configs --dir=.

Copy new Ignition files to Apache:

$ sudo cp *.ign /var/www/html/oc41827/ignition/
$ sudo chmod +r /var/www/html/oc41827/ignition/*
$ sudo restorecon -Rv /var/www/html

With fresh configurations, reset the VMs:

Shut down all nodes
Delete their virtual disks and attach a new one (to force clean installs)
Boot via iPXE menu selection

💡 Key Lesson: Keep your configuration workflow tight. Don't generate Ignition files until you're ready to deploy immediately afterward.

Bootstrap Complete: Removing the Temporary Node

If all goes well, you can expect outputs similar to this on your utilities ssh session:

$ openshift-install --dir=./oc41827upi wait-for bootstrap-complete --log-level debug
DEBUG OpenShift Installer 4.18.37  
...
INFO Bootstrap etcd member has been removed       
INFO It is now safe to remove the bootstrap resources 
DEBUG Time elapsed per stage:                      
DEBUG Bootstrap Complete: 26m48s                   
INFO Time elapsed: 26m48s                         
$

and this on the bootstrap session:

[core@bootstos ~]$ sudo journalctl -b -f -u release-image.service -u bootkube.service
May 01 13:55:00 bootstos.oc41827.internal.local cluster-bootstrap[4041]: "99_openshift-machineconfig_99-master-ssh.yaml": failed to create machineconfigs.v1.machineconfiguration.openshift.io/99-master-ssh -n : the server could not find the requested resource
May 01 13:55:00 bootstos.oc41827.internal.local cluster-bootstrap[4041]: "99_openshift-machineconfig_99-worker-ssh.yaml": failed to create machineconfigs.v1.machineconfiguration.openshift.io/99-worker-ssh -n : the server could not find the requested resource
May 01 13:55:00 bootstos.oc41827.internal.local cluster-bootstrap[4041]: Created "0000_00_cluster-version-operator_01_adminack_configmap.yaml" configmaps.v1./admin-acks -n openshift-config
...
May 01 14:23:13 bootstos.oc41827.internal.local bootkube.sh[5815]: Success while trying to reach API_INT_URL's https endpoint at https://api-int.oc41827.internal.local:6443/readyz
May 01 14:23:13 bootstos.oc41827.internal.local bootkube.sh[5815]: bootkube.service complete
May 01 14:23:13 bootstos.oc41827.internal.local systemd[1]: bootkube.service: Deactivated successfully.
May 01 14:23:13 bootstos.oc41827.internal.local systemd[1]: bootkube.service: Consumed 4.396s CPU time.

This typically takes 25-40 minutes depending on your hardware and network speed.

Once bootstrap-complete succeeds, OpenShift automatically removes the bootstrap etcd member. Now we must manually remove the bootstrap node from our HAProxy load balancer:

Edit HAProxy Configuration

$ sudo vim /etc/haproxy/haproxy.cfg

Comment out or remove the bootstrap server entries from both the API server and machine config server listen sections:

# round robin balancing for RHOCP Kubernetes API Server
#server bootstos bootstos.oc41827.internal.local:6443 verify none check check-ssl inter 10s fall 2 rise 3 backup

# round robin balancing for RHOCP Machine Config Server
#server bootstos bootstos.oc41827.internal.local:22623 check inter 1s backup

Then restart HAProxy:

$ sudo systemctl restart haproxy

Shutdown bootstrap

Now you can shutdown the bootstrap machine. Using the session you opened to monitor the progress, press Crtl+C to finish the journalctl command and use the shutdown command.

[core@bootstos ~]$ sudo shutdown -h now
[core@bootstos ~]$ Connection to bootstos closed by remote host.
Connection to bootstos closed.
$

Finish the deployment

Check the status of the OpenShift cluster on your ssh session to the utilities server.

$ export KUBECONFIG=~/oc41827upi/auth/kubeconfig
$ oc whoami
system:admin
$ oc get nodes
NAME                                      STATUS   ROLES                  AGE   VERSION
masteros01.oc41827.internal.local   Ready    control-plane,master   32m   v1.31.14
masteros02.oc41827.internal.local   Ready    control-plane,master   30m   v1.31.14
masteros03.oc41827.internal.local   Ready    control-plane,master   30m   v1.31.14
$ oc get clusterversion
NAME      VERSION   AVAILABLE   PROGRESSING   SINCE   STATUS
version             False       True          36m     Unable to apply 4.18.37: some cluster operators are not available
$

Where are the worker nodes? Wait, we haven't finish yet, so let's run this:

$ openshift-install --dir=./oc41827upi wait-for install-complete --log-level=debug

On another session, keep an eye on Certificate Signing Requests (CSRs) being pending for approval:

$ export KUBECONFIG=~/oc41827upi/auth/kubeconfig
$ oc get csr

You might see an output similar to this:

NAME                                             AGE   SIGNERNAME                                    REQUESTOR                                                                         REQUESTEDDURATION   CONDITION
csr-2zppd                                        35m   kubernetes.io/kubelet-serving                 system:node:masteros02.oc41827.internal.local                                     <none>              Approved,Issued
...
csr-hnt8m                                        25m   kubernetes.io/kube-apiserver-client           system:node:masteros03.oc41827.internal.local                                     24h                 Approved,Issued
csr-lldhf                                        1s    kubernetes.io/kube-apiserver-client-kubelet   system:serviceaccount:openshift-machine-config-operator:node-bootstrapper         <none>              Pending
csr-lrphg                                        35m   kubernetes.io/kube-apiserver-client-kubelet   system:serviceaccount:openshift-machine-config-operator:node-bootstrapper         <none>              Approved,Issued
csr-pqbm8                                        25m   kubernetes.io/kube-apiserver-client           system:node:masteros02.oc41827.internal.local                                     24h                 Approved,Issued
csr-v8wtg                                        35m   kubernetes.io/kube-apiserver-client-kubelet   system:serviceaccount:openshift-machine-config-operator:node-bootstrapper         <none>              Approved,Issued
csr-xwtxx                                        26m   kubernetes.io/kube-apiserver-client           system:node:masteros02.oc41827.internal.local                                     24h                 Approved,Issued
...

Those pending CSR need to be approved. This is where many administrators get stuck. When nodes first join the cluster, they request certificates for communication with the API server. Until these are approved, nodes remain in NotReady state.

Approving Certificate Signing Requests (CSRs)

Manual Approval

Approve pending CSRs individually:

$ oc adm certificate approve csr-lldhf

Automated Batch Approval
For efficiency, especially when workers join, use this command to approve all pending CSRs at once:

$ oc get csr -o go-template='{{range .items}}{{if not .status}}{{.metadata.name}}{{"\n"}}{{end}}{{end}}' | xargs oc adm certificate approve

Keep reviewing the list of CSRs and keep approving until the deployment has finished.

Output confirming deployment success

$ openshift-install --dir=oc41827upi wait-for install-complete --log-level=debug
DEBUG OpenShift Installer 4.18.37                  
DEBUG Built from commit 488926dc2c95d96460ee9939929a76ed23e1c596 
...
INFO All cluster operators have completed progressing 
INFO Checking to see if there is a route at openshift-console/console... 
DEBUG Route found in openshift-console namespace: console 
DEBUG OpenShift console route is admitted          
INFO Install complete!                            
INFO To access the cluster as the system:admin user when using 'oc', run 
INFO     export KUBECONFIG=/home/labadmin/oc41827upi/auth/kubeconfig 
INFO Access the OpenShift web-console here: https://console-openshift-console.apps.oc41827.internal.local 
INFO Login to the console with user: "kubeadmin", and password: "ABcde-fghIKk-lmnpQ-RSTUv" 
DEBUG Time elapsed per stage:                      
DEBUG Cluster Operators Available: 2m23s           
INFO Time elapsed: 2m23s                          
$

⚠️ Security Warning: Save that kubeadmin password somewhere secure — you should only use it to create permanent admin users and for very specific tasks.

✅ Verifying Cluster Health

Once the installer reports completion, verify everything is working:

All Nodes Ready

$ oc get nodes

Expected output:

NAME                                      STATUS   ROLES                  AGE    VERSION
masteros01.oc41827.internal.local   Ready    control-plane,master   134m   v1.31.14
masteros02.oc41827.internal.local   Ready    control-plane,master   133m   v1.31.14
masteros03.oc41827.internal.local   Ready    control-plane,master   132m   v1.31.14
workeros01.oc41827.internal.local   Ready    worker                 96m    v1.31.14
workeros02.oc41827.internal.local   Ready    worker                 96m    v1.31.14
workeros03.oc41827.internal.local   Ready    worker                 96m    v1.31.14

No Degraded Operators

$ oc get clusteroperator

Every row should show True in the Available column, False in Progressing, and False in Degraded.

NAME                                       VERSION   AVAILABLE   PROGRESSING   DEGRADED   SINCE   MESSAGE
authentication                             4.18.37   True        False         False      28m     
baremetal                                  4.18.37   True        False         False      120m 
...
service-ca                                 4.18.37   True        False         False      121m    
storage                                    4.18.37   True        False         False      121m

Cluster seen as available

$ oc get clusterversion

NAME      VERSION   AVAILABLE   PROGRESSING   SINCE   STATUS
version   4.18.37   True        False         25m     Cluster version is 4.18.37

🧪 Testing Access: The Web Console

The web console is only accessible from within your lab's network unless you configure external routing. On my local workstation, I added entries to /etc/hosts:

192.168.110.22 console-openshift-console.apps.oc41827.internal.local
192.168.110.22 oauth-openshift.apps.oc41827.internal.local
192.168.110.21 api.oc41827.internal.local

Navigate to https://console-openshift-console.apps.oc41827.internal.local and log in with the kubeadmin credentials shown above.

🛡️ Remember: The kubeadmin account should be disabled or replaced ASAP. Create proper administrative users instead (we'll cover this in Part 4).

🏃 Stopping and Restarting the Cluster

⚠️ Critical: Always shut down workers before control plane nodes. Shutting down all etcd members simultaneously can cause quorum loss and data corruption.

Because this is a VM-based lab, I periodically shut down and restarted the cluster. Here's the correct order:

Shutdown Order

Worker nodes (in any order):

$ ssh -i .ssh/oc41827upi core@workeros03
The authenticity of host 'workeros03 (192.168.110.113)' can't be established.
...
---
[core@workeros03 ~]$ sudo shutdown -h now
[core@workeros03 ~]$ Connection to workeros03 closed by remote host.
Connection to workeros03 closed.
$

$ ssh -i .ssh/oc41827upi core@workeros02
...
---
[core@workeros02 ~]$ sudo shutdown -h now
[core@workeros02 ~]$ Connection to workeros02 closed by remote host.
Connection to workeros02 closed.
$

$ ssh -i .ssh/oc41827upi core@workeros01
...
---
[core@workeros01 ~]$ sudo shutdown -h now
[core@workeros01 ~]$ Connection to workeros01 closed by remote host.
Connection to workeros01 closed.
$

Control plane nodes (in any order):

$ ssh -i .ssh/oc41827upi core@masteros03
...
---
[core@masteros03 ~]$ sudo shutdown -h now
[core@masteros03 ~]$ Connection to masteros03 closed by remote host.
Connection to masteros03 closed.
$

$ ssh -i .ssh/oc41827upi core@masteros02
...
---
[core@masteros02 ~]$ sudo shutdown -h now
[core@masteros02 ~]$ Connection to masteros02 closed by remote host.
Connection to masteros02 closed.
$

$ ssh -i .ssh/oc41827upi core@masteros01
...
---
[core@masteros01 ~]$ sudo shutdown -h now
[core@masteros01 ~]$ Connection to masteros01 closed by remote host.
Connection to masteros01 closed.
$

Startup Order

Control plane nodes (wait for them to stabilize)
Worker nodes (wait for CSR approvals)

After restarting, you might see pending CSRs. Approve them using the batch command from earlier, and nodes will return to Ready status within 5-10 minutes.

📋 Summary: Deployment Checklist

✅ Pull secret downloaded
✅ Ignition files regenerated and served
✅ VMs PXE booted from iPXE menu
✅ Deployment started
✅ Bootstrap monitored via journalctl
✅ Bootstrap removed from HAProxy
✅ CSRs approved
✅ Deployment finished
✅ Cluster operators verified stable

🔜 Coming Up in Part 4

Now that the cluster is running, we need to make it usable:

Creating HTPasswd users (admin and developer accounts)
Assigning roles (cluster-admin vs project-specific permissions)
Testing logins with new credentials
Disabling the kubeadmin account (security best practice)

The cluster is alive—but until we configure proper authentication, you're still flying blind with the emergency kubeadmin account. Stay tuned!

Did your deployment run smoothly, or did you hit certificate expiration issues too? Share your experiences in the comments below! 👇

Building an OpenShift 4.18 Cluster from Scratch: Part 2 – Generating Ignition Configs & VM Prep

Ana Villar — Thu, 16 Jul 2026 19:54:28 +0000

Note: This is Part 2 of a multi-part series.

✅ Part 1: The Network Foundation & Utilities Server

Part 3: The Deployment Lifecycle & Troubleshooting (Coming Soon)

Part 4: Post-Install Hardening & User Management (Coming Soon)

In Part 1, we built the Utilities Server—DNS, DHCP, TFTP, HTTP, and HAProxy. Now it's time to prepare the actual OpenShift deployment artifacts.

This part is all about Ignition: what it is, how to generate it, and how to feed it to our VMs so they can boot into Red Hat CoreOS and join the cluster automatically.

We'll also cover a critical—and poorly documented—step: disabling Secure Boot on libvirt VMs to allow iPXE chainloading. Without this, your nodes will simply refuse to boot.

Note that all the tasks mentioned in this blog are performed in the utilities server.

Let's get into it.

1. Download OpenShift RHCOS images

To deploy OpenShift, we need to download the Red Hat CoreOS (formerly Red Hat Enterprise Linux CoreOS) images. It's the immutable, container-optimized operating system that OpenShift uses on all cluster nodes—bootstrap, masters, and workers alike.

RHCOS images (kernel, initramfs, rootfs) are the three core artifacts needed to network-boot RHCOS: the kernel is the Linux kernel that initializes the hardware, the initramfs is a minimal in-memory filesystem that loads early in the boot process and handles loading drivers and fetching the rootfs, and the rootfs is the full RHCOS filesystem that gets loaded into RAM and serves as the base operating system before Ignition takes over.

Those files can be found in this OpenShift mirror site.

At the time I deployed the cluster, I checked what was the latest available 4.18 version, which happened to be 4.18.27. That is the reason you are going to see some folders called "oc41827". But you can name them as you prefer, but ensure you review the commands and configuration files accordantly.

First, let's create the folders to hold those files.

$ sudo mkdir -p /var/www/html/oc41827/{ignition,rhcos}

Define some variables to ease the download process.

$ ocp_maj=4.18;rhcos_ver=4.18.27
$ mirror=https://mirror.openshift.com/pub/openshift-v4
$ baseurl=${mirror}/dependencies/rhcos/${ocp_maj}/${rhcos_ver}
$ cd /var/www/html/oc1827/rhcos/

And download the files

$ sudo wget ${baseurl}/rhcos-${rhcos_ver}-x86_64-live-rootfs.x86_64.img
$ sudo wget ${baseurl}/rhcos-${rhcos_ver}-x86_64-live-kernel-x86_64
$ sudo wget ${baseurl}/rhcos-${rhcos_ver}-x86_64-live-initramfs.x86_64.img

Note that on version 4.20, the kernel file name is rhcos-4.20.0-x86_64-live-kernel.x86_64, while on 4.18 is rhcos-4.18.27-x86_64-live-kernel-x86_64. Note the difference between .x86 and -x86.

2. Downloading the OpenShift Tools

We need the tools to generate the cluster configuration, which are the OpenShift Installer & OpenShift Client.

They can be found in the OpenShift mirror site. At the time I was deploying this cluster, the latest 4.18 version available was 4.18.37.

Let's download them.

$ sudo su
# mirror="https://mirror.openshift.com/pub/openshift-v4/clients"
# wget ${mirror}/ocp/4.18.37/openshift-client-linux-4.18.37.tar.gz
# wget ${mirror}/ocp/4.18.37/openshift-install-linux-4.18.37.tar.gz

Extract both, move binaries to /usr/bin/ and ensure we have some helping aliases

# tar -xvf openshift-client-linux-4.18.37.tar.gz -C /usr/bin/
# tar -xvf openshift-install-linux-4.18.37.tar.gz -C /usr/bin/
# oc completion bash > /etc/bash_completion.d/openshift
# openshift-install completion bash > /etc/bash_completion.d/openshift-install
# exit
$ source /etc/bash_completion.d/openshift
$ source /etc/bash_completion.d/openshift-install

And now you can test them. You should see something similar to the following lines

$ oc version
Client Version: 4.18.37
Kustomize Version: v5.4.2
$ openshift-install version
openshift-install 4.18.37
built from commit 488926dc2c95d96460ee9939929a76ed23e1c596
release image quay.io/openshift-release-dev/ocp-release@sha256:9b7068aa6f6087c2f0a7cefa241c5dbb0ede0efaad783607dff0da98cac432d2
release architecture amd64
$

3. Generating installation configuration file

In order to deploy the OpenShift nodes, we need to generate the Ignition files. Those are JSON-based configuration specifications that tell RHCOS exactly how to configure itself on first boot—partitioning disks, writing network configs, embedding the pull secret, and registering the node with the OpenShift cluster. Think of them as the "first-run setup script" that transforms a blank RHCOS machine into a functioning OpenShift node.

To generate those files, we can runs the OpenShift installer, which asks for the necessary cluster information and then creates the installation configuration file install-config.yaml accordingly.

Instead, I have a install-config.yaml template I used to create the Kubernetes manifests and the ignition configuration files for the bootstrap node bootstrap.ign, control plane nodes master.ign, and compute nodes worker.ign.

install-config.yaml

Note the importance of the correct contents of this file, as it defines the OpenShift cluster.

apiVersion: v1
baseDomain: internal.local
compute:
- hyperthreading: Enabled
  name: worker
  replicas: 3
controlPlane:
  hyperthreading: Enabled
  name: master
  replicas: 3
metadata:
  name: oc41827
networking:
  clusterNetwork:
  - cidr: 10.128.0.0/14
    hostPrefix: 23
  networkType: OVNKubernetes
  serviceNetwork:
  - 172.30.0.0/16
platform:
  none: {}
fips: false
pullSecret: 'CHANGEME'
sshKey: 'CHANGEMETOO'

What It Defines	Why It Matters
Cluster Identity (metadata.name, baseDomain)	Determines all DNS names (api.., .apps..)*
Networking (clusterNetwork, serviceNetwork)	Ensures pods, services, and node IPs don't conflict with each other or existing infrastructure
Topology (node replicas, control plane size)	Sets the minimum resources needed for high availability (3 masters, at least 1 worker)
Authentication (pullSecret, sshKey)	Allows nodes to pull container images from Red Hat registries and enables emergency SSH access
Platform (platform: none: {})	Tells the installer we're doing bare metal/external provisioning, not cloud integration

As you can see, there are two pieces of information are essential before we can use install-config.yaml that we need to change.

Pull Secret

Log into the OpenShift console using this link, or navigate to Red Hat OpenShift, under Get started with OpenShift select Create Cluster, Select Datacenter, then Bare Metal (x86_64), and next select Full Control.

Under Pull secret, press Download the pull secret. This file authenticates your cluster with Red Hat's registries.

Save it and convert it into a one-liner json file. Create a working directory from where the OpenShift deployment will be run, for example:

$ mkdir oc41827upi

and then

$ python3 -m json.tool pull-secret > pull-secret.json
$ cat pull-secret.json | jq . -c > ~/oc41827upi/pull-secret-online.json

SSH key

You'll need an SSH key pair to access the nodes from the utilities server.

$ ssh-keygen -t rsa -b 4096 -N '' -f .ssh/oc41827upi

Make note of the public key path—we'll reference it in the install config.

Update install-config.yaml

Now it is time to get all the information together:

cat <<EOF > ~/oc41827upi/install-config.yaml
apiVersion: v1
baseDomain: internal.local
compute:
- hyperthreading: Enabled
  name: worker
  replicas: 3
controlPlane:
  hyperthreading: Enabled
  name: master
  replicas: 3
metadata:
  name: oc41827
networking:
  clusterNetwork:
  - cidr: 10.128.0.0/14
    hostPrefix: 23
  networkType: OVNKubernetes
  serviceNetwork:
  - 172.30.0.0/16
platform:
  none: {}
fips: false
pullSecret: '$(cat ~/oc41827upi/pull-secret.json)'
sshKey: '$(cat ~/.ssh/oc41827upi.pub)'
EOF

⚠️ Important: The metadata.name (oc41827) becomes part of your cluster's FQDN. Make sure this matches the DNS records we created in Part 1 (api.oc41827.internal.local).

🔒 Sensitive Data: The pullSecret and sshKey fields are populated at generation time. Once you run openshift-install create manifests, these values are embedded in the Ignition files. Do not commit install-config.yaml to a public repository without redacting these fields.

Key Fields Explained

Field	Value	Why
baseDomain	internal.local	Matches the DNS zone from Part 1
metadata.name	oc41827	Cluster identifier, part of the FQDN
platform	none: {}	Platform-agnostic (bare metal / VM)
networkType	OVNKubernetes	Default SDN for 4.18
replicas (master)	3	Minimum for HA control plane
replicas (worker)	3	Adjust as needed for your lab, minimum 1

4. Generating Manifests & Ignition Files

Now we transform the blueprint into machine-readable configuration. This is a one-way operation: once you generate manifests, you can make targeted edits, but after Ignition files are created, the config is frozen.

Step 1: Create Manifests

$ cd ~/oc41827upi
$ openshift-install create manifests --dir=.

This creates two directories:

manifests/ — YAML definitions for cluster resources
openshift/ — Internal OpenShift configuration files

💡 Optional: At this stage, you can modify files in manifests/ to customize the cluster before Ignition generation. Common modifications include adjusting default node settings or removing the infrastructure components you don't need. For this lab, we'll proceed with defaults.

Step 2: Generate Ignition Files

$ openshift-install create ignition-configs --dir=.

This produces three critical files:

File	Target
bootstrap.ign	The temporary bootstrap node
master.ign	Each control plane node
worker.ign	Each compute node

These Ignition files contain the complete initial configuration for each node type: disk partitioning, systemd units, network settings, and the embedded pull secret. They are the single source of truth that tells RHCOS how to become an OpenShift node.

5. Serving Ignition Files via Apache

Copy the Ignition files to the web server

sudo cp ~/oc41827upi/bootstrap.ign /var/www/html/oc41827/ignition/
sudo cp ~/oc41827upi/master.ign /var/www/html/oc41827/ignition/
sudo cp ~/oc41827upi/worker.ign /var/www/html/oc41827/ignition/

Set permissions

$ sudo chmod +r /var/www/html/oc41827/ignition/*

Verify they are accessible:

$ curl -I http://192.168.110.20/oc41827/ignition/bootstrap.ign

Expected: HTTP/1.1 200 OK

6. Creating the boot.ipxe Menu

Now we create the iPXE boot script to include OpenShift entries. Each node type points to the same kernel and rootfs but fetches a different Ignition file via the coreos.inst.ignition_url kernel argument.

Here's the structure for the menu entries in your boot.ipxe (/var/www/html/boot.ipxe):

#!ipxe
dhcp

set base http://192.168.110.20/
set oc41827 http://192.168.110.20/oc41827/

:bootstrap
kernel ${oc41827}rhcos/rhcos-4.18.27-x86_64-live-kernel-x86_64 initrd=main coreos.live.rootfs_url=${oc41827}rhcos/rhcos-4.18.27-x86_64-live-rootfs.x86_64.img coreos.inst.install_dev=/dev/vda coreos.inst.ignition_url=${oc41827}ignition/bootstrap.ign
initrd --name main ${oc41827}rhcos/rhcos-4.18.27-x86_64-live-initramfs.x86_64.img
boot

:master
kernel ${oc41827}rhcos/rhcos-4.18.27-x86_64-live-kernel-x86_64 initrd=main coreos.live.rootfs_url=${oc41827}rhcos/rhcos-4.18.27-x86_64-live-rootfs.x86_64.img coreos.inst.install_dev=/dev/vda coreos.inst.ignition_url=${oc41827}ignition/master.ign
initrd --name main ${oc41827}rhcos/rhcos-4.18.27-x86_64-live-initramfs.x86_64.img
boot

:worker
kernel ${oc41827}rhcos/rhcos-4.18.27-x86_64-live-kernel-x86_64 initrd=main coreos.live.rootfs_url=${oc41827}rhcos/rhcos-4.18.27-x86_64-live-rootfs.x86_64.img coreos.inst.install_dev=/dev/vda coreos.inst.ignition_url=${oc41827}ignition/worker.ign
initrd --name main ${oc41827}rhcos/rhcos-4.18.27-x86_64-live-initramfs.x86_64.img
boot

⚠️ Disk Device Name: coreos.inst.install_dev=vda assumes your VMs use virtio disks. If your VMs use SATA or SCSI, change this to sda accordingly.

7. Testing the environment

Before we continue, I would recommend to create a test virtual machine and to check if it can be installed using iPXE. This step can be bypassed, but it can give us the confidence that all is ready for the OpenShift deployment.

I am adding here two examples, RHEL and Ubuntu

RHEL 10

Previously, I copied the RHEL 10 iso image in the utilities server in a folder called /isos. Let's mount it.

$ ls /isos
rhel-10.1-x86_64-dvd.iso
$ sudo mkdir -v /mnt/dvd
mkdir: created directory '/mnt/dvd'
$ sudo mount -v /isos/rhel-10.1-x86_64-dvd.iso /mnt/dvd
mount: /mnt/dvd: WARNING: source write-protected, mounted read-only.
mount: /dev/loop0 mounted on /mnt/dvd.
$

Let´s copy now the contents of the iso image to our Apache server folder.

$ sudo mkdir /var/www/html/rhel10
$ sudo cp -R /mnt/dvd/* /var/www/html/rhel10/
$ sudo restorecon -Rv /var/www/html
$

Ubuntu 24.04 and 26.04

Similarly as with RHEL, I copied the isos to the server in the /isos folder.

Place their contents into the web server:

$ sudo mkdir -p /var/www/html/ubuntuserver/24.04
$ sudo mkdir -p /var/www/html/ubuntuserver/26.04
$ sudo mount -o loop /isos/ubuntu-24.04.4-live-server-amd64.iso /mnt/dvd
mount: /mnt/dvd: WARNING: source write-protected, mounted read-only.
$ sudo cp -a /mnt/dvd/. /var/www/html/ubuntuserver/24.04/
$ sudo umount /mnt/dvd
$ sudo mount -o loop /isos/ubuntu-26.04-live-server-amd64.iso /mnt/dvd
mount: /mnt/dvd: WARNING: source write-protected, mounted read-only.
$ sudo cp -a /mnt/dvd/. /var/www/html/ubuntuserver/26.04/
$ sudo umount /mnt/dvd

Correct SELinux:

$ sudo restorecon -Rv /var/www/html

Update the iPXE boot file

This is the full contents of the ipxe boot file.

/var/www/html/boot.ipxe

#!ipxe
dhcp

set base http://192.168.110.20/
set rhel10 http://192.168.110.20/rhel10/
set ubuntuserver2404 http://192.168.110.20/ubuntuserver/24.04/
set ubuntuserver2604 http://192.168.110.20/ubuntuserver/26.04/
set oc41827 http://192.168.110.20/oc41827/

menu iPXE menu
item redhat    Install RHEL 10 interactively
item ubuntuserver2404  Install Ubuntu Server 24.04.4 LTS interactively
item ubuntuserver2604  Install Ubuntu Server 26.04 LTS interactively
item bootstrap  Install OpenShift 4.18.27 Bootstrap
item master  Install OpenShift 4.18.27 Master Node
item worker  Install OpenShift 4.18.27 Worker Node
item shell      Drop to iPXE shell
choose --default shell --timeout 1500000 target && goto ${target}

:redhat
kernel ${rhel10}images/pxeboot/vmlinuz ip=dhcp inst.repo=${rhel10} inst.stage2=${rhel10} quiet
initrd ${rhel10}images/pxeboot/initrd.img
boot

:ubuntuserver2404
kernel ${ubuntuserver2404}casper/vmlinuz ip=dhcp url=${ubuntuserver2404}
initrd ${ubuntuserver2404}casper/initrd
boot

:ubuntuserver2604
kernel ${ubuntuserver2604}casper/vmlinuz ip=dhcp url=${ubuntuserver2604}
initrd ${ubuntuserver2604}casper/initrd
boot

:bootstrap
kernel ${oc41827}rhcos/rhcos-4.18.27-x86_64-live-kernel-x86_64 initrd=main coreos.live.rootfs_url=${oc41827}rhcos/rhcos-4.18.27-x86_64-live-rootfs.x86_64.img coreos.inst.install_dev=/dev/vda coreos.inst.ignition_url=${oc41827}ignition/bootstrap.ign
initrd --name main ${oc41827}rhcos/rhcos-4.18.27-x86_64-live-initramfs.x86_64.img
boot

:master
kernel ${oc41827}rhcos/rhcos-4.18.27-x86_64-live-kernel-x86_64 initrd=main coreos.live.rootfs_url=${oc41827}rhcos/rhcos-4.18.27-x86_64-live-rootfs.x86_64.img coreos.inst.install_dev=/dev/vda coreos.inst.ignition_url=${oc41827}ignition/master.ign
initrd --name main ${oc41827}rhcos/rhcos-4.18.27-x86_64-live-initramfs.x86_64.img
boot

:worker
kernel ${oc41827}rhcos/rhcos-4.18.27-x86_64-live-kernel-x86_64 initrd=main coreos.live.rootfs_url=${oc41827}rhcos/rhcos-4.18.27-x86_64-live-rootfs.x86_64.img coreos.inst.install_dev=/dev/vda coreos.inst.ignition_url=${oc41827}ignition/worker.ign
initrd --name main ${oc41827}rhcos/rhcos-4.18.27-x86_64-live-initramfs.x86_64.img
boot

:shell
shell

8. Disabling Secure Boot on VMs

This is the step that cost me several hours of debugging. If your libvirt VMs have Secure Boot enabled, iPXE will fail to chainload. The UEFI firmware rejects the unsigned iPXE binary, and your VMs won't boot.

Those steps are to be done in your hypervisor, where all the virtual machines are being hosted (the utilities server, your test virtual machine to boot from ipxe, the OpenShift nodes).

If you are using a different hypervisor, check their documentation to disable Secure Boot. Here I am explaining how I managed to do it for RHEL virtualization.

Dump the VM definition as XML

Replace test by the name of your virtual machine.

$ sudo virsh dumpxml test > test.xml

Edit the VM definition

Using your preferred editor (for example vim or nano), edit the file test.xml.

Find the section and change:

  <vcpu placement='static'>2</vcpu>
  <os firmware='efi'>
    <type arch='x86_64' machine='pc-q35-rhel10.0.0'>hvm</type>
    <firmware>
      <feature enabled='yes' name='enrolled-keys'/>
      <feature enabled='yes' name='secure-boot'/>
    </firmware>
    <loader readonly='yes' secure='yes' type='pflash' format='raw'>/usr/share/edk2/ovmf/OVMF_CODE.secboot.fd</loader>
    <nvram template='/usr/share/edk2/ovmf/OVMF_VARS.secboot.fd' templateFormat='raw' format='raw'>/var/lib/libvirt/qemu/nvram/test_VARS.fd</nvram>
  </os>
  <features>
    <acpi/>
    <apic/>
    <smm state='on'/>
  </features>

to:

  <vcpu placement='static'>2</vcpu>
  <os>
    <type arch='x86_64' machine='pc-q35-rhel10.0.0'>hvm</type>
    <loader readonly='yes' type='pflash' format='raw'>/usr/share/edk2/ovmf/OVMF_CODE.fd</loader>
    <nvram template='/usr/share/edk2/ovmf/OVMF_VARS.fd' templateFormat='raw' format='raw'>/var/lib/libvirt/qemu/nvram/test_VARS.fd</nvram>
  </os>
  <features>
    <acpi/>
    <apic/>
    <smm state='off'/>
  </features>

🔑 Key Changes:

Replace <os firmware='efi'> by <os>
Remove the full section starting with <firmware> to </firmware>
At the line starting with <loader, remove secure='yes' and replace OVMF_CODE.secboot.fd by OVMF_CODE.fd
At the line starting with <nvram, replace OVMF_VARS.secboot.fd by OVMF_VARS.fd
And replace the line <smm state='on'/> by <smm state='off'/>

Update the VM definition

Update the configuration of the virtual machine in your host:

$ sudo virsh define test.xml

9. Verification

After disabling Secure Boot on the VM, power on the VM and connect to its console:

$ sudo virsh start test --console

or using your Cockpit interface.

You should now see the iPXE menu appear. If it loads the boot.ipxe script correctly, and you can install the OS into your test VM, you're ready for deployment.

Part 2 Recap

Let's review what we accomplished:

✅ Downloaded OpenShift installer and CLI tools
✅ Secured the pull secret and SSH key
✅ Wrote install-config.yaml matching our DNS/DHCP from Part 1
✅ Generated manifests and Ignition files
✅ Published Ignition files and RHCOS images via Apache
✅ Updated boot.ipxe with OpenShift boot entries
✅ Disabled Secure Boot on all VMs to enable iPXE chainloading

Everything is staged. The Ignition files are on the web server, the iPXE menu is updated, and the VMs can boot.

🔜 Coming Up in Part 3: The Deployment Lifecycle

Powering on the bootstrap node and monitoring logs
Waiting for bootstrap-complete and removing the bootstrap node
Approving CSRs for master and worker nodes
Verifying cluster health with oc commands

Stay tuned!

Building an OpenShift 4.18 Cluster from Scratch: Part 1 – The Network Foundation & Utilities Server

Ana Villar — Tue, 30 Jun 2026 19:21:50 +0000

Note: This is Part 1 of a multi-part series.

[Part 2: Generating Ignition Configs & VM Prep] (Coming Soon)

[Part 3: The Deployment Lifecycle & Troubleshooting] (Coming Soon)

[Part 4: Post-Install Hardening & User Management] (Coming Soon)

In this series, I walk through a full OpenShift Container Platform 4.18 deployment from scratch. While most tutorials target cloud providers or pre-provisioned infrastructure, this guide replicates a true platform-agnostic (bare metal) installation—executed within a lab of Virtual Machines hosted on RHEL 10.

This approach allows us to master the critical underlying infrastructure—DNS, DHCP, PXE booting, and load balancing—without the cost of physical hardware. By the end of Part 1, you will have a fully functional Utilities Server that acts as the command center for the entire cluster, handling:

DNS: Internal resolution for all cluster nodes.
DHCP: IP allocation and iPXE boot redirection via Kea.
TFTP & HTTP: Serving bootloader images, RHCOS ISOs, and Ignition configs.
HAProxy: Load balancing for the Kubernetes API and Ingress traffic.

We won't run openshift-install just yet; first, we must build the foundation upon which the cluster relies.

📚 References & Background

This lab strictly follows the Platform-Agnostic installation methodology defined by Red Hat. The setup was heavily inspired by the DO322: Red Hat OpenShift Installation Lab training course, ensuring we cover the same critical edge cases and network requirements found in production environments.

Why use VMs for a "Bare Metal" guide? While running on virtual machines provides speed and portability for this lab, the network stack (DNS/DHCP/PXE) and the Ignition configuration flow are identical to what you would encounter on physical hardware. Following the DO322 methodology ensures this tutorial remains relevant for real-world bare-metal deployments.

Let's get the foundation laid.

🛠 Lab Environment Overview

Before diving in, here is the topology I'm working with. All these VMs are hosted on a RHEL 10 hypervisor.

Role	VM Name	IP Address	Specs
Utilities Server	utilities	192.168.110.20	4 vCPU, 8GB RAM, 250GB Disk
Bootstrap Node	bootstos	192.168.110.100	4 vCPU, 16GB RAM, 100GB NVMe
Control Plane	masteros01-03	.101 to .103	4 vCPU, 24GB RAM, 100GB NVMe
Compute Nodes	workeros01-03	.111 to .113	2 vCPU, 8GB RAM, 100GB SSD

1. Setting Up the Utilities Server

We start with a fresh RHEL 10 installation. Once installed, we register the system and ensure all packages are up to date.

$ sudo subscription-manager register --username <YOUR_USER> --password <PASSWORD>
$ sudo dnf update redhat-release
$ sudo dnf upgrade -y
$ sudo reboot

After reboot, we verify connectivity and prepare for the services.

Network Configuration

The utilities server has two interfaces. I configured them via nmtui to assign static IPs:

enp1s0: 192.168.1.20 (Management/Internet Gateway)
enp7s0: 192.168.110.20 (Internal Cluster Network)

and then, add two extra IP addresses to interface enp7s0, 192.168.110.21 and 192.168.110.22, to be used by OpenShift services.

$ nmcli
enp1s0: connected to enp1s0
        "Red Hat Virtio 1.0"
        ethernet (virtio_net), 52:54:00:C5:C1:9E, hw, mtu 1500
        ip4 default
        inet4 192.168.1.20/24
        route4 default via 192.168.1.1 metric 100
        route4 192.168.1.0/24 metric 100
        inet6 fe80::5054:ff:fec5:c19e/64
        route6 fe80::/64 metric 1024

enp7s0: connected to enp7s0
        "Red Hat Virtio 1.0"
        ethernet (virtio_net), 52:54:00:E6:D1:A4, hw, mtu 1500
        inet4 192.168.110.22/24
        inet4 192.168.110.21/24
        inet4 192.168.110.20/24
        route4 192.168.110.0/24 metric 101
        route4 192.168.110.0/24 metric 101
        route4 192.168.110.0/24 metric 101
        inet6 fe80::5054:ff:fee6:d1a4/64
        route6 fe80::/64 metric 1024
...

2. Installing & Configuring DNS (BIND)

OpenShift relies heavily on proper DNS. We need records for the API VIPs, ingress VIP, and every node.

Installation

$ sudo dnf install bind bind-utils -y

Configuration

I modified the default config (/etc/named.conf) to listen on both interfaces and allow recursion only for our internal subnets. Crucially, we define our zones here.

# /etc/named.conf snippet
options {
    listen-on port 53 { 127.0.0.1; 192.168.1.20; 192.168.110.20; };
    allow-query { localhost; 192.168.1.0/24; 192.168.110.0/24; };
    allow-recursion { localhost; 192.168.1.0/24; 192.168.110.0/24; };
    forwarders { 8.8.8.8; 8.8.4.4; }; # Or your ISP DNS
    recursion yes;
};

zone "internal.local" {
    type master;
    file "internal.local.zone";
    allow-query { any; };
};

zone "110.168.192.in-addr.arpa" {
    type master;
    file "110.168.192.in-addr.arpa.zone";
    allow-query { any; };
};

Zone Files

We create the forward and reverse lookup zones. Notice the VIPs for the API (192.168.110.21) and Ingress (192.168.110.22). These point to our HAProxy server (which runs on the utilities node).

/var/named/internal.local.zone:

$TTL 8h
@ IN SOA ns1.internal.local. hostmaster.internal.local. (
    2026042601 ; serial
    1d         ; refresh
    3h         ; retry
    3d         ; expire
    3h )       ; minimum

IN NS ns1.internal.local.

ntp               IN A    192.168.110.20
dns               IN A    192.168.110.20

; Static infrastructure
;hostname IN A 192.168.110.x
utilities.internal.local.  IN A    192.168.110.20

; OpenShift VIPs
api.oc41827.internal.local.       IN A    192.168.110.21
api-int.oc41827.internal.local.   IN A    192.168.110.21
*.apps.oc41827.internal.local.    IN A    192.168.110.22

; Bootstrap Node
bootstos.oc41827.internal.local.     IN A 192.168.110.100

; Master Nodes
masteros01.oc41827.internal.local. IN A 192.168.110.101
masteros02.oc41827.internal.local. IN A 192.168.110.102
masteros03.oc41827.internal.local. IN A 192.168.110.103

; Worker Nodes
workeros01.oc41827.internal.local. IN A 192.168.110.111
workeros02.oc41827.internal.local. IN A 192.168.110.112
workeros03.oc41827.internal.local. IN A 192.168.110.113

/var/named/110.168.192.in-addr.arpa.zone:

$TTL 8h
@ IN SOA ns1.internal.local. hostmaster.internal.local. (
          2026041901 ; serial number
          1d         ; refresh period
          3h         ; retry period
          3d         ; expire time
          3h )       ; minimum TTL

 IN NS   ns1.internal.local.

20                IN PTR  ns1.internal.local.
20                IN PTR  utilities.internal.local.

21    IN PTR api.oc41827.internal.local.
21    IN PTR api-int.oc41827.internal.local.

100  IN PTR bootstos.oc41827.internal.local.
101  IN PTR masteros01.oc41827.internal.local.
102  IN PTR masteros02.oc41827.internal.local.
103  IN PTR masteros03.oc41827.internal.local.

111  IN PTR workeros01.oc41827.internal.local.
112  IN PTR workeros02.oc41827.internal.local.
113  IN PTR workeros03.oc41827.internal.local.

Edit: oc41827 is the metadata name I will provide to the OpenShift cluster, and it becomes part of the FQDN of those nodes.

Check configuration and start the service

Change ownership and permissions, and check the configuration:

$ sudo named-checkconf
$ sudo chown root:named /var/named/internal.local.zone
$ sudo chown root:named /var/named/110.168.192.in-addr.arpa.zone
$ sudo chmod 640 /var/named/internal.local.zone
$ sudo chmod 640 /var/named/110.168.192.in-addr.arpa.zone
$ sudo named-checkzone internal.local /var/named/internal.local.zone
zone internal.local/IN: loaded serial 2026041901
OK
$ sudo named-checkzone 110.168.192.in-addr.arpa /var/named/110.168.192.in-addr.arpa.zone
zone 110.168.192.in-addr.arpa/IN: loaded serial 2026041901
OK
$

Enable and start the service

$ sudo systemctl enable --now named

and allow the service through the firewall.

$ sudo firewall-cmd --permanent --add-service=dns
$ sudo firewall-cmd --reload

3. Time Synchronization (Chrony)

Kubernetes clusters are extremely sensitive to time skew. If the clocks drift, certificates and authentication will fail immediately.

We install chrony (it's already present in RHEL, but we configure it):

# /etc/chrony.conf snippet
pool 2.rhel.pool.ntp.org iburst
allow 192.168.1.0/24
allow 192.168.110.0/24
local stratum 10

This allows the utility server to act as a local NTP source for all nodes while syncing itself with external sources.

Enable and start the service

$ sudo systemctl enable --now chronyd
Created symlink '/etc/systemd/system/multi-user.target.wants/chronyd.service' → '/usr/lib/systemd/system/chronyd.service'.
$

and allow the service through the firewall.

$ sudo firewall-cmd --add-service=ntp --permanent
$ sudo firewall-cmd --reload

4. DHCP with Kea

Instead of the legacy ISC DHCP server, I used Kea, which is the recommended choice for RHEL 10.

Installation & Config

sudo dnf install kea -y

The configuration /etc/kea/kea-dhcp4.conf is where the magic happens for PXE booting. We define client classes to distinguish between iPXE clients and standard UEFI/BIOS PXE clients.

{
  "Dhcp4": {
    "interfaces-config": {
      "interfaces": [ "enp7s0/192.168.110.20" ]
    },

    "client-classes": [
        { 
            "name": "iPXE Clients", 
            "test": "option[175].exists", 
            "option-data": [
               { "name": "tftp-server-name", "data": "192.168.110.20" },
               { "name": "boot-file-name", "data": "http://192.168.110.20/boot.ipxe" }
            ]
        },
        {
            "name": "UEFI PXE Clients",
            "test": "option[93].hex == 0x0007 and not option[175].exists",
            "next-server": "192.168.110.20",
            "boot-file-name": "ipxe-snponly-x86_64.efi"
        },
        {
            "name": "BIOS PXE Clients",
            "test": "option[93].hex == 0x0000 and not option[175].exists",
            "next-server": "192.168.110.20",
            "boot-file-name": "undionly.kpxe"
        }
    ],

    "subnet4": [
      {
        "id": 1,
        "subnet": "192.168.110.0/24",
        "pools": [
          {
            "pool": "192.168.110.200 - 192.168.110.250"
          }
        ],

        "reservations": [
          { "hw-address": "AA:BB:CC:DD:EE:01", "ip-address": "192.168.110.100", "hostname": "bootstos.oc41827.internal.local" },

          { "hw-address": "AA:BB:CC:DD:EE:02", "ip-address": "192.168.110.101", "hostname": "masteros01.oc41827.internal.local" },
          { "hw-address": "AA:BB:CC:DD:EE:03", "ip-address": "192.168.110.102", "hostname": "masteros02.oc41827.internal.local" },
          { "hw-address": "AA:BB:CC:DD:EE:04", "ip-address": "192.168.110.103", "hostname": "masteros03.oc41827.internal.local" },

          { "hw-address": "AA:BB:CC:DD:EE:05", "ip-address": "192.168.110.111", "hostname": "workeros01.oc41827.internal.local" },
          { "hw-address": "AA:BB:CC:DD:EE:06", "ip-address": "192.168.110.112", "hostname": "workeros02.oc41827.internal.local" },
          { "hw-address": "AA:BB:CC:DD:EE:07", "ip-address": "192.168.110.113", "hostname": "workeros03.oc41827.internal.local" }
        ],

        "option-data": [
          { "name": "routers", "code": 3, "data": "192.168.110.1" },
          { "name": "domain-name-servers", "code": 6, "space": "dhcp4", "data": "192.168.110.20" },
          { "name": "domain-name", "data": "internal.local" },
          { "name": "domain-search", "data": "oc41827.internal.local internal.local" }
        ]

      },
    ]
  }
}

Note: Ensure you replace the MAC addresses with the actual ones assigned to your VMs.

Check the configuration and enable Kea

$ sudo kea-dhcp4 -t /etc/kea/kea-dhcp4.conf

You might see some warnings, you might ignore them (but do not ignore any error), see this as an example:

$ sudo kea-dhcp4 -t /etc/kea/kea-dhcp4.conf
2026-04-21 20:52:38.159 WARN  [kea-dhcp4.dhcpsrv/6313.140336065439872] DHCPSRV_MT_DISABLED_QUEUE_CONTROL disabling dhcp queue control when multi-threading is enabled.
2026-04-21 20:52:38.159 WARN  [kea-dhcp4.dhcp4/6313.140336065439872] DHCP4_RESERVATIONS_LOOKUP_FIRST_ENABLED Multi-threading is enabled and host reservations lookup is always performed first.
2026-04-21 20:52:38.160 INFO  [kea-dhcp4.dhcpsrv/6313.140336065439872] DHCPSRV_CFGMGR_NEW_SUBNET4 a new subnet has been added to configuration: 192.168.110.0/24 with params: valid-lifetime=7200
2026-04-21 20:52:38.160 INFO  [kea-dhcp4.dhcpsrv/6313.140336065439872] DHCPSRV_CFGMGR_SOCKET_TYPE_SELECT using socket type raw
2026-04-21 20:52:38.160 INFO  [kea-dhcp4.dhcpsrv/6313.140336065439872] DHCPSRV_CFGMGR_USE_ADDRESS listening on address 192.168.110.20, on interface enp7s0
2026-04-21 20:52:38.160 INFO  [kea-dhcp4.dhcpsrv/6313.140336065439872] DHCPSRV_CFGMGR_SOCKET_TYPE_DEFAULT "dhcp-socket-type" not specified , using default socket type raw
2026-04-21 20:52:38.160 INFO  [kea-dhcp4.dhcpsrv/6313.140336065439872] DHCPSRV_LEASE_MGR_BACKENDS_REGISTERED the following lease backend types are available: memfile
2026-04-21 20:52:38.160 INFO  [kea-dhcp4.hosts/6313.140336065439872] HOSTS_BACKENDS_REGISTERED the following host backend types are available: 
2026-04-21 20:52:38.160 INFO  [kea-dhcp4.dhcpsrv/6313.140336065439872] DHCPSRV_FORENSIC_BACKENDS_REGISTERED the following forensic backend types are available: 
2026-04-21 20:52:38.160 INFO  [kea-dhcp4.database/6313.140336065439872] CONFIG_BACKENDS_REGISTERED the following config backend types are available: 
$

Enable and start the service:

$ sudo systemctl enable --now kea-dhcp4

and allow the service through the firewall.

$ sudo firewall-cmd --add-service=dhcp --permanent
$ sudo firewall-cmd --reload

5. Web Services & iPXE Boot

OpenShift uses a live-boot mechanism. We need an HTTP server to serve the RHCOS kernel, rootfs, and ignition files, plus TFTP for the initial bootloader.

Apache Setup

Install Apache

$ sudo dnf install httpd -y

To prevent interferences with haproxy, change the listen port to include the IP address:

$ sudo nano /etc/httpd/conf/httpd.conf

From

Listen 80

Listen 192.168.110.20:80

Allow the service through the firewall.

$ sudo firewall-cmd --add-service=http --permanent
$ sudo firewall-cmd --add-service=https --permanent
$ sudo firewall-cmd --reload

and enable and start the service:

$ sudo systemctl enable --now httpd.service

TFTP Setup

Install TFTP:

$ sudo dnf install tftp-server -y

Enable and start the service:

$ sudo systemctl enable --now tftp.socket

and allow the service through the firewall.

$ sudo firewall-cmd --add-service=tftp --permanent
$ sudo firewall-cmd --reload

iPXE Setup

We are going to deploy the OpenShift nodes using ipxe and tftp-server. The key is the boot.ipxe script, which we will discuss in the next blog. For now, we prepare iPXE.

Install iPXE

$ sudo dnf install ipxe-bootimgs

and prepare the basic structure.

$ sudo cp /usr/share/ipxe/undionly.kpxe /var/lib/tftpboot/
$ sudo cp /usr/share/ipxe/ipxe-snponly-x86_64.efi /var/lib/tftpboot/
$ sudo restorecon -Rv /var/lib/tftpboot

It can be later used to install other OS, like RHEL or Ubuntu.

6. Load Balancing with HAProxy

This is critical for High Availability. HAProxy listens on the API VIP (192.168.110.21) and Ingress VIP (192.168.110.22) and forwards traffic to the backend nodes.

Install HAProxy

$ sudo dnf install haproxy -y

HAProxy Configuration for Openshift

Use nano or vim to update the configuration file (/etc/haproxy/haproxy.cfg). See below the changes I made:

# /etc/haproxy/haproxy.cfg snippet
    chroot      /var/lib/haproxy
    #pidfile     /var/run/haproxy.pid

defaults
    mode                    tcp
    log                     global
    option                  tcplog
    retries                 3
    timeout connect         10s
    timeout client          1m
    timeout server          1m
    maxconn                 3000

#---------------------------------------------------------------------
# round robin balancing for RHOCP Kubernetes API Server
#---------------------------------------------------------------------
 listen api-server-6443
   bind 192.168.110.21:6443
   mode tcp
   option httpchk GET /readyz HTTP/1.0
   option log-health-checks
   balance roundrobin
   server bootstos bootstos.oc41827.internal.local:6443 verify none check check-ssl inter 10s fall 2 rise 3 backup
   server masteros01 masteros01.oc41827.internal.local:6443 weight 1 verify none check check-ssl inter 10s fall 2 rise 3
   server masteros02 masteros02.oc41827.internal.local:6443 weight 1 verify none check check-ssl inter 10s fall 2 rise 3
   server masteros03 masteros03.oc41827.internal.local:6443 weight 1 verify none check check-ssl inter 10s fall 2 rise 3

# ---------------------------------------------------------------------
# round robin balancing for RHOCP Machine Config Server
# ---------------------------------------------------------------------
 listen machine-config-server-22623
   bind 192.168.110.21:22623
   mode tcp
   server bootstos bootstos.oc41827.internal.local:22623 check inter 1s backup
   server masteros01 masteros01.oc41827.internal.local:22623 check inter 1s
   server masteros02 masteros02.oc41827.internal.local:22623 check inter 1s
   server masteros03 masteros03.oc41827.internal.local:22623 check inter 1s

# ---------------------------------------------------------------------
# round robin balancing for RHOCP Ingress Insecure Port
# ---------------------------------------------------------------------
 listen ingress-router-80
   bind 192.168.110.22:80
   mode tcp
   balance source
   server workeros01 workeros01.oc41827.internal.local:80 check inter 1s
   server workeros02 workeros02.oc41827.internal.local:80 check inter 1s
   server workeros03 workeros03.oc41827.internal.local:80 check inter 1s

# ---------------------------------------------------------------------
# round robin balancing for RHOCP Ingress Secure Port
# ---------------------------------------------------------------------
 listen ingress-router-443
   bind 192.168.110.22:443
   mode tcp
   balance source
   server workeros01 workeros01.oc41827.internal.local:443 check inter 1s
   server workeros02 workeros02.oc41827.internal.local:443 check inter 1s
   server workeros03 workeros03.oc41827.internal.local:443 check inter 1s

Updating firewalld and SELinux

We need to allow the tcp ports used by OpenShift through firewalld

$ sudo firewall-cmd --permanent --add-service=https
$ sudo firewall-cmd --permanent --add-port=6443/tcp
$ sudo firewall-cmd --permanent --add-port=22623/tcp
$ sudo firewall-cmd --reload

and also ensure SELinux allows those ports to be used as HTTP ports

$ sudo semanage port -a -t http_port_t -p tcp 6443
$ sudo semanage port -m -t http_port_t -p tcp 6443
$ sudo semanage port -a -t http_port_t -p tcp 22623
$ sudo semanage port -m -t http_port_t -p tcp 22623

Configuration check and enabling the HAProxy service

Check the configuration file:

$ sudo haproxy -c -f /etc/haproxy/haproxy.cfg

Note that no output from the previous command is good news!

and enable and start the service.

$ sudo systemctl enable --now haproxy

🔜 Coming Up in Part 2

Now that the network is breathing correctly, we need to generate the Ignition files.

Downloading RHCOS and OpenShift CLI tools.
Creating the install-config.yaml.
Running openshift-install to generate manifests.
Critical Step: Disabling Secure Boot on VMs (the "secret" to getting iPXE to work).
Powering on the nodes and watching the magic happen.

Stay tuned!

Did you find this guide helpful? Let me know in the comments if you'd prefer using Ansible for the setup instead of manual commands! Also, subscribe to follow the rest of the series.

Building a Kubernetes Cluster on Red Hat Enterprise Linux 10: A kubeadm Guide

Ana Villar — Thu, 18 Jun 2026 18:22:11 +0000

Introduction

In this post, I'll walk you through deploying a production-ready Kubernetes cluster on Red Hat Enterprise Linux 10 using kubeadm. This lab was inspired by Anthony E. Nocentino's excellent Certified Kubernetes Administrator (CKA): Using kubadm to Install a Basic Cluster training course, which is part of the official Certified Kubernetes Administrator (CKA) path on Pluralsight.

⭐ Shout-out: Anthony is a fantastic trainer! His course uses Ubuntu 22.04 as the base OS. I adapted his approach to work on RHEL 10, adding some additional considerations specific to Red Hat's ecosystem.

One intentional decision in this setup: I deployed Kubernetes v1.35 and CRI-O v1.35, which wasn't the latest version available at installation time.

This was purposeful. Anthony's course includes a dedicated section on upgrading clusters, and using a slightly older baseline makes that learning path clearer.

The upgrade procedures (not covered here) are what really solidify your understanding of cluster lifecycle management.

Lab Infrastructure Overview

Nodes Configuration

Node	Role	RAM	vCPUs	IP Address
rh-cp1	Control Plane	12 GiB	2	192.168.110.120
rh-node1	Worker	6 GiB	2	192.168.110.121
rh-node2	Worker	6 GiB	2	192.168.110.122
rh-node3	Worker	6 GiB	2	192.168.110.123

Note: The IP address schema is just an example and what was more convenient for me.

Supporting Infrastructure

A dedicated utilities VM (also RHEL 10) provides essential services:

DNS (BIND/named)
NTP (chrony)
HTTP (Apache/httpd)
DHCP (Kea)

This centralized infrastructure simplifies name resolution across all cluster nodes. But this is not essential for this project. You can, instead, ensure the nodes are able to reach each other updating the file /etc/hosts on all nodes.

Prerequisites & OS Preparation

Before diving into Kubernetes, we need consistent node preparation across all machines.

1. System Registration and Updates

$ sudo subscription-manager register --username <username> --password <password>
$ sudo dnf update redhat-release
$ sudo dnf upgrade
$ sudo reboot

2. Disable Swap (Required by Kubernetes)

Edit /etc/fstab to comment out swap entries:

UUID=xxxxxxxx-xxx-xxxx-xxxx-xxxxxxxxxxxx none swap defaults 0 0
# ^ Comment this line out

Verify:

$ sudo swapoff -a
$ free

3. Disable Firewalld

Disable firewalld, as indicated in the Calico System requirements for Kubernetes:

$ sudo systemctl stop firewalld
$ sudo systemctl disable firewalld
$ sudo systemctl mask firewalld

⚠️ Production Note: Use Calico to maintaining security and enforce network policies later.

4. Load Kernel Modules and Enable IP Forwarding

$ cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

$ sudo modprobe overlay
$ sudo modprobe br_netfilter

Configure sysctl parameters:

$ cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
EOF

$ sudo sysctl --system

Verify the modules loaded correctly:

$ lsmod | grep overlay
$ lsmod | grep br_netfilter

Installing Kubernetes Components

Setting Version Variables

$ KUBERNETES_VERSION=v1.35
$ CRIO_VERSION=v1.35

Adding Repositories

Create the Kubernetes repo:

$ cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/$KUBERNETES_VERSION/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/$KUBERNETES_VERSION/rpm/repodata/repomd.xml.key
EOF

Create the CRI-O repo:

$ cat <<EOF | sudo tee /etc/yum.repos.d/cri-o.repo
[cri-o]
name=CRI-O
baseurl=https://download.opensuse.org/repositories/isv:/cri-o:/stable:/$CRIO_VERSION/rpm/
enabled=1
gpgcheck=1
gpgkey=https://download.opensuse.org/repositories/isv:/cri-o:/stable:/$CRIO_VERSION/rpm/repodata/repomd.xml.key
EOF

Installing Packages

$ sudo dnf install -y kubelet kubeadm kubectl cri-o container-selinux

Configuring CRI-O

Create a cgroup manager configuration file:

$ cat <<EOF | sudo tee /etc/crio/crio.conf.d/02-cgroup-manager.conf
[crio.runtime]
conmon_cgroup = "pod"
cgroup_manager = "cgroupfs"
EOF

Enable and start services:

$ sudo systemctl enable --now crio kubelet
$ sudo systemctl restart crio

Version Locking

To prevent accidental upgrades:

$ sudo dnf install 'dnf-command(versionlock)'
$ sudo dnf versionlock add kubeadm-1.35.4 kubelet-1.35.4 kubectl-1.35.4 cri-o-1.35.2

Note: Review the output from the installation of the packages kubeadm, kubelet, kubectl and cri-o, and update the versions to lock in the command above.

Initializing the Control Plane

On rh-cp1, download and configure Calico networking. To know the current lastest version, check Tigera documentation, in the Manifest tab:

$ wget https://raw.githubusercontent.com/projectcalico/calico/v3.32.0/manifests/calico.yaml

Edit the CALICO_IPV4POOL_CIDR value to match your pod network plan:

- name: CALICO_IPV4POOL_CIDR
  value: "10.244.0.0/16"

Initialize the cluster, to use the same subnet:

$ sudo kubeadm init \
  --kubernetes-version v1.35.4 \
  --pod-network-cidr=10.244.0.0/16 \
  --cri-socket unix:///var/run/crio/crio.sock \
  --upload-certs

Once successful, save the join commands that appear at the end of the output—you'll need these for worker nodes!

To start using your cluster, you need to run the following as a regular user:

  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config

Alternatively, if you are the root user, you can run:

  export KUBECONFIG=/etc/kubernetes/admin.conf

You should now deploy a pod network to the cluster.
Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
  https://kubernetes.io/docs/concepts/cluster-administration/addons/

Then you can join any number of worker nodes by running the following on each as root:

kubeadm join 192.168.110.120:6443 --token xxxxxx.xxxxxxxxxxxxxxxx \
 --discovery-token-ca-cert-hash sha256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  
$

Your Kubernetes control-plane has initialized successfully!

Configuring kubectl

$ mkdir -p $HOME/.kube
$ sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
$ sudo chown $(id -u):$(id -g) $HOME/.kube/config

Deploy Calico Network

$ kubectl apply -f calico.yaml

Wait a few minutes and verify pods are running:

$ kubectl get pods --all-namespaces
$ kubectl get nodes

Expected output:

$ kubectl get pods --all-namespaces
NAMESPACE     NAME                                       READY   STATUS    RESTARTS   AGE
kube-system   calico-kube-controllers-6b4b6457d5-p98c2   1/1     Running   0          2m47s
kube-system   calico-node-5vjrr                          1/1     Running   0          2m47s
kube-system   coredns-7d764666f9-r4vqp                   1/1     Running   0          4m9s
kube-system   coredns-7d764666f9-vh7df                   1/1     Running   0          4m9s
kube-system   etcd-rh-cp1                                1/1     Running   0          4m28s
kube-system   kube-apiserver-rh-cp1                      1/1     Running   0          4m28s
kube-system   kube-controller-manager-rh-cp1             1/1     Running   0          4m27s
kube-system   kube-proxy-4r6h8                           1/1     Running   0          4m10s
kube-system   kube-scheduler-rh-cp1                      1/1     Running   0          4m28s
$ kubectl get nodes
NAME     STATUS   ROLES           AGE     VERSION
rh-cp1   Ready    control-plane   4m40s   v1.35.4
$

Joining Worker Nodes

On each worker node (rh-node1, rh-node2, rh-node3), run the join command saved during kubeadm init:

$ sudo kubeadm join 192.168.110.120:6443 \
  --token <token> \
  --discovery-token-ca-cert-hash sha256:<hash>

Verify the cluster health from the control plane:

$ kubectl get nodes

All nodes should show Ready status.

$ kubectl get nodes
NAME       STATUS   ROLES           AGE     VERSION
rh-cp1     Ready    control-plane   10m     v1.35.4
rh-node1   Ready    <none>          2m11s   v1.35.4
rh-node2   Ready    <none>          113s    v1.35.4
rh-node3   Ready    <none>          102s    v1.35.4
$

Install bash completion for kubectl:

$ sudo dnf install bash-completion
$ echo "source <(kubectl completion bash)" >> ~/.bashrc
$ source ~/.bashrc

Testing the Deployment

Deploy a test application:

$ kubectl create deployment hello-world --image=psk8s.azurecr.io/hello-app:1.0
$ kubectl get pods -o wide

Expose it via a service:

$ kubectl expose deployment hello-world --port=80 --target-port=8080
$ kubectl get service hello-world

For example:

$ kubectl get service hello-world
NAME          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
hello-world   ClusterIP   10.99.168.218   <none>        80/TCP    8s
$

Then, test it. You should see a response from your running container!

$ curl http://10.99.168.218:80
Hello, world!
Version: 1.0.0
hello-world-b5b7f67cc-d26dt
$

Clean up after testing:

$ kubectl delete service hello-world
$ kubectl delete deployment hello-world

Key Considerations When Moving from Ubuntu to RHEL

Here are the main differences I encountered adapting Anthony's tutorial:

Aspect	Ubuntu Approach	RHEL 10 Adaptation
Package Manager	apt/dpkg	dnf/rpm
Firewall Management	ufw/firewalld optional	firewalld disabled (use Calico policies)
Subscription	N/A	subscription-manager required
SELinux	Permissive mode default	Need to handle SELinux context
CRI Runtime	containerd	CRI-O

What's Next?

This setup provides a solid foundation for learning Kubernetes administration. From here, you could explore:

Cluster upgrades (covered extensively in Anthony's course)
Network policy enforcement with Calico
High availability with multiple control plane nodes
Storage classes and persistent volumes
Monitoring stack with Prometheus/Grafana

If you found this walkthrough helpful, I'd highly recommend checking out the original Pluralsight course. Anthony's explanations are crystal clear, and adapting them to different distributions is an excellent way to deepen your understanding of what happens under the hood.

Resources

Pluralsight: Certified Kubernetes Administrator Certification Path
Official Kubernetes Documentation
Calico Project GitHub

Thanks for reading! Feel free to share your own experiences with Kubernetes on RHEL in the comments below.

Complete Guide: Setting Up XWiki 17 on Premises

Ana Villar — Fri, 12 Jun 2026 19:04:27 +0000

This guide walks through deploying XWiki 17.10.8 on Red Hat Enterprise Linux 10.2 with Apache Tomcat and PostgreSQL. Total setup time: ~45 minutes. Requires minimum 8GB RAM and 4 vCPUs for acceptable performance.

If you're looking to deploy a self-hosted wiki solution with enterprise-grade features, XWiki is an excellent choice. Unlike some alternatives, it offers powerful permission management, structured data, and extensibility through extensions. However, the on-premises setup can be intimidating due to multiple moving parts.

This guide details setting up XWiki 17 on Red Hat Linux Server 10.2 with 16GB RAM and 4 vCPUs. I initially validated these steps in a Mac-hosted VM before deploying them to my production environment on a Dell OptiPlex 7050 Micro.

What You'll Need

Hardware Requirements

Resource	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	4 GB	16 GB
Storage	20 GB	100 GB

Note: During my initial setup on a 2GB RAM old laptop, XWiki was functional but painfully slow. The jump to 16GB made a night-and-day difference in responsiveness.

Software Stack

Operating System: Red Hat Enterprise Linux 10.2 or Fedora Server
Servlet Container: Apache Tomcat 10.1.x (Jetty is also supported)
Database: PostgreSQL 16.x
Java: OpenJDK 21
XWiki Platform: 17.10.8 WAR package

Comments:

As Operating System, you can use other Linux Distributions, including Ubuntu, Windows Server and Docker Engine.
As Servlet Container, Jetty is also a supported option.
Other supported databases are HyperSQL, MariaDB, MySQL, or Oracle.
For more information, review XWiki prerequisites.

Time Investment

Installation: ~30 minutes
Configuration: ~15 minutes
Testing: ~10 minutes

Preparation Steps

Install Your Base OS

For this guide, I'm using Red Hat Enterprise Linux, but most steps work equally well on Fedora Server if you don't have RHEL subscriptions.

Download from Red Hat Developer Program or Fedora Server.

Once installed, register (if using RHEL), update, and reboot:

~$ sudo subscription-manager register --username <username> --password <password>
~$ sudo dnf upgrade -y
~$ reboot

Installing Dependencies

Install and configure Apache Tomcat

Tomcat serves as our servlet container for hosting XWiki:

~$ sudo dnf install tomcat -y

This command pulls in Java 21 along with necessary dependencies automatically. Review the installation output to confirm java-21-openjdk-headless was included.

Architecture Note:
Package names vary by architecture:

x86_64: java-21-openjdk-headless.x86_64
aarch64: java-21-openjdk-headless.aarch64

If it seems to be missing:

~$ sudo dnf install java-21-openjdk-headless.x86_64 -y

~$ sudo dnf install java-21-openjdk-headless.aarch64 -y

Configure Firewall

Allow HTTP traffic on port 8080 (Tomcat's default):

~$ sudo firewall-cmd --permanent --add-port=8080/tcp
~$ sudo firewall-cmd --reload

Verify it's open:

~$ sudo firewall-cmd --list-all

Configure Tomcat Memory Settings

By default, Tomcat won't allocate enough memory for XWiki to perform well. Create a custom setenv.sh file:

~$ sudo mkdir -p /var/lib/tomcat/bin
~$ sudo chown tomcat:tomcat -R /var/lib/tomcat
~$ sudo nano /var/lib/tomcat/bin/setenv.sh

Add this configuration:

#!/bin/sh
export JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true"
export CATALINA_OPTS="-server -Xms1080m -Xmx1600m -Dfile.encoding=utf-8 \
-Djava.awt.headless=true \
--add-opens java.base/java.lang=ALL-UNNAMED \
--add-opens java.base/java.io=ALL-UNNAMED \
--add-opens java.base/java.util=ALL-UNNAMED \
--add-opens java.base/java.util.concurrent=ALL-UNNAMED"

Memory Explanation:

Setting	Value	Purpose
-Xms	1080MB	Initial heap size (prevents startup allocation spikes)
-Xmx	1600MB	Maximum heap size (prevents runaway memory consumption)
--add-opens	N/A	Required for Java 17+ compatibility with certain libraries

Set ownership and test:

~$ sudo chown tomcat:tomcat /var/lib/tomcat/bin/setenv.sh
~$ sudo systemctl enable --now tomcat
~$ sudo systemctl status tomcat

Test from another machine by visiting http://your-server-name:8080. You should see the Tomcat welcome page. Once confirmed, stop the service — we'll restart after XWiki deployment:

~$ sudo systemctl stop tomcat

Database Configuration (PostgreSQL)

Install PostgreSQL

~$ sudo dnf install postgresql-server postgresql-contrib -y

Initialize and Start PostgreSQL

~$ sudo postgresql-setup --initdb
~$ sudo systemctl enable --now postgresql
~$ sudo systemctl status postgresql

Create XWiki User and Database

Switch to the postgres user:

~$ sudo su postgres
bash-5.2$ psql

Then run these SQL commands:

CREATE USER xwiki PASSWORD 'xwikipassword';
CREATE DATABASE xwiki WITH OWNER=xwiki;
GRANT ALL ON SCHEMA public TO xwiki;
\q

⚠️ Security Warning: Replace 'xwikipassword' with a strong, unique password. Never use default credentials in production. Consider using environment variables or secret management tools like HashiCorp Vault for sensitive data.

Configure PostgreSQL Authentication

Find the authentication config file:

~$ sudo su postgres
bash-5.2$ psql -c "SHOW hba_file;"

By default, the file and location is /var/lib/pgsql/data/pg_hba.conf

Edit the pg_hba.conf file to change authentication method:

~$ sudo nano /var/lib/pgsql/data/pg_hba.conf

Replace these lines:

# OLD (insecure)
host    all             all             127.0.0.1/32            ident
host    all             all             ::1/128                 ident

# NEW (secure)
host    all             all             127.0.0.1/32            scram-sha-256
host    all             all             ::1/128                 scram-sha-256

Reload PostgreSQL to apply changes:

~$ sudo systemctl reload postgresql

Verify Database Connection:

~$ psql postgresql://xwiki:xwikipassword@localhost
xwiki=> \l  # Should list databases including 'xwiki'
xwiki=> \q  # Exit psql
~$

Deploying XWiki

Download Required Files

Get these two files from official sources:

XWiki WAR Package: Production Installation → Select "WAR Package for Servlet Container"
PostgreSQL JDBC Driver: Official Downloads

Place them in a download directory:

~$ mkdir ~/downloads
~$ cd ~/downloads
# wget the links here from browser or CLI
~$ ls downloads/
postgresql-42.7.11.jar  xwiki-platform-distribution-war-17.10.8.jar
~$

Deploy the WAR Package

Copy and extract the XWiki WAR:

~$ sudo cp ~/downloads/xwiki-platform-distribution-war-17.10.8.jar /var/lib/tomcat/webapps/
~$ cd /var/lib/tomcat/webapps
~$ sudo unzip xwiki-platform-distribution-war-17.10.8.jar
~$ sudo mkdir xwiki
~$ sudo mv META-INF redirect resources skins templates WEB-INF xwiki/
~$ sudo rm xwiki-platform-distribution-war-17.10.8.jar
~$ sudo chown -R tomcat:tomcat xwiki/

Common Pitfall: If you get an error about moving files into themselves, ensure you're not inside the extracted directory when creating the target folder.

Add PostgreSQL JDBC Driver

~$ cd /var/lib/tomcat/webapps/xwiki/WEB-INF/lib
~$ sudo cp ~/downloads/postgresql-42.7.11.jar .
~$ sudo chown tomcat:tomcat *.jar

Configure Hibernate for PostgreSQL

Edit the Hibernate configuration:

~$ cd /var/lib/tomcat/webapps/xwiki/WEB-INF
~$ sudo nano hibernate.cfg.xml

Find and comment out the default database section:

    <!--
    <property name="hibernate.connection.url">jdbc:hsqldb:file:${environment.permanentDirectory}/database/xwiki_db;shutdown=true</property>
    <property name="hibernate.connection.username">sa</property>
    <property name="hibernate.connection.password"></property>
    <property name="hibernate.connection.driver_class">org.hsqldb.jdbcDriver</property>
    -->

Find and uncomment the PostgreSQL section:

    <!-- PostgreSQL configuration.
         Uncomment if you want to use PostgreSQL and comment out other database configurations.
         Notes:
           - "hibernate.jdbc.use_streams_for_binary" needs to be set to "false",
             see https://community.jboss.org/wiki/HibernateCoreMigrationGuide36
           - "xwiki.virtual_mode" can be set to either "schema" or "database". Note that currently the database mode
             doesn't support database creation (see https://jira.xwiki.org/browse/XWIKI-8753)
           - if you want the main wiki database to be different than "xwiki" (or "public" in schema mode)
             you will also have to set the property xwiki.db in xwiki.cfg file
    -->

    <property name="hibernate.connection.url">jdbc:postgresql://localhost:5432/xwiki</property>
    <property name="hibernate.connection.username">xwiki</property>
    <property name="hibernate.connection.password">**xwikipassword**</property>
    <property name="hibernate.connection.driver_class">org.postgresql.Driver</property>
    <property name="hibernate.jdbc.use_streams_for_binary">false</property>
    <property name="xwiki.virtual_mode">schema</property>

    <property name="hibernate.connection.charSet">UTF-8</property>
    <property name="hibernate.connection.useUnicode">true</property>
    <property name="hibernate.connection.characterEncoding">utf8</property>

    <mapping resource="xwiki.postgresql.hbm.xml"/>
    <mapping resource="feeds.hbm.xml"/>
    <mapping resource="instance.hbm.xml"/>
    <mapping resource="notification-filter-preferences.hbm.xml"/>
    <mapping resource="mailsender.hbm.xml"/>


    <!-- Oracle configuration.
...

⚠️ Password Reminder: Update the password value to match what you set earlier!

Configure Permanent Directory

Create a dedicated directory for XWiki data:

~$ sudo mkdir -p /var/lib/xwiki/data
~$ sudo chown -R tomcat:tomcat /var/lib/xwiki

Edit the properties file:

~$ nano /var/lib/tomcat/webapps/xwiki/WEB-INF/xwiki.properties

Uncomment and verify this line:

environment.permanentDirectory = /var/lib/xwiki/data/

Starting the Application

~$ sudo systemctl start tomcat

Wait 3-5 minutes for Tomcat to fully initialize XWiki (it compiles resources on first boot). Monitor logs:

~$ sudo tail -f /var/log/tomcat/catalina.out

Look for messages like XWiki context has been initialized successfully.

XWiki Configuration Wizard

Running the Configuration Wizard

Navigate to your server: http://your-server-name:8080/xwiki.

You'll see an initialization banner briefly, then the wizard will appear.

Wizard Steps

Press Continue to begin

Create Administrator Account: Set a strong admin password (save this securely!).

Press Register and Login.

Press Continue

Install Standard Flavor: Select "XWiki Standard Flavor" from the dropdown—this includes useful built-in applications

Press Install this flavor: Wait 2-5 minutes depending on hardware

Press Install

Once you see it has been Installed, Press Continue to completion.

After finalization, press Continue and you'll be redirected to your XWiki home page with example documentation.

Your XWiki server is ready!

Post-Installation Checklist

Security Hardening

Action	Priority	Command/File
Change default PostgreSQL password	High	psql ALTER USER command
Update Tomcat manager passwords	High	tomcat-users.xml
Enable HTTPS via reverse proxy	High	nginx/Apache configuration
Restrict database access	Medium	pg_hba.conf network rules
Regular backups	High	XWiki GUI + cron jobs + pg_dump

Performance Tuning

With 16GB RAM, you may want to increase XWiki's maximum heap:

# Edit setenv.sh
CATALINA_OPTS="-Xmx2048m ..."  # Increase if needed

Enable query caching in xwiki.properties:

cache.default.maxSize = 5000

Backup Strategy

Using XWiki GUI

Go to Administer Wiki:

Select Content:

And select Export:

You can select what pages to export/backup.

Database:

pg_dump -U xwiki xwiki > xwiki_backup_$(date +%Y%m%d).sql

File Data:

tar czf xwiki_files_$(date +%Y%m%d).tar.gz /var/lib/xwiki/data/

Schedule these as cron jobs for automated backups.

Troubleshooting Common Issues

Issue: XWiki Won't Load After Startup

Symptoms: Browser shows blank page or timeout at /xwiki

Solutions:

Check logs: tail -f /var/log/tomcat/catalina.out
Verify database connection is active
Ensure hibernate.cfg.xml has correct credentials
Restart Tomcat completely

Issue: Slow Page Loading

Symptoms: Pages take 5+ seconds to load

Solutions:

Increase JVM heap in setenv.sh
Check available RAM with free -h
Disable unnecessary extensions in XWiki admin panel
Consider upgrading to SSD storage

Issue: Database Connection Error

Symptoms: "Cannot connect to database" during wizard

Solutions:

Verify PostgreSQL is running: sudo systemctl status postgresql
Test connectivity: psql -U xwiki -d xwiki
Check pg_hba.conf has scram-sha-256 authentication
Ensure firewall allows localhost PostgreSQL connections (port 5432)

Why On-Premises Over Cloud?

You might wonder why choose self-hosted instead of XWiki Cloud. Here are compelling reasons:

Factor	On-Premises	Cloud
Data Control	Full	Limited by provider
Customization	Unlimited	Restricted
Cost (Long-term)	Lower	Subscription-based
Offline Access	Yes	Requires internet
Integration	Direct system access	API-only

For organizations handling sensitive data or requiring deep integration, on-premises deployment provides the flexibility you need.

Final Thoughts

Setting up XWiki on-premises involves coordinating several components, but once configured, you have a powerful, self-contained knowledge management platform. The setup I've outlined balances security, performance, and maintainability.

Got questions or encountered different errors? Drop a comment below — I'm happy to help troubleshoot!

Further Resources

Hello, DEV Community! 👋

Ana Villar — Sat, 30 May 2026 15:53:23 +0000

I'm Ana, and I'm excited to start sharing my technical journey here. This is a brief post to introduce myself and give you a heads-up on what's coming.

What to Expect

In upcoming posts, I'll be diving into hands-on, infrastructure-focused tutorials and walkthroughs, including:

Setting up a XWiki server on-premises — from installation to configuration, getting a collaborative wiki platform running in your own environment.
Deploying Kubernetes on RHEL 10 virtual machines — step-by-step guidance on building a Kubernetes cluster on Red Hat Enterprise Linux 10.
Deploying OpenShift as virtual machines on a RHEL 10 host — exploring how to run OpenShift on top of RHEL 10, combining the power of containers with VM-level control.

My goal is to keep things practical, clear, and rooted in real-world experience — the kind of content I wish I'd had when tackling these setups myself.

Why These Topics?

Because on-premises infrastructure is far from dead. Whether it's compliance requirements, performance needs, or simply wanting full control over your stack, there's still a strong case for running things yourself. And RHEL was my choice for certification purposes, and it's given me the flexibility to keep using hardware that other vendors have discontinued.

Stay tuned, and feel free to follow me so you don't miss the upcoming posts. If any of these topics spark your interest, I'd love to hear about it in the comments! 🚀