Deploy di OKD Single Node su Proxmox

Questa guida documenta la configurazione completa di OKD (The Community Distribution of Kubernetes that powers Red Hat OpenShift) come cluster Single Node Operator (SNO) su una macchina virtuale ospitata da Proxmox VE. Questa configurazione è ideale per home lab, sviluppo e test.

✅ Prerequisiti

Nodo Proxmox VE: Un host Proxmox VE funzionante con virtualizzazione hardware (VT-x/AMD-V) abilitata nel BIOS/UEFI.
Risorse Sufficienti:
- CPU: Minimo 8 vCPU raccomandate per SNO.
- RAM: Minimo 32GB RAM raccomandati per SNO.
- Storage: Minimo 120GB-150GB di storage veloce (SSD/NVMe) per la VM OKD.
Macchina Amministrativa (Client): Una macchina Linux (es. Ubuntu, Fedora) o macOS per eseguire openshift-install, oc, podman e altri strumenti client. Questa sarà indicata come “Admin Client Machine”.
Rete: Una rete locale con server DHCP e capacità di risoluzione DNS (es. un router come OpenWRT). La VM OKD richiederà un indirizzo IP statico.
Red Hat Pull Secret: Ottieni un pull secret da Red Hat OpenShift Cluster Manager (è sufficiente un account developer Red Hat gratuito). È necessario per alcuni operator certificati e immagini.

🔧 Fase 1: Preparazione sulla Admin Client Machine

Tutti i comandi in questa fase vengono eseguiti sulla tua Admin Client Machine.

1. Imposta le Variabili d’Ambiente

Definisci la versione OKD e l’architettura per coerenza.

export OKD_VERSION=4.18.0-0.okd-scos.10 # Verifica l'ultima release SCOS stabile
export ARCH=x86_64

2. Scarica OpenShift Client (`oc`)

curl -L "https://github.com/okd-project/okd/releases/download/${OKD_VERSION}/openshift-client-linux-${OKD_VERSION}.tar.gz" -o oc.tar.gz
tar zxf oc.tar.gz
chmod +x oc kubectl # kubectl è incluso
sudo mv oc kubectl /usr/local/bin/ # Opzionale: sposta nel PATH per accesso globale
oc version

3. Scarica OpenShift Installer (`openshift-install`)

curl -L "https://github.com/okd-project/okd/releases/download/${OKD_VERSION}/openshift-install-linux-${OKD_VERSION}.tar.gz" -o openshift-install-linux.tar.gz
tar zxvf openshift-install-linux.tar.gz
chmod +x openshift-install
sudo mv openshift-install /usr/local/bin/ # Opzionale: sposta nel PATH
openshift-install version

4. Ottieni la ISO Live di Fedora CoreOS (FCOS)

L’installer determinerà l’URL corretto della ISO FCOS corrispondente alla versione OKD.

