kube_schema 1.3.9 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6aa0c152a33c1414287852fa61f79812af549964f17bb95546b6a27f639927f8
-  data.tar.gz: fe3a7c986782b8cb49d7f03c23ac749158ec86f4a7a75d2a138cdd63473f332c
+  metadata.gz: f145d4e219013c8c1f0091ce99d7a2a10d1700201e77c6ed2d3d26db140206b0
+  data.tar.gz: 0114343af9ef19eb9f7496ed0506859126cef3912bb593c855c36565550dd504
 SHA512:
-  metadata.gz: c87f68db595b46071d3603283804ead4e0cf943ee4a7873743fbeb6ddb383f331bc351fb8bc30bb2c3bf77f6db00ab20c6dd663af6bc9f2ac4e658d605861146
-  data.tar.gz: c1b5704684f5b7070103c5dc4c2187bc85d440db73be64f157086526dace4a553bc707f9e6102dab065876085f9c93850c5aebad6efcbbb9520a9ee0157d927e
+  metadata.gz: cd5ee4e5f81546204cc2ff1040131a3cb09f4d512a4230adcaab86f7a2db0c65d0ec3034fc6613461f8de2eb549ea7c2e297da6e3de5ddc107f23629afe93727
+  data.tar.gz: cf4e3bf4b4a913ccc5108fe42c274c350d7d09db67fdc195028f6f0ddd513d82fa0799674d453cdfd7f3e7c086739c4150175cd7c62b5b7ab5ffca90e8b32b3f

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kube_schema (1.3.9)
+    kube_schema (1.4.0)
       json_schemer (~> 2.5.0)
       rubyshell (~> 1.5.0)
 

data/bin/copy-schemas-over

@@ -9,3 +9,5 @@ git ls-tree --name-only schemas2 data/k8s.io/ | while read -r path; do
   git show "schemas2:$path" > "schemas/$(basename "$path")"
 done
 
+bin/create-kubevirt-x-values
+

data/bin/create-kubevirt-x-values

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+#
+# Rewrites schemas/kubevirt-definitions.json in-place to:
+#   1. Add x-kubernetes-group-version-kind annotations
+#   2. Fix $ref pointers from k8s.io.* to io.k8s.* prefix
+#
+set -euo pipefail
+
+DEFS_FILE="schemas/kubevirt-definitions.json"
+
+echo "Rewriting $DEFS_FILE..."
+
+jq '
+  # GVK map: definition key -> [{ group, version, kind }]
+  {
+    "v1.KubeVirt":                              [{ group: "kubevirt.io",              version: "v1",        kind: "KubeVirt" }],
+    "v1.VirtualMachine":                        [{ group: "kubevirt.io",              version: "v1",        kind: "VirtualMachine" }],
+    "v1.VirtualMachineExport":                  [{ group: "export.kubevirt.io",       version: "v1",        kind: "VirtualMachineExport" }],
+    "v1.VirtualMachineInstance":                [{ group: "kubevirt.io",              version: "v1",        kind: "VirtualMachineInstance" }],
+    "v1.VirtualMachineInstanceMigration":       [{ group: "kubevirt.io",              version: "v1",        kind: "VirtualMachineInstanceMigration" }],
+    "v1.VirtualMachineInstancePreset":          [{ group: "kubevirt.io",              version: "v1",        kind: "VirtualMachineInstancePreset" }],
+    "v1.VirtualMachineInstanceReplicaSet":      [{ group: "kubevirt.io",              version: "v1",        kind: "VirtualMachineInstanceReplicaSet" }],
+    "v1alpha1.MigrationPolicy":                 [{ group: "migrations.kubevirt.io",   version: "v1alpha1",  kind: "MigrationPolicy" }],
+    "v1alpha1.VirtualMachineBackup":            [{ group: "backup.kubevirt.io",       version: "v1alpha1",  kind: "VirtualMachineBackup" }],
+    "v1beta1.VirtualMachineClone":              [{ group: "clone.kubevirt.io",        version: "v1beta1",   kind: "VirtualMachineClone" }],
+    "v1beta1.VirtualMachineClusterInstancetype":[{ group: "instancetype.kubevirt.io", version: "v1beta1",   kind: "VirtualMachineClusterInstancetype" }],
+    "v1beta1.VirtualMachineClusterPreference":  [{ group: "instancetype.kubevirt.io", version: "v1beta1",   kind: "VirtualMachineClusterPreference" }],
+    "v1beta1.VirtualMachineInstancetype":       [{ group: "instancetype.kubevirt.io", version: "v1beta1",   kind: "VirtualMachineInstancetype" }],
+    "v1beta1.VirtualMachinePool":               [{ group: "pool.kubevirt.io",         version: "v1beta1",   kind: "VirtualMachinePool" }],
+    "v1beta1.VirtualMachinePreference":         [{ group: "instancetype.kubevirt.io", version: "v1beta1",   kind: "VirtualMachinePreference" }],
+    "v1beta1.VirtualMachineRestore":            [{ group: "snapshot.kubevirt.io",     version: "v1beta1",   kind: "VirtualMachineRestore" }],
+    "v1beta1.VirtualMachineSnapshot":           [{ group: "snapshot.kubevirt.io",     version: "v1beta1",   kind: "VirtualMachineSnapshot" }],
+    "v1beta1.VirtualMachineSnapshotContent":    [{ group: "snapshot.kubevirt.io",     version: "v1beta1",   kind: "VirtualMachineSnapshotContent" }]
+  } as $gvk_map |
+
+  # Inject x-kubernetes-group-version-kind annotations
+  with_entries(
+    if $gvk_map[.key] then
+      .value["x-kubernetes-group-version-kind"] = $gvk_map[.key]
+    else . end
+  ) |
+
+  # Fix $ref pointers: kubevirt uses k8s.io.* but base schema uses io.k8s.*
+  walk(
+    if type == "string" and startswith("#/definitions/k8s.io.")
+    then sub("^#/definitions/k8s\\.io\\."; "#/definitions/io.k8s.")
+    else . end
+  )
+' "$DEFS_FILE" > "${DEFS_FILE}.tmp" && mv "${DEFS_FILE}.tmp" "$DEFS_FILE"
+
+ANNOTATED=$(jq '[.[] | select(has("x-kubernetes-group-version-kind"))] | length' "$DEFS_FILE")
+TOTAL=$(jq 'length' "$DEFS_FILE")
+STALE_REFS=$(jq -r '[.. | strings | select(startswith("#/definitions/k8s.io."))] | length' "$DEFS_FILE")
+echo "Done. $ANNOTATED/$TOTAL definitions annotated. $STALE_REFS stale k8s.io refs remaining."

