Use codegen to produce CRDs

.github/workflows/build.yml

@@ -50,3 +50,27 @@ jobs:
 #        with:
 #          path-to-profile: coverage.out
 
+  verify-crd:
+    name: Verify CRD is up-to-date
+    runs-on: ubuntu-latest
+    if: >
+      (( github.event.pull_request.head.repo.owner.login != github.event.pull_request.base.repo.owner.login ) &&
+        github.event_name == 'pull_request' ) || (github.event_name == 'push' && github.event.commits != '[]' )
+    steps:
+      - name: Set up Go 1.21
+        uses: actions/setup-go@v5
+        with:
+          go-version: 1.21
+
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Verify CRD is up-to-date
+        run: |
+          ./hack/update-crdgen.sh
+          if ! git diff --quiet scheme.yml; then
+            echo "ERROR: CRD scheme.yml is out of date. Please run './hack/update-crdgen.sh' and commit the changes."
+            git diff scheme.yml
+            exit 1
+          fi
+

README.md

@@ -40,6 +40,26 @@ It provides new CRD for Network Policy, MultiNetworkPolicy, to prevent it from c
 (TBD)
 
 
+## Development
+
+### Regenerating CRD Schema
+
+The CRD schema (`scheme.yml`) is generated from Go type definitions in `pkg/apis/k8s.cni.cncf.io/`. To regenerate the CRD after modifying the types:
+
+```bash
+./hack/update-crdgen.sh
+```
+
+This script uses [controller-gen](https://book.kubebuilder.io/reference/controller-gen.html) to generate the CRD manifest from kubebuilder markers in the Go source files.
+
+### Regenerating Go Code
+
+To regenerate deepcopy functions and client code:
+
+```bash
+./hack/update-codegen.sh
+```
+
 ## TODO
 
 * Alternative packet processing other than iptables (e.g. xdp)

hack/update-crdgen.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+SCRIPT_ROOT=$(dirname "${BASH_SOURCE[0]}")/..
+
+# Determine GOBIN
+GOBIN="${GOBIN:-$(go env GOPATH)/bin}"
+
+# Install controller-gen if not present
+if ! command -v controller-gen &> /dev/null && [ ! -f "${GOBIN}/controller-gen" ]; then
+    echo "Installing controller-gen..."
+    go install sigs.k8s.io/controller-tools/cmd/controller-gen@latest
+fi
+
+# Use controller-gen from GOBIN if not in PATH
+CONTROLLER_GEN="${GOBIN}/controller-gen"
+if command -v controller-gen &> /dev/null; then
+    CONTROLLER_GEN="controller-gen"
+fi
+
+cd "${SCRIPT_ROOT}"
+
+# Generate CRD manifests
+echo "Generating CRD manifests..."
+"${CONTROLLER_GEN}" crd \
+    paths="./pkg/apis/k8s.cni.cncf.io/..." \
+    output:crd:artifacts:config=.
+
+# Rename the generated file to scheme.yml
+mv k8s.cni.cncf.io_multi-networkpolicies.yaml scheme.yml
+
+echo "Done."

pkg/apis/k8s.cni.cncf.io/v1beta1/doc.go

@@ -1,5 +1,7 @@
 // +k8s:deepcopy-gen=package,register
 // +groupName=k8s.cni.cncf.io
 // +groupGoName=K8sCniCncfIo
+// +kubebuilder:object:generate=true
 
+// Package v1beta1 contains API Schema definitions for the k8s.cni.cncf.io v1beta1 API group.
 package v1beta1

pkg/apis/k8s.cni.cncf.io/v1beta1/types.go

@@ -26,8 +26,14 @@
 // +genclient:noStatus
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 // +resourceName=multi-networkpolicies
-
-// MultiNetworkPolicy ...
+// +kubebuilder:object:root=true
+// +kubebuilder:storageversion
+// +kubebuilder:resource:path=multi-networkpolicies,singular=multi-networkpolicy,shortName=multi-policy,scope=Namespaced
+
+// MultiNetworkPolicy is a CRD schema to provide NetworkPolicy mechanism for
+// net-attach-def which is specified by the Network Plumbing Working Group.
+// MultiNetworkPolicy is identical to Kubernetes NetworkPolicy,
+// See: https://kubernetes.io/docs/concepts/services-networking/network-policies/ .
 type MultiNetworkPolicy struct {
 	metav1.TypeMeta `json:",inline"`
 	// Standard object's metadata.
@@ -39,8 +45,9 @@
 }
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+// +kubebuilder:object:root=true
 
-// MultiNetworkPolicyList ...
+// MultiNetworkPolicyList contains a list of MultiNetworkPolicy.
 type MultiNetworkPolicyList struct {
 	metav1.TypeMeta `json:",inline"`
 	// Standard object's metadata.
@@ -50,74 +57,165 @@
 	Items []MultiNetworkPolicy `json:"items"`
 }
 
-// MultiPolicyType ...
+// Policy Type string describes the NetworkPolicy type This type is beta-level
+// in 1.8
+// +kubebuilder:validation:Enum=Ingress;Egress
 type MultiPolicyType string
 
 const (
-	// PolicyTypeIngress ...
+	// PolicyTypeIngress is a NetworkPolicy that affects ingress traffic on selected pods.
 	PolicyTypeIngress MultiPolicyType = "Ingress"
-	// PolicyTypeEgress ...
+	// PolicyTypeEgress is a NetworkPolicy that affects egress traffic on selected pods.
 	PolicyTypeEgress MultiPolicyType = "Egress"
 )
 
-// MultiNetworkPolicySpec ...
+// Specification of the desired behavior for this MultiNetworkPolicy.
 type MultiNetworkPolicySpec struct {
+	// podSelector selects the pods to which this MultiNetworkPolicy object applies.
 	PodSelector metav1.LabelSelector `json:"podSelector"`
 
+	// List of ingress rules to be applied to the selected pods. Traffic is
+	// allowed to a pod if there are no NetworkPolicies selecting the pod
+	// (and cluster policy otherwise allows the traffic), OR if the traffic
+	// source is the pod's local node, OR if the traffic matches at least one
+	// ingress rule across all of the NetworkPolicy objects whose podSelector
+	// matches the pod. If this field is empty then this NetworkPolicy does not
+	// allow any traffic (and serves solely to ensure that the pods it selects
+	// are isolated by default)
 	// +optional
 	Ingress []MultiNetworkPolicyIngressRule `json:"ingress,omitempty"`
 
+	// List of egress rules to be applied to the selected pods. Outgoing traffic
+	// is allowed if there are no NetworkPolicies selecting the pod (and cluster
+	// policy otherwise allows the traffic), OR if the traffic matches at least
+	// one egress rule across all of the NetworkPolicy objects whose podSelector
+	// matches the pod. If this field is empty then this NetworkPolicy limits
+	// all outgoing traffic (and serves solely to ensure that the pods it selects
+	// are isolated by default). This field is beta-level in 1.8
 	// +optional
 	Egress []MultiNetworkPolicyEgressRule `json:"egress,omitempty"`
+
+	// List of rule types that the NetworkPolicy relates to. Valid options are
+	// 'Ingress', 'Egress', or 'Ingress,Egress'. If this field is not specified,
+	// it will default based on the existence of Ingress or Egress rules;
+	// policies that contain an Egress section are assumed to affect Egress,
+	// and all policies (whether or not they contain an Ingress section) are
+	// assumed to affect Ingress. If you want to write an egress-only policy,
+	// you must explicitly specify policyTypes [ 'Egress' ]. Likewise, if you
+	// want to write a policy that specifies that no egress is allowed, you must
+	// specify a policyTypes value that include 'Egress' (since such a policy
+	// would not include an Egress section and would otherwise default to just
+	// [ 'Ingress' ]). This field is beta-level in 1.8
 	// +optional
 	PolicyTypes []MultiPolicyType `json:"policyTypes,omitempty"`
 }
 
-// MultiNetworkPolicyIngressRule ...
+// NetworkPolicyIngressRule describes a particular set of traffic that is
+// allowed to the pods matched by a NetworkPolicySpec's podSelector. The traffic
+// must match both ports and from.
 type MultiNetworkPolicyIngressRule struct {
+	// List of ports which should be made accessible on the pods selected for
+	// this rule. Each item in this list is combined using a logical OR. If this
+	// field is empty or missing, this rule matches all ports (traffic not
+	// restricted by port). If this field is present and contains at least one
+	// item, then this rule allows traffic only if the traffic matches at least
+	// one port in the list.
 	// +optional
 	Ports []MultiNetworkPolicyPort `json:"ports,omitempty"`
 
+	// List of sources which should be able to access the pods selected for this
+	// rule. Items in this list are combined using a logical OR operation. If
+	// this field is empty or missing, this rule matches all sources (traffic
+	// not restricted by source). If this field is present and contains at least
+	// one item, this rule allows traffic only if the traffic matches at least
+	// one item in the from list.
 	// +optional
 	From []MultiNetworkPolicyPeer `json:"from,omitempty"`
 }
 
-// MultiNetworkPolicyEgressRule ...
+// NetworkPolicyEgressRule describes a particular set of traffic that is allowed
+// out of pods matched by a NetworkPolicySpec's podSelector. The traffic must
+// match both ports and to. This type is beta-level in 1.8
 type MultiNetworkPolicyEgressRule struct {
+	// List of destination ports for outgoing traffic. Each item in this list is
+	// combined using a logical OR. If this field is empty or missing, this rule
+	// matches all ports (traffic not restricted by port). If this field is
+	// present and contains at least one item, then this rule allows traffic
+	// only if the traffic matches at least one port in the list.
 	// +optional
 	Ports []MultiNetworkPolicyPort `json:"ports,omitempty"`
 
+	// List of destinations for outgoing traffic of pods selected for this rule.
+	// Items in this list are combined using a logical OR operation. If this
+	// field is empty or missing, this rule matches all destinations (traffic
+	// not restricted by destination). If this field is present and contains at
+	// least one item, this rule allows traffic only if the traffic matches at
+	// least one item in the to list.
 	// +optional
 	To []MultiNetworkPolicyPeer `json:"to,omitempty"`
 }
 
-// MultiNetworkPolicyPort ...
+// NetworkPolicyPort describes a port to allow traffic on.
 type MultiNetworkPolicyPort struct {
+	// The protocol (TCP, UDP, or SCTP) which traffic must match.
+	// If not specified, this field defaults to TCP.
 	// +optional
 	Protocol *v1.Protocol `json:"protocol,omitempty"`
 
+	// The port on the given protocol. This can either be a numerical or named
+	// port on a pod. If this field is not provided, this matches all port names
+	// and numbers.
 	// +optional
 	Port *intstr.IntOrString `json:"port,omitempty"`
 
+	// If set, indicates that the range of ports from port to endPort, inclusive,
+	// should be allowed by the policy. This field cannot be defined if the port
+	// field is not defined or if the port field is defined as a named (string)
+	// port. The endPort must be equal or greater than port.
 	// +optional
 	EndPort *int32 `json:"endPort,omitempty"`
 }
 
-// IPBlock ...
+// IPBlock defines policy on a particular IPBlock. If this field is set then
+// neither of the other fields can be.
 type IPBlock struct {
+	// CIDR is a string representing the IP Block.
+	// Valid examples are '192.168.1.1/24'.
 	CIDR string `json:"cidr"`
+
+	// Except is a slice of CIDRs that should not be included within an IP Block.
+	// Valid examples are '192.168.1.1/24'.
+	// Except values will be rejected if they are outside the CIDR range.
 	// +optional
 	Except []string `json:"except,omitempty"`
 }
 
-// MultiNetworkPolicyPeer ...
+// NetworkPolicyPeer describes a peer to allow traffic to/from. Only certain
+// combinations of fields are allowed.
 type MultiNetworkPolicyPeer struct {
+	// This is a label selector which selects Pods. This field follows standard
+	// label selector semantics; if present but empty, it selects all pods.
+	//
+	// If NamespaceSelector is also set, then the NetworkPolicyPeer as a whole
+	// selects the Pods matching PodSelector in the Namespaces selected by
+	// NamespaceSelector. Otherwise it selects the Pods matching PodSelector
+	// in the policy's own Namespace.
 	// +optional
 	PodSelector *metav1.LabelSelector `json:"podSelector,omitempty"`
 
+	// Selects Namespaces using cluster-scoped labels. This field follows
+	// standard label selector semantics; if present but empty, it selects all
+	// namespaces.
+	//
+	// If PodSelector is also set, then the NetworkPolicyPeer as a whole selects
+	// the Pods matching PodSelector in the Namespaces selected by
+	// NamespaceSelector. Otherwise it selects all Pods in the Namespaces
+	// selected by NamespaceSelector.
 	// +optional
 	NamespaceSelector *metav1.LabelSelector `json:"namespaceSelector,omitempty"`
 
+	// IPBlock defines policy on a particular IPBlock. If this field is set then
+	// neither of the other fields can be.
 	// +optional
 	IPBlock *IPBlock `json:"ipBlock,omitempty"`
 }

pkg/apis/k8s.cni.cncf.io/v1beta2/doc.go

@@ -1,5 +1,7 @@
 // +k8s:deepcopy-gen=package,register
 // +groupName=k8s.cni.cncf.io
 // +groupGoName=K8sCniCncfIo
+// +kubebuilder:object:generate=true
 
+// Package v1beta2 contains API Schema definitions for the k8s.cni.cncf.io v1beta2 API group.
 package v1beta2