/ 
IO-K8s-1.108
⭐ Starred 0 / IO::K8s::Cilium

NAME

IO::K8s::Cilium - Cilium CRD resource map provider for IO::K8s

VERSION

version 1.108

SYNOPSIS

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

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

print $cnp->to_yaml;

DESCRIPTION

Resource map provider for Cilium Custom Resource Definitions. Registers 31 resource_map entries (22 short-name keys plus 9 domain-qualified back-compat keys for v2alpha1 BGP/CIDR/LB tracks and CiliumExternalWorkload) covering cilium.io/v2 and cilium.io/v2alpha1, matching upstream Cilium v1.20.1.

cilium.io/v2 is modeled to full depth: every Kind's spec (and, where upstream declares one, status) is a typed object graph of further IO::K8s::Cilium::V2::* classes, one per upstream Go structure, named after the upstream Go types (IO::K8s::Cilium::V2::CiliumNetworkPolicy's spec is an IO::K8s::Cilium::V2::Rule, whose egress is an array of IO::K8s::Cilium::V2::EgressRule, and so on down) rather than an opaque hashref — 17 Kinds, 121 further classes. Embedded core types (Meta::V1::LabelSelector, Core::V1::NamespaceCondition, ...) are referenced, not re-modeled. policy/api.Rule — the shared policy engine struct upstream embeds literally the same in both CiliumNetworkPolicy and CiliumClusterwideNetworkPolicy, at both their spec (one Rule) and specs (Rule[]) fields — is one shared IO::K8s::Cilium::V2::Rule class, not a copy per Kind. CiliumEndpoint and CiliumIdentity are the two Kinds with no spec field upstream at all — CiliumEndpoint's status is still fully typed (IO::K8s::Cilium::V2::EndpointStatus), CiliumIdentity's security-labels is a genuine free-form string map upstream (no per-key schema to model further).

cilium.io/v2alpha1 is modeled to full depth the same way -- 12 Kinds (the five v2alpha1-only Kinds plus the seven BGP/CIDR/LoadBalancerIPPool back-compat tracks, which share the very kinds.<Kind> overlay entry the cilium.io/v2 render of the same Kind uses -- the version directory alone disambiguates, so a Go type is never accidentally shared across v2/v2alpha1), under IO::K8s::Cilium::V2alpha1::*. CiliumEndpointSlice is the third and last Kind with no spec field upstream; its endpoints is still fully typed (IO::K8s::Cilium::V2alpha1::CoreCiliumEndpoint).

