ClusterNetworkPolicy: implementation and clients #306

npinaeva · 2025-07-31T13:19:26Z

This PR introduced the API changes discussed in the previous iteration #289 as v1alpha2.
Conformance tests for the new API should probably be done in a separate PR, but also nice to be tested before this PR is merged to avoid any mistakes in the API.

code generation script as always inspired by gateway-api, https://github.com/kubernetes-sigs/gateway-api/blob/main/hack/update-clientset.sh

Tested locally with #307 and kubernetes-sigs/kube-network-policies#199, tests seem to pass!

Kubebuilder was used to originally generate the CRDs, but for us it offers only a very limited scaffolding. Kubebuilder has strong opinions on where the apis should be stored (./api instead of currently used ./apis) and migrating to it should be a separate effort (if we ever want to). Signed-off-by: Nadia Pinaeva <[email protected]>

netlify · 2025-07-31T13:19:32Z

✅ Deploy Preview for kubernetes-sigs-network-policy-api ready!

Name	Link
🔨 Latest commit	`77282fa`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-sigs-network-policy-api/deploys/68a870a27b5a130008c58ba7
😎 Deploy Preview	https://deploy-preview-306--kubernetes-sigs-network-policy-api.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

apis/v1alpha2/clusternetworkpolicy_types.go

aojea · 2025-07-31T15:01:31Z

just to confirm, the only diff from v1alpha1 to v1alpha2 are

type AdminNetworkPolicy + BaselineAdminNetworkPolicy --> ClusterNetworkPolicy
and this new Tier field inside the new Type, the rest is the same?

I want to get this into kube-network-policies

npinaeva · 2025-07-31T16:12:17Z

just to confirm, the only diff from v1alpha1 to v1alpha2 are
* type AdminNetworkPolicy + BaselineAdminNetworkPolicy --> ClusterNetworkPolicy

* and  this new `Tier` field inside the new Type, the rest is the same?
I want to get this into kube-network-policies

Yes that is a good summary, and thank you for the implementation!
We do have some more changes planned (some re-work on the protocols field) that will come after this one. So you could decide to wait for all changes to come it, or implement it in stages

aojea · 2025-07-31T19:32:37Z

My time for implementation is limited, so I prefer to spend only one time

apis/v1alpha2/clusternetworkpolicy_types.go

bowei

From what I can tell, this is follows what we discussed at Kubecon

I did notice some tweaking that needs to be done in some of the comments but it's probably better to do that as follow-up PRs to make the update less unwieldy.

LGTM from me so we can get the CRD structure change in. We do need to go through the godoc -- and also as important is to update the documentation

bowei · 2025-07-31T18:35:11Z

PROJECT

@@ -1,24 +0,0 @@
-domain: policy.networking.k8s.io


What is this file used for?

it is used by kubebuilder, see 9a065f3 comment

bowei · 2025-07-31T18:35:43Z

apis/v1alpha2/clusternetworkpolicy_types.go

