Clarify ports behavior in NetworkPolicy to and from blocks

[krishnamanaiducloud]

What is the problem?
The current Kubernetes documentation does not explicitly mention that the ports field in the to and from blocks of a NetworkPolicyPeer is optional. This omission leads to confusion for users who may assume that omitting ports blocks traffic by default. Instead, the actual behavior is that omitting ports allows traffic to all ports for the specified destination(s).

---

Proposed Solution
Update the Kubernetes documentation to explicitly state:

1. ports is optional in the to and from blocks of a NetworkPolicyPeer.
2. Default behavior: If ports is omitted, all ports are allowed for the specified destinations (ipBlock, namespaceSelector, or podSelector).
3. Include examples that demonstrate:
   • Traffic behavior without ports (allowing all ports).
   • Traffic behavior with ports (restricting to specific ports).

Examples for Documentation:

• Without ports:

  egress:
  - to:
      - podSelector:
          matchLabels:
            app: database

  • Behavior: All ports are allowed to pods labeled app=database.

• With ports:

  egress:
  - to:
      - podSelector:
          matchLabels:
            app: database
        ports:
        - protocol: TCP
          port: 3306

  • Behavior: Only TCP port 3306 is allowed to pods labeled app=database.

---

Where to Update
The following sections of the Kubernetes documentation should be updated:

1. [Network Policies Documentation](https://kubernetes.io/docs/concepts/services-networking/network-policies/):

   • Add clarification about ports being optional and its default behavior.
   • Include updated examples that show the behavior when ports is omitted or specified.

2. [NetworkPolicyPeer API Reference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#networkpolicypeer-v1-networking-k8s-io):

   • Update the to and from blocks to include the optional ports field.
   • Clarify the behavior when ports is omitted.

---

Why This Is Important

• Explicitly documenting the behavior of ports will:
  • Improve clarity for users configuring NetworkPolicies.
  • Align user expectations with actual Kubernetes behavior.
  • Reduce confusion for both ingress and egress rules where ports may not be specified.

---

Additional Context
This clarification aligns with Kubernetes behavior verified through testing. Below is an additional example demonstrating traffic allowed to specific namespaces and pods when ports is omitted:

egress:
- to:
    - namespaceSelector:
        matchLabels:
          team: backend
      podSelector:
        matchLabels:
          app: redis

• Behavior: All ports are allowed to pods labeled app=redis in namespaces labeled team=backend.

[k8s-ci-robot]

This issue is currently awaiting triage.

SIG Docs takes a lead on issue triage for this website, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

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.