Cilium’s NetworkPolicy is fundamentally a node-local construct, while ClusterwideCiliumNetworkPolicy operates at the cluster level, offering a more centralized policy management approach.
Let’s see this in action. Imagine you have a simple Kubernetes cluster with two nodes, node-1 and node-2. We’ll deploy a couple of pods:
app-aonnode-1app-bonnode-2
We want to restrict communication.
First, let’s create a NetworkPolicy that applies only to app-a. This policy will be managed by the Cilium agent running on node-1.
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-ingress-to-app-a
namespace: default
spec:
podSelector:
matchLabels:
app: app-a
policyTypes:
- Ingress
ingress:
- from:
- podSelector:
matchLabels:
app: app-b
ports:
- protocol: TCP
port: 80
With this policy, app-b on node-2 can now talk to app-a on node-1 on TCP port 80. If app-a were on node-2 instead, this policy would have no effect because the NetworkPolicy is processed by the Cilium agent on the node where the target pod resides.
Now, consider a scenario where you want to enforce a policy across all pods labeled app-c in your entire cluster, regardless of which node they land on. This is where ClusterwideCiliumNetworkPolicy shines.
apiVersion: cilium.io/v2alpha1
kind: ClusterwideCiliumNetworkPolicy
metadata:
name: allow-egress-to-external
spec:
endpointSelector:
matchLabels:
app: app-c
egress:
- toCIDR:
- 192.168.1.0/24
This ClusterwideCiliumNetworkPolicy will be applied by the Cilium control plane (or the agent acting in a control plane role) to all Cilium agents in the cluster. Any pod with the label app: app-c will be restricted to only sending traffic to the 192.168.1.0/24 CIDR. This policy is not tied to a specific node’s Cilium agent in the same way a standard NetworkPolicy is.
The core problem NetworkPolicy solves is fine-grained, often namespace-scoped, network segmentation. It’s ideal for defining communication rules between pods within the same namespace or between specific pods and namespaces. The fact that NetworkPolicy is effectively node-local means its scope is implicitly limited to the pods on that node. When you create a NetworkPolicy, the Cilium agent on that node reads and enforces it. If you have a pod running on node-1 and another on node-2, and you want to control their interaction, you need to ensure that the policy is applied to the Cilium agent on both nodes if it’s a general rule, or that the policy targeted at the ingress pod is on the node where that pod resides.
ClusterwideCiliumNetworkPolicy addresses the need for cluster-wide, consistent policy enforcement. It’s particularly useful for:
- Global Egress/Ingress Control: Defining default rules for all pods in the cluster, like allowing egress only to specific external CIDRs or denying all ingress by default.
- Cross-Namespace Policies: Easily defining policies that span multiple namespaces without needing to replicate the policy in each namespace.
- Centralized Management: Providing a single point of truth for policies that should apply universally.
The key internal difference lies in how these policies are distributed and enforced. Standard NetworkPolicy objects are watched by each Cilium agent for pods it manages. ClusterwideCiliumNetworkPolicy objects are typically watched by a central Cilium component (or a designated agent) and then translated into node-local policies that are pushed to the relevant agents. This distinction is crucial for understanding scalability and management.
A common pitfall is assuming a NetworkPolicy will automatically apply cluster-wide. It won’t. If you need a policy to affect pods across multiple nodes, and you’re using standard NetworkPolicy, you’d have to create that policy in each namespace where the target pods reside. For instance, to allow app-a on node-1 to talk to app-b on node-2, and app-a on node-3 to talk to app-b on node-4, you’d need a NetworkPolicy in the respective namespaces on both node-1 and node-3 (assuming app-a is the ingress target). ClusterwideCiliumNetworkPolicy simplifies this by allowing you to define the rule once and have it applied everywhere.
The primary reason NetworkPolicy is node-local is performance and scalability. Distributing and enforcing policies directly on the node where the pods run reduces latency and the overhead of a central control plane managing every single policy for every single pod. However, this comes at the cost of less centralized management for cluster-wide rules.
When you define a ClusterwideCiliumNetworkPolicy, Cilium internally translates this into a set of node-local policies and distributes them. This means that even though you define it once, the enforcement still happens on the individual nodes by their respective Cilium agents. The ClusterwideCiliumNetworkPolicy acts as a higher-level abstraction that simplifies the creation and management of these distributed policies.
The next logical step in policy management is exploring Cilium’s identity-based policies and how they integrate with ClusterwideCiliumNetworkPolicy for more dynamic and granular control, especially in complex microservice architectures.