export ISO_URL=$(openshift-install coreos print-stream-json | grep location | grep "${ARCH}" | grep iso | cut -d\" -f4)
echo "Download della ISO FCOS da: ${ISO_URL}"
curl -L "${ISO_URL}" -o fcos-live.iso

Nota: Questa fcos-live.iso verrà caricata su Proxmox successivamente.

5. Prepara `install-config.yaml`

Crea una directory per i file di installazione e il file install-config.yaml.

mkdir okd-sno-install
cd okd-sno-install

Crea install-config.yaml con il seguente contenuto:

apiVersion: v1
baseDomain: okd.lan # Il tuo dominio base locale
metadata:
  name: okd4sno    # Il nome del tuo cluster
compute:
- name: worker
  replicas: 0     # Essenziale per SNO
controlPlane:
  name: master
  replicas: 1     # Essenziale per SNO
networking:
  networkType: OVNKubernetes
  clusterNetwork:
  - cidr: 10.128.0.0/14
    hostPrefix: 23
  machineNetwork:
  - cidr: 192.168.7.0/24 # La subnet della rete VM Proxmox
  serviceNetwork:
  - 172.30.0.0/16
platform:
  none: {} # Per installazioni bare-metal/VM non gestite da un cloud provider
bootstrapInPlace:
  # IMPORTANTE: Identifica il disco target della VM Proxmox per l'installazione.
  # Può essere /dev/vda, /dev/sda, o un path WWN più stabile.
  # Esempio per un disco VirtIO, spesso /dev/vda:
  installationDisk: /dev/vda
  # Esempio usando WWN (più robusto, ottienilo dai dettagli del disco della VM Proxmox o dall'ambiente live FCOS):
  # installationDisk: /dev/disk/by-id/wwn-0x64cd98f04fde100024684cf3034da5c2
pullSecret: '<INCOLLA_QUI_IL_TUO_PULL_SECRET_JSON>' # Sostituisci con il tuo pull secret effettivo
sshKey: |
  ssh-rsa AAAA...la_tua_chiave_ssh_pubblica_qui # Sostituisci con la tua chiave SSH pubblica

Note Importanti per install-config.yaml:

baseDomain e metadata.name: Questi formeranno gli FQDN del cluster (es. api.okd4sno.okd.lan).
machineNetwork.cidr: Assicurati che corrisponda alla subnet in cui risiederà la VM OKD.
installationDisk:
- Per dischi VirtIO Proxmox, questo è tipicamente /dev/vda. Per SCSI, potrebbe essere /dev/sda.
- Usare /dev/disk/by-id/wwn-0x... è più robusto se i nomi dei dischi potrebbero cambiare. Puoi identificare il WWN corretto o il path del dispositivo avviando la ISO Live FCOS sulla VM target e usando comandi come lsblk o ls /dev/disk/by-id/.
pullSecret: Incolla l’intera stringa JSON da Red Hat.
sshKey: La tua chiave SSH pubblica per accedere all’utente core sul nodo FCOS.

6. Genera la Configurazione Ignition per Single Node

Questo comando usa install-config.yaml nella directory corrente.

# Ancora nella directory okd-sno-install
openshift-install create single-node-ignition-config

Questo creerà bootstrap-in-place-for-live-iso.ign nella directory corrente.

7. Incorpora Ignition nella ISO Live FCOS

Abbiamo bisogno di coreos-installer per questo, che può essere eseguito via Podman.

# Assicurati di essere nella directory contenente fcos-live.iso e il file ignition di bootstrap
# (che dovrebbe essere okd-sno-install se hai seguito i passi precedenti)

# Se fcos-live.iso è nella directory parent:
# coreos-installer iso ignition embed -fi bootstrap-in-place-for-live-iso.ign ../fcos-live.iso
# Se fcos-live.iso è nella directory corrente (okd-sno-install):
# Prima, sposta fcos-live.iso in okd-sno-install o regola i path. Assumiamo sia nel parent.
# Assicurati che fcos-live.iso sia nella directory dove esegui questo comando o fornisci il path completo.
# Assumiamo che fcos-live.iso sia nella directory parent di okd-sno-install per questo esempio.

# Se hai scaricato fcos-live.iso nella directory okd-sno-install:
podman run --privileged --pull always --rm \
  -v /dev:/dev -v /run/udev:/run/udev -v "$PWD":"$PWD" -w "$PWD" \
  quay.io/coreos/coreos-installer:release \
  iso ignition embed -fi bootstrap-in-place-for-live-iso.ign fcos-live.iso

Questo modifica fcos-live.iso in place per includere la configurazione Ignition.

⚙️ Fase 2: Creazione della VM Proxmox e Installazione FCOS

1. Carica la ISO Modificata su Proxmox

Carica la fcos-live.iso modificata (quella con la configurazione Ignition incorporata) nello storage “ISO Images” del tuo Proxmox VE (es. storage local).

2. Crea la Macchina Virtuale OKD in Proxmox

General:
- Name: okd4sno-vm (o simile)
- Guest OS Type: Linux, Version: 6.x - 2.6 Kernel (o l’ultimo disponibile)
System:
- Machine: q35
- BIOS: OVMF (UEFI)
- EFI Storage: Seleziona lo storage Proxmox per il disco EFI.
- Abilita Qemu Agent.
Disks:
- Crea un disco rigido virtuale (VirtIO Block o SCSI) con almeno 120GB-150GB su storage veloce. Questo è il disco che hai specificato in installationDisk (es. /dev/vda).
CPU:
- Cores: 8 (o più)
- Type: host (per le migliori prestazioni)
Memory:
- 32768 MiB (32GB) o più. Disabilita “Ballooning Device”.
Network:
- Model: VirtIO (paravirtualized)
- Bridge: Il bridge Proxmox connesso alla tua LAN (es. vmbr0).
CD/DVD Drive:
- Seleziona la fcos-live.iso modificata che hai caricato.
Boot Order:
- Imposta il drive CD/DVD (con la ISO FCOS) come primo dispositivo di boot.

3. Installa Fedora CoreOS

Avvia la VM. Si avvierà dalla ISO Live FCOS modificata.
Poiché la configurazione Ignition è incorporata e bootstrapInPlace.installationDisk è impostato, FCOS dovrebbe installarsi automaticamente sul disco specificato (/dev/vda) e poi riavviarsi.
Monitora l’installazione tramite la console della VM Proxmox. Dovresti vedere coreos-installer in esecuzione.
Una volta riavviato per la prima volta dopo che coreos-installer ha terminato, si avvierà dal disco rigido e inizierà il processo di bootstrap di OKD.
Importante: Dopo il primo avvio riuscito dal disco rigido, puoi spegnere la VM e rimuovere la ISO dal drive CD/DVD o cambiare l’ordine di boot per dare priorità al disco rigido.

🌐 Fase 3: DNS e Accesso al Cluster

1. Configurazione DNS (Esempio: OpenWRT)

La VM OKD necessita di un indirizzo IP statico. L’install-config.yaml non lo imposta; FCOS inizialmente userà DHCP a meno che la tua configurazione Ignition (non coperta in questa versione semplificata) non imposti un IP statico. È raccomandato configurare una reservation DHCP sul tuo router per il MAC address della VM OKD, oppure configurare un IP statico sul nodo FCOS stesso (più avanzato, richiede la modifica dell’Ignition per scrivere file di connessione NetworkManager).

Per questa guida, assumiamo che la VM OKD ottenga l’IP 192.168.7.126 (tramite reservation DHCP o IP statico configurato manualmente se hai adattato l’Ignition).

Sul tuo server DNS (es. router OpenWRT, Pi-hole): Aggiungi entry host statiche che puntano all’IP della VM OKD (es. 192.168.7.126):

api.okd4sno.okd.lan → 192.168.7.126
console-openshift-console.apps.okd4sno.okd.lan → 192.168.7.126
oauth-openshift.apps.okd4sno.okd.lan → 192.168.7.126
*.apps.okd4sno.okd.lan → 192.168.7.126 (Se il tuo DNS supporta record A wildcard. Se no, come l’UI di OpenWRT, dovrai aggiungere entry per route app specifiche man mano che le crei, o usare config custom dnsmasq per i wildcard).

Alternativa per la Admin Client Machine (se non c’è DNS centrale): Modifica /etc/hosts sulla tua Admin Client Machine:

192.168.7.126 api.okd4sno.okd.lan console-openshift-console.apps.okd4sno.okd.lan oauth-openshift.apps.okd4sno.okd.lan

2. Monitora l’Installazione dalla Admin Client Machine

Una volta che la VM OKD si è avviata dal disco rigido e l’installazione FCOS + elaborazione Ignition è completa, il processo di bootstrap OKD inizierà.

# Sulla tua Admin Client Machine, nella directory okd-sno-install
openshift-install wait-for bootstrap-complete --log-level=info
# Questo può richiedere 20-40 minuti.
# Una volta completato il bootstrap:
openshift-install wait-for install-complete --log-level=info
# Questo può richiedere altri 30-60+ minuti.

3. Accesso alla Web Console

Dopo che install-complete termina:

Naviga a: https://console-openshift-console.apps.okd4sno.okd.lan
Accedi usando:
- Username: kubeadmin
- Password: Trovata in okd-sno-install/auth/kubeadmin-password sulla tua Admin Client Machine.

👤 Fase 4: Post-Installazione - Utente e Storage (Admin Client Machine)

Tutti i comandi oc vengono eseguiti dalla tua Admin Client Machine, puntando al tuo nuovo cluster OKD. Assicurati che il tuo KUBECONFIG sia impostato:

export KUBECONFIG="${PWD}/okd-sno-install/auth/kubeconfig"
oc whoami # Dovrebbe mostrare kube:admin

1. Crea un Utente Admin Persistente

Non è raccomandato usare kubeadmin per le operazioni quotidiane. Crea un file htpasswd per un nuovo utente (es. andrea):

htpasswd -c -B -b users.htpasswd andrea LA_TUA_PASSWORD_SICURA_SCELTA
oc create secret generic htpasswd-secret --from-file=htpasswd=users.htpasswd -n openshift-config
rm users.htpasswd # Pulizia

Crea oauth.yaml con il seguente contenuto:

apiVersion: config.openshift.io/v1
kind: OAuth
metadata:
  name: cluster
spec:
  identityProviders:
  - name: local_htpasswd # Dagli un nome univoco
    mappingMethod: claim
    type: HTPasswd
    htpasswd:
      fileData:
        name: htpasswd-secret

Applica la configurazione OAuth:

oc apply -f oauth.yaml

Concedi i diritti cluster-admin al tuo nuovo utente:

oc adm policy add-cluster-role-to-user cluster-admin andrea

Ora puoi fare logout da kubeadmin e login come andrea (selezionando il provider “local_htpasswd”).

2. Configura la StorageClass HostPath per lo Storage Persistente (Setup Lab Semplice)

Questo crea un provisioner hostPath non dinamico, adatto per lab SNO. Sul Nodo VM OKD (via SSH come utente core): Crea la directory che verrà usata dal PersistentVolume.

# Connettiti alla VM OKD: ssh core@192.168.7.126
sudo mkdir -p /mnt/data/pv01
sudo chmod 777 /mnt/data/pv01 # O permessi più restrittivi a seconda del caso d'uso
exit

Sulla tua Admin Client Machine: Crea pv-hostpath.yaml:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-hostpath-10gi # Nome univoco per il PV
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce # Regola se necessario (RWO, ROX, RWX - RWO è tipico per hostPath)
  hostPath:
    path: "/mnt/data/pv01" # Path creato sul nodo VM OKD
  persistentVolumeReclaimPolicy: Retain # O Delete/Recycle
  storageClassName: hostpath-sc # Nome della StorageClass a cui appartiene questo PV

Crea sc-hostpath.yaml:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: hostpath-sc # Deve corrispondere a storageClassName nel PV
provisioner: kubernetes.io/no-provisioner # Indica provisioning manuale del PV
volumeBindingMode: WaitForFirstConsumer
# Per SNO, considera di rendere questa la StorageClass di default:
# metadata:
#   name: hostpath-sc
#   annotations:
#     storageclass.kubernetes.io/is-default-class: "true"

Applica le configurazioni:

oc apply -f pv-hostpath.yaml
oc apply -f sc-hostpath.yaml

🐳 Fase 5: Setup del Local Image Registry (Opzionale)

Questo configura un registry Docker/OCI basato su Podman che gira direttamente sul nodo VM OKD.

1. Esegui il Container Registry sul Nodo VM OKD

Sul Nodo VM OKD (via SSH come utente core):

sudo mkdir -p /opt/registry/data
# Questo comando podman esegue il registry sulla rete host, rendendolo accessibile sulla porta 5000
podman run -d --name registry --restart=always \
  --network host \
  -v /opt/registry/data:/var/lib/registry:z \
  -e REGISTRY_HTTP_ADDR=0.0.0.0:5000 \
  -e REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/var/lib/registry \
  docker.io/library/registry:2 # Usando l'immagine ufficiale da Docker Hub

2. Configura OKD per Fidarsi del Local Registry Insicuro

Sulla tua Admin Client Machine:

oc patch image.config.openshift.io/cluster --type=merge \
  -p '{"spec":{"registrySources":{"insecureRegistries":["192.168.7.126:5000"]}}}'

Nota: Questo attiverà un aggiornamento della machine config sul nodo, che potrebbe richiedere alcuni minuti. Monitora con oc get mcp (Machine Config Pool).

3. Configura Podman/Docker sulle Macchine Client (Opzionale, per il push)

Se vuoi fare push di immagini verso questo registry dalla tua Admin Client Machine o altre macchine di sviluppo, devi configurare i loro strumenti container locali per fidarsi di questo registry insicuro. Crea o modifica /etc/containers/registries.conf (per Podman) o /etc/docker/daemon.json (per Docker) su quelle macchine client.

Per Podman sulla tua Admin Client Machine:

# Modifica /etc/containers/registries.conf (richiede sudo)
# Aggiungi o modifica per includere:
# [[registry]]
# location = "192.168.7.126:5000"
# insecure = true

Riavvia il servizio Podman/Docker se necessario.

Testa l’accesso al registry dalla tua Admin Client Machine:

curl http://192.168.7.126:5000/v2/_catalog
# Output atteso: {"repositories":[]} (se vuoto)

🚀 Fase 6: Deploy di un’Applicazione Go Custom (Esempio)

Questo dimostra come buildare un’applicazione Go, fare push verso il registry locale, e deployarla su OKD.

1. Codice Applicazione e Dockerfile

Sulla tua Admin Client Machine (o macchina di sviluppo): Crea un semplice main.go:

package main

import (
	"fmt"
	"log"
	"net/http"
	"os"
)

func handler(w http.ResponseWriter, r *http.Request) {
	hostname, _ := os.Hostname()
	fmt.Fprintf(w, "Hello from Go! Running on host: %s\n", hostname)
}

func main() {
	http.HandleFunc("/", handler)
	log.Println("Go server starting on port 8080...")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

Crea go.mod (nella stessa directory):

module go-example-rest

go 1.21 # O la tua versione Go

Crea un Dockerfile (multi-stage):

# Stage Builder
FROM golang:1.22-alpine AS builder # Usa una versione Go recente
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
# RUN apk add --no-cache git # Solo se il tuo go get necessita di git
ENV CGO_ENABLED=0
ENV GOOS=linux
ENV GOARCH=amd64
RUN go build -v -o server main.go

# Stage Finale
FROM alpine:latest
RUN apk --no-cache add ca-certificates && adduser -D -u 1001 appuser
WORKDIR /home/appuser/
COPY --from=builder /app/server ./server
# Assicurati che server sia eseguibile, anche se `go build` di solito gestisce questo per binari Linux
# RUN chmod +x ./server
USER appuser
EXPOSE 8080
ENTRYPOINT ["./server"]

2. Build e Push dell’Immagine verso il Local Registry

Sulla tua Admin Client Machine (o dovunque tu abbia Podman/Docker e il codice sorgente):

podman build -t 192.168.7.126:5000/go-example-rest:latest .
podman push --tls-verify=false 192.168.7.126:5000/go-example-rest:latest

3. Deploy dell’Applicazione su OKD

Sulla tua Admin Client Machine:

oc new-project go-example
# Importa l'immagine nel registry interno di OKD dal tuo registry locale
oc import-image go-example-rest --from="192.168.7.126:5000/go-example-rest:latest" --confirm -n go-example

# Deploy dell'applicazione usando l'image stream importato
oc new-app --image-stream=go-example-rest:latest -n go-example
# O più esplicitamente: oc new-app go-example/go-example-rest:latest

# Esponi il service per creare una route
oc expose service/go-example-rest -n go-example

4. Accedi alla Tua Applicazione

Ottieni l’URL della route:

oc get route go-example-rest -n go-example -o jsonpath='{.spec.host}'
# Output esempio: go-example-rest-go-example.apps.okd4sno.okd.lan

Apri http://<route_url> nel tuo browser. Dovresti vedere “Hello from Go!…”

✅ Prerequisiti#

🔧 Fase 1: Preparazione sulla Admin Client Machine#

1. Imposta le Variabili d’Ambiente#

2. Scarica OpenShift Client (oc)#

3. Scarica OpenShift Installer (openshift-install)#

4. Ottieni la ISO Live di Fedora CoreOS (FCOS)#

5. Prepara install-config.yaml#

6. Genera la Configurazione Ignition per Single Node#

7. Incorpora Ignition nella ISO Live FCOS#

⚙️ Fase 2: Creazione della VM Proxmox e Installazione FCOS#

1. Carica la ISO Modificata su Proxmox#

2. Crea la Macchina Virtuale OKD in Proxmox#

3. Installa Fedora CoreOS#

🌐 Fase 3: DNS e Accesso al Cluster#

1. Configurazione DNS (Esempio: OpenWRT)#

2. Monitora l’Installazione dalla Admin Client Machine#

3. Accesso alla Web Console#

👤 Fase 4: Post-Installazione - Utente e Storage (Admin Client Machine)#

1. Crea un Utente Admin Persistente#

2. Configura la StorageClass HostPath per lo Storage Persistente (Setup Lab Semplice)#

🐳 Fase 5: Setup del Local Image Registry (Opzionale)#

1. Esegui il Container Registry sul Nodo VM OKD#

2. Configura OKD per Fidarsi del Local Registry Insicuro#

3. Configura Podman/Docker sulle Macchine Client (Opzionale, per il push)#

🚀 Fase 6: Deploy di un’Applicazione Go Custom (Esempio)#

1. Codice Applicazione e Dockerfile#

2. Build e Push dell’Immagine verso il Local Registry#

3. Deploy dell’Applicazione su OKD#

4. Accedi alla Tua Applicazione#