Salta ai contenuti
OpenShift Virtualization per Admin VMware

Comandi base oc e virtctl

Quick reference dei comandi più utili nel quotidiano. Pensata come la “PowerCLI cheat sheet” di chi viene da vSphere: tieni questa pagina aperta finché i comandi non entrano nelle dita.

Indice

  1. Setup CLI
  2. Login e contesto
  3. Navigazione del cluster
  4. Operazioni di base sulle VM
  5. Console, VNC, SSH
  6. Live migration
  7. Snapshot, restore, clone
  8. Manutenzione dei nodi
  9. Risorse, capacity, troubleshooting
  10. Storage e PVC
  11. Networking
  12. Output e formattazione

1. Setup CLI

Le due CLI che usi quotidianamente:

  • oc — la CLI di OpenShift, superset di kubectl. Per qualunque operazione “Kubernetes” generale.
  • virtctl — la CLI specifica per le operazioni VM (start, stop, console, migrate, ssh, …).

Installazione

Terminal window
# oc — scaricabile dal Cluster Operator help della console, oppure:
curl -L https://mirror.openshift.com/pub/openshift-v4/clients/ocp/stable/openshift-client-linux.tar.gz \
  | tar -xz -C ~/.local/bin oc kubectl


# virtctl — disponibile come download dalla stessa console (Help → Command Line Tools)
# Su Linux/macOS:
curl -L -o virtctl <URL_dalla_console>
chmod +x virtctl
sudo mv virtctl /usr/local/bin/

Auto-completamento bash/zsh

Terminal window
# Bash
oc completion bash | sudo tee /etc/bash_completion.d/oc


# Zsh
oc completion zsh > "${fpath[1]}/_oc"

2. Login e contesto

Login

Terminal window
# Con utente/password (LDAP, htpasswd, ecc.)
oc login https://api.miocluster.example.com:6443 -u admin


# Con token (consigliato per CI/CD; il token si copia da console: User → Copy Login Command)
oc login --token=sha256~XXX --server=https://api.miocluster.example.com:6443


# Logout
oc logout

Contesto e namespace di lavoro

Terminal window
# Quale cluster e namespace stai usando?
oc whoami
oc whoami --show-context
oc project


# Cambiare namespace (= "cd" nella folder vCenter)
oc project produzione-app


# Lista namespace
oc get namespace
oc get project   # in OpenShift il "project" è un namespace con annotation extra

Multi-cluster con kubeconfig

Terminal window
# Aggiungere un cluster a kubeconfig
oc login https://api.cluster-b.example.com:6443
oc config get-contexts                         # lista contesti
oc config use-context <nome-contesto>          # switch fra cluster

3. Navigazione del cluster

Visione d’insieme

Terminal window
oc get nodes -o wide                           # lista nodi (= host ESXi)
oc get vm -A                                   # tutte le VM definite
oc get vmi -A                                  # tutte le VM in esecuzione
oc get pods -A                                 # tutti i pod (anche quelli che eseguono le VM)
oc get co                                      # cluster operators e loro stato

Cosa c’è in un namespace

Terminal window
oc get all -n produzione-app                   # vista "tutto" dello namespace
oc get vm,vmi,pvc,svc,route -n produzione-app  # solo le risorse rilevanti per VM

4. Operazioni di base sulle VM

Lifecycle

Terminal window
# Creare una VM da YAML
oc apply -f rhel9-test.yaml


# Avviare una VM
virtctl start rhel9-test -n lab-vm


# Spegnimento "soft" (chiede al qemu-ga di shutdown)
virtctl stop rhel9-test -n lab-vm


# Spegnimento forzato (= power off)
virtctl stop rhel9-test -n lab-vm --force --grace-period=0


# Riavvio
virtctl restart rhel9-test -n lab-vm


# Pausa / ripresa
virtctl pause vm rhel9-test -n lab-vm
virtctl unpause vm rhel9-test -n lab-vm


# Lista VM
oc get vm -n lab-vm
oc get vmi -n lab-vm -o wide                   # include IP e nodo


# Eliminare
oc delete vm rhel9-test -n lab-vm

Modificare una VM

Terminal window
# Editing interattivo (apre $EDITOR)
oc edit vm rhel9-test -n lab-vm


# Patch puntuale
oc patch vm rhel9-test -n lab-vm --type=merge -p '
spec:
  template:
    spec:
      domain:
        cpu:
          cores: 4
'

💡 Modifiche a CPU/RAM richiedono di solito un restart della VM, salvo che hot-plug sia supportato dalla feature/versione.

Ispezionare lo stato

