Skip to content

Fix: Clarify optional podSelector in NetworkPolicy docs and schema #131354

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Fix: Clarify optional podSelector in NetworkPolicy docs and schema #131354

wants to merge 1 commit into from
+16 −20

Conversation

tomoish
Copy link

@tomoish tomoish commented Apr 17, 2025 •
edited
Loading

Updates references and descriptions to reflect that podSelector in NetworkPolicy objects can be omitted, defaulting to matching all pods in the namespace.

What type of PR is this?

/kind bug

What this PR does / why we need it:

  • What this PR does

    • This PR addresses the documentation and schema inconsistencies regarding the podSelector field in Kubernetes NetworkPolicy objects.

    • This change updates the documentation, OpenAPI specifications, Go structs, and generated Protobuf files to accurately reflect that podSelector is optional. When omitted, it defaults to an empty selector, which matches all pods within the policy's namespace.

  • Why we need it.
    Previous documentation and comments were misleading: they implied podSelector was required and only governed ingress behavior. This update aligns all docs, schemas, and code comments with the actual behavior—making podSelector optional and applicable to both ingress and egress.

Which issue(s) this PR fixes:

Fixes #130896

Special notes for your reviewer:

Does this PR introduce a user-facing change?

 This PR corrects that documentation, making it clear to users that podSelector is optional and describes its default behavior.

Additional documentation e.g., KEPs (Kubernetes Enhancement Proposals), usage docs, etc.:

@k8s-ci-robot k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. release-note Denotes a PR that will be considered when it comes time to generate release notes. labels Apr 17, 2025
@k8s-ci-robot
Copy link
Contributor

Please note that we're already in Test Freeze for the release-1.33 branch. This means every merged PR will be automatically fast-forwarded via the periodic ci-fast-forward job to the release branch of the upcoming v1.33.0 release.

Fast forwards are scheduled to happen every 6 hours, whereas the most recent run was: Thu Apr 17 13:31:58 UTC 2025.

@k8s-ci-robot k8s-ci-robot added kind/bug Categorizes issue or PR as related to a bug. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. do-not-merge/needs-sig Indicates an issue or PR lacks a `sig/foo` label and requires one. needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Apr 17, 2025
@k8s-ci-robot
Copy link
Contributor

Hi @tomoish. Thanks for your PR.

I'm waiting for a kubernetes member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@k8s-ci-robot k8s-ci-robot added the needs-priority Indicates a PR lacks a `priority/foo` label and requires one. label Apr 17, 2025
@tomoish tomoish marked this pull request as ready for review April 17, 2025 14:29
@k8s-ci-robot k8s-ci-robot added area/code-generation kind/api-change Categorizes issue or PR as related to adding, removing, or otherwise changing an API sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. sig/network Categorizes an issue or PR as relevant to SIG Network. and removed do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. do-not-merge/needs-sig Indicates an issue or PR lacks a `sig/foo` label and requires one. labels Apr 17, 2025
@k8s-triage-robot
Copy link

This PR may require API review.

If so, when the changes are ready, complete the pre-review checklist and request an API review.

Status of requested reviews is tracked in the API Review project.

@cici37
Copy link
Contributor

cici37 commented Apr 17, 2025

/remove-sig api-machinery

@k8s-ci-robot k8s-ci-robot removed the sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. label Apr 17, 2025
danwinship
danwinship reviewed Apr 18, 2025
View reviewed changes
pkg/apis/networking/types.go
// This field is optional. If it is not specified, it defaults to an empty selector,
// which matches all pods in this namespace.
// An explicitly specified empty selector also matches all pods.
// +optional
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm. I don't like talking about the default and then going back to add more detail about the non-default case.

Also, the existing text turns out to have another bug; it shouldn't say "ingress rules" since this applies to egress as well.

So how about

	// podSelector selects the pods to which this NetworkPolicy object applies.
	// The array of rules is applied to any pods selected by this field. An empty
	// selector matches all pods in the policy's namespace.
	// Multiple network policies can select the same set of pods. In this case,
	// the ingress rules for each are combined additively.
	// This field is optional. If it is not specified, it defaults to an empty selector.
	// +optional

