/ 
Kubernetes-Comb-0.001
/ Kubernetes::Comb::Role::Client

NAME

Kubernetes::Comb::Role::Client - The Kubernetes client surface a Comb works through

VERSION

version 0.001

SYNOPSIS

package My::Client;
use Moo;
with 'Kubernetes::Comb::Role::Client';
sub get { ... }   # and the rest of the surface

# what a Comb does with any of them
$comb->k8s->list('Pod', namespace => 'platform', labelSelector => 'app=nats')
  ->then(sub { my ( $list ) = @_; ... });

DESCRIPTION

The one seam between a Comb and Kubernetes. A Comb never talks to Kubernetes::REST or Net::Async::Kubernetes directly; it calls these methods on its k8s client. Kubernetes::Comb::Client::Sync and Kubernetes::Comb::Client::Async implement them, and so does the fake client of the test suite, which is how that fake stays interchangeable with the real ones.

The role only names the surface. Every request method returns a Future and never throws: a failure, including bad arguments, is a failed Future. Its failure is the message the underlying client produced, for an API error Kubernetes API error (<what>): <status> <body>. "server_url" and "for_context" are plain methods.

Resource names are what Kubernetes::REST takes: a short Kind ('Pod'), a qualified 'group/version/Kind', or '+Full::Class' -- the last one needs no resource map, which is how a Comb addresses its own CR class.

get

my $f = $client->get('Deployment', 'nats', namespace => 'platform');

Future of the object.

list

my $f = $client->list('Pod', namespace => 'platform', labelSelector => 'app=nats');

Future of an IO::K8s::List; the objects are in ->items. Without namespace it lists across all namespaces.

ensure

my $f = $client->ensure($object_or_hashref);

Create or update. Future of the object as stored. status is not written this way -- see "update_status".

Two kinds are not updated once they exist, as ensure of Kubernetes::REST and Net::Async::Kubernetes has it: a v1 PersistentVolumeClaim is returned as it is, and so is a batch/v1 Job that runs or has succeeded (status.active, status.succeeded); any other existing Job is deleted and created anew. A Comb relies on that: what is left as it is never makes "reconcile" in Kubernetes::Comb deploy by its digest.

delete

my $f = $client->delete('Service', 'nats', namespace => 'platform');
my $f = $client->delete($object);
my $f = $client->delete($job, propagationPolicy => 'Background');

Future of 1. propagationPolicy (Background, Foreground or Orphan) decides what becomes of the objects the deleted one owns; without it the API server orphans the Pods of a Job. Any other option fails the Future.

update

my $f = $client->update($object);

Full replacement (PUT) of the main resource. Future of the stored object.

patch

my $f = $client->patch('Deployment', 'nats',
  namespace => 'platform',
  patch     => { spec => { replicas => 0 } },
  type      => 'strategic',   # or merge, json
);
my $f = $client->patch($object, patch => { ... });

Future of the patched object.

update_status

my $f = $client->update_status($object);

Replaces status through the status subresource; needs the current resourceVersion. Future of the stored object.

patch_status

my $f = $client->patch_status($object, patch => { status => { phase => 'Running' } });

Merge patch (the default type) through the status subresource, no resourceVersion needed. Future of the stored object.

log

my $f = $client->log('Pod', 'nats-0',
  namespace => 'platform',
  container => 'nats',
  previous  => 1,
  tailLines => 100
);

Future of the log text.

server_url

my $url = $client->server_url;

The API server URL of this client's context. Croaks when the context cannot be resolved. Two clients whose URLs are equal talk to the same cluster.

for_context

my $dev = $client->for_context('dev');

A client of the same class for another kube context from the same kubeconfig, made once per context and kept -- Kubernetes::Comb::Upstream::K8s asks for it on every step. Resolving the context is deferred: a missing or broken context fails the first request's Future, and makes "server_url" croak.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-kubernetes-comb/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 <getty@cpan.org>

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.