beaker-kubevirt 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42851521ceebcac0549527587051965bce3698a15ea7995f3111db7b481b5ce9
-  data.tar.gz: 4ed638d67f36721a8d656e57096f09ccd4e32c010c642625608ac830de41fea3
+  metadata.gz: 5b2973046f9f272d05b8397362b0cacd9fdb2a7aec80be0e9459d36bce83ee4c
+  data.tar.gz: a6b64fd54c8276ceb60a6904f636e9ff7a380849b652a3c7e51ab5f28848e4f4
 SHA512:
-  metadata.gz: aaef810b582931893e1828c4fcf7cde1d42b86f30ab030ef0937bde204eb1b8cccc4e520e0b0bbbc854c55f774514c27dc5d5f1c00cb8ea41e1d39d632bd137d
-  data.tar.gz: a56cb846fc5bb309755fca675017abd7c66f518bf266b092c26482ed64254f10e4cfae25580217b750dbb747cf2230c8bdd1cf8e8b947c7c5bf3c399bdc23187
+  metadata.gz: 75a0558dd8ad93cc7ef7c70ed129d05754a3998165768f0b94da4046cdd33e3e8d9a20617982c89095023225136afbcf54d1a09014d4957b91a992ca31d22f0e
+  data.tar.gz: b8716d9af99b6d13f86f2ab1df4bca2c6894392a6a2572863fbc5735578d426f1cb212ca9fcd1d81e29e1161ea58e6feeeda281a8b11bf8dc7b91c83b8a528c7

