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

NAME

IO::K8s::Role::APIObject - Role for top-level Kubernetes API objects

VERSION

version 1.108

metadata

Standard object's metadata. See IO::K8s::Apimachinery::Pkg::Apis::Meta::V1::ObjectMeta.

A plain hashref is coerced (since 1.108), exactly as on any other object-bearing field, so

IO::K8s::Api::Core::V1::Pod->new(
    metadata => { name => 'web', namespace => 'prod' },
    spec     => { containers => [ { name => 'c', image => 'nginx' } ] });

builds the ObjectMeta itself. It is the same inflation "FROM_HASH" in IO::K8s::Role::Resource performs, so an unknown field inside metadata is preserved (or refused under IO::K8s->new(strict => 1)) identically on both routes. An ObjectMeta passed in is used as it is.

api_version

Returns the Kubernetes API version derived from the class name. For a consumer subclass registered via "class_namespaces" in IO::K8s, the version is derived from the first ancestor in a known namespace.

$pod->api_version;  # "v1"
$deployment->api_version;  # "apps/v1"

Derived identity, not a writable field: passing an argument croaks rather than silently rebinding (k67). CRD classes installed via "api_version" in IO::K8s::APIObject install a fixed-value method with the same contract -- see there for the precise error message.

kind

Returns the Kubernetes kind derived from the class name: the last :: segment, or the whole name for a single-segment class such as a CRD registered as +Widget.

$pod->kind;  # "Pod"
$deployment->kind;  # "Deployment"

Derived identity, not a writable field: passing an argument croaks rather than silently rebinding (k67). Auto-generated CRD classes install a fixed-value method with the same contract -- see IO::K8s::AutoGen for the precise error message.

resource_plural

Returns the plural resource name Kubernetes addresses this Kind by in RBAC resources: rules, and in REST paths for a Kind on an API track upstream still serves, or undef when there is none.

$pod->resource_plural;            # "pods"
$endpoints->resource_plural;      # "endpoints"
$network_policy->resource_plural; # "networkpolicies"
$ingress->resource_plural;        # "ingresses"

For built-in Kinds the value comes from two tables generated from the upstream OpenAPI spec's REST paths. The exact API version and kind are looked up first, so Event in the core group and Event in events.k8s.io resolve independently. A Kind on an API track upstream no longer serves then falls back to its API group and kind: the plural is a property of the GroupResource, which is what RBAC apiGroups/resources rules address, and the fallback is only generated where every version of that group agrees on the plural. It is still group and kind, never a bare kind, so the two Events stay distinct on that path too.

That fallback value is right for RBAC, and no other plural would serve a Kind on such a track better -- do not "fix" it. It is not a promise that the REST path built from the plural and the class's own api_version resolves: upstream has stopped serving that track entirely, so the path 404s against a current cluster regardless of what the plural is.

A consumer subclass registered via "class_namespaces" in IO::K8s inherits the plural from its first ancestor in a known namespace, the same way api_version does.

undef means "not a top-level resource, or not known" and should never be turned into a guess: Eviction, Scale and TokenRequest are subresources (pods/eviction, deployments/scale, serviceaccounts/token) and have no plural of their own, and the embedded PodTemplateSpec-style types never appear as a kind: on the wire at all.

CRD classes declare their own, which always wins over the built-in table:

use IO::K8s::APIObject
    api_version     => 'homelab.example.com/v1',
    resource_plural => 'staticwebsites';

Derived identity, not a writable field: passing an argument croaks rather than silently rebinding (k70). CRD classes installed via "resource_plural" in IO::K8s::APIObject install a fixed-value method with the same contract -- see there for the precise error message.

to_crd

my $crd = $pod->to_crd;
my $crd = IO::K8s::Api::Core::V1::Pod->to_crd;

The CustomResourceDefinition this class's own attribute registry describes (D9), emitted through "crd_for_class" in IO::K8s::CRD. It is a schema export, not a lossless reverse round-trip through add_crd: see "crd_for_class" in IO::K8s::CRD for the Quantity export and typed-map / scalar-array inference limits.

to_yaml

my $yaml = $pod->to_yaml;

Serialize the object to YAML format suitable for kubectl apply -f.

save

$pod->save('pod.yaml');

Save the object to a YAML file. Returns the object for chaining.

add_label

$obj->add_label(app => 'web');

Add a single label. Returns $self for chaining.

add_labels

$obj->add_labels(app => 'web', tier => 'frontend');

Add multiple labels at once. Returns $self for chaining.

label

my $val = $obj->label('app');  # => 'web'

Get the value of a single label, or undef if missing.

has_label

$obj->has_label('app');  # => 1

Returns true if the label key exists.

remove_label

$obj->remove_label('tier');

Remove a label by key. Returns $self for chaining.

match_labels

$obj->match_labels(app => 'web', tier => 'frontend');  # => Bool

Returns true if all given key/value pairs match the object's labels.

add_annotation

$obj->add_annotation('prometheus.io/scrape' => 'true');

Add a single annotation. Returns $self for chaining.

annotation

my $val = $obj->annotation('prometheus.io/scrape');

Get the value of a single annotation, or undef if missing.

has_annotation

$obj->has_annotation('prometheus.io/scrape');  # => 1

Returns true if the annotation key exists.

remove_annotation

$obj->remove_annotation('prometheus.io/scrape');

Remove an annotation by key. Returns $self for chaining.

conditions

my $conds = $obj->conditions;  # => ArrayRef

Returns all status conditions as an arrayref.

get_condition

my $cond = $obj->get_condition('Ready');  # => hashref/object or undef

Get a single condition by type name.

is_condition_true

$obj->is_condition_true('Available');  # => Bool

Returns true if the named condition has status = "True".

is_ready

$obj->is_ready;  # => Bool

Returns true if the Ready or Available condition is true.

condition_message

my $msg = $obj->condition_message('Ready');

Returns the message string for the named condition, or undef.

set_owner

$pod->set_owner($deployment);
$pod->set_owner($configmap, controller => 0);

Add an ownerReference pointing to another API object. Returns $self for chaining.

The owner must carry a metadata.uid — the uid is assigned by the API server, so only an object read back from the cluster can be referenced. A locally built owner (no metadata, or no uid) makes set_owner die, naming the owner.

controller => 0|1 (default 1) marks the reference as the managing controller. Kubernetes allows at most one ownerReference with controller: true per object: adding a second one dies, naming the existing controller reference — pass controller => 0 for additional, non-controlling owners.

Setting the same owner twice (same uid) is an idempotent no-op, even when the repeated call asks for controller — the existing reference is left untouched.

blockOwnerDeletion is never set; upstream defaults it to false.

is_owned_by

$pod->is_owned_by($deployment);  # => Bool

Returns true if this object has an ownerReference matching the given object.

owner_refs

my $refs = $obj->owner_refs;  # => ArrayRef

Returns the ownerReferences array, or an empty arrayref.

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