Terminal window
# Vista completa di una VM
oc describe vm rhel9-test -n lab-vm


# Stato in esecuzione (VMI = istanza)
oc get vmi rhel9-test -n lab-vm -o yaml


# Eventi della VM
oc get events -n lab-vm \
  --field-selector involvedObject.name=rhel9-test

5. Console, VNC, SSH

Console seriale

Terminal window
virtctl console rhel9-test -n lab-vm
# Per uscire: Ctrl-]

Console VNC (utile soprattutto per Windows)

Terminal window
virtctl vnc rhel9-test -n lab-vm
# Apre un client VNC locale collegato alla VM

SSH tramite virtctl (port forwarding automatico)

Terminal window
virtctl ssh cloud-user@vm/rhel9-test.lab-vm


# Con chiave specifica
virtctl ssh -i ~/.ssh/id_ed25519 cloud-user@vm/rhel9-test.lab-vm

Port forwarding generico (di un servizio sulla VM)

Terminal window
# Forwarda la porta locale 8080 → porta 80 della VM
virtctl port-forward vm/rhel9-test 8080:80 -n lab-vm

6. Live migration

Terminal window
# Avviare una migrazione manuale
virtctl migrate rhel9-test -n lab-vm


# Verificare lo stato (l'oggetto si chiama VirtualMachineInstanceMigration, alias vmim)
oc get vmim -n lab-vm


# Cancellare una migrazione in corso (se possibile)
virtctl migrate-cancel rhel9-test -n lab-vm


# Storia delle migrazioni di una VM
oc get vmim -n lab-vm -o jsonpath='{range .items[?(@.spec.vmiName=="rhel9-test")]}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end}'

7. Snapshot, restore, clone

Snapshot

Terminal window
# Creare una VirtualMachineSnapshot
oc apply -f - <<EOF
apiVersion: snapshot.kubevirt.io/v1beta1
kind: VirtualMachineSnapshot
metadata:
  name: rhel9-test-pre-upgrade
  namespace: lab-vm
spec:
  source:
    apiGroup: kubevirt.io
    kind: VirtualMachine
    name: rhel9-test
EOF


# Lista
oc get vmsnapshot -n lab-vm


# Eliminare
oc delete vmsnapshot rhel9-test-pre-upgrade -n lab-vm

Restore

Terminal window
oc apply -f - <<EOF
apiVersion: snapshot.kubevirt.io/v1beta1
kind: VirtualMachineRestore
metadata:
  name: rhel9-test-restore-001
  namespace: lab-vm
spec:
  target:
    apiGroup: kubevirt.io
    kind: VirtualMachine
    name: rhel9-test
  virtualMachineSnapshotName: rhel9-test-pre-upgrade
EOF


oc get vmrestore -n lab-vm

⚠️ Per il restore la VM target deve essere spenta.

Clone

Terminal window
# Clone con virtctl (richiede che la VM sorgente sia spenta o che il backend supporti hot clone)
virtctl clone vm rhel9-test --target-name rhel9-test-clone -n lab-vm

Memory dump

Terminal window
virtctl memory-dump get rhel9-test \
  --claim-name=rhel9-test-memdump \
  --create-claim \
  -n lab-vm

8. Manutenzione dei nodi

Maintenance mode “manuale”

Terminal window
# Cordon: il nodo non riceve più nuovi pod/VM
oc adm cordon worker-01.example.com


# Drain: live-migrate le VM, evict i pod
oc adm drain worker-01.example.com \
  --delete-emptydir-data \
  --ignore-daemonsets \
  --force


# Verifica che i pod virt-launcher siano usciti
oc get pods -A --field-selector spec.nodeName=worker-01.example.com


# Quando hai finito: rimettere il nodo in servizio
oc adm uncordon worker-01.example.com

Maintenance dichiarativa (Node Maintenance Operator)

Terminal window
oc apply -f - <<EOF
apiVersion: nodemaintenance.medik8s.io/v1beta1
kind: NodeMaintenance
metadata:
  name: maint-worker-01
spec:
  nodeName: worker-01.example.com
  reason: "Aggiornamento firmware NIC"
EOF


# Stato
oc get nodemaintenance


# Uscire dalla manutenzione
oc delete nodemaintenance maint-worker-01

9. Risorse, capacity, troubleshooting

Uso risorse

Terminal window
# Top dei nodi (richiede metrics-server / monitoring stack)
oc adm top nodes


# Top dei pod in un namespace
oc adm top pods -n produzione-app


# Risorse di un nodo specifico
oc describe node worker-01.example.com | head -50

Logs di troubleshooting

