Merge pull request #363 from TheBeeZee/pr-ports-doc-update

Update docs to match port/protocol schema changes in v1alpha2

Author: k8s-ci-robot

npeps/npep-126-egress-traffic-control.md

@@ -1,12 +1,12 @@
-# NPEP-126: Add northbound traffic support in (B)ANP API
+# NPEP-126: Add northbound traffic support in ClusterNetworkPolicy API
 
 * Issue: [#126](https://github.com/kubernetes-sigs/network-policy-api/issues/126)
 * Status: Experimental
 
 ## TLDR
 
 This NPEP proposes adding support for cluster egress (northbound) traffic control
-in the `AdminNetworkPolicy` and `BaselineAdminNetworkPolicy` API objects.
+in the `ClusterNetworkPolicy` API object.
 
 ## Goals
 
@@ -15,9 +15,9 @@ in the `AdminNetworkPolicy` and `BaselineAdminNetworkPolicy` API objects.
   - Currently the behaviour for policies defined around traffic from cluster
     workloads (non-hostNetworked pods) towards nodes in the
     cluster is undefined. See https://github.com/kubernetes-sigs/network-policy-api/issues/73.
-    - ANP currently supports only east-west traffic and this traffic flow cuts from
+    - KCNP currently supports only east-west traffic and this traffic flow cuts from
     overlay to underlay which makes this part of the egress (northbound) use case.
-    - Let's provide a defined behaviour in ANP to explicitly achieve the use case.
+    - Let's provide a defined behaviour in KCNP to explicitly achieve the use case.
     - NOTE: Traffic towards nodes here includes traffic towards host-networked pods on that node
       because a "node" resource encompasses all objects that share the host-networking resources
 * Implement egress traffic control towards k8s-apiservers
@@ -32,10 +32,10 @@ in the `AdminNetworkPolicy` and `BaselineAdminNetworkPolicy` API objects.
   - Currently the behaviour for policies defined around traffic from cluster
   workloads (non-hostNetworked pods) towards hostNetworked pods in the
   cluster is undefined. See https://github.com/kubernetes-sigs/network-policy-api/issues/73.
-  - ANP currently supports only east-west traffic and this traffic flow cuts from
+  - KCNP currently supports only east-west traffic and this traffic flow cuts from
   overlay to underlay which makes this part of the egress (northbound) use case.
   - NOTE: Currently there are no user stories for `CNI pod to arbitrarily chosen hostNetworked pods`.
-    Let's provide a defined behaviour in ANP to explicitly achieve the use case in the future if we have
+    Let's provide a defined behaviour in KCNP to explicitly achieve the use case in the future if we have
     user stories for this outside of the k8s-apiserver usecase which is already covered in the goals.
     If that happens, this can be moved to goals.
 
@@ -83,21 +83,21 @@ Proof of Concept for the API design details can be found here:
 
 ### Implementing egress traffic control towards cluster nodes
 
-This NPEP proposes to add a new type of `AdminNetworkPolicyEgressPeer` called `Nodes`
+This NPEP proposes to add a new type of `ClusterNetworkPolicyEgressPeer` called `Nodes`
 to be able to explicitly select nodes (based on the node's labels) in the cluster.
 This ensures that if the list of IPs on a node OR list of nodes change, the users
 don't need to manually intervene to include those new IPs. The label selectors will
 take care of this automatically. Note that the nodeIPs that this type of peer matches
 on are the IPs present in `Node.Status.Addresses` field of the node.
 
 ```
-// AdminNetworkPolicyEgressPeer defines a peer to allow traffic to.
+// ClusterNetworkPolicyEgressPeer defines a peer to allow traffic to.
 // Exactly one of the selector pointers must be set for a given peer. If a
 // consumer observes none of its fields are set, they must assume an unknown
 // option has been specified and fail closed.
 // +kubebuilder:validation:MaxProperties=1
 // +kubebuilder:validation:MinProperties=1
-type AdminNetworkPolicyEgressPeer struct {
+type ClusterNetworkPolicyEgressPeer struct {
     <snipped>
 	// Nodes defines a way to select a set of nodes in
 	// in the cluster. This field follows standard label selector
@@ -108,23 +108,18 @@ type AdminNetworkPolicyEgressPeer struct {
 }
 ```
 
-Note that `AdminNetworkPolicyPeer` will be changed to
-`AdminNetworkPolicyEgressPeer` and `AdminNetworkPolicyIngressPeer` since ingress and
-egress peers have started to diverge at this point and it is easy to
-maintain it with two sets of peer definitions.
-This ensures nodes can be referred to only as "egress peers".
-
 Example: Admin wants to deny egress traffic from tenants who don't have
 `restricted`, `confidential` or `internal` level security clearance
 to control-plane nodes at 443 and 6443 ports in the cluster
 
 ```
 apiVersion: policy.networking.k8s.io/v1alpha1
-kind: AdminNetworkPolicy
+kind: ClusterNetworkPolicy
 metadata:
   name: node-as-egress-peer
 spec:
   priority: 55
+  tier: Admin
   subject:
     namespaces:
       matchExpressions:
@@ -136,30 +131,30 @@ spec:
     - nodes:
         matchLabels:
           node-role.kubernetes.io/control-plane:
-    ports:
-      - portNumber:
-          protocol: TCP
-          port: 443
-      - portNumber:
-          protocol: TCP
-          port: 6443
+    protocols:
+      - tcp:
+        destinationPort:
+          number: 443
+      - tcp:
+        destinationPort:
+          number: 6443
 ```
 
 ### Implementing egress traffic control towards CIDRs
 
-This NPEP proposes to add a new type of `AdminNetworkPolicyEgressPeer` called `Networks`
+This NPEP proposes to add a new type of `ClusterNetworkPolicyEgressPeer` called `Networks`
 to be able to select destination CIDRs. This is provided to be able to select entities
 outside the cluster that cannot be selected using the other peer types.
-This peer type will not be supported in `AdminNetworkPolicyIngressPeer`.
+This peer type will not be supported in `ClusterNetworkPolicyIngressPeer`.
 
 ```
-// AdminNetworkPolicyEgressPeer defines a peer to allow traffic to.
+// ClusterNetworkPolicyEgressPeer defines a peer to allow traffic to.
 // Exactly one of the selector pointers must be set for a given peer. If a
 // consumer observes none of its fields are set, they must assume an unknown
 // option has been specified and fail closed.
 // +kubebuilder:validation:MaxProperties=1
 // +kubebuilder:validation:MinProperties=1
-type AdminNetworkPolicyEgressPeer struct {
+type ClusterNetworkPolicyEgressPeer struct {
     <snipped>
 	// Networks defines a way to select peers via CIDR blocks. This is
 	// intended for representing entities that live outside the cluster,
@@ -187,11 +182,12 @@ destination.
 Example: Let's define ANP and BANP that refer to some CIDR networks:
 ```
 apiVersion: policy.networking.k8s.io/v1alpha1
-kind: AdminNetworkPolicy
+kind: ClusterNetworkPolicy
 metadata:
   name: network-as-egress-peer
 spec:
   priority: 70
+  tier: Admin
   subject:
     namespaces: {}
   egress:
@@ -202,10 +198,10 @@ spec:
       - 194.0.2.0/24
       - 205.0.113.15/32
       - 199.51.100.10/32
-    ports:
-      - portNumber:
-          protocol: UDP
-          port: 53
+    protocols:
+      - udp:
+        destinationPort:
+          number: 53
   - name: "allow-all-egress-to-intranet"
     action: "Allow"
     to:
@@ -227,10 +223,11 @@ spec:
       - 0.0.0.0/0
 ---
 apiVersion: policy.networking.k8s.io/v1alpha1
-kind: BaselineAdminNetworkPolicy
+kind: ClusterNetworkPolicy
 metadata:
   name: default
 spec:
+  tier: Baseline
   subject:
     namespaces: {}
   egress:
@@ -251,17 +248,16 @@ This allows admins to specify rules that define:
 
 * Instead of adding CIDR peer directly into the main object, we can
 define a new object called `NetworkSet` and use selectors or
-name of that object to be referred to from AdminNetworkPolicy and
-BaselineAdminNetworkPolicy objects. This is particularly useful
-if CIDR ranges are prone to changes versus the current model is
-is better if the set of CIDRs are mostly a constant and are only referred
-to from one or two egress rules. It increases readability. However the
-drawback is if the CIDRs do change, then one has to ensure to update all
-the relevant ANPs and BANP accordingly. In order to see whether we need
-a new object to be able to define CIDRs in addition to the in-line peer,
-we have another NPEP where that is being discussed
-https://github.com/kubernetes-sigs/network-policy-api/pull/183. The scope
-of this NPEP is limited to inline CIDR peers.
+name of that object to be referred to from the ClusterNetworkPolicy
+object. This is particularly useful if CIDR ranges are prone to changes
+versus the current model is is better if the set of CIDRs are mostly a
+constant and are only referred to from one or two egress rules. It
+increases readability. However the drawback is if the CIDRs do change,
+then one has to ensure to update all the relevant KCNPs accordingly.
+In order to see whether we need a new object to be able to define CIDRs
+in addition to the in-line peer, we have another NPEP where that is being
+discussed https://github.com/kubernetes-sigs/network-policy-api/pull/183.
+The scope of this NPEP is limited to inline CIDR peers.
 
 ## References
 

npeps/npep-133-fqdn-egress-selector.md

@@ -29,20 +29,21 @@ Names](https://www.wikipedia.org/wiki/Fully_qualified_domain_name) (FQDNs).
     belong to the domain. While this is definitely undesirable, it is at least
     not an unsafe failure.
 
-* Currently only AdminNetworkPolicy is the intended scope for this proposal.
+* Currently only Admin tier of ClusterNetworkPolicy is the intended scope for this
+  proposal.
   * Since Kubernetes NetworkPolicy does not have a FQDN selector, adding this
-    capability to BaselineAdminNetworkPolicy could result in writing baseline
-    rules that can't be replicated by an overriding NetworkPolicy. For example,
-    if BANP allows traffic to `example.io`, but the namespace admin installs a
-    Kubernetes Network Policy, the namespace admin has no way to replicate the
-    `example.io` selector using just Kubernetes Network Policies.
+    capability to Baseline tier could result in writing baseline rules that can't
+    be replicated by an overriding NetworkPolicy. For example, if Baseline tier
+    allows traffic to `example.io`, but the namespace admin installs a Kubernetes
+    Network Policy, the namespace admin has no way to replicate the `example.io`
+    selector using just Kubernetes Network Policies.
 
 ## Non-Goals
 
 * This enhancement does not include a FQDN selector for allowing ingress
   traffic.
 * This enhancement only describes enhancements to the existing L4 filtering as
-  provided by AdminNetworkPolicy. It does not propose any new L7 matching or
+  provided by ClusterNetworkPolicy. It does not propose any new L7 matching or
   filtering capabilities, like matching HTTP traffic or URL paths.
   * This selector should not control what DNS records are resolvable from a
     particular workload.
@@ -81,7 +82,7 @@ hampers the readability of the network policies.
 * As a cluster admin, I want to allow Pods in the cluster to send traffic to a
   entire tree of domains. For example, our CDN has domains of the format
   `<session>.<random>.<region>.my-app.cdn.com`. I want to be able to use a
-  wild-card selector toallow the full tree of subdomains below
+  wild-card selector to allow the full tree of subdomains below
   `**.my-app.cdn.com`.
 
 ### Future User Stories
@@ -92,14 +93,14 @@ goal in this case is to ensure we do not make these unimplementable down the
 line.
 
 * As a cluster admin, I want to switch the default disposition of the cluster to
-  be default deny. This is enforced using a `BaselineAdminNetworkPolicy`. I also
-  want individual namespace owners to be able to specify their egress peers.
+  be default deny. This is enforced using a `Baseline` tier in ClusterNetworkPolicy`.
+  I also want individual namespace owners to be able to specify their egress peers.
   Namespace admins would then use a FQDN selector in the Kubernetes
   `NetworkPolicy` objects to allow `my-service.com`.
 
 ## API
 
-This NPEP proposes adding a new type of `AdminNetworkPolicyEgressPeer` called
+This NPEP proposes adding a new type of `ClusterNetworkPolicyEgressPeer` called
 `FQDNPeerSelector` which allows specifying domain names.
 
 ```golang
@@ -126,7 +127,7 @@ This NPEP proposes adding a new type of `AdminNetworkPolicyEgressPeer` called
 // +kubebuilder:validation:Pattern=`^(\*\.)?([a-zA-z0-9]([-a-zA-Z0-9_]*[a-zA-Z0-9])?\.)+[a-zA-z0-9]([-a-zA-Z0-9_]*[a-zA-Z0-9])?\.?$`
 type DomainName string
 
-type AdminNetworkPolicyEgressPeer struct {
+type ClusterNetworkPolicyEgressPeer struct {
     <snipped>
     // DomainNames provides a way to specify domain names as peers.
     // 
@@ -151,11 +152,12 @@ type AdminNetworkPolicyEgressPeer struct {
 
 ```yaml
 apiVersion: policy.networking.k8s.io/v1alpha1
-kind: AdminNetworkPolicy
+kind: ClusterNetworkPolicy
 metadata:
   name: allow-my-service-egress
 spec:
   priority: 55
+  tier: Admin
   subject:
     namespaces:
       matchLabels:
@@ -167,10 +169,10 @@ spec:
     - domainNames:
       - "my-service.com"
       - "*.cloud-provider.io"
-    ports:
-    - portNumber:
-        protocol: TCP
-        port: 443
+    protocols:
+    - tcp:
+        destinationPort:
+          number: 443
 ```
 
 #### Maintaining an allowlist of domains
@@ -181,11 +183,12 @@ This example, includes the DENY rule in the same ANP object. It's also possible
 to use another ANP object with a lower priority (e.g. `100` in this example):
 ```yaml
 apiVersion: policy.networking.k8s.io/v1alpha1
-kind: AdminNetworkPolicy
+kind: ClusterNetworkPolicy
 metadata:
   name: allow-my-service-egress
 spec:
   priority: 55
+  tier: Admin
   subject:
     namespaces:
       matchLabels:
@@ -197,26 +200,27 @@ spec:
     - domainNames:
       - "my-service.com"
       - "*.cloud-provider.io"
-    ports:
-    - portNumber:
-        protocol: TCP
-        port: 443
+    protocols:
+    - tcp:
+      destinationPort:
+        number: 443
   - name: "default-deny"
     action: "Deny"
     to:
     - networks:
       - "0.0.0.0/0"
 ```
 
-This example uses a default-deny BaselineAdminNetworkPolicy to create the
+This example uses a default-deny Baseline ClusterNetworkPolicy to create the
 allowlist:
 ```yaml
 apiVersion: policy.networking.k8s.io/v1alpha1
-kind: AdminNetworkPolicy
+kind: ClusterNetworkPolicy
 metadata:
   name: allow-my-service-egress
 spec:
   priority: 55
+  tier: Admin
   subject:
     namespaces:
       matchLabels:
@@ -228,16 +232,17 @@ spec:
     - domainNames:
       - "my-service.com"
       - "*.cloud-provider.io"
-    ports:
-    - portNumber:
-        protocol: TCP
-        port: 443
+    protocols:
+    - tcp:
+      destinationPort:
+        number: 443
 ---
 apiVersion: policy.networking.k8s.io/v1alpha1
-kind: BaselineAdminNetworkPolicy
+kind: ClusterNetworkPolicy
 metadata:
   name: default
 spec:
+  tier: Baseline
   subject:
     namespaces: {}
   ingress:

site-src/api-overview.md

@@ -121,9 +121,20 @@ before policies with higher priority values in the same tier.
 Each CNP should define at least one `Ingress` or `Egress` relevant in-cluster traffic flow 
 along with the associated Action that should occur. In each `gress` rule the user 
 should AT THE MINIMUM define an `Action`, and at least one `ClusterNetworkPolicyPeer`.
-Optionally the user may also define select `Ports` to filter traffic on and also 
+Optionally the user may also define select `Protocols` to filter traffic on and also
 a name for each rule to make management and reporting easier for Admins.
 
+Within the `Protocols` array, `TCP`, `UDP`, or `SCTP` protocols can be specified, each with an
+optional `DestinationPort`. The `DestinationPort` can be a single `Number` or a `Range`
+with a `Start` and `End`. If `DestinationPort` is omitted, all ports for the specified
+protocol match.
+
+Alternatively, `DestinationNamedPort` can be used to target a port by name. A named port is
+defined directly within the ports section of the `Pod` or `Deployment` container spec by assigning
+a string to the name field alongside the containerPort. Existing named ports can be located by
+inspecting the resource's YAML under `spec.containers[].ports` or by running `kubectl get pod <pod-name> -o jsonpath='{.spec.containers[*].ports[*].name}'`. Using a name instead of a number allows the ClusterNetworkPolicy to remain valid even
+if the container’s underlying port number is updated.
+
 ### Status 
 
 For `v1alpha2` of this API the ANP status field is simply defined as a list of