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:
- Exact match on full key (for power users)
- Short-name match on last segment
- 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