data/examples/sub_specs.rb

@@ -0,0 +1,412 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demonstrates Kube::Schema::SubSpec — typed, schema-validated wrappers
+# for non-resource Kubernetes definitions (Container, Volume, Probe, etc.).
+#
+# SubSpec objects validate against the OpenAPI JSON Schema and auto-coerce
+# to plain hashes when placed inside Resource specs.
+#
+# Run:  bundle exec ruby examples/sub_specs.rb
+
+require_relative "../lib/kube/schema"
+
+SubSpec  = Kube::Schema::SubSpec
+Manifest = Kube::Schema::Manifest
+
+puts "=" * 60
+puts "Kube::Schema::SubSpec Examples"
+puts "=" * 60
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  1. CONTAINER — the core use case
+# ══════════════════════════════════════════════════════════════
+
+app = SubSpec["Container"].new {
+  self.name  = "app"
+  self.image = "myapp:1.4.2"
+  self.imagePullPolicy = "IfNotPresent"
+  self.command = ["/usr/bin/myapp"]
+  self.args    = ["--config", "/etc/myapp/config.yaml"]
+  self.ports = [
+    { name: "http",    containerPort: 8080, protocol: "TCP" },
+    { name: "metrics", containerPort: 9090, protocol: "TCP" }
+  ]
+  self.env = [
+    { name: "LOG_LEVEL",  value: "info" },
+    { name: "WORKERS",    value: "4" },
+    { name: "DB_PASSWORD", valueFrom: { secretKeyRef: { name: "db-creds", key: "password" } } }
+  ]
+  self.resources.requests = { cpu: "100m", memory: "128Mi" }
+  self.resources.limits   = { cpu: "500m", memory: "256Mi" }
+  self.volumeMounts = [
+    { name: "config", mountPath: "/etc/myapp",  readOnly: true },
+    { name: "data",   mountPath: "/var/data" }
+  ]
+  self.livenessProbe = {
+    httpGet: { path: "/healthz", port: 8080 },
+    initialDelaySeconds: 10,
+    periodSeconds: 30
+  }
+  self.readinessProbe = {
+    httpGet: { path: "/ready", port: 8080 },
+    initialDelaySeconds: 5,
+    periodSeconds: 10
+  }
+  self.securityContext.runAsNonRoot = true
+  self.securityContext.readOnlyRootFilesystem = true
+  self.securityContext.allowPrivilegeEscalation = false
+}
+
+puts "1. Container: #{app.name}"
+puts "   image: #{app.image}"
+puts "   ports: #{app.ports.map { |p| p[:name] }.join(", ")}"
+puts "   valid? #{app.valid?}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  2. CONTAINER PORT — typed port definitions
+# ══════════════════════════════════════════════════════════════
+
+http_port = SubSpec["ContainerPort"].new {
+  self.name          = "http"
+  self.containerPort = 8080
+  self.protocol      = "TCP"
+}
+
+grpc_port = SubSpec["ContainerPort"].new(
+  name: "grpc", containerPort: 9090, protocol: "TCP"
+)
+
+puts "2. ContainerPorts:"
+puts "   - #{http_port.name}: #{http_port.containerPort}"
+puts "   - #{grpc_port.name}: #{grpc_port.containerPort}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  3. ENV VAR — plain values and valueFrom references
+# ══════════════════════════════════════════════════════════════
+
+env_plain = SubSpec["EnvVar"].new(name: "APP_ENV", value: "production")
+
+env_secret = SubSpec["EnvVar"].new {
+  self.name = "DB_PASSWORD"
+  self.valueFrom.secretKeyRef = { name: "db-creds", key: "password" }
+}
+
+env_configmap = SubSpec["EnvVar"].new {
+  self.name = "LOG_FORMAT"
+  self.valueFrom.configMapKeyRef = { name: "app-config", key: "log_format" }
+}
+
+env_field = SubSpec["EnvVar"].new {
+  self.name = "POD_NAME"
+  self.valueFrom.fieldRef = { fieldPath: "metadata.name" }
+}
+
+puts "3. EnvVars:"
+[env_plain, env_secret, env_configmap, env_field].each do |e|
+  puts "   - #{e.name}: valid? #{e.valid?}"
+end
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  4. VOLUME + VOLUME MOUNT — paired definitions
+# ══════════════════════════════════════════════════════════════
+
+config_volume = SubSpec["Volume"].new {
+  self.name = "config"
+  self.configMap = { name: "app-config" }
+}
+
+secret_volume = SubSpec["Volume"].new {
+  self.name = "tls-certs"
+  self.secret = { secretName: "tls-secret" }
+}
+
+data_volume = SubSpec["Volume"].new {
+  self.name = "data"
+  self.emptyDir = { sizeLimit: "1Gi" }
+}
+
+pvc_volume = SubSpec["Volume"].new(
+  name: "storage",
+  persistentVolumeClaim: { claimName: "app-pvc" }
+)
+
+config_mount = SubSpec["VolumeMount"].new(
+  name: "config", mountPath: "/etc/app", readOnly: true
+)
+
+tls_mount = SubSpec["VolumeMount"].new {
+  self.name      = "tls-certs"
+  self.mountPath = "/etc/tls"
+  self.readOnly  = true
+}
+
+data_mount = SubSpec["VolumeMount"].new(
+  name: "data", mountPath: "/var/data"
+)
+
+puts "4. Volumes:"
+[config_volume, secret_volume, data_volume, pvc_volume].each do |v|
+  puts "   - #{v.name}: valid? #{v.valid?}"
+end
+puts "   Mounts:"
+[config_mount, tls_mount, data_mount].each do |m|
+  puts "   - #{m.name} -> #{m.mountPath}"
+end
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  5. PROBE — liveness, readiness, startup
+# ══════════════════════════════════════════════════════════════
+
+http_probe = SubSpec["Probe"].new {
+  self.httpGet = { path: "/healthz", port: 8080 }
+  self.initialDelaySeconds = 15
+  self.periodSeconds       = 20
+  self.timeoutSeconds      = 3
+  self.failureThreshold    = 3
+}
+
+tcp_probe = SubSpec["Probe"].new {
+  self.tcpSocket = { port: 5432 }
+  self.initialDelaySeconds = 5
+  self.periodSeconds       = 10
+}
+
+exec_probe = SubSpec["Probe"].new {
+  self.exec = { command: ["/bin/sh", "-c", "pg_isready -U postgres"] }
+  self.initialDelaySeconds = 10
+  self.periodSeconds       = 30
+}
+
+grpc_probe = SubSpec["Probe"].new {
+  self.grpc = { port: 50051 }
+  self.periodSeconds = 10
+}
+
+puts "5. Probes:"
+puts "   - HTTP:  valid? #{http_probe.valid?}"
+puts "   - TCP:   valid? #{tcp_probe.valid?}"
+puts "   - Exec:  valid? #{exec_probe.valid?}"
+puts "   - gRPC:  valid? #{grpc_probe.valid?}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  6. SECURITY CONTEXT — hardened container
+# ══════════════════════════════════════════════════════════════
+
+hardened = SubSpec["SecurityContext"].new {
+  self.runAsNonRoot             = true
+  self.runAsUser                = 1000
+  self.runAsGroup               = 1000
+  self.readOnlyRootFilesystem   = true
+  self.allowPrivilegeEscalation = false
+  self.capabilities = { drop: ["ALL"] }
+  self.seccompProfile = { type: "RuntimeDefault" }
+}
+
+puts "6. SecurityContext:"
+puts "   runAsUser: #{hardened.runAsUser}"
+puts "   readOnlyRootFilesystem: #{hardened.readOnlyRootFilesystem}"
+puts "   valid? #{hardened.valid?}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  7. TOLERATION + TOPOLOGY SPREAD CONSTRAINT
+# ══════════════════════════════════════════════════════════════
+
+gpu_toleration = SubSpec["Toleration"].new(
+  key: "nvidia.com/gpu", operator: "Exists", effect: "NoSchedule"
+)
+
+spot_toleration = SubSpec["Toleration"].new {
+  self.key      = "kubernetes.azure.com/scalesetpriority"
+  self.operator = "Equal"
+  self.value    = "spot"
+  self.effect   = "NoSchedule"
+}
+
+zone_spread = SubSpec["TopologySpreadConstraint"].new {
+  self.maxSkew           = 1
+  self.topologyKey       = "topology.kubernetes.io/zone"
+  self.whenUnsatisfiable = "DoNotSchedule"
+  self.labelSelector = { matchLabels: { app: "web" } }
+}
+
+puts "7. Scheduling:"
+puts "   Tolerations:"
+puts "   - #{gpu_toleration.key}: valid? #{gpu_toleration.valid?}"
+puts "   - #{spot_toleration.key}: valid? #{spot_toleration.valid?}"
+puts "   TopologySpreadConstraint:"
+puts "   - #{zone_spread.topologyKey}: valid? #{zone_spread.valid?}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  8. SERVICE PORT — for Service specs
+# ══════════════════════════════════════════════════════════════
+
+svc_http = SubSpec["ServicePort"].new(
+  name: "http", port: 80, targetPort: 8080, protocol: "TCP"
+)
+
+svc_https = SubSpec["ServicePort"].new {
+  self.name        = "https"
+  self.port        = 443
+  self.targetPort  = 8443
+  self.protocol    = "TCP"
+  self.appProtocol = "kubernetes.io/h2c"
+}
+
+puts "8. ServicePorts:"
+puts "   - #{svc_http.name}: #{svc_http.port} -> #{svc_http.targetPort}"
+puts "   - #{svc_https.name}: #{svc_https.port} -> #{svc_https.targetPort}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  9. COMPOSING A FULL DEPLOYMENT — tying it all together
+# ══════════════════════════════════════════════════════════════
+
+# Build typed sub-specs
+web_container = SubSpec["Container"].new {
+  self.name  = "web"
+  self.image = "nginx:1.27-alpine"
+  self.ports = [http_port.to_h]
+  self.resources.requests = { cpu: "50m",  memory: "64Mi" }
+  self.resources.limits   = { cpu: "200m", memory: "128Mi" }
+  self.volumeMounts = [config_mount.to_h, tls_mount.to_h]
+  self.livenessProbe  = http_probe.to_h
+  self.readinessProbe = http_probe.to_h
+  self.securityContext = hardened.to_h
+}
+
+sidecar = SubSpec["Container"].new {
+  self.name  = "log-shipper"
+  self.image = "fluent/fluent-bit:3.2"
+  self.resources.requests = { cpu: "25m",  memory: "32Mi" }
+  self.resources.limits   = { cpu: "100m", memory: "64Mi" }
+  self.volumeMounts = [data_mount.to_h]
+  self.securityContext = hardened.to_h
+}
+
+# Compose into a Deployment — SubSpec instances auto-coerce
+deployment = Kube::Schema["Deployment"].new {
+  metadata.name      = "web"
+  metadata.namespace = "production"
+  metadata.labels    = { app: "web", tier: "frontend" }
+
+  spec.replicas = 3
+  spec.selector.matchLabels = { app: "web" }
+  spec.strategy.type = "RollingUpdate"
+  spec.strategy.rollingUpdate = { maxSurge: 1, maxUnavailable: 0 }
+
+  spec.template.metadata.labels = { app: "web", tier: "frontend" }
+
+  # Auto-coercion: SubSpec instances become plain hashes automatically
+  spec.template.spec.containers = [web_container, sidecar]
+  spec.template.spec.volumes    = [config_volume, secret_volume, data_volume]
+
+  spec.template.spec.tolerations = [spot_toleration]
+  spec.template.spec.topologySpreadConstraints = [zone_spread]
+
+  spec.template.spec.securityContext.fsGroup    = 1000
+  spec.template.spec.securityContext.runAsGroup = 1000
+  spec.template.spec.serviceAccountName = "web"
+  spec.template.spec.terminationGracePeriodSeconds = 30
+}
+
+# Also compose a Service using typed ServicePorts
+service = Kube::Schema["Service"].new {
+  metadata.name      = "web"
+  metadata.namespace = "production"
+  metadata.labels    = { app: "web" }
+  spec.selector = { app: "web" }
+  spec.type     = "ClusterIP"
+  spec.ports    = [svc_http, svc_https]
+}
+
+puts "9. Composed resources:"
+puts "   Deployment: #{deployment.metadata[:name]} (#{deployment.spec[:replicas]} replicas)"
+puts "   - containers: #{deployment.to_h[:spec][:template][:spec][:containers].map { |c| c[:name] }.join(", ")}"
+puts "   - volumes: #{deployment.to_h[:spec][:template][:spec][:volumes].map { |v| v[:name] }.join(", ")}"
+puts "   - valid? #{deployment.valid?}"
+puts
+puts "   Service: #{service.metadata[:name]}"
+puts "   - ports: #{service.to_h[:spec][:ports].map { |p| "#{p[:name]}:#{p[:port]}" }.join(", ")}"
+puts "   - valid? #{service.valid?}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+# 10. VALIDATION — catching errors on sub-specs
+# ══════════════════════════════════════════════════════════════
+
+puts "10. Validation examples:"
+
+# Missing required field: Container requires "name"
+bad_container = SubSpec["Container"].new(image: "nginx")
+puts "    Container without name: valid? #{bad_container.valid?}"
+
+begin
+  bad_container.valid!
+rescue Kube::ValidationError => e
+  puts "    Error: #{e.errors.length} error(s)"
+  puts "    #{e.message.lines.grep(/required/).first&.strip}"
+end
+puts
+
+# Wrong type: ports should be an array
+bad_ports = SubSpec["Container"].new(name: "app", ports: "not-an-array")
+puts "    Container with string ports: valid? #{bad_ports.valid?}"
+puts
+
+# VolumeMount missing required fields
+bad_mount = SubSpec["VolumeMount"].new(name: "data")
+puts "    VolumeMount without mountPath: valid? #{bad_mount.valid?}"
+
+begin
+  bad_mount.valid!
+rescue Kube::ValidationError => e
+  puts "    #{e.message.lines.grep(/required/).first&.strip}"
+end
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+# 11. DISCOVERY — what sub-specs are available?
+# ══════════════════════════════════════════════════════════════
+
+instance = Kube::Schema::Instance.new("1.34")
+all_defs = instance.list_definitions
+
+puts "11. Discovery:"
+puts "    Total definitions available: #{all_defs.length}"
+puts "    Container-related:"
+all_defs.select { |d| d.include?("Container") }.each { |d| puts "      - #{d}" }
+puts "    Volume-related:"
+all_defs.select { |d| d.start_with?("Volume") }.each { |d| puts "      - #{d}" }
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+# 12. YAML OUTPUT
+# ══════════════════════════════════════════════════════════════
+
+manifest = Manifest.new(deployment, service)
+
+puts "=" * 60
+puts "YAML Output:"
+puts "=" * 60
+puts manifest.to_yaml

