view release on metacpan or  search on metacpan

lib/IO/K8s.pm  view on Meta::CPAN

    my $pod = $k8s->new_object('Pod', %args);
    my $pod = $k8s->new_object('Pod', \%args);
    my $np  = $k8s->new_object('NetworkPolicy', \%args, 'cilium.io/v2');
    my $np  = $k8s->new_object('cilium.io/v2/NetworkPolicy', \%args);

Create a new Kubernetes object of the given type. The type can be a short name
(like C<Pod>), a domain-qualified name (like C<cilium.io/v2/NetworkPolicy>),
or a full class path.

An optional third argument specifies the C<api_version> to disambiguate when
multiple providers register the same kind name.

=head2 inflate

    my $obj = $k8s->inflate($json_string);
    my $obj = $k8s->inflate(\%hashref);

Inflate a JSON string or hashref into a typed IO::K8s object. The class is
auto-detected from the C<kind> field in the data. When external resource maps
have been added via C<add()>, the C<apiVersion> field is used to disambiguate
colliding kind names.

=head2 json_to_object

    my $obj = $k8s->json_to_object($json_with_kind);
    my $obj = $k8s->json_to_object('Pod', $json_string);

Convert JSON to an IO::K8s object. With one argument, auto-detects the class
from C<kind>. With two arguments, uses the specified class.

=head2 struct_to_object

    my $obj = $k8s->struct_to_object(\%hashref_with_kind);
    my $obj = $k8s->struct_to_object('Pod', \%hashref);

Convert a Perl hashref to an IO::K8s object. With one argument, auto-detects
the class from C<kind>. With two arguments, uses the specified class.

=head2 object_to_json

    my $json = $k8s->object_to_json($obj);

Serialize an IO::K8s object to JSON.

=head2 object_to_struct

    my $hashref = $k8s->object_to_struct($obj);

Convert an IO::K8s object to a plain Perl hashref.

=head1 CILIUM CRD SUPPORT

IO::K8s includes L<IO::K8s::Cilium> with 23 Cilium CRD classes covering
C<cilium.io/v2> (12 CRDs) and C<cilium.io/v2alpha1> (11 CRDs). These are
not loaded by default -- opt in at construction:

  my $k8s = IO::K8s->new(with => ['IO::K8s::Cilium']);

  my $cnp = $k8s->new_object('CiliumNetworkPolicy',
      metadata => { name => 'allow-dns', namespace => 'kube-system' },
      spec => { endpointSelector => { matchLabels => { app => 'dns' } } },
  );

  print $cnp->to_yaml;

All Cilium kinds are C<Cilium>-prefixed, so there are no collisions with
core Kubernetes kind names.

=head1 EXTERNAL RESOURCE MAPS

IO::K8s supports merging resource maps from external packages (like
L<IO::K8s::Cilium> for Cilium CRDs). This allows multiple packages to
provide typed Kubernetes objects that work together.

=head2 Writing a resource map provider

Create a class that consumes L<IO::K8s::Role::ResourceMap>:

  package My::CRD::Provider;
  use Moo;
  with 'IO::K8s::Role::ResourceMap';

  sub resource_map {
      return {
          MyCustomKind => '+My::CRD::V1::MyCustomKind',
      };
  }

See L<IO::K8s::Cilium> for a real-world example with 23 CRD classes.

=head2 Collision handling

When two providers register the same kind name, the first-registered entry
keeps the short name. Both entries are always reachable via domain-qualified
names (C<api_version/Kind>):

  my $k8s = IO::K8s->new(with => ['My::Firewall::Provider']);

  # Short name -> core (first-registered)
  $k8s->expand_class('NetworkPolicy');
  # -> IO::K8s::Api::Networking::V1::NetworkPolicy

  # Domain-qualified -> specific version
  $k8s->expand_class('firewall.example.com/v1/NetworkPolicy');
  # -> My::Firewall::V1::NetworkPolicy

  # api_version parameter for disambiguation
  $k8s->expand_class('NetworkPolicy', 'firewall.example.com/v1');
  # -> My::Firewall::V1::NetworkPolicy

=head2 Disambiguation in pk8s DSL

In C<.pk8s> manifest files, pass the api_version as a second argument:

  # Core NetworkPolicy (default)
  NetworkPolicy { name => 'deny-all', spec => { ... } };

  # Firewall NetworkPolicy (disambiguated, no comma - like grep/map syntax)
  NetworkPolicy { name => 'deny-all', spec => { ... } } 'firewall.example.com/v1';

=head1 UPGRADING FROM PREVIOUS VERSIONS