Improve documentation for Antrea-native policy #3512
Conversation
Dyanngg
added
the
kind/documentation
|
/skip-all |
Codecov Report
@@ Coverage Diff @@
## main #3512 +/- ##
==========================================
- Coverage 64.55% 56.35% -8.20%
==========================================
Files 278 392 +114
Lines 39513 55091 +15578
==========================================
+ Hits 25507 31046 +5539
- Misses 12022 21639 +9617
- Partials 1984 2406 +422
Flags with carried forward coverage won't be shown. Click here to find out more.
|
|
/skip-all |
Dyanngg
force-pushed
the
enhance-np-doc
branch
2 times, most recently
from
bb33f0d to
7b9a7f2
Compare
|
/skip-all @antoninbas @tnqn could you take another look to see if there are additional comments? Thanks |
|
/skip-all |
|
@antoninbas @tnqn @jianjuns Could you please give this a review? Want to merge this eow. Thanks! |
docs/antrea-network-policy.md
Outdated
| and up to 50,000 unique priorities at rule level, across all Tiers except for | ||
| the "baseline" Tier. For any two Antrea-native policy rules, their rule level | ||
| priorities are only considered equal if their policy objects share the same Tier | ||
| and have the same policy priority, plus the rules themselves are of the same rule | ||
| priority (rule priority is the sequence number of the rule within the policy's | ||
| ingress or egress section). | ||
| - For the "baseline" Tier, the max supported unique priorities (at rule level) is 150. | ||
| - If there are multiple Antrea-native policy rules created at the same rule-level | ||
| priority (same policy Tier, policy priority and rule priority), who happen to select | ||
| overlapping traffic patterns but have conflicting rule actions (e.g.`Allow`v.s.`Deny`), | ||
| the behavior of such traffic will be undeterministic. For example, consider two | ||
| AntreaNetworkPolicies created in the same Namespace and Tier with the same policy | ||
| priority. The first policy applies to all `app=web` Pods in the Namespace and has only | ||
| one ingress rule to `Deny` all traffic from `role=dev` Pods. The other policy also | ||
| applies to all `app=web` Pods in the Namespace and has only one ingress rule, which is | ||
| to `Allow` all traffic from `app=client` Pods. Those two ingress rules might not always | ||
| conflict, but in case a Pod with both `app=client` and `role=dev` labels initiate | ||
| traffic towards the web Pods in the Namespace, both rules will be matched at the same | ||
| priority with conflicting actions. It will be the policy writer's responsibility to | ||
| identify such ambiguities in rule definitions and avoid potential undeterministic | ||
| rule enforcement results. In general, it is recommended that rules of conflicting | ||
| actions are always created at different rule-level priorities. |
There was a problem hiding this comment.
honestly, I feel like we should just discourage users from defining policies at the same priority if they apply to the same Pods. Having the notion of rule-level priority across multiple policies is a bit confusing as it is not based on a user-provided priority value, but on the rule position in the list of rules.
what do you think @jianjuns @tnqn ?
There was a problem hiding this comment.
We can first say the behaviors are not deterministic / predictable if two policies with the same priority apply to the same Pod, if there are both allow and deny rules. Then we can explain further the details like rule priority (assuming most readers will not read it)?
There was a problem hiding this comment.
I was hoping that with this paragraph it discourages people from defining policies at the same priority if they apply to the same Pods. From Antrea perspective it is hard to enforce this though.
|
/skip-all |
|
/skip-all |
|
/skip-all |
docs/antrea-network-policy.md
Outdated
| rule enforcement results. In general, it is recommended that rules of conflicting | ||
| actions are always created at different rule-level priorities. |
There was a problem hiding this comment.
I think this is not strong enough. IMO, it should be:
In general, it is recommended not to create rules with conflicting actions in policy resources with the same priority, if these rules may apply to the same traffic, as the behavior could be undeterministic.
And actually I think this should be the first sentence of that bullet list item (and in bold), and you can get into the details after if needed, as Jianjun suggested. The whole concept of rule level priority for rules which are defined across policies with the same priority, is an implementation detail as far as I am concerned. I don't think it is really needs to be a part of the API contract. Inserting a new rule in one of the policies could change rule enforcement order, in ways which are surprising to users.
|
/skip-all |
Signed-off-by: Yang Ding <[email protected]>
|
Addressed all comments so far /skip-all |
Changes include:
namespaces match: selffield.Signed-off-by: Yang Ding [email protected]