/ 
Net-Async-Kubernetes-0.007
/ Net::Async::Kubernetes::Controller

NAME

Net::Async::Kubernetes::Controller - Minimal controller runtime for Net::Async::Kubernetes

VERSION

version 0.007

SYNOPSIS

use IO::Async::Loop;
use Net::Async::Kubernetes;

my $loop = IO::Async::Loop->new;
my $kube = Net::Async::Kubernetes->new(
    kubeconfig => "$ENV{HOME}/.kube/config",
);
$loop->add($kube);

my $controller = $kube->controller(
    on_reconcile => sub {
        my ($ctx) = @_;

        return $ctx->{controller}->patch_status('Pod', $ctx->{object},
            status => { phase => 'Running' },
        );
    },
);

$controller->watch_resource('Pod', namespace => 'default');
$loop->run;

DESCRIPTION

Net::Async::Kubernetes::Controller is a minimal controller runtime built on top of Net::Async::Kubernetes and its watcher support.

It is intentionally small. The module focuses on the operational pieces most controllers need:

  • watch registration

  • keyed queueing with deduplication

  • serialized reconcile dispatch

  • retry hooks with configurable delay policy

  • status subresource helpers

It does not attempt to provide higher-level controller DSL sugar.

configure

Internal IO::Async::Notifier configuration method.

Accepted parameters:

kube

Existing Net::Async::Kubernetes instance to bind to.

kubeconfig, context, server, credentials, resource_map, resource_map_from_cluster

Client construction parameters used when kube is not supplied.

on_reconcile

Required reconcile callback. Receives a hashref with controller, kube, resource, event_type, object, key, and attempt.

retry_delay

Optional retry policy. Accepts a fixed scalar delay, an arrayref of delays, or a coderef receiving ($attempt, $ctx, $error).

kube

Returns the bound Net::Async::Kubernetes client.

on_reconcile

Returns the reconcile callback.

retry_delay

Returns the configured retry delay policy. Defaults to 1.

start

Starts all registered resource watches. Called automatically when the controller is added to an event loop.

stop

Stops registered watches and prevents further queue processing.

watch_resource

$controller->watch_resource('Pod',
    namespace => 'default',
    key_for   => sub {
        my ($object, $spec) = @_;
        return $object->metadata->name;
    },
);

Registers a watched resource and returns the watcher instance once started. Repeated events for the same reconcile key are coalesced into a single queued entry.

get_object

Thin wrapper around $controller->kube->get(...).

list_objects

Thin wrapper around $controller->kube->list(...).

patch_status

$controller->patch_status('Pod', 'my-pod',
    namespace => 'default',
    status    => { phase => 'Running' },
)->get;

Patch the /status subresource for an object. Accepts either a class/name pair or an object instance plus a status payload.

update_status

$controller->update_status($object)->get;

Update the /status subresource for a full object instance.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-net-async-kubernetes/issues.

IRC

Join #kubernetes on irc.perl.org or message Getty directly.

CONTRIBUTING

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

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.