data/lib/kube/schema/instance.rb

@@ -27,6 +27,7 @@ module Kube
 
       def initialize(version)
         @resource_classes = {}
+        @sub_spec_classes = {}
 
         unless Gem::Version.correct?(version)
           raise UnknownVersionError,
@@ -71,6 +72,39 @@ module Kube
         (gvk_index.keys + Schema.custom_schemas.keys).uniq.sort
       end
 
+      # Look up a sub-spec definition by short name (e.g. "Container",
+      # "ContainerPort", "Volume", "Probe"). Returns a class that
+      # inherits from Kube::Schema::SubSpec.
+      #
+      # Also accepts a full definition key like
+      # "io.k8s.api.core.v1.Container" for disambiguation.
+      #
+      #   instance.sub_spec("Container")     # => SubSpec subclass
+      #   instance.sub_spec("ContainerPort") # => SubSpec subclass
+      #
+      def sub_spec(name)
+        @sub_spec_classes[name] ||= begin
+          definition_key = find_definition_key(name)
+
+          if definition_key.nil?
+            raise "No definition found for #{name}!" \
+              "\nUse #list_definitions to see available definitions for v#{version}."
+          end
+
+          ref_schema = schemer.ref("#/definitions/#{definition_key}")
+          build_sub_spec_class(ref_schema, name)
+        end
+      end
+
+      # All available definition short names for this version.
+      #
+      # @return [Array<String>] sorted, deduplicated short names
+      def list_definitions
+        schemer.value.fetch("definitions", {}).keys
+          .map { |k| k.split(".").last }
+          .uniq.sort
+      end
+
       private
 
         # The JSONSchemer instance for this version's Swagger document.
