/ 
Kubernetes-Comb-0.001
/ Kubernetes::Comb::Role::Upstream

NAME

Kubernetes::Comb::Role::Upstream - What a Comb borrows its service from instead of running it

VERSION

version 0.001

SYNOPSIS

package MyApp::Upstream::Catalog;
use Moo;
with 'Kubernetes::Comb::Role::Upstream';

has url => ( is => 'ro', required => 1 );

sub status {
  my ( $self, $comb ) = @_;
  return Future->done( { reachable => 1, phase => 'Running', via => [ 'vendor' ] } );
}

sub endpoints {
  my ( $self, $comb ) = @_;
  return Future->done( [
    Kubernetes::Comb::Endpoint->new( name => 'api', port => 443, cluster => 'catalog.example.com:443' )
  ] );
}

# in a Comb class, or returned by the upstream coderef of the controlling code
sub upstream { '+MyApp::Upstream::Catalog' => ( url => 'https://catalog.example.com' ) }

DESCRIPTION

An upstream is where a Comb borrows its service from instead of running it itself. "reconcile" in Kubernetes::Comb accepts as upstream any object doing this role, and builds one from the short forms (K8s => (...), '+Full::Class' => (...)) and from spec.upstream of the custom resource -- the arguments go to new, so an upstream class takes the keys the custom resource names as its constructor arguments.

The Comb is not a constructor argument: every method gets it as its first argument, so the upstream can take the Comb's namespace, name and client from it.

status

my $seen = $upstream->status($comb)->get;

Future of a hashref:

reachable

Whether the upstream can be used at all. False makes the Comb Blocked, with message as the reason. An upstream reports unreachability this way, not by failing: a failed Future makes the Comb Error.

phase

The phase the upstream reports for itself; the Comb is Running only while it is Running.

via

Optional arrayref of the layers the service is borrowed through, nearest first -- for a chain [ 'dev', 'prod' ].

context

Optional kube context of the upstream, recorded in status.upstream.

message

Optional, human-readable: why it is unreachable, or what else there is to know.

endpoints

my $endpoints = $upstream->endpoints($comb)->get;

Future of an arrayref of Kubernetes::Comb::Endpoint: what the upstream offers under which name. The upstream decides which address is reachable: cluster is the address to use from inside the Comb's cluster (the one the bridge points at), external the one from outside. Without cluster the Comb uses external from inside too.

replicate_into

$upstream->replicate_into($comb)->get;

Optional. Called with the Comb on every "reconcile" in Kubernetes::Comb step that borrows from the upstream, before the bridge is deployed, to replicate data into it. May return a Future; a failure makes the Comb Error.

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.