NAME
IO::K8s::Role::Resource - Role providing Kubernetes resource instance behavior
VERSION
version 1.110
UNKNOWN FIELDS
A constructor key that no k8s-declared attribute claims is not dropped, at every nesting level and every entry point -- a top-level ->new, "inflate" in IO::K8s, "new_object" in IO::K8s, "json_to_object" in IO::K8s, "struct_to_object" in IO::K8s, and every inline struct built along the way. It exists so a document written against a newer upstream schema than this distribution ships still round-trips instead of silently losing the field. TO_JSON re-emits it alongside the declared attributes, with a declared attribute winning on a name clash. The bag itself lives on _unknown_fields, a plain hashref attribute that TO_JSON's own attribute walk never sees as a field of its own.
An instance created through IO::K8s with strict => 1 turns this into a fatal error instead: any key that would otherwise land in the bag dies as Unknown field '<name>' for <class>, again at every nesting level, for the duration of that call.
Since 1.108, IO::K8s::List -- the generic envelope a list Kind (PodList, a bare kind: List, ...) inflates to -- composes this role too, so its own top-level keys besides items/metadata/item_class are preserved and checked exactly like any other resource's, under strict or otherwise. It keeps its own hand-rolled TO_JSON/FROM_STRUCT rather than the role's (kind/api_version derive from the items, not from a class name) but reuses this exact bag and BUILD mechanism for the envelope. Objects inside items round-trip independently, each through its own class's composition of this role.
TO_JSON
my $struct = $pod->TO_JSON;Returns a plain hashref representation of the object suitable for JSON encoding -- the canonical wire format Kubernetes accepts. Walks the attribute registry of the class and emits each declared field with the right JSON type: integers unquoted, booleans as true/false, nested objects recursively via their own TO_JSON, hashes and arrays of objects in their canonical shape. A Str field and each element of a [Str] array are always emitted as a JSON string, even when the Perl value itself is numeric: EnvVar->new(value => 8080) serializes value as "8080", not a bare 8080. The other way round, a Num field and each element of a [Num] array are always emitted as a JSON number, so a numeric string such as '0.25' goes out unquoted. Each element of an [IntOrStr] array follows the rule of an IntOrStr field: an all-digit value goes out as a JSON number, anything else ('25%', 'http') as the string it is. A Quantity or Time value always goes out as a JSON string, the form Kubernetes writes both in -- a scalar field, each value of a { Quantity => 1 } or { Time => 1 } map and each element of a [Quantity] or [Time] array alike: limits => { cpu => 1 } is emitted as {"cpu":"1"}. The object keeps the value it was given. Each value of a string map -- { Str => 1 } or HashRef[Str]: labels, annotations, ConfigMap data, ... -- goes out as a JSON string too, so labels => { v => 5 } is {"v":"5"}. A reference value in a { Str => 1 } map is copied through unchanged and warns once per class and field, in the deprecated category: declare such a field Opaque or HashRef[...]. The free map, Opaque or a bare HashRef (fieldsV1, a RawExtension, ...), is exempt from all of this -- its values are copied through unchanged, keeping whatever JSON type they already had. For classes that compose IO::K8s::Role::APIObject, the apiVersion, kind and metadata fields are prepended.
A field that holds undef is omitted -- unless it is declared nullable and present, which has_<accessor> tells: that one is written as an explicit JSON null (see "Field options" in IO::K8s::Resource).
This is the entry point "to_json" builds on, and the inverse of "FROM_HASH".
to_json
my $json = $pod->to_json;Returns a UTF-8 encoded JSON byte string for the object. Thin wrapper over "TO_JSON" that runs the resulting hashref through the canonical encoder configured internally. Symmetric to "from_json" on the consumer side.
TO_YAML
my $yaml_string = $pod->TO_YAML;Returns a YAML string for the object, built via YAML::PP on top of "TO_JSON". Real booleans and numbers go out bare. A string is quoted whenever a JSON, YAML 1.2 core or YAML 1.1 reader would take its bare form for a boolean, null or number (True, yes, on, ~, 012, 0x1F, +1, ...), so kubectl and the API server read it back as a string. Symmetric to "TO_JSON" -- the YAML is just another wire format over the same canonical struct.
to_yaml
my $yaml_string = $pod->to_yaml;Returns a YAML byte string for the object, suitable for kubectl apply -f. Thin wrapper over "TO_YAML"; provided so the role offers both TO_JSON and "save" in IO::K8s::APIObject a single canonical entry point.
FROM_HASH
my $pod = IO::K8s::Api::Core::V1::Pod->FROM_HASH($struct);Builds an object of this class from a plain hashref of JSON field names, inflating nested objects, arrays of objects and hashes of objects through the attribute registry -- the same inflation "inflate" in IO::K8s performs, so a struct from "TO_JSON" round-trips back. Before 1.108 this was a bare $class->new(%$hash) and any nested field had to be pre-built.
A defined value at an object-bearing position that is not a hashref (or already an object of the right class) -- an arrayref, a plain string, a code or scalar reference -- fails closed the same way inflation does everywhere else: it croaks naming the target class, the shape it actually received, and, for a nested field, the field itself, rather than silently building an empty object. So does a blessed value whose class has no TO_JSON returning a hashref, such as a JSON boolean, and an array or hash field holding the wrong container. See "new_object" in IO::K8s for the exact messages. undef and an omitted field are unaffected and remain allowed.
from_json
my $pod = IO::K8s::Api::Core::V1::Pod->from_json($json_bytes);Builds an object of this class from a JSON document, symmetric to "to_json". The argument is a UTF-8 encoded byte string -- exactly what to_json produces; a decoded character string is not accepted and fails loudly in the JSON decoder rather than silently round-tripping to mojibake. Decode-tolerance was rejected on purpose: it would leave from_json more permissive than $k8s->json_to_object, which has always been byte-oriented.
compare_to_schema
my $diff = IO::K8s::Api::Core::V1::Pod->compare_to_schema($swagger_def);Drift detector used by "spec-drift-check.pl" in maint and other coverage checks. Compares this class's declared attributes against an OpenAPI schema hashref (one entry from a swagger.json) and returns a hashref:
{
missing_locally => [ ...property names the schema has but the class does not... ],
missing_in_schema => [ ...json_key names the class has but the schema does not... ],
type_mismatch => [ { attr => $name, local => $type, schema => $type }, ... ],
}apiVersion, kind and metadata are skipped on the schema side -- they are not declared with the k8s DSL but are supplied by IO::K8s::Role::APIObject and the role mesh.
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