Skip to content
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.

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

Update Antrea-native policy doc for Namespace labels #2596

Merged
merged 2 commits into from
Aug 16, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 43 additions & 9 deletions docs/antrea-network-policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
<!-- /toc -->
Expand Down Expand Up @@ -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: <namespaceName>` [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.
Expand Down Expand Up @@ -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: <namespaceName>` 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
Expand Down