@@ -214,6 +248,62 @@ module Kube
           end
         end
 
+        # Resolve a short name like "Container" to its full definition key
+        # "io.k8s.api.core.v1.Container".
+        #
+        # Strategy:
+        #   1. Exact match on full key (for power users)
+        #   2. Short-name match on last segment
+        #   3. Prefer stable API versions (v1 > v1beta1 > v1alpha1)
+        def find_definition_key(name)
+          definitions = schemer.value.fetch("definitions", {})
+
+          # Exact full-key match
+          return name if definitions.key?(name)
+
+          # Short-name matches (last segment after final ".")
+          candidates = definitions.keys.select { |k| k.split(".").last == name }
+          return nil if candidates.empty?
+          return candidates.first if candidates.size == 1
+
+          # Disambiguation: prefer stable versions, then beta, then alpha
+          candidates.min_by { |k|
+            version_segment = k.split(".")[-2].to_s
+            case version_segment
+            when /\Av\d+\z/ then [0, version_segment]
+            when /beta/      then [1, version_segment]
+            when /alpha/     then [2, version_segment]
+            else                  [3, version_segment]
+            end
+          }
+        end
+
+        # Build a SubSpec subclass from a JSONSchemer instance and a
+        # human-readable definition name (for error messages).
+        def build_sub_spec_class(schema_instance, definition_name)
+          Class.new(::Kube::Schema::SubSpec) do
+            @schema = schema_instance
+            @definition_name = definition_name
+            @schema_properties = @schema.value.fetch("properties", {}).keys.map(&:to_sym)
+
+            def self.schema
+              @schema || superclass.schema
+            end
+
+            def self.definition_name
+              @definition_name
+            end
+
+            def self.schema_properties
+              @schema_properties
+            end
+
+            schema_instance.value.fetch("properties", {}).keys.each do |prop|
+              define_method(prop.to_sym) { @data[prop.to_sym] }
+            end
+          end
+        end
+
         # Called by Kube::Schema.register and reset_custom_schemas! to
         # invalidate cached resource classes so new registrations take effect.
         def clear_resource_cache!
