/ 
IO-K8s-1.108
⭐ Starred 0 / IO::K8s::Role::Resource

NAME

IO::K8s::Role::Resource - Role providing Kubernetes resource instance behavior

VERSION

version 1.108

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 k99, 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. For classes that compose IO::K8s::Role::APIObject, the apiVersion, kind and metadata fields are prepended.

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". Uses the JSON schema with JSON booleans (so true/false survive the round-trip the way they would to the API server). 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 (k59). Before 1.108 this was a bare $class->new(%$hash) and any nested field had to be pre-built.

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 (k53). 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