and then the same in the other copy.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@danwinship Thank you for the suggestion.
I agree that we shouldn’t repeat the default behavior twice.
I’ll fix it and remove the remaining mentions of “ingress rules.”

@danwinship
Copy link
Contributor

/ok-to-test
/triage accepted

@k8s-ci-robot k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. triage/accepted Indicates an issue or PR is ready to be actively worked on. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. labels Apr 18, 2025
@tomoish tomoish force-pushed the fix-netpol-podselector-doc branch from 377f3e7 to b0a5c77 Compare April 19, 2025 13:23
@k8s-ci-robot k8s-ci-robot added the sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. label Apr 19, 2025
@tomoish
Copy link
Author

tomoish commented Apr 19, 2025

/remove-sig api-machinery

@k8s-ci-robot k8s-ci-robot removed the sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. label Apr 19, 2025
@tomoish tomoish requested a review from danwinship April 20, 2025 08:06
@danwinship
Copy link
Contributor

/lgtm
/approve
(but it's going to sit for a few days until the tree unfreezes for 1.33)

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 20, 2025
@k8s-ci-robot
Copy link
Contributor

LGTM label has been added.

Git tree hash: 721c3dd1ead961b7bf31b7c459d9ab6088623b6e

@danwinship
Copy link
Contributor

/assign @thockin
for api (docs) approval

liggitt
liggitt reviewed Jun 12, 2025
View reviewed changes
staging/src/k8s.io/api/networking/v1/types.go Outdated
PodSelector metav1.LabelSelector `json:"podSelector" protobuf:"bytes,1,opt,name=podSelector"`
// This field is optional. If it is not specified, it defaults to an empty selector.
// +optional
PodSelector metav1.LabelSelector `json:"podSelector,omitempty" protobuf:"bytes,1,opt,name=podSelector"`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

don't add omitempty, which has serialization implications, just add the +optional bit

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@liggitt Thank you for your review. I've fixed it.

@tomoish
Fix NetworkPolicy podSelector comments
7a95f3e 
Clarify that podSelector is optional and defaults to an empty selector,
matching all pods.
Replace “ingress rules” with “rules” to reflect both directions.

Update podSelector descriptions in NetworkPolicy documentation for clarity
@tomoish tomoish force-pushed the fix-netpol-podselector-doc branch from b0a5c77 to 7a95f3e Compare June 15, 2025 15:12
@k8s-ci-robot k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jun 15, 2025
@k8s-ci-robot k8s-ci-robot requested a review from thockin June 15, 2025 15:13
@k8s-ci-robot
Copy link
Contributor

New changes are detected. LGTM label has been removed.

@k8s-ci-robot
Copy link
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: danwinship, tomoish
Once this PR has been reviewed and has the lgtm label, please ask for approval from thockin. For more information see the Code Review Process.

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

Needs approval from an approver in each of these files:

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@liggitt liggitt liggitt left review comments

@caseydavenport caseydavenport Awaiting requested review from caseydavenport

@andrewsykim andrewsykim Awaiting requested review from andrewsykim

@danwinship danwinship Awaiting requested review from danwinship

@thockin thockin Awaiting requested review from thockin

Assignees

@danwinship danwinship

@thockin thockin

Labels
area/code-generation cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/api-change Categorizes issue or PR as related to adding, removing, or otherwise changing an API kind/bug Categorizes issue or PR as related to a bug. needs-priority Indicates a PR lacks a `priority/foo` label and requires one. ok-to-test Indicates a non-member PR verified by an org member that is safe to test. release-note Denotes a PR that will be considered when it comes time to generate release notes. sig/network Categorizes an issue or PR as relevant to SIG Network. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. triage/accepted Indicates an issue or PR is ready to be actively worked on.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Required field is not actually required
7 participants
@tomoish @k8s-ci-robot @k8s-triage-robot @cici37 @danwinship @liggitt @thockin