From 25b398adf931cabe2d38edde8e3b7c2c7542f6e0 Mon Sep 17 00:00:00 2001 From: Abhishek Raut Date: Tue, 19 May 2020 18:59:27 -0700 Subject: [PATCH] Add documentation for ClusterNetworkPolicy --- docs/cluster-network-policy.md | 123 +++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 docs/cluster-network-policy.md diff --git a/docs/cluster-network-policy.md b/docs/cluster-network-policy.md new file mode 100644 index 00000000000..ecec831ab07 --- /dev/null +++ b/docs/cluster-network-policy.md @@ -0,0 +1,123 @@ +# Cluster Network Policy + +ClusterNetworkPolicy is a specification of how workloads within a cluster +communicate with each other and other external endpoints. +The ClusterNetworkPolicy is supposed to aid cluster-admins to determine +the security policy for the cluster, unlike K8s NetworkPolicy, which is +aimed towards developers to secure their apps. + +## The ClusterNetworkPolicy resource + +An example ClusterNetworkPolicy might look like this: +``` +apiVersion: security.antrea.tanzu.vmware.com/v1beta1 +kind: ClusterNetworkPolicy +metadata: + name: test-cnp +spec: + priority: 1 + appliedTo: + - podSelector: + matchLabels: + role: db + - namespaceSelector: + matchLabels: + env: prod + ingress: + - from: + action: Allow + - podSelector: + matchLabels: + role: db + - podSelector: + matchLabels: + role: db + namespaceSelector: + matchLabels: + role: db + ports: + - protocol: TCP + port: 8080 + name: httpPort + egress: + - to: + action: Drop + - ipBlock: + cidr: 10.0.10.0/24 + ports: + - protocol: TCP + port: 5978 +``` + +**spec**: The ClusterNetworkPolicy `spec` has all the information needed to +define a cluster-wide security policy. + +**appliedTo**: The `appliedTo` field specifies the grouping criteria of Pods to +which the policy applies to. Pods can be selected cluster-wide using +`podSelector`. If set with a `namespaceSelector`, all Pods from Namespaces +selected by the namespaceSelector will be selected. Specific Pods from +specific Namespaces can be selected by using a combination of +`podSelector` and `namespaceSelector` in the same peer. IPBlock is not allowed +to be set in the `appliedTo` field. +In the example, the policy applies to Pods, which either match the labels +"role=db" in all the Namespaces, or are from Namespaces which match the +labels "env=prod". + +**priority**: The `priority` field determines the relative priority of the policy +among all ClusterNetworkPolicies in the given cluster. This field is mandatory. +A lower priority value indicates higher precedence. Priority values can range +from 1-10000. +**Note**: Policies with same priorities will be evaluated +indeterministically. Users should therefore take care to use priorities to +ensure the behavior they expect. + +**ingress**: Each ClusterNetworkPolicy may consist of zero or more ordered +set of ingress rules. Each rule, depending on the `action` field of the rule, +allows or drops traffic which matches both the `from` and `ports` sections. +The example policy contains a single rule, which allows matched traffic on a +single port, from one of the two sources, first specified by the `podSelector` +and second, specified by the combination of `podSelector` and +`namespaceSelector`. +**Note**: The order in which the ingress rules are set matter. i.e. rules will be +evaluated in the order in which they are written. + +**egress**: Each ClusterNetworkPolicy may consist of zero or more ordered set of +egress rules. Each rule, depending on the `action` field of the rule, allows +or drops traffic which matches both the `to` and `ports` sections. The example +policy contains a single rule, which drops matched traffic on a single port, +to the 10.0.10.0/24 subnet specified by the `ipBlock` field. +**Note**: The order in which the egress rules are set matter. i.e. rules will be +evaluated in the order in which they are written. + +## Behavior of `to` and `from` selectors + +There are four kinds of selectors that can be specified in an ingress from +section or egress to section: + +**podSelector**: This selects particular Pods from all Namespaces as "sources", +if set in "ingress" section, or as "destinations", if set in "egress" section. + +**namespaceSelector**: This selects particular Namespaces for which all Pods are +grouped as ingress "sources" or egress "destinations". + +**podSelector** and **namespaceSelector**: A single to/from entry that specifies +both namespaceSelector and podSelector selects particular Pods within +particular Namespaces. + +**ipBlock**: This selects particular IP CIDR ranges to allow as ingress sources +or egress destinations. These should be cluster-external IPs, since Pod IPs are +ephemeral and unpredictable. + +## Key differences from K8s NetworkPolicy + +- ClusterNetworkPolicy is of cluster scope, hence a `podSelector` without any + `namespaceSelector` selects Pods from all Namespaces. +- There is no automatic isolation of Pods on being selected in appliedTo. +- Ingress/Egress rules in ClusterNetworkPolicy has an `action` field which + specifies whether the matched rule allows or drops the traffic. The default + action of a rule is to Allow traffic. +- IPBlock field in the ClusterNetworkPolicy rules do not have the `except` + field. A higher priority rule can be written to deny the specific CIDR range + to simulate the behavior of IPBlock field with `cidr` and `except` set. +- Rules assume the priority in which they are written. i.e. rule set at top + takes precedence over a rule set below it.