/ 
Kubernetes-REST-1.000
River stage zero No dependents
⭐ Starred 2 GitHub stars
/ README.md

Kubernetes-REST

A Perl REST Client for the Kubernetes API

Description

Kubernetes::REST provides a simple, object-oriented interface to the Kubernetes API using IO::K8s resource classes. The IO::K8s classes know their own metadata (API version, kind, whether they're namespaced), so URL building is automatic.

For async applications, see Net::Async::Kubernetes which builds on top of Kubernetes::REST and IO::K8s with IO::Async.

Installation

cpanm Kubernetes::REST

Synopsis

use Kubernetes::REST;

my $api = Kubernetes::REST->new(
    server => { endpoint => 'https://kubernetes.local:6443' },
    credentials => { token => $token },
);

# List pods
my $pods = $api->list('Pod', namespace => 'default');
for my $pod ($pods->items->@*) {
    say $pod->metadata->name;
}

# Get a specific pod
my $pod = $api->get('Pod', name => 'my-pod', namespace => 'default');

# Create a pod
my $new_pod = $api->create($pod_object);

# Update a pod
my $updated = $api->update($pod);

# Patch a pod (partial update)
my $patched = $api->patch('Pod', 'my-pod',
    namespace => 'default',
    patch     => { metadata => { labels => { env => 'staging' } } },
);

# Delete a pod
$api->delete($pod);

# Watch for changes
my $rv = $api->watch('Pod',
    namespace => 'default',
    on_event  => sub {
        my ($event) = @_;
        say $event->type . ': ' . $event->object->metadata->name;
    },
);

Using kubeconfig

use Kubernetes::REST::Kubeconfig;

# Use default ~/.kube/config and current context
my $api = Kubernetes::REST::Kubeconfig->new->api;

# Use a specific kubeconfig and context
my $api = Kubernetes::REST::Kubeconfig->new(
    kubeconfig_path => '/path/to/kubeconfig',
    context_name    => 'my-cluster',
)->api;

Supports token auth, client certificates (file and inline base64), and exec credential plugins.

HTTP Debugging

The default HTTP backend uses LWP::UserAgent, which supports LWP::ConsoleLogger for inspecting HTTP traffic:

use LWP::ConsoleLogger::Easy qw(debug_ua);

my $api = Kubernetes::REST->new(
    server      => { endpoint => 'https://kubernetes.local:6443' },
    credentials => { token => $token },
);

# Attach logger to see all HTTP requests/responses
debug_ua($api->io->ua);

$api->list('Pod', namespace => 'default');  # now shows HTTP traffic

To use HTTP::Tiny instead:

use Kubernetes::REST::HTTPTinyIO;

my $api = Kubernetes::REST->new(
    server      => ...,
    credentials => ...,
    io          => Kubernetes::REST::HTTPTinyIO->new,
);

Pluggable IO Architecture

The HTTP transport is decoupled via Kubernetes::REST::Role::IO. Implement call($req) and call_streaming($req, $callback) to plug in any HTTP backend (async, testing, etc.):

package My::AsyncIO;
use Moo;
with 'Kubernetes::REST::Role::IO';

sub call { ... }
sub call_streaming { ... }

CLI Tools

kube_client

Interactive CLI for Kubernetes CRUD operations:

kube_client get Pod -n default
kube_client get Pod my-pod -n default
kube_client create -f pod.json
kube_client delete Pod my-pod -n default

kube_watch

Watch Kubernetes resources for changes in real-time:

# Watch all pods across all namespaces
kube_watch Pod

# Watch pods in a specific namespace
kube_watch Pod -n default

# Filter by event type
kube_watch Pod -T ADDED,DELETED

# Filter by label
kube_watch Deployment -n production -l app=web

# JSON output for piping
kube_watch Pod -o json | jq '.object.metadata.name'

# Custom timestamp format
kube_watch Pod -F time      # 14:23:01
kube_watch Pod -F iso       # 2025-02-12T14:23:01+0100

Custom Resource Definitions (CRDs)

Register your own CRD classes and use them with the same API:

use My::StaticWebSite;

my $api = Kubernetes::REST->new(
    server      => ...,
    credentials => ...,
    resource_map => {
        StaticWebSite => '+My::StaticWebSite',
    },
);

my $site = $api->new_object(StaticWebSite =>
    metadata => { name => 'my-blog', namespace => 'default' },
    spec     => { domain => 'blog.example.com', replicas => 2 },
);
my $created = $api->create($site);

See Kubernetes::REST::Example for full CRD documentation including AutoGen from cluster OpenAPI specs.

Features

See Also

License

Apache 2.0

Authors