Terminal window
# Log del pod che esegue una VM (virt-launcher)
oc get pods -n lab-vm --selector kubevirt.io/vm=rhel9-test
oc logs -n lab-vm <virt-launcher-pod> -c compute


# Log dell'operator OpenShift Virtualization
oc logs -n openshift-cnv -l name=virt-operator --tail=200


# Log persistenti (se hai logging stack acceso): usa la console UI o LogQL

Debug di un nodo

Terminal window
# Apre una shell privilegiata sul nodo
oc debug node/worker-01.example.com
# Poi dentro:
chroot /host
journalctl -u crio --since "1 hour ago"

”Eventi” del cluster (analoghi al Tasks & Events di vCenter)

Terminal window
# Eventi del namespace, dal più recente
oc get events -n lab-vm --sort-by=.lastTimestamp


# Solo eventi di tipo Warning
oc get events -n lab-vm --field-selector type=Warning

10. Storage e PVC

Terminal window
# Lista PV / PVC / StorageClass
oc get pv
oc get pvc -n lab-vm
oc get storageclass


# Vedere i PVC associati a una VM
oc get vmi rhel9-test -n lab-vm -o jsonpath='{.spec.volumes[*].persistentVolumeClaim.claimName}{"\n"}'


# Espandere un PVC (online resize, se supportato dal driver CSI)
oc patch pvc rhel9-test-root -n lab-vm --type=merge -p '
spec:
  resources:
    requests:
      storage: 100Gi
'


# StorageProfile (capability di una StorageClass dal punto di vista delle VM)
oc get storageprofile

11. Networking

Terminal window
# NetworkAttachmentDefinition
oc get net-attach-def -n produzione-app
oc describe net-attach-def pg-mgmt-vlan100 -n produzione-app


# NMState policies sui nodi
oc get nodenetworkconfigurationpolicy
oc get nodenetworkstate worker-01.example.com -o yaml


# NetworkPolicy
oc get networkpolicy -n produzione-app


# Service e Route
oc get svc -n produzione-app
oc get route -n produzione-app

12. Output e formattazione

Formati utili

Terminal window
oc get vmi -n lab-vm -o wide                   # tabella estesa
oc get vmi -n lab-vm -o yaml                   # YAML completo
oc get vmi -n lab-vm -o json | jq '.items[].status.phase'


# Custom columns
oc get vmi -A -o custom-columns='NS:.metadata.namespace,NAME:.metadata.name,NODE:.status.nodeName,IP:.status.interfaces[0].ipAddress,PHASE:.status.phase'


# JSONPath
oc get vmi -A -o jsonpath='{range .items[?(@.status.phase=="Running")]}{.metadata.namespace}{"/"}{.metadata.name}{" → "}{.status.nodeName}{"\n"}{end}'


# Go template
oc get vm -A -o go-template='{{range .items}}{{.metadata.namespace}}/{{.metadata.name}}: {{.spec.running}}{{"\n"}}{{end}}'

Filtraggio per label

Terminal window
# Tutte le VM con label app=postgres
oc get vm -A -l app=postgres


# Esclusione
oc get vm -A -l 'tier!=db'


# Combinazioni
oc get vm -A -l 'env=prod,team=pagamenti'

Esportare la definizione di una VM (per riusarla altrove)

Terminal window
# Pulisce status e fields gestiti dal cluster
oc get vm rhel9-test -n lab-vm -o yaml \
  | yq 'del(.status, .metadata.uid, .metadata.resourceVersion, .metadata.creationTimestamp, .metadata.generation, .metadata.managedFields)' \
  > rhel9-test.yaml

(Richiede yq. In alternativa puoi usare oc neat se installato come plugin.)

Mini-FAQ rapida

“Come spengo brutalmente una VM bloccata?”

Terminal window
virtctl stop <vm> -n <ns> --force --grace-period=0

“Come trovo su che nodo gira una VM?”

Terminal window
oc get vmi <vm> -n <ns> -o jsonpath='{.status.nodeName}{"\n"}'

“Come vedo l’IP di una VM senza dover entrare in console?”

Terminal window
oc get vmi <vm> -n <ns> -o jsonpath='{.status.interfaces[*].ipAddress}{"\n"}'

(Funziona se il qemu-guest-agent è installato e attivo nella VM.)

“Come vedo tutte le VM accese in tutto il cluster?”

Terminal window
oc get vmi -A --field-selector status.phase=Running

“Come cambio la default StorageClass?”

Terminal window
oc patch storageclass <vecchia-default> -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"false"}}}'
oc patch storageclass <nuova-default> -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

Torna all’indice