@@ -0,0 +1,436 @@
+/*
+Copyright 2020 The Kubernetes Authors.


nit: Might want to update these dates at some point.

apis/v1alpha2/clusternetworkpolicy_types.go

bowei · 2025-08-07T06:14:31Z

apis/v1alpha2/clusternetworkpolicy_types.go

+// ClusterNetworkPolicySpec defines the desired state of ClusterNetworkPolicy.
+type ClusterNetworkPolicySpec struct {
+	// Tier is used as a first layer of rule prioritization.
+	// ClusterNetworkPolicy has 2 tiers: admin and baseline.


Note: I think it might be hard to describe the mental model for the Tier in a comment attached to the field itself.

Suggest:

// Tier is used as the top-level grouping for network policy prioritization. // // Policies are evaluated in the following order: // // * AdminTier // * NetworkPolicyTier // * BaselineTier // * DefaultTier // // The AdminTier takes precedence over all other policies. Policies // defined in this tier are used to set cluster-wide security rules that cannot // be overridden in the other tiers. Only ClusterNetworkPolicy can be // created in the AdminTier. An example use case would be to "block all traffic // to a given IP CIDR block" for all Pods in the cluster. // // NetworkPolicyTier is the tier for the namespaced v1.NetworkPolicy. These // policies are intended for the application developer to describe the security // policy associated with their deployments inside of their namespace. Policies // in this tier are applied after AdminTier. // // BaselineTier is a cluster-wide policy override for the default allow // ingress/egress for Pods not selected by an namespaced v1.NetworkPolicy. // An example use case for BaselineTier would be to set "default deny" in // any matching namespace that does not have a v1.NetworkPolicy defined. // // DefaultTier is the overall policy applied if there is no matching policy // definition in any Tier. This is (currently) not configurable and always // set to "allow all" on both ingress and egress directions, matching the // default behavior of Kubernetes with no network policies enabled.

I am not sure if API doc is a good place for use cases, I left them our for now, but open for discussion

apis/v1alpha2/clusternetworkpolicy_types.go

bowei · 2025-08-07T06:16:16Z

apis/v1alpha2/clusternetworkpolicy_types.go

+	// ClusterNetworkPolicyRuleActionPass indicates that matching traffic will
+	// jump to the next tier evaluation. That means that all the rules with lower
+	// priority at the same tier will be ignored, but evaluation will continue at the next tier.
+	// For example, if an admin tier CNP uses Pass action, NetworkPolicy evaluation will happen next.


nit: use the constants (AdminTier)

// For example, a Pass action in the AdminTier will skip the rest of the rules // defined in the AdminTier and continue evaluation with policicies in the // NetworkPolicyTier.

So we want this to be readable on the kubectl explain and that means the AdminTier will be printer like that, while I want to say Admin tier, because Admin is valid value for the tier field?

apis/v1alpha2/clusternetworkpolicy_types.go

npinaeva · 2025-08-14T07:46:49Z

apis/v1alpha2/clusternetworkpolicy_types.go

+	// If a given connection wasn't allowed or denied by any of the tiers,
+	// the default kubernetes policy is applied, which says that
+	// all pods can communicate with each other.
+	Tier Tier `json:"tier"`


I think we haven't discussed this explicitly in the NPEP, but I am making both tier and priority fields required, so no default values. The main difference is that BANP will now have to set some priority, while before there was only 1 BANP allowed

I had assumed tier would default to Admin...

that is up for discussion - my thinking is that considering we are squashing 2 APIs into 1, it could be easy for people to upgrade to the wrong tier if we have any defaults (also keeping in mind that we wanted to have a very explicit API)

fasaxc · 2025-08-18T16:52:18Z

Also LGTM on same basis as @bowei (and Mazdak was able to do a trial integration with the clients and it all seemed to work ok).

I think we may want to rephrase some of the bigger godoc or trim it down to avoid confusion but the shape of the structs is what I was expecting and it'd be good to get this first tranche of work in so that we can iterate on top of it.

bowei · 2025-08-18T16:57:26Z

/lgtm

danwinship · 2025-08-21T20:30:28Z

apis/v1alpha2/clusternetworkpolicy_types.go

+	//
+	// Baseline tier is a cluster-wide policy that can be overridden by the
+	// v1.NetworkPolicy. It will only be evaluated for Pods not selected by a
+	// namespaced v1.NetworkPolicy.


This PR doesn't need to block on having absolutely perfect documentation, but at some point we should revisit this text. eg, you point out that Baseline is only evaluated when NetworkPolicy isn't, but you don't point out that NetworkPolicy is only evaluated when ANP doesn't match or Passes.

Let me try to make it more unified

(To be clear, I was just pointing out "we need to revisit this text before the first official v1alpha2 release" not "we need to revisit this text in this PR".)

danwinship · 2025-08-21T20:33:46Z

apis/v1alpha2/clusternetworkpolicy_types.go

+	//
+	// If a given connection wasn't allowed or denied by any of the tiers,
+	// the default kubernetes policy is applied, which says that
+	// all pods can communicate with each other.


Is this a change? I thought the text before tried to allow the possibility that a cluster might have a deny default rather than an allow default (even though there's no standard way to do that).

We first wanted to use the concept of "Default" tier, but that was problematic (see last meeting notes), so we agreed to just explain what happens when no policies match. Not sure how important it is in this context to talk about potential default-deny considering it doesn't exist?

I just meant that I feel like in the past we've allowed for the possibility that a network plugin might have some --pod-network-deny-by-default option, whereas the wording here seems to explicitly forbid that. (OTOH I'm not sure how to word the text here in a way that allows for that possibility without getting really hung up in the fact that it's purely hypothetical. So maybe just ignore this for now...)

danwinship · 2025-08-21T20:34:40Z

apis/v1alpha2/clusternetworkpolicy_types.go

+	// If a given connection wasn't allowed or denied by any of the tiers,
+	// the default kubernetes policy is applied, which says that
+	// all pods can communicate with each other.
+	Tier Tier `json:"tier"`


I had assumed tier would default to Admin...

danwinship · 2025-08-21T20:36:18Z

apis/v1alpha2/clusternetworkpolicy_types.go

+	// Priority is a value from 0 to 1000.
+	// Policies with lower priority values have higher precedence,
+	// and are checked before policies with higher priority values.
+	// All Admin tier rules have higher precedence than NetworkPolicy or
+	// Baseline tier rules.


Priority is a value from 0 to 1000 indicating the precedence of the policy within its tier.
Policies with lower priority values have higher precedence, and are checked before policies with higher priority values in the same tier.
All Admin tier rules have higher precedence than NetworkPolicy or Baseline tier rules.

danwinship · 2025-08-21T20:37:51Z

apis/v1alpha2/clusternetworkpolicy_types.go

+	// and are checked before policies with higher priority values.
+	// All Admin tier rules have higher precedence than NetworkPolicy or
+	// Baseline tier rules.
+	// If two (or more) policies with the same priority could match a connection,


"policies in the same tier with the same priority"

danwinship · 2025-08-21T21:02:41Z

apis/v1alpha2/clusternetworkpolicy_types.go

+// +kubebuilder:validation:MaxProperties=1
+// +kubebuilder:validation:MinProperties=1
+type ClusterNetworkPolicyPort struct {
+	// Port selects a port on a pod(s) based on number.


Port selects a destination port based on protocol and port number.

danwinship · 2025-08-21T21:03:35Z

apis/v1alpha2/clusternetworkpolicy_types.go

+	// +optional
+	PortNumber *Port `json:"portNumber,omitempty"`
+
+	// NamedPort selects a port on a pod(s) based on name.


NamedPort selects a destination port on a pod based on the ContainerPort name.
You can't use this in a rule with Nodes or Networks peers, because they do not have named ports.

danwinship · 2025-08-21T21:04:07Z

apis/v1alpha2/clusternetworkpolicy_types.go

+	NamedPort *string `json:"namedPort,omitempty"`
+
+	// PortRange selects a port range on a pod(s) based on provided
+	// start and end values.


PortRange selects a destination port range based on protocol and start and end port numbers.

danwinship · 2025-08-21T21:04:30Z

apis/v1alpha2/clusternetworkpolicy_types.go

+	//
+	// +optional
+	PortRange *PortRange `json:"portRange,omitempty"`
+}


should probably order that as Port, PortRange, NamedPort rather than Port, NamedPort, PortRange...

danwinship · 2025-08-21T21:05:31Z

apis/v1alpha2/clusternetworkpolicy_types.go

+	// +kubebuilder:validation:Minimum=1
+	// +kubebuilder:validation:Maximum=65535
+	//
+	End int32 `json:"end"`


shouldn't we have CEL validation that Start < End?

that sounds reasonable

Signed-off-by: Nadia Pinaeva <[email protected]>

danwinship · 2025-08-26T16:49:17Z

/lgtm
/approve

k8s-ci-robot · 2025-08-26T16:49:26Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: danwinship, npinaeva

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [danwinship]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Jul 31, 2025

k8s-ci-robot requested review from aojea and Dyanngg July 31, 2025 13:19

k8s-ci-robot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Jul 31, 2025

npinaeva force-pushed the npep-285-impl branch 2 times, most recently from d1841d4 to fdedcef Compare July 31, 2025 14:44

aojea reviewed Jul 31, 2025

View reviewed changes

apis/v1alpha2/clusternetworkpolicy_types.go Outdated Show resolved Hide resolved

matthewdupre reviewed Aug 1, 2025

View reviewed changes

apis/v1alpha2/clusternetworkpolicy_types.go Outdated Show resolved Hide resolved

bowei reviewed Aug 7, 2025

View reviewed changes

npinaeva force-pushed the npep-285-impl branch from fdedcef to 467e31c Compare August 12, 2025 14:00

fasaxc reviewed Aug 12, 2025

View reviewed changes

apis/v1alpha2/clusternetworkpolicy_types.go Outdated Show resolved Hide resolved

npinaeva force-pushed the npep-285-impl branch 2 times, most recently from f245770 to e3ff32d Compare August 13, 2025 12:17

npinaeva commented Aug 14, 2025

View reviewed changes

k8s-ci-robot assigned bowei Aug 18, 2025

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 18, 2025

danwinship reviewed Aug 21, 2025

View reviewed changes

npinaeva added 3 commits August 22, 2025 15:28

v1alpha2: Generate new CRDs after to merge ANP and BANP into CNP

437fc0f

Signed-off-by: Nadia Pinaeva <[email protected]>

v1alpha2: Update code generation scripts to account for multiple apis.

5127a0b

Signed-off-by: Nadia Pinaeva <[email protected]>

Run make generate: generate v1alpha2 code.

77282fa

Signed-off-by: Nadia Pinaeva <[email protected]>

npinaeva force-pushed the npep-285-impl branch from e3ff32d to 77282fa Compare August 22, 2025 13:29

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 22, 2025

k8s-ci-robot assigned danwinship Aug 26, 2025

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 26, 2025

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Aug 26, 2025

k8s-ci-robot merged commit d5cee02 into kubernetes-sigs:main Aug 26, 2025
10 checks passed

npinaeva deleted the npep-285-impl branch August 27, 2025 09:31

This was referenced Aug 27, 2025

[CRD doc] replace "lower priority" with "lower precedence". #310

Merged

CNP update tests #307

Open

ClusterNetworkPolicy: implementation and clients #306

ClusterNetworkPolicy: implementation and clients #306

Uh oh!

Conversation

npinaeva commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for kubernetes-sigs-network-policy-api ready!

Uh oh!

Uh oh!

aojea commented Jul 31, 2025

Uh oh!

npinaeva commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aojea commented Jul 31, 2025

Uh oh!

Uh oh!

bowei left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fasaxc commented Aug 18, 2025

Uh oh!

bowei commented Aug 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

npinaeva commented Jul 31, 2025 •

edited

Loading

netlify bot commented Jul 31, 2025 •

edited

Loading

npinaeva commented Jul 31, 2025 •

edited

Loading