Bare Metal Deployment

This guide provides instructions for deploying PiVirt directly onto physical bare-metal servers using deployer and out-of-band management protocols (IPMI/Redfish).

Prerequisites

Hardware Requirements

• Control Plane Nodes: Minimum 3 nodes
  • 4+ CPU cores
  • 8+ GB RAM
  • 50+ GB disk
  • IPMI/BMC access
• Worker Nodes: As needed
  • 8+ CPU cores
  • 16+ GB RAM
  • 200+ GB disk
  • IPMI/BMC access
• Network: 1 Gbps+ connectivity
• Storage: Shared storage (iSCSI/NFS) or local storage

Network Requirements

• DHCP or static IP configuration
• PXE boot server (for OS installation)
• IPMI network access
• Management network
• Storage network (optional, for iSCSI)

Deployment Configuration

Cluster Definition

deploy/baremetal-cluster.yaml

apiVersion: deployer.pilab.hu/v1
kind: Deployment
metadata:
  name: "pivirt-cluster-prod"
  namespace: "production"
spec:
  provider: "baremetal"
  topology:
    control_plane:
      count: 3
      profile: "control-plane"
      labels:
        role: "control-plane"
    workers:
      count: 5
      profile: "worker"
      labels:
        role: "worker"

  profiles:
    control-plane:
      cpu: 8
      memory: 32Gi
      disk: 200Gi
      network:
        - name: "mgmt"
          vlan: 10
        - name: "storage"
          vlan: 20
      ipmi:
        address: "10.0.0.{100-102}"
        credentials: "default"

    worker:
      cpu: 16
      memory: 64Gi
      disk: 500Gi
      network:
        - name: "mgmt"
          vlan: 10
        - name: "storage"
          vlan: 20
        - name: "vm"
          vlan: 30
      ipmi:
        address: "10.0.0.{110-114}"
        credentials: "default"

  cloud_init:
    template: "cluster-node.yaml.tmpl"
    vars:
      pivirt_version: "v0.0.89"
      cluster_name: "pivirt-cluster-prod"
      pitrust_ca_server: "pitrust.pilab.hu:8080"

  steps:
    - name: "wait-ssh"
      type: "wait"
      condition: "ssh_ready"
      timeout: "10m"

    - name: "install-agent"
      type: "ansible"
      playbook: "install-pivirt-agent.yaml"
      vars:
        pivirt_version: "v0.0.89"

    - name: "provision-certificates"
      type: "script"
      script: "provision-pitrust-certs.sh"
      env:
        PITRUST_SERVER: "pitrust.pilab.hu:8080"

    - name: "verify-cluster"
      type: "command"
      command: "pvcli cluster get {{ .metadata.name }}"
      retries: 30
      interval: "10s"

Deployer Configuration

/etc/deployer/config.yaml

server:
  grpc_addr: "0.0.0.0:9003"
  http_addr: "0.0.0.0:9004"

providers:
  baremetal:
    enabled: true
    default_bmc_user: "admin"
    default_bmc_password_ref: "vault:secret/data/bmc#password"
    ipmi_lanplus: true
    redfish_insecure: false

templates:
  directory: "/etc/deployer/templates"
  cloud_init:
    default_user: "pivirt"
    ssh_keys_ref: "vault:secret/data/ssh#public_keys"

ssh:
  user: "pivirt"
  key_ref: "vault:secret/data/ssh#private_key"
  known_hosts: "/etc/deployer/known_hosts"
  timeout: "5m"

Deployment Process

1. Plan Deployment

# Review deployment plan
deployer plan -f deploy/baremetal-cluster.yaml

# Check for issues
deployer validate -f deploy/baremetal-cluster.yaml

2. Apply Deployment

# Start deployment
deployer apply -f deploy/baremetal-cluster.yaml

# Or using pvcli
pvcli deploy apply -f deploy/baremetal-cluster.yaml

3. Monitor Progress

# Check deployment status
deployer status -n pivirt-cluster-prod

# View logs
deployer logs -n pivirt-cluster-prod --follow

# Check specific step
deployer step get pivirt-cluster-prod install-agent -o yaml

4. Verify Deployment

# Check cluster status
pvcli cluster get prod-cluster

# Check node status
pvcli cluster node list

# Create test VM
pvcli vm create --name test-vm \
  --image ubuntu-24.04 \
  --cpu 1 \
  --memory 1Gi \
  --disk 10Gi

cloud-init Template

Cluster Node Template

templates/cluster-node.yaml.tmpl

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

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

network:
  version: 2
  ethernets:
    {{- range .interfaces }}
    {{ .name }}:
      match:
        macaddress: {{ .mac }}
      {{- if .dhcp }}
      dhcp4: true
      {{- else }}
      addresses: [{{ .ip }}/{{ .cidr }}]
      routes:
        - to: default
          via: {{ .gateway }}
      nameservers:
        addresses: {{ .dns_servers }}
      {{- end }}
    {{- end }}

packages:
  - qemu-kvm
  - bridge-utils
  - open-iscsi
  - multipath-tools
  - ocfs2-tools
  - pivirt-agent
  - pvcli

write_files:
  - path: /etc/pivirtd/config.yaml
    permissions: "0644"
    content: |
      {{ .pivirtd_config | indent 6 }}

  - path: /etc/pivirt-agent/config.yaml
    permissions: "0644"
    content: |
      {{ .agent_config | indent 6 }}

bootcmd:
  - modprobe kvm_intel
  - modprobe vhost_net
  - systemctl enable --now open-iscsi
  - systemctl enable --now multipathd

runcmd:
  - /usr/local/bin/provision-pitrust-certs.sh
  - systemctl enable --now pivirt-agent
  - systemctl enable --now pivirtd
  - pvcli config use-context production

final_message: "PiVirt node {{ .node_name }} provisioned successfully"

Rollback

# List deployment history
deployer history -n pivirt-cluster-prod

# Rollback to previous version
deployer rollback -n pivirt-cluster-prod --revision 3

# Or rollback to specific revision
deployer rollback -n pivirt-cluster-prod --revision 2

Troubleshooting

Node Won’t Boot

# Check IPMI
ipmitool -I lanplus -H 10.0.0.11 -U admin -P password power status

# Power cycle
ipmitool -I lanplus -H 10.0.0.11 -U admin -P password power cycle

# Check boot device
ipmitool -I lanplus -H 10.0.0.11 -U admin -P password chassis bootdev pxe

SSH Connection Failed

# Test SSH
ssh -i /etc/deployer/ssh/id_rsa root@10.0.0.110

# Check cloud-init
ssh root@10.0.0.110 "cloud-init status --wait"

# Check cloud-init logs
ssh root@10.0.0.110 "journalctl -u cloud-init -f"

Deployment Stuck

# Check deployment status
deployer status -n pivirt-cluster-prod

# View logs
deployer logs -n pivirt-cluster-prod --follow

# Cancel deployment
deployer cancel -n pivirt-cluster-prod

Related

• Deployment Guide
• deployer Guide
• Cluster Bootstrap