Skip to content

Minikube

Use this guide to deploy QMigrator on Minikube for local, lab, and non-production environments.

Note

This page covers two deployment paths: general Linux with the Docker driver, and RHEL with the Podman driver in both rootless and rootful modes.

  • 8 vCPUs
  • 32 GB RAM
  • 256 GB storage
  • At least 100 GB free space in /home and /var/lib

Common Requirements

  • A Linux host with root or sudo access
  • Internet access to download packages and binaries
  • kubectl, helm, and minikube
  • A container runtime supported by Minikube

Common Setup (Linux and RHEL)

Install tools required for both Linux Docker and RHEL Podman deployment paths.

Step 1: Update Package Index and Install Required Packages

sudo apt-get update
sudo apt-get install -y git curl socat docker.io

Verify Docker:

docker version

sudo dnf -y update
sudo dnf -y install podman podman-docker conntrack iptables iproute-tc socat git curl

Verify Podman:

podman --version

Step 2: Install Minikube

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

Step 3: Install kubectl and Helm

Install kubectl:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install kubectl /usr/local/bin/kubectl

Install Helm:

curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Step 4: Verify Common Tooling

minikube version
kubectl version --client
helm version

Linux: Minikube with Docker

Use this section for Ubuntu, Debian, and other Linux distributions where Docker is the preferred Minikube driver.

Step 1: Setup Minikube Docker

Enable and start Docker:

sudo systemctl enable --now docker
sudo usermod -aG docker $USER

Verify Docker:

docker version

RHEL: Minikube with Podman

Use this section for RHEL 8 and RHEL 9 deployments where Podman is the preferred container runtime.

Prerequisites

  • RHEL 8 or RHEL 9
  • A Linux user for running Minikube, recommended: qmigrator
  • Podman packages available from configured repositories

Step 1: Create QMigrator User

sudo groupadd -g 4000 qmigrator
sudo useradd -u 5000 -g 4000 -m -s /bin/bash qmigrator
sudo loginctl enable-linger qmigrator

Info

enable-linger allows user services to continue after logout, which is important for rootless Podman.

Step 2: Ensure cgroup v2 is Enabled

Check cgroup mode:

stat -fc %T /sys/fs/cgroup/

Expected output: cgroup2fs

If cgroup v2 is not enabled, run:

sudo grubby --update-kernel=ALL --args="systemd.unified_cgroup_hierarchy=1 cgroup_no_v1=all"
sudo reboot

Step 3: Select Podman Mode

Check the kernel version:

uname -r
  • Kernel > 5.11: rootless mode is recommended and common on RHEL 9
  • Kernel <= 5.11: rootful mode is commonly used on RHEL 8

Step 4: Configure Podman Mode

Allow the qmigrator user to run Podman with sudo:

sudo visudo

Add this line:

qmigrator ALL=(ALL) NOPASSWD: /usr/bin/podman

Switch to the qmigrator user and verify access:

sudo su - qmigrator
sudo -k -n podman version

Configure systemd delegation:

sudo mkdir -p /etc/systemd/system/user@.service.d
sudo tee /etc/systemd/system/user@.service.d/delegate.conf > /dev/null <<EOF
[Service]
Delegate=cpu cpuset io memory pids
EOF
sudo systemctl daemon-reload

Switch to the qmigrator user and enable rootless mode:

sudo su - qmigrator
minikube config set rootless true

Common: Start Minikube and Validate Cluster

Run this section after completing the runtime-specific setup above.

Step 1: Prepare Mount Paths

mkdir -p $HOME/qmigrator/{shared,db,cache}
chmod -R 777 $HOME/qmigrator/{shared,db,cache}

Step 2: Start Minikube

minikube start \
  --driver=docker \
  --cpus=8 \
  --memory=6gb \
  --mount \
  --mount-string="$HOME/qmigrator:/mnt/qmigrator" \
  --embed-certs

minikube start \
  --driver=podman \
  --cpus=8 \
  --memory=6gb \
  --mount \
  --mount-string="$HOME/qmigrator:/mnt/qmigrator" \
  --embed-certs

Step 3: Validate Cluster

minikube status
kubectl get nodes

Next Steps

  • Install QMigrator Helm charts
  • Configure namespaces and storage
  • Expose services via Gateway or Ingress

Post Steps: Expose QMigrator on VM Port

After deployment, QMigrator services run inside Minikube. Expose a VM port so external users can access the service.

Step 1: Open Firewall Port

sudo firewall-cmd --permanent --add-port=1500/tcp
sudo firewall-cmd --reload

Step 2: Expose Service

Use socat to map VM port 1500 to the Minikube NodePort service.

nohup socat tcp-listen:1500,reuseaddr,fork tcp:<minikube-ip>:<service-nodeport> > logfile.log 2>&1 &

Find the Minikube IP and service NodePort:

minikube ip
kubectl get svc qmig-gateway-nginx -n <namespace>

Use socat to map VM port 1500 to the Minikube NodePort service.

nohup socat tcp-listen:1500,reuseaddr,fork tcp:<minikube-ip>:<service-nodeport> > logfile.log 2>&1 &

Find the Minikube IP and service NodePort:

minikube ip
kubectl get svc qmig-gateway-nginx -n <namespace>

Use port-forward to bind service port 80 to VM port 1500.

kubectl port-forward service/qmig-gateway-nginx 1500:80 --address 0.0.0.0 > logfile.log 2>&1 &

Info

--address 0.0.0.0 allows access from outside the VM.

Step 3: Verify Access

curl http://<VM-IP>:1500

Replace <VM-IP> with your RHEL host IP.