/ 
Net-Async-Kubernetes-0.001
/ Net::Async::Kubernetes::Watcher

NAME

Net::Async::Kubernetes::Watcher - Auto-reconnecting Kubernetes watch as IO::Async::Notifier

VERSION

version 0.001

SYNOPSIS

my $watcher = $kube->watcher('Pod',
    namespace      => 'default',
    label_selector => 'app=web',
    on_added       => sub { my ($pod) = @_; say "Added: " . $pod->metadata->name },
    on_modified    => sub { my ($pod) = @_; say "Modified: " . $pod->metadata->name },
    on_deleted     => sub { my ($pod) = @_; say "Deleted: " . $pod->metadata->name },
    on_error       => sub { my ($status) = @_; warn "Error: $status->{message}" },
);

# Client-side filtering by name and event type
$kube->watcher('Pod',
    namespace   => 'default',
    names       => [qr/^nginx/, qr/^redis/],  # only matching names
    event_types => ['ADDED', 'DELETED'],        # skip MODIFIED
    on_added    => sub { ... },
    on_deleted  => sub { ... },
);

# Watch multiple resources concurrently
$kube->watcher('Deployment', namespace => 'production', on_modified => sub { ... });
$kube->watcher('Service', namespace => 'production', on_added => sub { ... });

# Stop watching
$watcher->stop;

# Restart
$watcher->start;

DESCRIPTION

An IO::Async::Notifier that watches a Kubernetes resource for changes. Created via "watcher" in Net::Async::Kubernetes.

The watcher automatically:

  • Reconnects when the server-side timeout expires

  • Resumes from the last resourceVersion to avoid missing events

  • Handles 410 Gone by clearing the resourceVersion and restarting

  • Retries on connection errors after a 1-second delay

  • Filters events client-side by name patterns (names) and event types (event_types)

configure

Internal IO::Async::Notifier configuration method. Handles initialization of kube, resource, namespace, timeout, label_selector, field_selector, names, event_types, and all event callbacks (on_added, on_modified, on_deleted, on_error, on_event).

kube

Returns the parent Net::Async::Kubernetes instance.

resource

Required. The Kubernetes resource kind to watch (e.g., 'Pod', 'Deployment').

namespace

Optional. Namespace to watch. Omit for cluster-scoped resources or to watch all namespaces.

timeout

Server-side timeout per watch cycle in seconds. Default: 300.

label_selector

Optional label selector (e.g., 'app=web,env=prod').

field_selector

Optional field selector (e.g., 'status.phase=Running').

names

Optional client-side filter for resource names. Accepts a single regex, a string (exact match), or an arrayref of regexes/strings. Events whose resource name does not match any of the patterns are silently dropped before callbacks fire.

# Single regex
names => qr/^nginx/

# Multiple patterns (any match passes)
names => [qr/^nginx/, qr/^redis/]

# Exact string match
names => 'my-pod'

event_types

Optional client-side filter for event types. Accepts an arrayref of type strings (ADDED, MODIFIED, DELETED, ERROR). Events whose type is not in the list are silently dropped.

# Only ADDED and DELETED events
event_types => ['ADDED', 'DELETED']

When not set, event types are automatically derived from which callbacks are registered. If only on_added is set, only ADDED events are dispatched. If on_event is set (catch-all), all types pass through.

on_added

Callback for ADDED events. Receives the inflated IO::K8s object.

on_modified

Callback for MODIFIED events. Receives the inflated IO::K8s object.

on_deleted

Callback for DELETED events. Receives the inflated IO::K8s object.

on_error

Callback for ERROR events. Receives the raw error hashref.

on_event

Catch-all callback. Receives the Kubernetes::REST::WatchEvent object. Called in addition to the type-specific callbacks.

start

Start (or restart) the watch stream. Called automatically when the watcher is added to the event loop. Safe to call multiple times (idempotent).

stop

Stop the watch stream and cancel the current HTTP request. The watcher will not automatically reconnect until start() is called again.

NAME

Net::Async::Kubernetes::Watcher - Auto-reconnecting Kubernetes watch as IO::Async::Notifier

SEE ALSO

Net::Async::Kubernetes, Kubernetes::REST::WatchEvent, IO::Async::Notifier

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) 2025 by Torsten Raudssus.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004