Fixed in 1.108 (karr #108): IO::K8s::Cilium::V2alpha1::AccessLogs (nested under CiliumGatewayClassConfig's spec.telemetry.accessLogs[]) has a real upstream field literally named json, which used to collide with IO::K8s::Role::Resource's own internal JSON-encoder attribute (previously also named json). The role's encoder attribute is now private (_json_encoder), so to_json/ to_yaml work normally on AccessLogs and any parent recursing into a populated accessLogs[].

Not loaded by default — opt in via the with constructor parameter of IO::K8s or by calling $k8s->add('IO::K8s::Cilium') at runtime.

Included CRDs (cilium.io/v2)

  • CiliumNetworkPolicy -- a Kubernetes third-party resource with an extended version of NetworkPolicy, adding L3-L7 rules the base Kubernetes API can't express.

  • CiliumClusterwideNetworkPolicy -- a modified version of CiliumNetworkPolicy which is cluster-scoped rather than namespace-scoped, and adds node-selector-based rules.

  • CiliumLocalRedirectPolicy -- redirects pod traffic destined to an IP:port/ protocol tuple, or to a Kubernetes Service, to backend pod(s) local to the same node, using eBPF.

  • CiliumEgressGatewayPolicy -- routes egress traffic from selected pods through a designated gateway node so cluster-external destinations see a predictable, SNAT'd egress IP.

  • CiliumIdentity -- represents a security identity managed by Cilium: the numeric ID its policy engine assigns to a set of endpoint labels.

  • CiliumEndpoint -- the runtime status of a Cilium-managed endpoint (pod): identity, networking and policy enforcement state. Has no spec upstream at all -- see below.

  • CiliumNode -- represents a node managed by Cilium: per-node IPAM and networking state the agent and operator maintain.

  • CiliumNodeConfig -- a list of per-node configuration key/value overrides layered on top of the cluster-wide Cilium ConfigMap for a selected set of nodes.

  • CiliumLoadBalancerIPPool -- defines pools of IPs the Cilium operator can allocate and advertise for Services of type LoadBalancer, filling the gap when no cloud provider load-balancer is available.

  • CiliumEnvoyConfig -- namespaced Envoy xDS configuration Cilium's embedded Envoy proxy uses for L7 traffic management on selected Services.

  • CiliumClusterwideEnvoyConfig -- the cluster-scoped counterpart of CiliumEnvoyConfig.

  • CiliumCIDRGroup -- a named list of external CIDRs (peers outside the cluster) that can be referenced as a single entity from CiliumNetworkPolicy and CiliumClusterwideNetworkPolicy rules.

  • CiliumBGPClusterConfig -- cluster-wide BGP Control Plane configuration: one or more virtual-router "instances" and the node selector choosing which nodes run them.

  • CiliumBGPPeerConfig -- reusable BGP peer configuration (timers, graceful restart, address families, ...), referenced by name from a peer entry in a CiliumBGPClusterConfig.

  • CiliumBGPAdvertisement -- declares which routes (Service VIPs, Pod CIDRs, ...) a BGP instance advertises, and under what attributes.

  • CiliumBGPNodeConfig -- per-node BGP Control Plane state, derived automatically by the operator from a CiliumBGPClusterConfig's node selector: one per selected node.

  • CiliumBGPNodeConfigOverride -- manual, per-node overrides layered on top of a node's derived CiliumBGPNodeConfig.

Included CRDs (cilium.io/v2alpha1)

  • CiliumEndpointSlice -- batches many CiliumEndpoint objects into one resource to reduce per-endpoint API server load in large clusters. Has no spec upstream at all -- see above.

  • CiliumL2AnnouncementPolicy -- fine-grained control over which Services are announced over L2 (ARP/NDP), from which nodes and which network interfaces.

  • CiliumGatewayClassConfig -- referenced from a Gateway API GatewayClass's parametersRef to customize Cilium's own Gateway API controller behaviour.

  • CiliumPodIPPool -- defines a cluster-wide CIDR pool used in multi-pool IPAM mode, from which per-node Pod CIDRs are allocated based on workload/node labels.

  • CiliumDatapathPlugin -- registers an external datapath plugin with Cilium and reports its status; creating, updating or deleting one triggers a full datapath reinitialization.

Back-compat CRDs (older Cilium releases)

Reachable only via their domain-qualified resource_map key (never a bare short name), for clusters that have not yet upgraded past the Cilium release where each was superseded or removed (k78, k83):

  • cilium.io/v2alpha1/CiliumBGPAdvertisement, cilium.io/v2alpha1/CiliumBGPClusterConfig, cilium.io/v2alpha1/CiliumBGPNodeConfig, cilium.io/v2alpha1/CiliumBGPNodeConfigOverride, cilium.io/v2alpha1/CiliumBGPPeerConfig, cilium.io/v2alpha1/CiliumCIDRGroup, cilium.io/v2alpha1/CiliumLoadBalancerIPPool -- the same BGP/CIDR/LoadBalancerIPPool Kinds described above under cilium.io/v2, at the older v2alpha1 API group version those Kinds shipped at before being promoted.

  • cilium.io/v2alpha1/CiliumBGPPeeringPolicy -- the pre-BGP-Control-Plane-v2 Kind for configuring BGP peering, superseded by the CiliumBGPClusterConfig/CiliumBGPPeerConfig/CiliumBGPAdvertisement/ CiliumBGPNodeConfig split above and removed from newer Cilium releases.

  • cilium.io/v2/CiliumExternalWorkload -- represented a non-Kubernetes workload (e.g. a VM) joined to the cluster mesh. The external-workloads feature itself was removed from Cilium at v1.18, ahead of this provider's pinned v1.20.1.

SEE ALSO

IO::K8s

Cilium documentation

Cilium CRD reference

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/pplu/io-k8s-p5/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHORS

  • Torsten Raudssus <getty@cpan.org>

  • Jose Luis Martinez Torres <jlmartin@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018-2026 by Jose Luis Martinez Torres <jlmartin@cpan.org>.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004