› kube_schema › Source › Kube › Schema › Instance

class Instance

Represents a single Kubernetes version's OpenAPI schema. Lazily loads the Swagger JSON once per version (shared across instances) and builds resource classes by kind.

instance = Kube::Schema::Instance.new("1.34") instance["Deployment"] # => Resource subclass instance["NetworkPolicy"] # => Resource subclass instance.list_resources # => sorted array of kind strings

Nested

Definitions

def [](input)

Look up a resource by kind or full GVK string.

Accepts: instance["Deployment"] — kind-only lookup instance["apps/v1/Deployment"] — group/version/kind instance["v1/Pod"] — version/kind (core, empty group) instance["networking.k8s.io/v1/Ingress"] — fully qualified

Returns a class that inherits from Kube::Schema::Resource.

Custom schemas registered via Kube::Schema.register take precedence over built-in definitions (kind-only lookups only).

Implementation

def [](input)
  @resource_classes[input] ||= begin
    if input.include?("/")
      parts = input.split("/")

      case parts.length
      when 3
        group, version, kind = parts
      when 2
        group = ""
        version, kind = parts
      else
        raise "Invalid GVK format: #{input.inspect}." \
          "\nExpected \"group/version/kind\" or \"version/kind\"."
      end

      # Custom schemas take precedence on full-GVK lookups too.
      custom = find_custom_entry_by_gvk(group, version, kind)
      if custom
        return build_resource_class(Lazy::Source.spilled(catalog, custom[:entry]), custom[:defaults])
      end

      entry = find_gvk_entry_by_full_gvk(group, version, kind)
    else
      # Kind-only lookup — custom schemas take precedence.
      custom = find_custom_entry(input)
      if custom
        return build_resource_class(Lazy::Source.spilled(catalog, custom[:entry]), custom[:defaults])
      end

      entry = find_gvk_entry(input)
    end

    if entry.nil?
      raise "No resource schema found for #{input.inspect}!" \
        "\nUse #list_resources to see available kinds for v#{@version}."
    end

    ref_schema = Lazy::Source.indexed(catalog, entry[:definition_key])
    build_resource_class(ref_schema, entry[:defaults].freeze)
  end
end

def list_resources

All available resource kinds for this version, including any custom schemas registered via Kube::Schema.register.

Implementation

def list_resources
  custom_kinds = Schema.custom_schemas.values.map { |v| v[:defaults]["kind"] }
  (gvk_index.keys + custom_kinds).uniq.sort
end

def api_groups

All API groups known to this version, including any custom schemas registered via Kube::Schema.register. The core API group is the empty string.

instance.api_groups # => ["", "apps", "argoproj.io", "batch", ...]

Implementation

def api_groups
  custom_groups = Schema.custom_schemas.keys.filter_map do |key|
    parts = key.split("/")
    parts.first if parts.size == 3
  end
  (gvk_index.values.flatten.map { |entry| entry[:group] } + custom_groups).uniq.sort
end

def sub_spec(name)

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

Implementation

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 = Lazy::Source.indexed(catalog, definition_key)
    build_sub_spec_class(ref_schema, name)
  end
end

def list_definitions

All available definition short names for this version.

Implementation

def list_definitions
  catalog.keys
    .map { |k| k.split(".").last }
    .uniq.sort
end

def gvk_index

Builds a map from kind to full GVK entry: { "Deployment" => { definition_key: "io.k8s.api.apps.v1.Deployment", group: "apps", version: "v1", kind: "Deployment", defaults: "apiVersion" => "apps/v1", "kind" => "Deployment" }, "Pod" => { definition_key: "io.k8s.api.core.v1.Pod", group: "", version: "v1", kind: "Pod", defaults: "apiVersion" => "v1", "kind" => "Pod" }, ... }

Implementation

def gvk_index
  @gvk_index ||= begin
    index = Hash.new { |h, k| h[k] = [] }

    catalog.entries.each do |key, entry|
      gvks = entry.gvks
      next unless gvks

      gvks.each do |gvk|
        group = gvk["group"].to_s
        version = gvk["version"]
        kind = gvk["kind"]
        api_version = group.empty? ? version : "#{group}/#{version}"

        index[kind] << {
          definition_key: key,
          group: group,
          version: version,
          kind: kind,
          defaults: {
            "apiVersion" => api_version,
            "kind" => kind
          }
        }
      end
    end

    index
  end
end

def find_gvk_entry(kind)

Find a GVK entry by kind name (case-insensitive). Returns the first matching entry hash or nil.

Implementation

def find_gvk_entry(kind)
  entries = gvk_index[kind]
  return entries.first if entries && !entries.empty?

  gvk_index.each do |k, v|
    return v.first if k.downcase == kind.downcase
  end

  nil
end

def find_gvk_entry_by_full_gvk(group, version, kind)

Find a GVK entry by exact group, version, and kind. Returns the matching entry hash or nil.

Implementation

def find_gvk_entry_by_full_gvk(group, version, kind)
  entries = gvk_index[kind]
  return nil if entries.nil? || entries.empty?

  entries.find do |entry|
    entry[:group] == group && entry[:version] == version
  end
end

def find_custom_entry(kind)

Find a custom schema entry by kind (case-insensitive). The registry is keyed by full GVK, so match on each entry's recorded kind. When several groups register the same kind, the first registered wins. Returns the schema:, defaults: hash or nil.

Implementation

def find_custom_entry(kind)
  registry = Schema.custom_schemas
  registry.each_value { |v| return v if v[:defaults]["kind"] == kind }
  registry.each_value { |v| return v if v[:defaults]["kind"].casecmp?(kind) }

  nil
end

def find_custom_entry_by_gvk(group, version, kind)

Find a custom schema entry by exact group, version, and kind. Returns the schema:, defaults: hash or nil.

Implementation

def find_custom_entry_by_gvk(group, version, kind)
  api_version = group.empty? ? version : "#{group}/#{version}"
  Schema.custom_schemas["#{api_version}/#{kind}"]
end

def build_resource_class(schema_instance, defaults)

Build a Resource subclass from a JSONSchemer instance and defaults hash.

Implementation

def build_resource_class(schema_instance, defaults)
  Class.new(::Kube::Schema::Resource) do
    @schema = schema_instance
    @defaults = defaults
    @schema_properties = @schema.value["properties"].keys.map(&:to_sym)

    def self.schema
      @schema || superclass.schema
    end

    def self.defaults
      @defaults || superclass.defaults
    end

    def self.schema_properties
      @schema_properties || superclass.schema_properties
    end

    schema_instance.value["properties"].keys.then do |properties|
      properties.each do |prop|
        define_method(prop.to_sym) { @data[prop.to_sym] }
      end
    end
  end
end

def find_definition_key(name)

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)

Implementation

def find_definition_key(name)
  definitions = catalog.entries

  # 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

def build_sub_spec_class(schema_instance, definition_name)

Build a SubSpec subclass from a JSONSchemer instance and a human-readable definition name (for error messages).

Implementation

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 || superclass.definition_name
    end

    def self.schema_properties
      @schema_properties || superclass.schema_properties
    end

    schema_instance.value.fetch("properties", {}).keys.each do |prop|
      define_method(prop.to_sym) { @data[prop.to_sym] }
    end
  end
end

def clear_resource_cache!

Called by Kube::Schema.register and reset_custom_schemas! to invalidate cached resource classes so new registrations take effect.

Implementation

def clear_resource_cache!
  @resource_classes.clear
end