/ 
IO-K8s-1.108
⭐ Starred 0 / IO::K8s::List

NAME

IO::K8s::List - Generic list container for Kubernetes API responses

VERSION

version 1.108

SYNOPSIS

use IO::K8s::List;

my $list = IO::K8s::List->new(
    items => \@pods,
    metadata => $list_meta,
);

# apiVersion and kind are derived from items
print $list->api_version;  # v1
print $list->kind;         # PodList

DESCRIPTION

Generic container for Kubernetes list responses. Instead of having separate PodList, ServiceList, DeploymentList classes, this single class handles all list types.

The apiVersion and kind are automatically derived from the items.

items

Array of Kubernetes API objects. Required.

metadata

List metadata (IO::K8s::Apimachinery::Pkg::Apis::Meta::V1::ListMeta). Contains pagination info like continue and resourceVersion.

item_class

Optional. The class of items in the list. If not provided, derived from the first item. Used for empty lists where the type can't be inferred, or to override the item type "FROM_STRUCT" would otherwise derive.

Accepted only as a fully-qualified class name, exactly like every other class-name-taking parameter in this distribution: a leading + is stripped before use ("this is already a full class name"), and a short or partially-qualified name is not guessed at -- "kind" and "api_version" simply have nothing to derive from it (k49).

api_version

Returns the Kubernetes API version, derived from items or item_class.

kind

Returns the Kubernetes kind (e.g., "PodList"), derived from items or item_class. For an item_class the Kind is its last :: segment, or the whole name for a single-segment class such as a CRD registered as +Widget -- but only when "api_version" can also resolve for the same item_class; otherwise undef, never a Kind with no apiVersion to go with it (k49).

FROM_STRUCT

my $list = IO::K8s::List->FROM_STRUCT($struct, $k8s);

Inflation hook called by "inflate" in IO::K8s (and so by json_to_object and struct_to_object) whenever the wire kind is List or ends in List -- the shape every real Kubernetes API list response has, and the generic kind: List wrapper besides. Upstream a list response carries no apiVersion/kind on the individual items (the API server omits them there), so the item type is derived from the LIST's own Kind and apiVersion: kind: PodList, apiVersion: v1 means items are v1/Pod.

item_class travels as a sibling key of kind/apiVersion/items in the struct to override the derived type -- the same "use this class, don't derive one" meaning it already has for an empty list built directly via new. It is the only way to inflate a bare kind: List payload, whose Kind minus its List suffix is empty and so derives nothing on its own.

Fails closed (k39/k46): an item Kind that cannot be resolved to a class dies with the same "Cannot resolve Kubernetes GVK" error every other entry point in this distribution uses, naming the ITEM's kind/apiVersion, never a silently empty or half-inflated list.

TO_JSON

my $struct = $list->TO_JSON;

Returns the canonical wire-format hashref for the list: apiVersion and kind when "api_version" and "kind" can derive them, plus an items array of each entry's own TO_JSON (untouched when an item is not a blessed object with a TO_JSON method) and metadata when set. This is the inverse of "FROM_STRUCT" and the input "to_json" runs through its JSON encoder.

to_json

my $json_bytes = $list->to_json;

Serializes the List to a canonical JSON document as a UTF-8 encoded byte string -- the same convention every IO::K8s::Role::Resource class uses (k53), and the input "from_json" reads back (k64).

from_json

my $list = IO::K8s::List->from_json($json_bytes);
my $list = IO::K8s::List->from_json($json_bytes, $k8s);

Builds a List from a JSON document, symmetric to "to_json". The argument is a UTF-8 encoded byte string -- exactly what to_json emits -- and is decoded and handed to "FROM_STRUCT", so the items inflate to typed objects the same way "inflate" in IO::K8s does. Pass an IO::K8s instance as the second argument when the item types must resolve through that instance's providers or class_namespaces; without one a shared default instance is used, as FROM_STRUCT does.

List composes IO::K8s::Role::Resource (since k99) so its top-level envelope gets the same _unknown_fields bag and strict handling as every other resource, but it is a container, not an API object with its own GVK, so to_json/from_json/TO_JSON/FROM_STRUCT stay hand-rolled overrides rather than the role's own -- kind/api_version derive from the items, not from a class name. $k8s->inflate reaches the same FROM_STRUCT path from a full wire payload and remains the entry point when the Kind is only known at runtime.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/pplu/io-k8s-p5/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHORS

  • Torsten Raudssus <getty@cpan.org>

  • Jose Luis Martinez Torres <jlmartin@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018-2026 by Jose Luis Martinez Torres <jlmartin@cpan.org>.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004