YAML Configuration Schema Reference

ReferenceYAML SchemaAll Components

All PiVirt components use declarative YAML configuration files. This document provides the authoritative schema reference for each daemon and CLI tool.

Default Configuration File Locations

• pivirtd: /etc/pivirtd/config.yaml
• agent: /etc/pivirt-agent/config.yaml
• pvcli: ~/.config/pvcli/config.yaml
• iscsiman: /etc/iscsiman/config.yaml
• deployer: /etc/deployer/config.yaml

Declarative Resource Manifests (pivirtctl apply)

In addition to daemon configuration files, PiVirt uses Kubernetes-style declarative manifests (apiVersion: pivirt.hu/v1) to manage host and cluster virtualization infrastructure objects:

• VirtualMachine: CPU, memory, virtual disks, network interfaces, firmware (UEFI/TPM), and cloud-init user-data.
• StoragePool: Directory, ZFS, Btrfs, LVM, and NFS shared storage mounts.
• VirtualDisk: Standalone disk images and VM-attached volumes.
• Network & OverlayNetwork: Linux bridges, VLAN filtering, and OVS VXLAN/Geneve tunnel overlays.
• ExternalIP / IPPool: Public IP bindings, NAT routing, and port-forwarding rules.
• Snapshot: VM disk and RAM point-in-time state snapshots.

Resource Kinds & Manifest ReferenceField-by-field specifications, YAML examples, and kind aliases for all declarative resources.

Declarative GitOps CLI GuideHow to use pivirtctl apply, get, describe, and delete with label selectors and cascade teardown.

---

Component Configuration Schemas

Select a component tab below to inspect its complete YAML specification:

pivirtd

The hypervisor daemon configuration file controls QEMU runtime parameters, listening endpoints, default storage pools, and network bridge bindings:

/etc/pivirtd/config.yaml

server:
  grpc_addr: "0.0.0.0:9001"
  http_addr: "0.0.0.0:9002"
  tls:
    cert_file: "/etc/pivirtd/tls/server.crt"
    key_file: "/etc/pivirtd/tls/server.key"
    ca_file: "/etc/pivirtd/tls/ca.crt"

hypervisor:
  type: "qemu"
  default_machine_type: "pc-q35-8.0"
  cpu_model: "host-passthrough"

storage:
  default_pool: "default"
  pools: []

network:
  default_bridge: "virbr0"
  bridges: []

logging:
  level: "info"
  format: "json"
  output: "journald"

metrics:
  enabled: true
  path: "/metrics"

agent

The node agent configuration file specifies ConnectRPC endpoint bindings, PiTrust PKI certificate paths, etcd service discovery, and backend socket paths:

/etc/pivirt-agent/config.yaml

server:
  connectrpc:
    addr: "0.0.0.0:8443"
    tls:
      cert_file: "/etc/pivirt-agent/tls/server.crt"
      key_file: "/etc/pivirt-agent/tls/server.key"
      ca_file: "/etc/pivirt-agent/tls/ca.crt"
      client_ca_file: "/etc/pivirt-agent/tls/ca.crt"
  grpc_internal:
    addr: "0.0.0.0:9000"
  metrics:
    addr: "0.0.0.0:8444"
    path: "/metrics"

tls:
  enabled: true
  ca_file: "/etc/pivirt/certs/ca-chain.pem"
  cert_file: "/etc/pivirt/certs/agent-client.crt"
  key_file: "/etc/pivirt/certs/agent-client.key"
  verify_peer: true
  require_client_cert: true

service_discovery:
  type: "etcd"
  etcd:
    endpoints: ["https://etcd-0:2379"]
    ca_file: "/etc/pivirt-agent/etcd/ca.crt"
    cert_file: "/etc/pivirt-agent/etcd/client.crt"
    key_file: "/etc/pivirt-agent/etcd/client.key"
    prefix: "/pivirt/services"

backends:
  pivirtd:
    endpoint: "unix:///run/pivirtd/pivirtd.sock"
    timeout: "30s"
  iscsiman:
    endpoint: "unix:///run/iscsiman/iscsiman.sock"
    timeout: "10s"
  osinfodb:
    endpoint: "https://osinfodb:8443"
    timeout: "30s"

auth:
  oidc:
    issuer_url: "https://auth.pilab.hu/realms/pivirt"
    client_id: "pivirt-agent"
  rbac_policy: "/etc/pivirt-agent/rbac.yaml"

logging:
  level: "info"
  format: "json"
  output: "stdout"

tracing:
  enabled: true
  endpoint: "http://jaeger:14268/api/traces"
  sampling_rate: 0.1

pvcli

The CLI user configuration file manages cluster contexts, mTLS certificates, output formatting defaults, and command aliases:

~/.config/pvcli/config.yaml

current_context: "production"

contexts:
  - name: "development"
    endpoint: "localhost:9001"
    tls:
      insecure: true
  - name: "production"
    endpoint: "pivirtd-prod.pilab.hu:9001"
    tls:
      ca_file: "~/.config/pvcli/ca.crt"
      cert_file: "~/.config/pvcli/client.crt"
      key_file: "~/.config/pvcli/client.key"

