Kubernetes Workload Installation

Deploy PiVirt into existing Kubernetes clusters using the official Helm charts or operator manifests to manage hypervisor nodes declaratively.

Prerequisites

• Kubernetes 1.28+
• kubectl configured
• Helm 3.x (optional)
• Nodes with KVM support

Installation Methods

Method 1: Helm (Recommended)

# Add PiVirt Helm repository
helm repo add pivirt https://charts.pilab.hu
helm repo update

# Install PiVirt operator
helm install pivirt pivirt/pivirt-operator \
  --namespace pivirt-system \
  --create-namespace \
  --set operator.replicas=3

# Verify installation
kubectl get pods -n pivirt-system

Method 2: kubectl

# Install CRDs
kubectl apply -f https://github.com/pilab-dev/pivirt/releases/latest/download/crds.yaml

# Install operator
kubectl apply -f https://github.com/pilab-dev/pivirt/releases/latest/download/operator.yaml

# Verify installation
kubectl get pods -n pivirt-system

Create a PiVirt Cluster

cluster.yaml

apiVersion: pivirt.pilab.hu/v1
kind: PiVirtCluster
metadata:
  name: production
  namespace: pivirt-system
spec:
  version: "v0.0.89"

  # Control plane
  controlPlane:
    replicas: 3
    resources:
      requests:
        cpu: "2"
        memory: "4Gi"
      limits:
        cpu: "4"
        memory: "8Gi"
    storage:
      size: "50Gi"
      storageClass: "standard"

  # Workers
  workers:
    replicas: 5
    resources:
      requests:
        cpu: "8"
        memory: "16Gi"
      limits:
        cpu: "16"
        memory: "32Gi"
    storage:
      size: "200Gi"
      storageClass: "standard"

  # Networking
  networking:
    serviceType: LoadBalancer
    externalTrafficPolicy: Local

  # Storage
  storage:
    defaultPool:
      type: "lvm"
      volumeGroup: "pivirtd-vg"
      thinPool: "pivirtd-thin"

  # Security
  security:
    tls:
      enabled: true
      pitrust:
        enabled: true
        operator: true
    rbac:
      enabled: true

# Apply cluster
kubectl apply -f cluster.yaml

# Wait for cluster to be ready
kubectl wait --for=condition=Ready pivirtcluster/production -n pivirt-system --timeout=600s

# Check cluster status
kubectl get pivirtcluster production -n pivirt-system -o yaml

Configuration

High Availability

spec:
  controlPlane:
    replicas: 3  # Minimum 3 for HA
    antiAffinity: true  # Spread across nodes
    podDisruptionBudget:
      minAvailable: 2

Storage Configuration

spec:
  storage:
    defaultPool:
      type: "lvm"
      volumeGroup: "pivirtd-vg"
      thinPool: "pivirtd-thin"

    additionalPools:
      - name: "fast-pool"
        type: "iscsi"
        targetIQN: "iqn.2024-01.hu.pilab:storage"
        portal: "10.0.1.10:3260"

Monitoring

spec:
  monitoring:
    enabled: true
    prometheus:
      serviceMonitor: true
      rules: true
    grafana:
      dashboards: true

Accessing the Cluster

Get Credentials

# Get admin token
kubectl get secret pivirt-admin-token -n pivirt-system -o jsonpath='{.data.token}' | base64 -d

# Get CA certificate
kubectl get secret pivirt-ca-cert -n pivirt-system -o jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt

Configure pvcli

# Get cluster endpoint
ENDPOINT=$(kubectl get service pivirt-agent -n pivirt-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

# Configure pvcli
pvcli config set-context production \
  --endpoint $ENDPOINT:8443 \
  --ca-file ca.crt \
  --token $(kubectl get secret pivirt-admin-token -n pivirt-system -o jsonpath='{.data.token}' | base64 -d)

pvcli config use-context production

Upgrading

# Upgrade operator
helm upgrade pivirt pivirt/pivirt-operator \
  --namespace pivirt-system \
  --set operator.replicas=3

# Upgrade cluster
kubectl patch pivirtcluster production -n pivirt-system \
  --type='merge' \
  -p '{"spec":{"version":"v0.0.90"}}'

# Monitor upgrade
kubectl get pivirtcluster production -n pivirt-system -w

Uninstalling

# Delete cluster
kubectl delete pivirtcluster production -n pivirt-system

# Uninstall operator
helm uninstall pivirt -n pivirt-system

# Delete CRDs
kubectl delete -f https://github.com/pilab-dev/pivirt/releases/latest/download/crds.yaml

# Delete namespace
kubectl delete namespace pivirt-system

Troubleshooting

Check operator logs

kubectl logs -n pivirt-system deployment/pivirt-operator -f

Check cluster status

kubectl describe pivirtcluster production -n pivirt-system

Check pod status

kubectl get pods -n pivirt-system -o wide

Related

• Getting Started
• Bare Metal Installation
• Docker Installation