Declarative Resource Envelope & Model

apiVersion: pivirt.hu/v1GitOps EngineDeclarative Schema

PiVirt manages all infrastructure entities through a declarative, Kubernetes-style resource model. Instead of making imperative API calls to create or mutate virtual hardware, operators define the desired end-state in YAML manifests and submit them via pivirtctl apply -f or the ConnectRPC resource API.

---

The Standard Resource Envelope

Every PiVirt manifest adheres to the standard pivirt.hu/v1 envelope:

apiVersion: pivirt.hu/v1
kind: <KindName>
metadata:
  name: <string>                  # Required: unique name within this kind
  labels:                         # Optional: key-value string metadata
    environment: production
    tier: frontend
  annotations:                    # Optional: non-identifying operational metadata
    pivirt.hu/client-token: "2c9e..."
  ownerReferences:                # Optional: controller references for cascade deletion
    - apiVersion: pivirt.hu/v1
      kind: VirtualMachine
      name: web-01
      uid: "8f3a9e21-bc14-41d3-a55b-4395b0c9a128"
      blockOwnerDeletion: true
spec:
  # Desired state (defined by the operator)
status:
  # Actual state (observed and maintained by pivirtd)
  phase: Running
  observedGeneration: 3

---

Metadata Architecture

1. User Labels vs. Reserved Labels (pivirt.hu/*)

• User Labels: Free-form key-value string pairs used for organizational categorization, querying, and filtering with pivirtctl get -l "env=prod".
• Reserved Namespace (pivirt.hu/*): Strictly protected by admission controllers (ValidateUserLabels). External clients and regular users cannot supply keys prefixed with pivirt.hu/. These are stamped exclusively by the Director and Agent to maintain cluster identity:
  • pivirt.hu/uid: Cluster-wide unique identifier.
  • pivirt.hu/generation: Cluster desired generation counter.
  • pivirt.hu/owner-org: Tenant organization ID for RBAC and billing.
  • pivirt.hu/owner-project: Project ID.
  • pivirt.hu/owner-principal: Identity of resource creator.
  • pivirt.hu/managed-by: Tooling tag (director, terraform, etc.).
  • pivirt.hu/node: Scheduled host node ID.

2. Owner References & Cascade Deletion

Parent-child relationships (e.g. a VirtualMachine owning attached VirtualDisk resources or local Snapshot instances) are tracked via metadata.ownerReferences:

• Cascade deletion follows owner references automatically.
• Setting blockOwnerDeletion: true on a child prevents the parent from being deleted until the child is safely removed (e.g., blocking VM deletion while a backup snapshot is being committed).

3. Decoupled Two-Generation Model

PiVirt keeps cluster generation strictly separated from host-local generation:

• metadata.generation: An integer incremented by pivirtd whenever the local spec changes on disk. The host reconciler updates status.observedGeneration once the hardware state matches.
• pivirt.hu/generation (Label): Managed by the Director and carried opaquely by pivirtd. Direct host edits or maintenance operations never cause false cluster drift.

---

Registered Resource Kinds by Tier

Host Tier Kinds (pivirtd)

The low-level hypervisor runtime daemon (pivirtd) manages physical host-level hardware, QEMU processes, kernel bridges, and local disk allocations:

Kind	Aliases	Primary Responsibility	Documentation
VirtualMachine	vm, vms, virtualmachine	Guest CPU, memory, disks, NICs, UEFI/TPM firmware, and cloud-init	VirtualMachine Spec
StoragePool	pool, pools, storagepool	Local and shared storage mount targets (dir, zfs, lvm, nfs)	StoragePool Spec
VirtualDisk	disk, disks, virtualdisk	Standalone volumes or attached VM disk drives (qcow2, raw)	VirtualDisk Spec
Network	net, nets, network, bridge	Linux bridges, NAT networks, routed gateways, and VLAN trunks	Network Spec
NetworkSegment	segment, segments	Host-local bridge realization and delegated host DHCP ranges	NetworkSegment Spec
DHCPLease	lease, leases, dhcplease	Active host dynamic leases and permanent static IP reservations	DHCPLease Spec
OverlayNetwork	overlay, overlays	OVS multi-host tunnel networks (VXLAN, Geneve)	OverlayNetwork Spec
ExternalIP	ippool, ippools, extip	Public IP bindings (1:1 NAT or port forwards), on the host or inside a VPCRouter	ExternalIP Spec
Snapshot	snap, snaps, snapshot	VM point-in-time disk and RAM checkpoint states (qmp savevm)	Snapshot Spec
PortSecurity	portsecurity, portsec	Per-interface MAC/IP pin, DHCP/RA guard and stateful ACL — the tenant-isolation enforcement point	PortSecurity Spec
VPCRouter	vpcrouter, router, routers	Per-VPC network-namespace router on a gateway node: inside/uplink veths, forwarding, masquerade	VPCRouter Spec

Cluster & Node Tier Kinds (director & agent)

The cluster control plane (director) and node supervisor (agent) manage multi-node IPAM, placement, and tenant isolation:

Kind	Role	Description	Documentation
IPPool	Cluster IPAM	Subnet CIDRs, gateways, DNS servers, and delegated host DHCP blocks	Cluster IPAM Spec
IPAllocation	Port Lease	IP address leases bound to virtual machine network interfaces	Cluster IPAM Spec
IPReservation	Fixed VIP	Pinned IP reservations for infrastructure, routers, or VIPs	Cluster IPAM Spec
Datastore	Storage	Clustered shared storage abstraction across nodes	Storage Guide
PortGroup	Networking	Logical virtual switch port groups with VLAN tagging	Networking Guide
Task	Execution	Cluster and node asynchronous task execution and leases	Architecture
Organization / Project	Tenancy	The org/project namespace every tenant resource carries	Multi-Tenancy
Quota / RoleBinding	Tenancy	Per-namespace limits with usage derived by counting; roles scoped to org/project, org or the cluster	Multi-Tenancy
VPC / Subnet	Networking	One VNI, a CIDR and a router placement per tenant network (planned, PIVIRT-186)	Multi-Tenancy
FloatingIP / SecurityGroup	Networking	Port-bound public addresses; group rules compiled to per-port PortSecurity (planned, PIVIRT-186)	Multi-Tenancy

---

Quick Navigation

VirtualMachine

Provision and configure guest virtual machines.

View VirtualMachine Reference →

DHCPLease & Reservations

Inspect active IP leases and declare static IP reservations.

View DHCPLease Reference →

StoragePool & VirtualDisk

Configure local filesystems, ZFS, and virtual disk images.

View StoragePool Reference →

Network & NetworkSegment

Linux bridges, NAT networks, and delegated host IP ranges.

View Network Reference →