output: "table"
namespace: "default"

aliases:
  vm: "virtual-machine"
  svc: "service"
  ns: "namespace"

iscsiman

The storage manager configuration defines iSCSI target/initiator parameters, LIO backend settings, OCFS2 cluster locking, and IPMI fencing:

/etc/iscsiman/config.yaml

server:
  grpc_addr: "0.0.0.0:9002"
  http_addr: "0.0.0.0:9003"
  tls:
    cert_file: "/etc/iscsiman/tls/server.crt"
    key_file: "/etc/iscsiman/tls/server.key"
    ca_file: "/etc/iscsiman/tls/ca.crt"

target:
  backend: "lio"
  iqn_base: "iqn.2024-01.hu.pilab:iscsiman"
  portal:
    address: "0.0.0.0"
    port: 3260
  auth:
    method: "chap"
    incoming_user: "iscsi-user"
    incoming_password_ref: "vault:secret/data/iscsi/chap#incoming"
    outgoing_user: "iscsi-target"
    outgoing_password_ref: "vault:secret/data/iscsi/chap#outgoing"

initiator:
  enabled: true
  iscsid_config: "/etc/iscsi/iscsid.conf"
  discovery:
    portals: ["10.0.1.10:3260", "10.0.1.11:3260"]
    sendtargets: true
  multipath:
    enabled: true
    config: "/etc/multipath.conf"
    default_policy: "service-time"

cluster:
  enabled: true
  name: "pivirt-cluster"
  o2cb:
    stack: "o2cb"
    nodes:
      - name: "node-01"
        ip: "10.0.1.10"
        number: 0
      - name: "node-02"
        ip: "10.0.1.11"
        number: 1
  dlm:
    lockspace: "pivirt-dlm"
    recovery_timeout: "30s"
  fencing:
    enabled: true
    agent: "ipmi"
    device:
      ip: "10.0.0.11"
      user: "admin"
      password_ref: "vault:secret/data/bmc/node-01#password"
      lanplus: true
    action: "reboot"
    timeout: "60s"

storage:
  pools:
    - name: "pivirtd-pool"
      type: "lvm"
      volume_group: "pivirtd-vg"
      thin_pool: "pivirtd-thin"
    - name: "shared-pool"
      type: "file"
      path: "/mnt/shared-storage"
      backend: "nfs"
      nfs_server: "nas.pilab.hu"
      nfs_export: "/exports/pivirt"
      nfs_version: "4.2"

logging:
  level: "info"
  format: "json"
  output: "journald"

metrics:
  enabled: true
  path: "/metrics"

deployer

The deployment automation tool configuration specifies etcd state backends, infrastructure provider credentials, and cloud-init templates:

/etc/deployer/config.yaml

server:
  grpc_addr: "0.0.0.0:9003"
  http_addr: "0.0.0.0:9004"
  tls:
    cert_file: "/etc/deployer/tls/server.crt"
    key_file: "/etc/deployer/tls/server.key"
    ca_file: "/etc/deployer/tls/ca.crt"

state:
  backend: "etcd"
  etcd:
    endpoints: ["https://etcd-0:2379"]
    ca_file: "/etc/deployer/etcd/ca.crt"
    cert_file: "/etc/deployer/etcd/client.crt"
    key_file: "/etc/deployer/etcd/client.key"
    prefix: "/deployer/state"

providers:
  baremetal:
    default_bmc_user: "admin"
    default_bmc_password_ref: "bmc-password"
    ipmi_lanplus: true
    redfish_insecure: false
  vmware:
    default_vcenter: "vcenter.pilab.hu"
    default_user: "administrator@vsphere.local"
    password_ref: "vmware-password"
    insecure: true
    datacenter: "DC1"
    cluster: "PiVirt-Cluster"
  proxmox:
    default_endpoint: "https://proxmox.pilab.hu:8006"
    default_user: "root@pam"
    token_ref: "proxmox-token"
    insecure: true
  aws:
    default_region: "eu-central-1"
    credentials_ref: "aws-credentials"
  gcp:
    default_project: "pilab-prod"
    credentials_ref: "gcp-credentials"

templates:
  directory: "/etc/deployer/templates"
  cloud_init:
    default_user: "pivirt"
    ssh_keys_ref: "ssh-public-keys"
    packages:
      - qemu-kvm
      - bridge-utils
      - open-iscsi
      - multipath-tools

ssh:
  user: "pivirt"
  key_ref: "ssh-private-key"
  known_hosts: "/etc/deployer/known_hosts"
  timeout: "5m"
  proxy_jump: "bastion.pilab.hu"

logging:
  level: "info"
  format: "json"
  output: "journald"

metrics:
  enabled: true
  path: "/metrics"

---

Related Configuration Guides

pivirtd Configuration GuideDetailed breakdown of hypervisor flags, CPU models, and QEMU settings.

agent Configuration GuideConfigure PiTrust PKI, etcd endpoints, and ConnectRPC limits.

Storage Configuration GuideSetup instructions for LVM pools, NFS exports, and iSCSI targets.

Network Configuration GuideConfigure Linux bridges, Open vSwitch, VLAN tags, and VXLAN overlays.