@@ -345,6 +435,22 @@ if __FILE__ == $0
         expect(resource.to_h[:kind]).to eq("VirtualMachine")
         expect(resource.to_h[:metadata][:name]).to eq("test-vm")
       end
+
+      it "validates a VirtualMachine without $ref resolution errors" do
+        resource = instance["VirtualMachine"].new {
+          metadata.name = "test-vm"
+          spec.runStrategy = "Always"
+          spec.template.metadata.labels = { "kubevirt.io/vm": "test-vm" }
+          spec.template.spec.domain.cpu = { cores: 1 }
+          spec.template.spec.domain.devices = {}
+          spec.template.spec.domain.memory = { guest: "1Gi" }
+          spec.template.spec.domain.resources = { requests: { memory: "1Gi" } }
+          spec.template.spec.volumes = [
+            { name: "rootdisk", containerDisk: { image: "registry.example.com/vm:latest" } }
+          ]
+        }
+        expect { resource.to_yaml }.not_to raise_error
+      end
     end
 
     describe "class-level schemer cache" do

data/lib/kube/schema/resource.rb

@@ -105,6 +105,8 @@ module Kube
 
         def deep_compact(obj)
           case obj
+          when Kube::Schema::SubSpec
+            deep_compact(obj.to_h)
           when Hash
             obj.each_with_object({}) do |(k, v), result|
               compacted = deep_compact(v)