diff --git a/docs/antrea-network-policy.md b/docs/antrea-network-policy.md index 7e76d9caf02..6bd66b069e1 100644 --- a/docs/antrea-network-policy.md +++ b/docs/antrea-network-policy.md @@ -29,6 +29,8 @@ - [The ClusterGroup resource](#the-clustergroup-resource) - [kubectl commands for ClusterGroup](#kubectl-commands-for-clustergroup) - [Select Namespace by Name](#select-namespace-by-name) + - [K8s clusters with version 1.21 and above](#k8s-clusters-with-version-121-and-above) + - [K8s clusters with version 1.20 and below](#k8s-clusters-with-version-120-and-below) - [RBAC](#rbac) - [Notes](#notes) @@ -835,8 +837,47 @@ The following kubectl commands can be used to retrieve CG resources: Kubernetes NetworkPolicies and Antrea-native policies allow selecting workloads from Namespaces with the use of a label selector (i.e. `namespaceSelector`). However, it is often desirable to be able to select Namespaces directly by their `name` -as opposed to using the `labels` associated with the Namespaces. In order to select -Namespaces by name, Antrea labels Namespaces with a reserved label `antrea.io/metadata.name`, +as opposed to using the `labels` associated with the Namespaces. + +### K8s clusters with version 1.21 and above + +Starting with K8s v1.21, all Namespaces are labeled with the `kubernetes.io/metadata.name: ` [label](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/#automatic-labelling) +provided that the `NamespaceDefaultLabelName` feature gate (enabled by default) is not disabled in K8s. +K8s NetworkPolicy and Antrea-native policy users can take advantage of this reserved label +to select Namespaces directly by their `name` in `namespaceSelectors` as follows: + +```yaml +apiVersion: crd.antrea.io/v1alpha1 +kind: NetworkPolicy +metadata: + name: test-anp-by-name + namespace: default +spec: + priority: 5 + tier: application + appliedTo: + - podSelector: {} + egress: + - action: Allow + to: + - podSelector: + matchLabels: + app: core-dns + namespaceSelector: + matchLabels: + kubernetes.io/metadata.name: kube-system + ports: + - protocol: TCP + port: 53 + name: AllowToCoreDNS +``` + +**Note**: `NamespaceDefaultLabelName` feature gate is scheduled to be removed in K8s v1.24, thereby +ensuring that labeling Namespaces by their name cannot be disabled. + +### K8s clusters with version 1.20 and below + +In order to select Namespaces by name, Antrea labels Namespaces with a reserved label `antrea.io/metadata.name`, whose value is set to the Namespace's name. Users can then use this label in the `namespaceSelector` field, in both K8s NetworkPolicies and Antrea-native policies to select Namespaces by name. By default, Namespaces are not labeled with the reserved name label. @@ -903,13 +944,6 @@ spec: The above example allows all Pods from Namespace "default" to connect to all "core-dns" Pods from Namespace "kube-system" on TCP port 53. -**Note**: A similar [effort](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/2161-apiserver-default-labels) is currently underway in Kubernetes to label all Namespaces -with `kubernetes.io/metadata.name: ` label. By introducing the -`antrea.io/metadata.name` label, we give our users early access to this feature. -When `kubernetes.io/metadata.name` is introduced upstream, we recommend updating -your policies to use the new label, but we will also keep providing our custom -admission controller for backwards-compatibility. - ## RBAC Antrea-native policy CRDs are meant for admins to manage the security of their