From 82314b9b4690a628b20f6293d0e6305f3c4aa72e Mon Sep 17 00:00:00 2001 From: Antonio Ojea Date: Wed, 27 Aug 2025 12:44:31 +0000 Subject: [PATCH 1/6] NPEP-311: Best Practices for Multi-Cluster NetworkPolicy in a Flat Network Model document some of the existing common practices for applying existing network policies across clusters without incresing the scope of the core kubernetes APIs. Change-Id: I91e8791b441b93dc6958617eb0828d0b6c879ab7 --- npeps/npep-311.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 npeps/npep-311.md diff --git a/npeps/npep-311.md b/npeps/npep-311.md new file mode 100644 index 00000000..a7bcf583 --- /dev/null +++ b/npeps/npep-311.md @@ -0,0 +1,134 @@ +# NPEP-311: NPEP template + +* Issue: + [#311](https://github.com/kubernetes-sigs/network-policy-api/issues/311) +* Status: Informational + +## TLDR + +This NPEP documents a recommended set of practices for applying standard +NetworkPolicy resources in a multi-cluster, flat network environment. It +proposes a conventional labeling scheme, aligned with SIG-Multicluster, to +enable consistent and predictable cross-cluster policy enforcement without +changes to the API. + +## Goals + +* To establish and document a common, intuitive operational model for + multi-cluster network policy. + +* To provide clear, reusable patterns for administrators to secure applications + that span multiple clusters. + +* To align these practices with the cluster identification conventions + established by SIG-Multicluster in + [KEP-2149](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/2149-clusterid). + +## Non-Goals + +* This proposal does not introduce any changes to the Kubernetes Network Policy + API specification or any extension based on labels and/or annotations. + +* This proposal does not mandate any specific CNI implementation or + multi-cluster architecture beyond the prerequisite of a flat network. + +## Introduction + +In a multi-cluster architecture with a flat network, every pod IP is unique and +directly routable from any other pod, regardless of its origin cluster. This +topology allows for a simplified security model where NetworkPolicy selectors +can be evaluated against a global inventory of all pods and namespaces within a +defined ClusterSet. + +The core principles of this model are: + +* Policies are Local: A NetworkPolicy resource is applied only to the cluster + where it is created. Policies are not replicated, which contains the impact of + changes and allows for per-cluster rollout strategies. + +* Selectors are Global: The policy engine within each cluster evaluates policy + rules against all known pods and namespaces in the entire ClusterSet. + +* Administrator-Defined Identity: The ability to differentiate between clusters + is important for cross-cluster communication. This model places the + responsibility on the cluster administrator to implement a consistent labeling + strategy that can be used for identity and policy selection. + +This document formalizes these principles as a set of best practices for the +community. + +## User-Stories/Use-Cases + +### Story 1: Securing a "Stretched" Application + +As a platform operator running an application across multiple clusters, + +I want to write a single policy to allow traffic from all frontend pods to my +database pods, + +so that I don't have to manage separate, IP-based policies for frontend +instances that are spread across different clusters. + +### Story 2: Enforcing Cross-Cluster Security Boundaries + +As a security administrator, + +I want to allow a database application in a production cluster to receive +traffic only from a specific billing application in a separate PCI-compliant +cluster, + +so that I can enforce strict, auditable cross-cluster communication paths. + +### Story 3: Maintaining Local Policy Scope + +As an application developer, + +I want to apply a NetworkPolicy to my application and be confident that it only +affects traffic within my local cluster, + +so that I don't accidentally expose my service to other clusters or break +connectivity by applying a policy that is too broad. + +## API + +No changes are proposed to the NetworkPolicy v1 API neither extensions based on +labels and/or annotations. This document describes a set of practices that +leverage the existing API. + +The central recommendation is to adopt a consistent labeling scheme for cluster +identification. To effectively manage policies in a multi-cluster environment, +it is highly recommended to align with the conventions outlined in [KEP-2149: +ClusterId](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/2149-clusterid). + +### Recommendation + +Each namespace within a cluster should be labeled with a key that identifies its +parent cluster. The recommended label is: + +`clusterset.k8s.io/cluster-name: ` + +The value should correspond to the unique name of the cluster +within the ClusterSet (e.g., cluster-a, us-west-2). This practice enables policy +authors to create selectors that precisely target peers from specific clusters. + +## Conformance Details + +Not applicable, as this is an informational proposal that does not introduce new +API features. + +## Alternatives + +The primary alternative is the absence of a documented best practice. This leads +to fragmented, implementation-specific approaches to multi-cluster policy, +reducing portability and creating a confusing experience for users. By +documenting a common pattern, we provide a consistent model that both users and +CNI implementers can reference. + +## References + +* KEP-2149: ClusterId for ClusterSet identification: + https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/2149-clusterid + +* Calico Multi-Cluster Flat model: Calico is one CNI that supports a flat + network model where policies can be applied across clusters, as described in + https://kubernetes.slack.com/archives/C01CWSHQWQJ/p1756283784627849 \ No newline at end of file From 2329a41d2a1976bf3362f8e7a84e3726d632ad12 Mon Sep 17 00:00:00 2001 From: Antonio Ojea Date: Wed, 27 Aug 2025 15:00:18 +0200 Subject: [PATCH 2/6] Update npeps/npep-311.md --- npeps/npep-311.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/npeps/npep-311.md b/npeps/npep-311.md index a7bcf583..a8392efe 100644 --- a/npeps/npep-311.md +++ b/npeps/npep-311.md @@ -1,4 +1,4 @@ -# NPEP-311: NPEP template +# NPEP-311: Best Practices for Multi-Cluster NetworkPolicy in a Flat Network * Issue: [#311](https://github.com/kubernetes-sigs/network-policy-api/issues/311) From a7220a8dbc2c9c47e2ddd0bd9a83c256095fb887 Mon Sep 17 00:00:00 2001 From: Antonio Ojea Date: Wed, 27 Aug 2025 18:48:07 +0200 Subject: [PATCH 3/6] Update npeps/npep-311.md --- npeps/npep-311.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/npeps/npep-311.md b/npeps/npep-311.md index a8392efe..84e97adb 100644 --- a/npeps/npep-311.md +++ b/npeps/npep-311.md @@ -102,7 +102,7 @@ ClusterId](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multi ### Recommendation -Each namespace within a cluster should be labeled with a key that identifies its +Each namespace within a cluster should be labeled by the cluster administrator with a key that identifies its parent cluster. The recommended label is: `clusterset.k8s.io/cluster-name: ` From a88f72cea72543e63db55e5f61d5ff6bbdc1ebde Mon Sep 17 00:00:00 2001 From: Antonio Ojea Date: Wed, 27 Aug 2025 23:25:48 +0200 Subject: [PATCH 4/6] Update npeps/npep-311.md --- npeps/npep-311.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/npeps/npep-311.md b/npeps/npep-311.md index 84e97adb..5388b008 100644 --- a/npeps/npep-311.md +++ b/npeps/npep-311.md @@ -105,7 +105,7 @@ ClusterId](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multi Each namespace within a cluster should be labeled by the cluster administrator with a key that identifies its parent cluster. The recommended label is: -`clusterset.k8s.io/cluster-name: ` +`cluster.clusterset.k8s.io/cluster-name: ` The value should correspond to the unique name of the cluster within the ClusterSet (e.g., cluster-a, us-west-2). This practice enables policy From 90f05282a65d1adb438b762d55fab16bf83aa2a0 Mon Sep 17 00:00:00 2001 From: Antonio Ojea Date: Thu, 28 Aug 2025 15:18:51 +0200 Subject: [PATCH 5/6] Update npeps/npep-311.md --- npeps/npep-311.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/npeps/npep-311.md b/npeps/npep-311.md index 5388b008..5d9e7ea6 100644 --- a/npeps/npep-311.md +++ b/npeps/npep-311.md @@ -105,7 +105,7 @@ ClusterId](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multi Each namespace within a cluster should be labeled by the cluster administrator with a key that identifies its parent cluster. The recommended label is: -`cluster.clusterset.k8s.io/cluster-name: ` +`cluster.clusterset.k8s.io: ` The value should correspond to the unique name of the cluster within the ClusterSet (e.g., cluster-a, us-west-2). This practice enables policy From c89c9fb5c614d3d1e4e3b77c0e65226b31f83415 Mon Sep 17 00:00:00 2001 From: Antonio Ojea Date: Thu, 28 Aug 2025 16:22:34 +0200 Subject: [PATCH 6/6] Update npeps/npep-311.md --- npeps/npep-311.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/npeps/npep-311.md b/npeps/npep-311.md index 5d9e7ea6..88a38b2f 100644 --- a/npeps/npep-311.md +++ b/npeps/npep-311.md @@ -26,6 +26,9 @@ changes to the API. ## Non-Goals +* This proposal does not support multi-cluster setups where there are overlapping IPs between clusters (or more generally, any multi-cluster setup where traffic isn't freely routed between clusters). + + * This proposal does not introduce any changes to the Kubernetes Network Policy API specification or any extension based on labels and/or annotations.