data/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.0](https://github.com/voxpupuli/beaker-kubevirt/tree/1.0.0) (2026-11-05)
+
+[Full Changelog](https://github.com/voxpupuli/beaker-kubevirt/compare/1.0.0...1.0.0)
+
+**Closed issues:**
+
+- Allow the test-group identifier to be supplied via the environment [\#63](https://github.com/voxpupuli/beaker-kubevirt/issues/63)
+- ImagePullBackOff treated as fatal aborts provisioning that would otherwise succeed [\#54](https://github.com/voxpupuli/beaker-kubevirt/issues/54)
+
+**Merged pull requests:**
+
+- Update voxpupuli-rubocop to ~\> 5.3.0 and fix new offenses [\#86](https://github.com/voxpupuli/beaker-kubevirt/pull/86) ([silug](https://github.com/silug))
+- Add kubevirt\_labels and kubevirt\_annotations [\#85](https://github.com/voxpupuli/beaker-kubevirt/pull/85) ([jaevans](https://github.com/jaevans))
+- Add kubevirt\_storage\_class for the root disk [\#84](https://github.com/voxpupuli/beaker-kubevirt/pull/84) ([jaevans](https://github.com/jaevans))
+- Add kubevirt\_node\_selector and kubevirt\_tolerations [\#83](https://github.com/voxpupuli/beaker-kubevirt/pull/83) ([jaevans](https://github.com/jaevans))
+- Honour BEAKER\_kubevirt\_disk\_cache [\#82](https://github.com/voxpupuli/beaker-kubevirt/pull/82) ([jaevans](https://github.com/jaevans))
+- Add kubevirt\_disk\_cache option for the root disk cache mode [\#77](https://github.com/voxpupuli/beaker-kubevirt/pull/77) ([silug](https://github.com/silug))
+- Update voxpupuli-rubocop requirement from ~\> 5.2.0 to ~\> 5.3.0 [\#72](https://github.com/voxpupuli/beaker-kubevirt/pull/72) ([dependabot[bot]](https://github.com/apps/dependabot))
+- Add kubevirt\_cpu\_request and kubevirt\_cpu\_limit [\#66](https://github.com/voxpupuli/beaker-kubevirt/pull/66) ([jaevans](https://github.com/jaevans))
+- Detect an unschedulable virt-launcher pod instead of waiting out the timeout [\#65](https://github.com/voxpupuli/beaker-kubevirt/pull/65) ([jaevans](https://github.com/jaevans))
+- feat: allow the test-group identifier to be supplied via the environment [\#64](https://github.com/voxpupuli/beaker-kubevirt/pull/64) ([jaevans](https://github.com/jaevans))
+- Remove CodeQL workflow in favor of default setup [\#62](https://github.com/voxpupuli/beaker-kubevirt/pull/62) ([silug](https://github.com/silug))
+- Give image pull backoff a grace window before failing [\#55](https://github.com/voxpupuli/beaker-kubevirt/pull/55) ([jaevans](https://github.com/jaevans))
+
 ## [1.0.0](https://github.com/voxpupuli/beaker-kubevirt/tree/1.0.0) (2026-07-17)
 
 [Full Changelog](https://github.com/voxpupuli/beaker-kubevirt/compare/a388e545ac4aa46006e53f006ad5af1a243bdbbd...1.0.0)

data/README.md

@@ -78,21 +78,33 @@ CONFIG:
 | `networks` | Custom network configuration | No | Auto-generated | HOSTS (per-host) |
 | `kubevirt_ssh_key` | SSH public key path or content | Yes | Auto-detect from `~/.ssh/` | HOSTS (per-host) |
 | `kubevirt_cpus` | CPU cores for VM | No | `1` | HOSTS (per-host) |
+| `kubevirt_cpu_request` | CPU request for the VM pod, as a Kubernetes CPU quantity (`2`, `1500m`). Unset leaves KubeVirt to derive it from `kubevirt_cpus` divided by the cluster's `cpuAllocationRatio`. Set it for guests that must not be throttled while booting. | No | unset | HOSTS (per-host), CONFIG |
+| `kubevirt_cpu_limit` | CPU limit for the VM pod, as a Kubernetes CPU quantity. Unset leaves the compute container burstable. | No | unset | HOSTS (per-host), CONFIG |
 | `kubevirt_memory` | Memory for VM | No | `2Gi` | HOSTS (per-host) |
 | `kubevirt_memory_overhead` | Extra memory added to the guest for the virt-launcher container memory limit. Raise this for Windows guests that OOMKill with the default. | No | `512Mi` | HOSTS (per-host), CONFIG |
 | `kubevirt_memory_request` | Memory request for the VM pod. | No | Same as `kubevirt_memory` | HOSTS (per-host), CONFIG |
 | `kubevirt_disk_size` | Size of the root disk | No | `10Gi` | HOSTS (per-host) |
+| `kubevirt_storage_class` | Storage class for the root disk's DataVolume, used when `kubevirt_vm_image` is an `http(s)://` URL or a PVC to clone. Unset uses the cluster's default storage class. A `docker://`/`oci://` containerDisk has no DataVolume and ignores it. Cloning a PVC into a different class may make CDI copy the data instead of using a CSI clone. A non-empty `BEAKER_kubevirt_storage_class` environment variable overrides the host and CONFIG values. | No | cluster default | `BEAKER_kubevirt_storage_class`, HOSTS (per-host), CONFIG |
 | `kubevirt_cloud_init` | Custom cloud-init YAML | No | Auto-generated | HOSTS (per-host) |
 | `kubevirt_vm_ssh_port` | SSH port inside the VM | No | `22` | HOSTS (per-host) |
 | `kubevirt_readiness_probe_disabled` | Skip the VMI SSH readinessProbe. Default is `false` for pod-network modes and `true` for `multus` (where a probe from the virt-launcher netns typically can't reach a bridge-only guest). | No | mode-dependent | HOSTS (per-host), CONFIG |
 | `kubevirt_readiness_probe` | Probe tuning hash (snake_case keys): `initial_delay_seconds` (30), `period_seconds` (10), `timeout_seconds` (3), `failure_threshold` (60), `success_threshold` (1). The default failure budget (600s) accommodates slow Windows first-boots. When the probe is enabled, `timeout` is auto-raised to cover this budget. | No | see description | HOSTS (per-host), CONFIG |
+| `kubevirt_unschedulable_grace` | Seconds the virt-launcher pod may stay unschedulable (`PodScheduled=False`, reason `Unschedulable` or `SchedulerError`) before provisioning gives up and reports the scheduler's own message. Cannot be immediate — an unschedulable pod is precisely what tells a cluster autoscaler to add a node. Bounded by the effective `timeout`, which this does not raise. | No | `300` | HOSTS (per-host), CONFIG |
+| `kubevirt_image_pull_grace` | Seconds a containerDisk pull may sit in `ImagePullBackOff`/`ErrImagePull` before provisioning gives up. kubelet retries pulls, so a cold pull-through cache, a slow upstream registry or a dropped connection normally clears on a later attempt. Bounded by the effective `timeout` (which this does not raise), and skipped when the registry's error is definitive — `manifest unknown`, containerd's `failed to resolve reference …: not found` for a missing tag, `pull access denied`, `requested access to the resource is denied`, `unauthorized: authentication required` — so a typo'd tag or a refused credential fails on the first poll that shows the error. A blob 404 from a cold cache, or a `permission denied` from the network, gets the window. Set it to `0` to switch the window off and fail on the first backoff, as provisioning did before this option existed. The first backoff seen for each container is logged as a warning, so a run that reaches `timeout` before the window ends still records why. | No | `600` | HOSTS (per-host), CONFIG |
 | `kubevirt_disable_virtio` | Disable virtio devices (for Windows compatibility). If set to true the disk bus will be set to `sata` and the network adapter will be model `e1000` | No | `false` | HOSTS (per-host) |
+| `kubevirt_disk_cache` | Cache mode for the root disk: `none`, `writethrough` or `writeback`. Unset leaves the choice to KubeVirt (`none` when the backing store supports O_DIRECT). `writeback` lets the virt-launcher's page cache absorb guest writes until the guest flushes; use it for throwaway test VMs on slow or shared storage, where a lost VM only costs a re-run. A non-empty `BEAKER_kubevirt_disk_cache` environment variable overrides both. | No | unset | `BEAKER_kubevirt_disk_cache`, HOSTS (per-host), CONFIG |
+| `kubevirt_node_selector` | Hash of node labels the VM's pod must match, e.g. `{ 'node-pool.example.com/ci' => 'true' }`. Select a group of nodes by a label they share, not a single node by name. Quote values that look like decimals (`'1.10'`): an unquoted float is refused, since YAML would read `1.10` as `1.1`. `BEAKER_kubevirt_node_selector`, a comma-separated list of `key=value` pairs, replaces the host and CONFIG values when non-empty. | No | unset | `BEAKER_kubevirt_node_selector`, HOSTS (per-host), CONFIG |
+| `kubevirt_tolerations` | List of taints the VM's pod tolerates. Each entry is a hash with `key`, `effect` (`NoSchedule`, `PreferNoSchedule` or `NoExecute`) and an optional `value`; an entry without a value tolerates the key whatever its value. Other fields (`operator`, `tolerationSeconds`) are refused rather than ignored. Tolerating a taint only allows the VM onto those nodes; pair it with `kubevirt_node_selector` to keep it on them. `BEAKER_kubevirt_tolerations`, a comma-separated list of `key=value:Effect` or `key:Effect` entries, replaces the host and CONFIG values when non-empty. | No | unset | `BEAKER_kubevirt_tolerations`, HOSTS (per-host), CONFIG |
+| `kubevirt_labels` | Hash of extra labels for every resource beaker labels: the VM, its template (and so the VMI and virt-launcher pod), the root DataVolume and the cloud-init Secret. `beaker/test-group`, `beaker/host` and `kubevirt.io/vm` are beaker's own and raise an error if set here, as does a key or value that is not valid Kubernetes label syntax (values are at most 63 characters of letters, digits, `-`, `_` and `.`). `BEAKER_kubevirt_labels`, a comma-separated list of `key=value` pairs, replaces the host and CONFIG values when non-empty. A host's hash replaces the CONFIG hash rather than merging with it. | No | unset | `BEAKER_kubevirt_labels`, HOSTS (per-host), CONFIG |
+| `kubevirt_annotations` | Hash of annotations for the VM template only (and so the VMI and virt-launcher pod), e.g. `cluster-autoscaler.kubernetes.io/safe-to-evict: "false"`. Keys must be valid Kubernetes keys; values are free text. `BEAKER_kubevirt_annotations`, a comma-separated list of `key=value` pairs, replaces the host and CONFIG values when non-empty. A host's hash replaces the CONFIG hash rather than merging with it; values given that way cannot contain commas, so set complex values in the hosts file. | No | unset | `BEAKER_kubevirt_annotations`, HOSTS (per-host), CONFIG |
 
 **Important**: The `namespace`, `kubeconfig`, and `kubecontext` options must be specified in the global `CONFIG` section, not per-host. All VMs will be created in the same Kubernetes namespace.
 
 Notes:
 - Several per-host options support global fallbacks via `CONFIG` (e.g., `kubevirt_cpus`, `kubevirt_memory`, `kubevirt_vm_ssh_port`).
 - The `networks` key for Multus is intentionally unprefixed (use `networks`, not `kubevirt_networks`).
+- `kubevirt_cpus` sets the guest's core count, which is not the same thing as the pod's CPU request. Left to itself, KubeVirt divides the core count by the cluster's `cpuAllocationRatio` — 10 by default — so a 2-core guest lands in a burstable pod requesting `200m`. On a busy node that guest is throttled to roughly a tenth of what it advertises, and a slow first boot can outlast the readiness probe's failure budget while nothing anywhere reports an error. Set `kubevirt_cpu_request` when boot time matters; Windows guests are the usual case.
+- A virt-launcher pod the scheduler cannot place used to be invisible: its phase is `Pending`, not `Failed`, and it carries no container statuses at all, so provisioning waited out the full `timeout` and reported `Timeout waiting for VM ... to be ready` — indistinguishable from a slow guest boot. It now reports the scheduler's own message (`0/8 nodes are available: 5 Insufficient cpu`) as soon as the state is seen, and fails after `kubevirt_unschedulable_grace`. Raise `kubevirt_memory_request` or a CPU request beyond what a node can offer and this is the error you will get.
 - Long-running commands aren't killed by idle-timeout drops, even when output streams in only one direction (e.g., a Windows scanner running for many minutes). The `port-forward` proxy no longer enforces a client-side read-silence timeout (it relied on net-ssh keepalive packets that net-ssh suppresses while server output is flowing) and instead sends a WebSocket protocol ping every 60s to keep the upstream tunnel alive. net-ssh keepalive defaults are also tightened to `keepalive_interval: 60`, `keepalive_maxcount: 5` — Beaker already enables `keepalive: true` — which protects `multus` and `nodeport` modes against NAT/conntrack timeouts. Override per-host under `ssh:` if needed.
 
 ### VM Image Formats
@@ -254,6 +266,29 @@ All resources created are labeled for traceability and cleanup:
 
 These labels are used during `cleanup` to remove VMs, secrets, and services associated with the test group.
 
+### Supplying the test-group identifier
+
+By default the test-group identifier is `beaker-<random hex>`, generated per process. Set `BEAKER_KUBEVIRT_TEST_GROUP` to choose it instead:
+
+```bash
+BEAKER_KUBEVIRT_TEST_GROUP="beaker-ci-${CI_JOB_ID}" bundle exec rake beaker
+```
+
+This matters when something outside the beaker process has to clean up after it. In CI, a cancelled job can be killed before beaker tears anything down, and with a random identifier the job has no way to name the resources it leaked. With a known identifier the job can delete by `beaker/test-group=<its own identifier>` once beaker is gone, without disturbing other runs that share the namespace:
+
+```bash
+kubectl -n "$namespace" delete vm,dv,secret,svc -l "beaker/test-group=beaker-ci-${CI_JOB_ID}"
+```
+
+The identifier must be unique to each run that can be live at the same time. It names the VMs, DataVolumes and Secrets as well as labelling them, so two runs that share it collide on create, and either run's cleanup deletes the other's resources. `CI_JOB_ID` is unique per job on GitLab. On GitHub Actions, `GITHUB_RUN_ID` is not: every job and matrix leg of a run shares it, and so do re-run attempts. Combine it with the attempt, the job and the matrix index, keeping the result within 63 characters (a longer value is refused rather than truncated, since truncation would cut off the part that tells runs apart):
+
+```yaml
+env:
+  BEAKER_KUBEVIRT_TEST_GROUP: beaker-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}-${{ strategy.job-index }}
+```
+
+Values that are not valid Kubernetes label values are sanitized (and a warning is logged), so prefer an identifier that is already label-safe — otherwise the label will not be the string you set.
+
 ## Requirements
 
 - KubeVirt and Kubernetes cluster access via `kubeconfig`

data/examples/hosts.yaml

@@ -8,6 +8,11 @@ HOSTS:
     kubevirt_network_mode: port-forward
     kubevirt_ssh_key: ~/.ssh/id_rsa.pub
     kubevirt_cpus: 2
+    # Guest core count is not the pod's CPU request: without kubevirt_cpu_request
+    # KubeVirt divides the cores by the cluster's cpuAllocationRatio (default 10),
+    # so these 2 cores request only 200m and get throttled on a busy node.
+    # kubevirt_cpu_request: 2
+    # kubevirt_cpu_limit: 2
     kubevirt_memory: 4Gi
     # Extra memory added to the guest for the virt-launcher container memory
     # limit. Bump this for Windows guests that get OOMKilled with the default.

data/lib/beaker/hypervisor/kubevirt.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require 'digest'
 require 'yaml'
 require 'base64'
 require 'socket'
@@ -53,10 +54,61 @@ module Beaker
 
     # VMI phases that indicate the VM will never reach Running.
     VMI_TERMINAL_PHASES = %w[Failed Succeeded].freeze
+
+    # Values KubeVirt accepts for a disk's cache mode
+    DISK_CACHE_MODES = %w[none writethrough writeback].freeze
+    # Taint effects a toleration may name
+    TOLERATION_EFFECTS = %w[NoSchedule PreferNoSchedule NoExecute].freeze
+    # Fields a kubevirt_tolerations entry may set
+    TOLERATION_FIELDS = %w[key value effect].freeze
+    # Labels beaker sets itself; cleanup and the NodePort service select on them
+    RESERVED_LABEL_KEYS = %w[beaker/test-group beaker/host kubevirt.io/vm].freeze
+    # Kubernetes label values, and the name part of label and annotation keys
+    LABEL_NAME_RE = /\A(?:[A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]\z/
+    # The optional prefix of a label or annotation key (an RFC 1123 subdomain)
+    KEY_PREFIX_RE = /\A[a-z0-9](?:[-a-z0-9]*[a-z0-9])?(?:\.[a-z0-9](?:[-a-z0-9]*[a-z0-9])?)*\z/
+    KEY_PREFIX_MAX = 253
     # virt-launcher container waiting reasons we treat as fatal.
-    FATAL_CONTAINER_WAITING_REASONS = %w[CrashLoopBackOff ImagePullBackOff ErrImagePull].freeze
+    FATAL_CONTAINER_WAITING_REASONS = %w[CrashLoopBackOff].freeze
+    # virt-launcher container waiting reasons that mean an image pull is being
+    # retried. kubelet re-attempts these with increasing backoff, and a cold
+    # pull-through cache, a slow upstream or a transient network error all clear
+    # without intervention — so they are only fatal once they persist (see
+    # DEFAULT_IMAGE_PULL_GRACE).
+    IMAGE_PULL_WAITING_REASONS = %w[ImagePullBackOff ErrImagePull].freeze
+    # How long an image pull may stay in backoff before we give up on it, unless
+    # overridden with :kubevirt_image_pull_grace. Still bounded by the overall
+    # wait_for_vm_ready timeout, which this does not extend.
+    DEFAULT_IMAGE_PULL_GRACE = 600
+    # Pull failures kubelet's retry will never fix — a bad tag, a missing repo or
+    # a rejected credential. Failing these immediately keeps a typo'd image as
+    # fast to diagnose as it was before the grace window existed. Transport-level
+    # failures (EOF, connection reset, timeouts) deliberately do not match. The
+    # patterns are anchored to the registry's and containerd's own wording: a
+    # bare "not found" would catch a cold pull-through cache's blob 404, and a
+    # bare "denied" would catch `connect: permission denied` from a network flap,
+    # both of which are what the window is for. containerd reports a missing tag
+    # as `failed to resolve reference "<ref>": <ref>: not found`; resolving is
+    # the tag/manifest lookup, never a blob fetch.
+    DEFINITIVE_IMAGE_PULL_FAILURE_RE = Regexp.union(
+      /manifest unknown/i,
+      /failed to resolve reference .*: not found/i,
+      /pull access denied/i,
+      /requested access to the resource is denied/i,
+      /unauthorized: authentication required/i,
+    )
     # virt-launcher container termination reasons we treat as fatal.
     FATAL_CONTAINER_TERMINATED_REASONS = %w[OOMKilled Error ContainerCannotRun].freeze
+    # PodScheduled=False reasons that mean the scheduler cannot place the virt-launcher pod.
+    # SchedulingGated is deliberately excluded: a gated pod is being held on purpose by
+    # whoever set the gate, and is not the cluster failing to find room.
+    UNSCHEDULABLE_POD_REASONS = %w[Unschedulable SchedulerError].freeze
+    # How long the virt-launcher pod may stay unschedulable before provisioning gives up,
+    # unless overridden with :kubevirt_unschedulable_grace. This cannot be immediate: a
+    # cluster autoscaler treats an unschedulable pod as its cue to add a node, and a node
+    # returning from a drain or reboot frees capacity on its own — both take minutes. Still
+    # bounded by the overall wait_for_vm_ready timeout, which this does not extend.
+    DEFAULT_UNSCHEDULABLE_GRACE = 300
 
     ##
     # Create a new instance of the KubeVirt hypervisor object
@@ -72,6 +124,12 @@ module Beaker
     # @option options [String] :kubevirt_network_mode Network mode (port-forward, nodeport, multus)
     # @option options [String] :kubevirt_ssh_key SSH public key to inject
     # @option options [String] :kubevirt_cpus CPU resources for VM
+    # @option options [String] :kubevirt_cpu_request CPU request for the VM pod, as a Kubernetes
+    #   CPU quantity ('2', '1500m'). Unset by default, which leaves KubeVirt to derive the request
+    #   from the guest core count divided by the cluster's cpuAllocationRatio (default 10). Set it
+    #   for guests that must not be throttled while booting -- Windows especially.
+    # @option options [String] :kubevirt_cpu_limit CPU limit for the VM pod, as a Kubernetes CPU
+    #   quantity. Unset by default, which leaves the compute container burstable.
     # @option options [String] :kubevirt_memory Memory resources for VM
     # @option options [String] :kubevirt_memory_overhead Extra memory added to guest for the
     #   container memory limit (default: '512Mi'). Needed for Windows guests where KubeVirt's
@@ -89,7 +147,21 @@ module Beaker
     #   (period_seconds * failure_threshold = 600s) accommodates slow Windows first-boots.
     # @option options [Integer] :timeout Timeout for operations. When the readiness probe is
     #   enabled, the effective wait is max(:timeout, probe budget + 60s).
+    # @option options [Integer] :kubevirt_image_pull_grace How long a containerDisk pull may
+    #   stay in ImagePullBackOff/ErrImagePull before it is treated as fatal (default: 600s).
+    #   kubelet retries image pulls, so a cold pull-through cache or a slow registry clears on
+    #   its own. Bounded by (and does not extend) the effective :timeout above, and skipped
+    #   entirely when the pull failure is definitive (an unknown manifest or tag, or the
+    #   registry refusing access).
+    #   Set it to 0 to switch the window off and fail on the first backoff, as this check
+    #   did before the option existed.
+    # @option options [Integer] :kubevirt_unschedulable_grace How long the virt-launcher pod may
+    #   remain unschedulable before it is treated as fatal (default: 300s). An unschedulable pod
+    #   is what triggers a cluster autoscaler to add a node, so this cannot be immediate.
+    #   Bounded by (and does not extend) the effective :timeout above.
     # @option options [Boolean] :kubevirt_disable_virtio Disable virtio devices (for compatibility with Windows)
+    # @option options [String] :kubevirt_disk_cache Cache mode for the root disk: none, writethrough
+    #   or writeback. Unset leaves the choice to KubeVirt.
     def initialize(kubevirt_hosts, options)
       require 'beaker/hypervisor/kubevirt_helper'
 
@@ -105,9 +177,16 @@ module Beaker
       @hosts = kubevirt_hosts
       # Ensure the helper gets the validated namespace
       @kubevirt_helper = KubevirtHelper.new(@options)
-      @test_group_identifier = "beaker-#{SecureRandom.hex(4)}"
+      @test_group_identifier = configured_test_group_identifier || "beaker-#{SecureRandom.hex(4)}"
       @cleanup_called = false
       @cleanup_mutex = Mutex.new
+      # "<pod_name>/<container>" => monotonic timestamp the container was first
+      # seen backing off an image pull. Cleared once it is running or terminated.
+      @image_pull_backoff_since = {}
+      # vm_name => { uid:, since: } — the virt-launcher pod's UID and the monotonic
+      # timestamp it was first seen unschedulable. Cleared as soon as the scheduler
+      # places it; restarted when a pod with a different UID replaces it.
+      @unschedulable_since = {}
 
       # Register at_exit handler to ensure cleanup happens even on non-success exits
       # This handles cases like Ctrl+C, errors, or test failures that occur after
@@ -277,7 +356,7 @@ module Beaker
       if vm_image&.start_with?('http://', 'https://')
         base_name = vm_image.split('/').last
         # Create a unique datavolume name by including the VM name in it
-        host['dv_name'] = sanitize_k8s_name("#{vm_name}-#{base_name}-dv")
+        host['dv_name'] = bounded_k8s_name("#{vm_name}-#{base_name}-dv")
       elsif vm_image && !vm_image.start_with?('docker://', 'oci://')
         # For PVC sources, we also need to clone to avoid sharing the same disk
         source_pvc = vm_image.sub(%r{^pvc://}, '')
@@ -287,7 +366,7 @@ module Beaker
         else
           source_pvc_name = source_pvc
         end
-        host['dv_name'] = sanitize_k8s_name("#{vm_name}-#{source_pvc_name}")
+        host['dv_name'] = bounded_k8s_name("#{vm_name}-#{source_pvc_name}")
 
       end
 
@@ -309,7 +388,7 @@ module Beaker
     def create_cloud_init_secret(host, cloud_init_data)
       raise 'Cloud-init data must be provided' unless cloud_init_data
 
-      secret_name = "#{host['vm_name']}-cloud-init"
+      secret_name = bounded_k8s_name("#{host['vm_name']}-cloud-init")
       @logger.debug("Creating cloud-init secret #{secret_name} in namespace #{@namespace}")
 
       secret_spec = {
@@ -337,7 +416,25 @@ module Beaker
     # @return [String] The generated VM name
     def generate_vm_name(host)
       host_name = host.respond_to?(:name) ? host.name : host['name']
-      sanitize_k8s_name("#{@test_group_identifier}-#{host_name}")
+      bounded_k8s_name("#{@test_group_identifier}-#{host_name}")
+    end
+
+    ##
+    # Sanitize a name to a DNS label, keeping distinct inputs distinct when
+    # they exceed the 63-char cap.
+    #
+    # Plain truncation drops the tail, which is where the host name (or a
+    # suffix such as "-ssh") sits, so hosts sharing a long test-group
+    # identifier would collide. At the cap the tail is replaced with a digest
+    # of the untruncated name instead.
+    # @param [String] full_name The unsanitized name
+    # @return [String] A valid DNS label of at most 63 characters
+    def bounded_k8s_name(full_name)
+      name = sanitize_k8s_name(full_name)
+      return name if name.length < K8S_NAME_MAX
+
+      digest = Digest::SHA256.hexdigest(full_name)[0, 8]
+      "#{name[0, K8S_NAME_MAX - digest.length - 1].sub(/-+\z/, '')}-#{digest}"
     end
 
     ##
@@ -442,12 +539,128 @@ module Beaker
       find_ssh_key_pair[:public_key]
     end
 
+    ##
+    # An externally supplied test-group identifier, from
+    # BEAKER_KUBEVIRT_TEST_GROUP.
+    #
+    # A caller that outlives the beaker process needs to be able to find this
+    # run's resources. CI is the motivating case: when a job is cancelled, the
+    # beaker process can be killed before it tears anything down, and a random
+    # per-process identifier leaves the job no way to name what it leaked.
+    # Deleting by `beaker/test-group=<the identifier it chose>` cleans up that
+    # run without touching other runs sharing the namespace.
+    #
+    # @return [String, nil] the sanitized identifier, or nil when unset or blank
+    def configured_test_group_identifier
+      raw = ENV.fetch('BEAKER_KUBEVIRT_TEST_GROUP', '')
+      return nil if raw.strip.empty?
+
+      # Truncating would cut off the tail, which is usually the part that tells
+      # runs apart (job ID, matrix index), and give concurrent runs one label.
+      if raw.strip.length > LABEL_VALUE_MAX
+        raise ArgumentError, "BEAKER_KUBEVIRT_TEST_GROUP must be at most #{LABEL_VALUE_MAX} characters, " \
+                             "got #{raw.strip.length}: #{raw.inspect}"
+      end
+
+      identifier = sanitize_k8s_label_value(raw)
+      if identifier != raw
+        @logger.warn(
+          "BEAKER_KUBEVIRT_TEST_GROUP #{raw.inspect} is not usable as a Kubernetes " \
+          "label value; using #{identifier.inspect} instead",
+        )
+      end
+      identifier
+    end
+
     def get_labels(host)
       raw_name = host.respond_to?(:name) ? host.name : host['name']
-      {
+      user_labels(host).merge(
         'beaker/test-group' => @test_group_identifier,
         'beaker/host' => sanitize_k8s_label_value(raw_name),
-      }
+      )
+    end
+
+    ##
+    # Extra labels for every resource that carries beaker's own labels, from
+    # BEAKER_kubevirt_labels, the host or the global CONFIG, in that order.
+    # Cleanup finds resources by beaker/test-group, so the keys beaker sets
+    # itself are refused rather than silently overridden.
+    # @param [Host] host The host configuration
+    # @return [Hash{String=>String}] The labels, empty when unset
+    def user_labels(host)
+      labels = key_value_option(host, 'kubevirt_labels')
+      reserved = labels.keys & RESERVED_LABEL_KEYS
+      raise ArgumentError, "kubevirt_labels may not set #{reserved.join(', ')}; beaker sets those itself" unless reserved.empty?
+
+      labels.each do |key, value|
+        next if value.empty? || (value.length <= LABEL_VALUE_MAX && LABEL_NAME_RE.match?(value))
+
+        raise ArgumentError, "kubevirt_labels value for #{key.inspect} must be at most #{LABEL_VALUE_MAX} characters of " \
+                             "letters, digits, '-', '_' or '.', starting and ending with a letter or digit, got #{value.inspect}"
+      end
+      labels
+    end
+
+    ##
+    # Extra annotations for the VM template, and so for the VMI and its
+    # virt-launcher pod, from BEAKER_kubevirt_annotations, the host or the
+    # global CONFIG, in that order.
+    # @param [Host] host The host configuration
+    # @return [Hash{String=>String}, nil] The annotations, or nil when unset
+    def user_annotations(host)
+      annotations = key_value_option(host, 'kubevirt_annotations')
+      annotations unless annotations.empty?
+    end
+
+    ##
+    # A hash option that BEAKER_<name> may replace with a comma-separated list
+    # of key=value pairs. Only the first = in a pair separates key from value.
+    # @param [Host] host The host configuration
+    # @param [String] name The option name
+    # @return [Hash{String=>String}] The option, empty when unset
+    def key_value_option(host, name)
+      env = env_option(name)
+      value = env ? parse_key_values(name, env) : host[name] || @options[name.to_sym]
+      return {} if value.nil?
+      raise ArgumentError, "#{name} must be a hash of keys to values, got #{value.inspect}" unless value.is_a?(Hash)
+
+      value.to_h do |key, val|
+        key = key.to_s
+        unless qualified_key?(key)
+          raise ArgumentError, "#{name} key #{key.inspect} is not a valid Kubernetes key: expected an optional DNS subdomain " \
+                               "prefix and '/', then a name of at most #{LABEL_VALUE_MAX} characters of letters, digits, " \
+                               "'-', '_' or '.', starting and ending with a letter or digit"
+        end
+
+        raise ArgumentError, "#{name} value for #{key.inspect} must be a single value, got #{val.inspect}" if val.is_a?(Hash) || val.is_a?(Array)
+
+        [key, val.to_s]
+      end
+    end
+
+    ##
+    # Whether a string is a valid label or annotation key: an optional
+    # DNS-subdomain prefix and '/', then a name. The API server rejects
+    # anything else with a 422, deep into provisioning.
+    # @param [String] key
+    # @return [Boolean]
+    def qualified_key?(key)
+      prefix, slash, name = key.rpartition('/')
+      return false unless name.length <= LABEL_VALUE_MAX && LABEL_NAME_RE.match?(name)
+
+      slash.empty? || (prefix.length <= KEY_PREFIX_MAX && KEY_PREFIX_RE.match?(prefix))
+    end
+
+    def parse_key_values(name, value)
+      pairs = value.split(',').map(&:strip).reject(&:empty?)
+      raise ArgumentError, "BEAKER_#{name} is set but has no key=value entries: #{value.inspect}" if pairs.empty?
+
+      pairs.to_h do |pair|
+        key, val = pair.split('=', 2).map(&:strip)
+        raise ArgumentError, "BEAKER_#{name} entries must be key=value, got #{pair.inspect}" if val.nil? || key.empty?
+
+        [key, val]
+      end
     end
 
     ##
@@ -483,19 +696,146 @@ module Beaker
       end
     end
 
+    ##
+    # The value of the BEAKER_<name> environment variable, which overrides the
+    # host and CONFIG settings of the option it names so that a CI environment
+    # can set it for every nodeset it runs, as beaker-google's BEAKER_gce_*
+    # variables do.
+    # @param [String] name The option name, e.g. 'kubevirt_disk_cache'
+    # @return [String, nil] The stripped value, or nil when unset or blank
+    def env_option(name)
+      value = ENV.fetch("BEAKER_#{name}", nil)&.strip
+      value unless value.nil? || value.empty?
+    end
+
+    ##
+    # Cache mode for the root disk, from BEAKER_kubevirt_disk_cache, the host
+    # or the global CONFIG, in that order.
+    # Unset leaves the choice to KubeVirt, which uses none when the backing
+    # store supports O_DIRECT and writethrough otherwise. writeback lets the
+    # virt-launcher's page cache absorb guest writes until the guest flushes,
+    # which suits throwaway test VMs on slow or shared storage.
+    # @param [Host] host The host configuration
+    # @return [String, nil] One of DISK_CACHE_MODES, or nil when unset
+    def disk_cache(host)
+      env = env_option('kubevirt_disk_cache')
+      value = env || host['kubevirt_disk_cache'] || @options[:kubevirt_disk_cache]
+      return nil if value.nil? || value.to_s.empty?
+
+      cache = value.to_s.downcase
+      unless DISK_CACHE_MODES.include?(cache)
+        source = env ? 'BEAKER_kubevirt_disk_cache' : 'kubevirt_disk_cache'
+        raise ArgumentError, "#{source} must be one of #{DISK_CACHE_MODES.join(', ')}, got #{value.to_s.inspect}"
+      end
+
+      cache
+    end
+
+    ##
+    # Node labels the VM's pod must match, from BEAKER_kubevirt_node_selector,
+    # the host or the global CONFIG, in that order. The variable is a
+    # comma-separated list of key=value pairs.
+    # @param [Host] host The host configuration
+    # @return [Hash{String=>String}, nil] The selector, or nil when unset
+    def node_selector(host)
+      env = env_option('kubevirt_node_selector')
+      selector = env ? parse_key_values('kubevirt_node_selector', env) : host['kubevirt_node_selector'] || @options[:kubevirt_node_selector]
+      return nil if selector.nil?
+      raise ArgumentError, "kubevirt_node_selector must be a hash of label keys to values, got #{selector.inspect}" unless selector.is_a?(Hash)
+      return nil if selector.empty?
+
+      selector.to_h do |key, value|
+        raise ArgumentError, "kubevirt_node_selector value for #{key.to_s.inspect} must be a single label value, got #{value.inspect}" unless scalar?(value)
+
+        [key.to_s, value.to_s]
+      end
+    end
+
+    def scalar?(value)
+      case value
+      # Not Float: YAML reads an unquoted 1.10 as 1.1, which would select the
+      # wrong nodes without an error. A quoted value is unambiguous.
+      when String, Symbol, Integer, true, false then true
+      else false
+      end
+    end
+
+    ##
+    # Tolerations for the VM's pod, from BEAKER_kubevirt_tolerations, the host
+    # or the global CONFIG, in that order. Each entry has a key, an effect and
+    # an optional value; one without a value tolerates the key whatever its
+    # value. The variable is a comma-separated list of key=value:Effect or
+    # key:Effect entries.
+    # @param [Host] host The host configuration
+    # @return [Array<Hash>, nil] Kubernetes tolerations, or nil when unset
+    def tolerations(host)
+      env = env_option('kubevirt_tolerations')
+      list = env ? parse_tolerations(env) : host['kubevirt_tolerations'] || @options[:kubevirt_tolerations]
+      return nil if list.nil?
+      raise ArgumentError, "kubevirt_tolerations must be a list of key/value/effect entries, got #{list.inspect}" unless list.is_a?(Array)
+      return nil if list.empty?
+
+      list.map { |entry| build_toleration(entry) }
+    end
+
+    def parse_tolerations(value)
+      entries = value.split(',').map(&:strip).reject(&:empty?)
+      raise ArgumentError, "BEAKER_kubevirt_tolerations is set but has no entries: #{value.inspect}" if entries.empty?
+
+      entries.map do |entry|
+        taint, separator, effect = entry.rpartition(':')
+        raise ArgumentError, "BEAKER_kubevirt_tolerations entries must be key=value:Effect or key:Effect, got #{entry.inspect}" if separator.empty?
+
+        key, toleration_value = taint.split('=', 2)
+        { 'key' => key, 'value' => toleration_value, 'effect' => effect }
+      end
+    end
+
+    def build_toleration(entry)
+      raise ArgumentError, "Each kubevirt_tolerations entry must be a hash, got #{entry.inspect}" unless entry.is_a?(Hash)
+
+      # operator and tolerationSeconds are not supported. Dropping them silently
+      # would change what the toleration matches or how long it lasts.
+      unknown = entry.keys.map(&:to_s) - TOLERATION_FIELDS
+      unless unknown.empty?
+        raise ArgumentError, "kubevirt_tolerations entry #{entry.inspect} has unsupported fields #{unknown.join(', ')}; " \
+                             "only #{TOLERATION_FIELDS.join(', ')} are accepted (an entry without a value tolerates any value)"
+      end
+
+      # key? rather than ||, so a YAML `value: false` is the string "false" and
+      # not a missing value, which would widen the toleration to Exists.
+      key, value, effect = %w[key value effect].map { |field| entry.key?(field) ? entry[field] : entry[field.to_sym] }
+      key = key.to_s.strip
+      effect = effect.to_s.strip
+      raise ArgumentError, "kubevirt_tolerations entry #{entry.inspect} has no key" if key.empty?
+      raise ArgumentError, "kubevirt_tolerations effect must be one of #{TOLERATION_EFFECTS.join(', ')}, got #{effect.inspect}" unless TOLERATION_EFFECTS.include?(effect)
+
+      # Only an absent value means Exists. An explicit empty string is Equal "",
+      # which matches only taints whose value is empty.
+      if value.nil?
+        { 'key' => key, 'operator' => 'Exists', 'effect' => effect }
+      else
+        { 'key' => key, 'operator' => 'Equal', 'value' => value.to_s.strip, 'effect' => effect }
+      end
+    end
+
     ##
     # Generate the hardware devices specification for the VM
     # @param [Host] host The host configuration
     # @return [Hash] Hardware devices specification
     def generate_hardware_spec(host)
+      rootdisk = {
+        'name' => 'rootdisk',
+        'disk' => {
+          'bus' => disk_bus(host),
+        },
+      }
+      cache = disk_cache(host)
+      rootdisk['cache'] = cache if cache
+
       {
         'disks' => [
-          {
-            'name' => 'rootdisk',
-            'disk' => {
-              'bus' => disk_bus(host),
-            },
-          },
+          rootdisk,
           {
             'name' => 'cidata',
             'disk' => {
@@ -536,6 +876,15 @@ module Beaker
       memory_request = "#{memory_request}Mi" if /\A\d+\z/.match?(memory_request.to_s)
       memory_limit = "#{parse_memory_mib(memory) + parse_memory_mib(overhead)}Mi"
 
+      # Both unset by default: KubeVirt then derives the pod's CPU request from the guest core
+      # count divided by the cluster's cpuAllocationRatio, and sets no limit at all.
+      cpu_request = host['kubevirt_cpu_request'] || @options[:kubevirt_cpu_request]
+      cpu_limit = host['kubevirt_cpu_limit'] || @options[:kubevirt_cpu_limit]
+      resource_requests = { 'memory' => memory_request }
+      resource_requests['cpu'] = cpu_request.to_s if cpu_request
+      resource_limits = { 'memory' => memory_limit }
+      resource_limits['cpu'] = cpu_limit.to_s if cpu_limit
+
       vm_image = host['kubevirt_vm_image'] || @options[:kubevirt_vm_image]
       host_name = host.respond_to?(:name) ? host.name : host['name']
 
@@ -561,7 +910,8 @@ module Beaker
               'labels' => get_labels(host).merge({
                                                    'kubevirt.io/vm' => vm_name,
                                                  }),
-            },
+              'annotations' => user_annotations(host),
+            }.compact,
             'spec' => {
               'domain' => {
                 'cpu' => {
@@ -573,8 +923,8 @@ module Beaker
                   'guest' => memory.to_s,
                 },
                 'resources' => {
-                  'requests' => { 'memory' => memory_request },
-                  'limits' => { 'memory' => memory_limit },
+                  'requests' => resource_requests,
+                  'limits' => resource_limits,
                 },
                 'devices' => generate_hardware_spec(host),
                 'features' => {
@@ -592,6 +942,8 @@ module Beaker
                 },
               },
               'hostname' => host_name,
+              'nodeSelector' => node_selector(host),
+              'tolerations' => tolerations(host),
               'networks' => generate_networks_spec(host),
               'readinessProbe' => generate_readiness_probe_spec(host),
               'volumes' => [
@@ -637,6 +989,18 @@ module Beaker
       end
     end
 
+    ##
+    # Storage class for the root disk's DataVolume, from
+    # BEAKER_kubevirt_storage_class, the host or the global CONFIG, in that
+    # order. Unset leaves the choice to the cluster's default class. A
+    # containerDisk root has no DataVolume, so it is unaffected.
+    # @param [Host] host The host configuration
+    # @return [String, nil] The storage class name, or nil when unset
+    def storage_class(host)
+      name = (env_option('kubevirt_storage_class') || host['kubevirt_storage_class'] || @options[:kubevirt_storage_class]).to_s.strip
+      name unless name.empty?
+    end
+
     ##
     # Generate a DataVolume Template for the root disk
     # @param [String] vm_image The VM image specification
@@ -660,6 +1024,9 @@ module Beaker
         },
       }
 
+      storage_class_name = storage_class(host)
+      dv_spec['spec']['storage']['storageClassName'] = storage_class_name if storage_class_name
+
       # If a custom service account is specified, add it to the DataVolume spec
       # so it can access the source PVC when required (including cross-namespace clones)
       dv_spec['spec']['serviceAccountName'] = @service_account if @service_account
@@ -779,7 +1146,7 @@ module Beaker
 
             raise "VMI #{vm_name} entered terminal phase #{phase} before becoming Ready" if VMI_TERMINAL_PHASES.include?(phase)
 
-            check_virt_launcher_health!(vm_name)
+            check_virt_launcher_health!(host)
 
             sleep SLEEPWAIT
           end
@@ -831,24 +1198,47 @@ module Beaker
 
     ##
     # Inspect the virt-launcher pod backing a VMI and raise with a specific reason
-    # if it has already failed (OOMKilled, image pull errors, crash loops, etc.)
-    # so we fail fast instead of waiting the full timeout.
-    # @param [String] vm_name
-    def check_virt_launcher_health!(vm_name)
+    # if it has already failed (OOMKilled, crash loops, a container that cannot run)
+    # or if the scheduler cannot place it, so we fail fast instead of waiting the
+    # full timeout. Image pull backoff is handled separately by
+    # check_image_pull_backoff!, since kubelet retries pulls and an early
+    # observation does not mean provisioning has failed.
+    # @param [Host] host The host being provisioned, carrying 'vm_name'
+    def check_virt_launcher_health!(host)
+      vm_name = host['vm_name']
       pod = @kubevirt_helper.get_virt_launcher_pod(vm_name)
       return unless pod
 
+      # Image-pull backoff is tracked per virt-launcher pod rather than per VMI.
+      # A pod replaced mid-provision -- rescheduled, or evicted while pulling --
+      # starts the pull again on a node whose cache may be cold, and must not
+      # inherit the window its predecessor already spent. Keying on the pod also
+      # means a momentary absence (API lag, or a `pods.first` that briefly sees
+      # the successor) neither resets nor shortens the window a live pod is
+      # accumulating.
+      pod_name = pod.dig('metadata', 'name') || vm_name
+
       phase = pod.dig('status', 'phase')
       raise "virt-launcher pod for #{vm_name} entered phase #{phase}" if phase == 'Failed'
 
+      check_pod_schedulable!(host, vm_name, pod)
+
       statuses = Array(pod.dig('status', 'containerStatuses')) +
                  Array(pod.dig('status', 'initContainerStatuses'))
       statuses.each do |cs|
         name = cs['name']
         waiting_reason = cs.dig('state', 'waiting', 'reason')
-        if FATAL_CONTAINER_WAITING_REASONS.include?(waiting_reason)
-          raise "virt-launcher container #{name} for #{vm_name} is #{waiting_reason}: " \
-                "#{cs.dig('state', 'waiting', 'message')}"
+        if IMAGE_PULL_WAITING_REASONS.include?(waiting_reason)
+          check_image_pull_backoff!(host, pod_name, name, waiting_reason, cs.dig('state', 'waiting', 'message').to_s)
+        else
+          # Only a container that has got past the pull ends its window. A
+          # transient other waiting state between two backoffs must not restart it.
+          @image_pull_backoff_since.delete("#{pod_name}/#{name}") if cs.dig('state', 'running') || cs.dig('state', 'terminated')
+
+          if FATAL_CONTAINER_WAITING_REASONS.include?(waiting_reason)
+            raise "virt-launcher container #{name} for #{vm_name} is #{waiting_reason}: " \
+                  "#{cs.dig('state', 'waiting', 'message')}"
+          end
         end
 
         last_term = cs.dig('lastState', 'terminated') || cs.dig('state', 'terminated')
@@ -860,6 +1250,137 @@ module Beaker
       end
     end
 
+    ##
+    # Decide whether a container backing off an image pull has waited long enough
+    # to be called a failure. kubelet retries pulls with increasing backoff, so a
+    # single observation of ImagePullBackOff proves nothing: an on-demand
+    # pull-through cache warming a multi-GB image, a slow upstream registry or a
+    # dropped connection all resolve on a later attempt. Raise only once the
+    # backoff has outlived the grace window — or immediately when the message says
+    # retrying is pointless, or when the window has been switched off.
+    # @param [Host] host The host being provisioned, carrying 'vm_name'
+    # @param [String] pod_name Name of the virt-launcher pod reporting the backoff
+    # @param [String] container Container name reporting the backoff
+    # @param [String] reason Waiting reason (ImagePullBackOff / ErrImagePull)
+    # @param [String] message Waiting message from kubelet
+    def check_image_pull_backoff!(host, pod_name, container, reason, message)
+      vm_name = host['vm_name']
+      grace = image_pull_grace(host)
+
+      # Two ways to skip the window and fail on this very observation: kubelet's
+      # retry will never fix a definitive failure, and a grace of zero is the
+      # documented way to opt out of the window entirely. Both keep the message
+      # the check raised before the window existed.
+      raise "virt-launcher container #{container} for #{vm_name} is #{reason}: #{message}" if DEFINITIVE_IMAGE_PULL_FAILURE_RE.match?(message) || grace <= 0
+
+      key = "#{pod_name}/#{container}"
+      now = monotonic_time
+      first_seen = !@image_pull_backoff_since.key?(key)
+      @image_pull_backoff_since[key] ||= now
+      elapsed = (now - @image_pull_backoff_since[key]).round
+
+      if elapsed > grace
+        raise "virt-launcher container #{container} for #{vm_name} is still #{reason} after #{elapsed}s, " \
+              "exceeding the :kubevirt_image_pull_grace window of #{grace}s: #{message}"
+      end
+
+      # Warn on first sight: when the ready timeout expires before the window
+      # does, this is the only record of why the VM never became ready.
+      if first_seen
+        @logger.warn("virt-launcher container #{container} for #{vm_name} is #{reason}, allowing #{grace}s " \
+                     "for kubelet to retry the pull: #{message}")
+      else
+        @logger.debug("virt-launcher container #{container} for #{vm_name} is #{reason} " \
+                      "(#{elapsed}s of #{grace}s grace); waiting for kubelet to retry the pull")
+      end
+    end
+
+    ##
+    # How long an image pull may stay in backoff before it is treated as fatal.
+    # Per-host first so a suite can give a multi-GB Windows containerDisk more room
+    # than a small cloud image, then the global option, then the default. Zero
+    # switches the window off rather than setting an empty one.
+    # @param [Host] host The host being provisioned
+    # @return [Integer] seconds
+    def image_pull_grace(host)
+      value = host['kubevirt_image_pull_grace'] || @options[:kubevirt_image_pull_grace]
+      return DEFAULT_IMAGE_PULL_GRACE if value.nil?
+
+      grace = Integer(value, exception: false)
+      raise ArgumentError, "kubevirt_image_pull_grace must be a whole number of seconds, got #{value.inspect}" if grace.nil? || grace.negative?
+
+      grace
+    end
+
+    ##
+    # Raise once the scheduler has been unable to place the virt-launcher pod for
+    # longer than the grace window.
+    #
+    # An unschedulable pod is invisible to every other check in
+    # check_virt_launcher_health!: its phase is Pending rather than Failed, and both
+    # containerStatuses and initContainerStatuses are absent entirely, because no
+    # container was ever assigned to a node. So the wait loop spins until the overall
+    # timeout and reports "Timeout waiting for VM ... to be ready" — the same message
+    # a slow guest boot produces. The one failure the cluster can describe precisely
+    # ("0/8 nodes are available: 5 Insufficient cpu") is the one that arrives with no
+    # explanation at all.
+    #
+    # Being unschedulable is not immediately terminal, which is why the grace window
+    # exists rather than raising on first sight. The reason is logged as soon as it is
+    # seen, so it is never silent even when the window is set wide.
+    #
+    # @param [Host] host The host being provisioned
+    # @param [String] vm_name
+    # @param [Hash] pod The virt-launcher pod
+    def check_pod_schedulable!(host, vm_name, pod)
+      condition = Array(pod.dig('status', 'conditions')).find { |c| c['type'] == 'PodScheduled' }
+      reason = (condition && condition['status'] == 'False') ? condition['reason'] : nil
+
+      unless UNSCHEDULABLE_POD_REASONS.include?(reason)
+        @unschedulable_since.delete(vm_name)
+        return
+      end
+
+      message = condition['message'].to_s
+      grace = unschedulable_grace(host)
+      uid = pod.dig('metadata', 'uid')
+      tracked = @unschedulable_since[vm_name]
+      # A replacement pod must get its own window, not inherit the elapsed time of
+      # the one it replaced.
+      if tracked.nil? || tracked[:uid] != uid
+        tracked = @unschedulable_since[vm_name] = { uid: uid, since: monotonic_time }
+        @logger.warn("virt-launcher pod for #{vm_name} is #{reason}, allowing #{grace}s " \
+                     "for capacity: #{message}")
+      end
+
+      waited = monotonic_time - tracked[:since]
+      return if waited < grace
+
+      raise "virt-launcher pod for #{vm_name} is still #{reason} after #{waited.round}s: #{message}"
+    end
+
+    ##
+    # Seconds the virt-launcher pod may remain unschedulable before it is fatal.
+    # @param [Host] host
+    # @return [Integer]
+    def unschedulable_grace(host)
+      value = host['kubevirt_unschedulable_grace'] || @options[:kubevirt_unschedulable_grace]
+      return DEFAULT_UNSCHEDULABLE_GRACE if value.nil?
+
+      grace = Integer(value, exception: false)
+      raise ArgumentError, "kubevirt_unschedulable_grace must be a whole number of seconds, got #{value.inspect}" if grace.nil? || grace.negative?
+
+      grace
+    end
+
+    ##
+    # Monotonic seconds, so a wall-clock adjustment mid-wait cannot shorten or
+    # extend a grace window.
+    # @return [Float]
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     ##
     # The guest-side port SSH listens on, shared between the VMI readiness probe
     # and client-side networking setup so they can never drift apart.
@@ -964,7 +1485,7 @@ module Beaker
     # @param [Host] host The host
     def setup_nodeport(host)
       vm_name = host['vm_name']
-      service_name = "#{vm_name}-ssh"
+      service_name = bounded_k8s_name("#{vm_name}-ssh")
 
       @logger.debug("Creating NodePort service for VM #{vm_name}")
       service = @kubevirt_helper.create_nodeport_service(vm_name, service_name, @test_group_identifier)

data/lib/beaker/hypervisor/port_forward.rb

@@ -547,7 +547,7 @@ class KubeVirtPortForwarder
   end
 
   # Manages state transitions with thread safety.
-  # rubocop:disable Naming/PredicateMethod
+  # rubocop:disable-next Naming/PredicateMethod
   def state_transition_to(new_state)
     @mutex.synchronize do
       case new_state
@@ -564,7 +564,6 @@ class KubeVirtPortForwarder
     end
     true
   end
-  # rubocop:enable Naming/PredicateMethod
 
   # Convert kubeclient SSL options to Faye::WebSocket/EventMachine TLS options.
   # @param ssl_options [Hash] The SSL options from kubeclient

data/lib/beaker/kubevirt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BeakerKubevirt
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/tests/spec/beaker/hypervisor/kubevirt_spec.rb

@@ -6,6 +6,6 @@ require 'beaker/hypervisor/kubevirt'
 describe Beaker::Hypervisor::Kubevirt do
   it 'can run a command' do
     result = on default, 'echo hello'
-    expect(result.stdout).to match(/hello/)
+    expect(result.stdout).to include('hello')
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: beaker-kubevirt
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Steven Pritchard
@@ -126,14 +126,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.2.0
+        version: 5.3.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.2.0
+        version: 5.3.0
 description: Enables Beaker to provision VMs using KubeVirt for automated acceptance
   testing of Puppet code.
 email:
@@ -182,7 +182,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: KubeVirt hypervisor support for Beaker acceptance testing
 test_files: []