VMware vSphere Deployment

This guide covers automating PiVirt cluster deployments onto VMware vSphere and ESXi infrastructure using deployer and vSphere automation APIs.

Prerequisites

VMware Requirements

• vCenter Server 7.0+ or 8.0+
• ESXi hosts with KVM-compatible CPUs (VT-x/AMD-V)
• Shared storage (vSAN, NFS, or VMFS)
• Network with VLAN support
• VM templates for PiVirt nodes

Credentials

/etc/deployer/config.yaml

providers:
  vmware:
    enabled: true
    default_vcenter: "vcenter.pilab.hu"
    default_user: "administrator@vsphere.local"
    password_ref: "vault:secret/data/vmware#password"
    datacenter: "DC1"
    cluster: "PiVirt-Cluster"
    datastore: "vsanDatastore"
    network: "VM Network"
    template_folder: "Templates/PiVirt"

Deployment Configuration

Cluster Definition

deploy/vmware-cluster.yaml

apiVersion: deployer.pilab.hu/v1
kind: Deployment
metadata:
  name: "pivirt-vmware-staging"
spec:
  provider: "vmware"
  topology:
    control_plane:
      count: 3
      template: "pivirt-cp-template"
      customization:
        cpu: 4
        memory: 16Gi
        disk: 100Gi
    workers:
      count: 3
      template: "pivirt-worker-template"
      customization:
        cpu: 8
        memory: 32Gi
        disk: 200Gi

  customization:
    domain: "pilab.hu"
    dns_servers:
      - "10.0.1.5"
      - "10.0.1.6"
    ntp_servers:
      - "time.pilab.hu"
    timezone: "Europe/Budapest"

  cloud_init:
    template: "vmware-node.yaml.tmpl"
    vars:
      pivirt_version: "v0.0.89"
      cluster_name: "pivirt-vmware-staging"

Create VM Templates

Control Plane Template

# Create base VM
govc vm.create \
  -ds=vsanDatastore \
  -net="VM Network" \
  -m=16384 \
  -c=4 \
  -disk=100GB \
  -on=false \
  pivirt-cp-base

# Install Ubuntu 24.04
govc vm.power -on pivirt-cp-base

# Install PiVirt components
# ... (install pivirtd, agent, pvcli)

# Shutdown and convert to template
govc vm.power -off pivirt-cp-base
govc vm.markastemplate pivirt-cp-base

Worker Template

# Similar process for worker template
govc vm.create \
  -ds=vsanDatastore \
  -net="VM Network" \
  -m=32768 \
  -c=8 \
  -disk=200GB \
  -on=false \
  pivirt-worker-base

# Install and configure
# ...

govc vm.markastemplate pivirt-worker-base

Deployment Process

1. Plan Deployment

deployer plan -f deploy/vmware-cluster.yaml

2. Apply Deployment

deployer apply -f deploy/vmware-cluster.yaml

3. Monitor Progress

deployer status -n pivirt-vmware-staging
deployer logs -n pivirt-vmware-staging --follow

4. Verify Deployment

pvcli cluster get staging
pvcli cluster node list

cloud-init Template

templates/vmware-node.yaml.tmpl

#cloud-config
hostname: {{ .node_name }}
fqdn: {{ .node_name }}.pilab.hu

users:
  - name: pivirt
    groups: [sudo, docker, kvm]
    sudo: ALL=(ALL) NOPASSWD:ALL
    ssh_authorized_keys:
      - {{ .ssh_public_key }}

packages:
  - qemu-kvm
  - open-vm-tools
  - pivirt-agent
  - pvcli

runcmd:
  - systemctl enable --now open-vm-tools
  - systemctl enable --now pivirt-agent
  - systemctl enable --now pivirtd

final_message: "PiVirt node {{ .node_name }} provisioned on VMware"

Troubleshooting

VM Won’t Start

# Check vCenter
govc vm.info pivirt-cp-01

# Check logs
govc vm.console pivirt-cp-01

Template Issues

# List templates
govc find -type m -template true

# Convert back to VM
govc vm.markasvm pivirt-cp-base

Related

• Deployment Guide
• deployer Guide