NAME

Net::Async::Kubernetes - Async Kubernetes client for IO::Async

VERSION

version 0.001

SYNOPSIS

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

my $loop = IO::Async::Loop->new;

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

# Or with explicit server/credentials
my $kube = Net::Async::Kubernetes->new(
    server      => { endpoint => 'https://kubernetes.local:6443' },
    credentials => { token => $token },
);
$loop->add($kube);

# Future-based CRUD
my $pods = $kube->list('Pod', namespace => 'default')->get;

my $pod = $kube->get('Pod', 'nginx', namespace => 'default')->get;

my $patched = $kube->patch('Pod', 'nginx',
    namespace => 'default',
    patch     => { metadata => { labels => { env => 'staging' } } },
)->get;

$kube->delete('Pod', 'nginx', namespace => 'default')->get;

# Watcher with auto-reconnect
my $watcher = $kube->watcher('Pod',
    namespace   => 'default',
    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 },
);

$loop->run;

DESCRIPTION

Net::Async::Kubernetes is an async Kubernetes client built on IO::Async. It extends IO::Async::Notifier and uses Net::Async::HTTP for non-blocking HTTP communication.

All CRUD methods return Future objects. The Net::Async::Kubernetes::Watcher provides auto-reconnecting event streaming with separate callbacks per event type.

Request preparation and response processing are delegated to Kubernetes::REST, so the same IO::K8s object inflation, short class names, and CRD support are available.

configure

Internal IO::Async::Notifier configuration method. Handles initialization of kubeconfig, context, server, credentials, resource_map, and resource_map_from_cluster parameters.

If kubeconfig is provided without explicit server or credentials, they are loaded automatically via Kubernetes::REST::Kubeconfig.

kubeconfig

Path to kubeconfig file. If provided, server and credentials are extracted automatically (via Kubernetes::REST::Kubeconfig).

context

Kubernetes context to use from the kubeconfig. Defaults to current-context.

resource_map

Optional. Custom resource map for short class names.

resource_map_from_cluster

Optional boolean. Load resource map from cluster OpenAPI spec. Defaults to false.

server

Returns the Kubernetes::REST::Server instance. Croaks if neither server nor kubeconfig was provided during initialization.

credentials

Returns the credentials object (typically Kubernetes::REST::AuthToken). Croaks if neither credentials nor kubeconfig was provided during initialization.

expand_class

my $full_class = $kube->expand_class('Pod');
# Returns 'IO::K8s::Api::Core::V1::Pod'

Expands a short resource name (e.g., 'Pod', 'Deployment') to its full IO::K8s class name. Delegates to "expand_class" in Kubernetes::REST.

list

my $future = $kube->list('Pod', namespace => 'default');
my $pods = $future->get;

List resources of the given type. Returns a Future that resolves to an ArrayRef of inflated IO::K8s objects.

Arguments:

$short_class - Resource type (e.g., 'Pod', 'Deployment')

%args - Optional parameters (namespace, etc.)

get

my $future = $kube->get('Pod', 'nginx', namespace => 'default');
my $pod = $future->get;

Get a single resource by name. Returns a Future that resolves to an inflated IO::K8s object.

Arguments:

$short_class - Resource type (e.g., 'Pod')

$name - Resource name (required)

%args - Optional parameters (namespace, etc.)

create

my $future = $kube->create($pod_object);
my $created = $future->get;

Create a resource from an IO::K8s object. Returns a Future that resolves to the created object with server-populated fields (resourceVersion, etc.).

Arguments:

$object - IO::K8s object instance (e.g., IO::K8s::Api::Core::V1::Pod)

update

my $future = $kube->update($modified_pod);
my $updated = $future->get;

Update an existing resource. The object must have metadata.name (and metadata.namespace if namespaced). Returns a Future that resolves to the updated object.

Arguments:

$object - Modified IO::K8s object with updated fields

patch

# By class and name
my $future = $kube->patch('Pod', 'nginx',
    namespace => 'default',
    patch     => { metadata => { labels => { env => 'prod' } } },
    type      => 'strategic',  # or 'merge', 'json'
);

# Or by object
my $future = $kube->patch($pod_object,
    patch => { spec => { replicas => 3 } },
);

Patch an existing resource. Returns a Future that resolves to the patched object.

Arguments:

$class_or_object - Resource class name or IO::K8s object

name - Resource name (required unless passing object)

namespace - Namespace (if namespaced)

patch - HashRef of changes to apply (required)

type - Patch type: 'strategic' (default), 'merge', or 'json'

delete

# By class and name
my $future = $kube->delete('Pod', 'nginx', namespace => 'default');
$future->get;

# Or by object
my $future = $kube->delete($pod_object);
$future->get;

Delete a resource. Returns a Future that resolves to 1 on success.

Arguments:

$class_or_object - Resource class name or IO::K8s object

$name - Resource name (required unless passing object)

%args - Optional parameters (namespace, etc.)

watcher

my $watcher = $kube->watcher('Pod',
    namespace      => 'default',
    label_selector => 'app=web',
    on_added       => sub { my ($pod) = @_; ... },
    on_modified    => sub { my ($pod) = @_; ... },
    on_deleted     => sub { my ($pod) = @_; ... },
);

Create and register a Net::Async::Kubernetes::Watcher for the specified resource type. The watcher is added as a child notifier and will start automatically when the parent is added to a loop.

Returns the watcher object.

Arguments:

$resource - Resource type to watch (e.g., 'Pod', 'Deployment')

%args - Watcher parameters (namespace, label_selector, callbacks, etc.)

See Net::Async::Kubernetes::Watcher for all available parameters.

NAME

Net::Async::Kubernetes - Async Kubernetes client for IO::Async

SEE ALSO

Net::Async::Kubernetes::Watcher, Kubernetes::REST, IO::Async, IO::K8s

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

cpanm Net::Async::Kubernetes

perl -MCPAN -e shell
install Net::Async::Kubernetes