Add tiered policies to Calico OSS (#1699)

Co-authored-by: Tomas Hruby <[email protected]> Co-authored-by: Christopher Tauchen <[email protected]>
tigera · Oct 21, 2024 · 918ec0c · 918ec0c
1 parent f803e9d
commit 918ec0c
Show file tree

Hide file tree

Showing 10 changed files with 823 additions and 31 deletions.
diff --git a/calico-cloud/network-policy/policy-tiers/tiered-policy.mdx b/calico-cloud/network-policy/policy-tiers/tiered-policy.mdx
@@ -1,8 +1,8 @@
 ---
-description: Learn about policies, tiers, and policy evaluation.
+description: Understand how tiered policy works and supports microsegmentation.
 ---
 
-# Policy tiers tutorial
+# Get started with policy tiers
 
 ## Seamless network policy integration
 
@@ -20,7 +20,7 @@ All {{prodname}} and Kubernetes network policies reside in tiers. You can start
 
 ![policy types](/img/calico-cloud/policy-types.svg)
 
-Next, you can determine the priority of policies in tiers (from top to bottom). In the following example, that platform and security tiers use {{prodname}} global network policies that apply to all pods, while developer teams can safely manage pods within namespaces using Kubernetes network policy for their applications and microservices.
+Next, you can determine the priority of policies in tiers (from top to bottom). In the following example, the platform and security tiers use {{prodname}} global network policies that apply to all pods, while developer teams can safely manage pods within namespaces using Kubernetes network policy for their applications and microservices.
 
 ![policy tiers](/img/calico-cloud/policy-tiers.png)
 
@@ -50,9 +50,9 @@ spec:
 kubectl apply -f security.yaml
 ```
 
-## The default tier: always last
+## The default tier:
 
-The default tier is created during installation and is always the last tier.
+The AdminNetworkPolicy tier where all [Kubernetes admin network policies](https://network-policy-api.sigs.k8s.io/reference/examples/) reside. It is automatically created during installation and has the order of 1,000. This value is fixed, and cannot be changed.
 
 ![default tier](/img/calico-cloud/default-tier.png)
 
@@ -62,6 +62,10 @@ The default tier is where:
 - Network and global network policies are placed when you upgrade from Project Calico to {{prodname}}
 - Recommended policies are placed when you use the **Recommend a policy** feature
 
+## AdminNetworkPolicy tier:
+
+The AdminNetworkPolicy tier is where all [Kubernetes admin network policies](https://network-policy-api.sigs.k8s.io/reference/examples/) reside. It is automatically created during installation and has the order of 1,000.
+
 ## System tiers
 
 System tiers are added during installation and are hidden by default. Always add your tiers after `allow-tigera` and `tigera-security` (in terms of order).
@@ -88,21 +92,21 @@ Now you can reorder tiers by dragging and moving them.
 
 ## Tier order
 
-Tiers are ordered from left to right, starting with the highest priority (also called highest precedence) tiers.
+Tiers are sorted by their orders (from left to right), starting from the lowest order (the highest priority) tiers.
 
 ![tier order](/img/calico-cloud/tier-order.png)
 
 In the example above, tier priorities are as follows:
 
 - **security tier** - is higher priority than platform tier
 - **platform tier** - is higher priority than default tier
-- **default tier** - is always the last tier, and cannot be reordered
+- **default tier** - is the lowest priority
 
 The tier you put as the highest priority (after system tiers), depends on your environment. In compliance-driven environments, the security tier may be the highest priority (as shown above). There is no one-size-fits-all order.
 
 ## Policy processing
 
-Policies are processed in sequential order from top to bottom.
+Policies are processed in sequential order from lowest order (highest priority) to highest order (lowest priority), which is from top to bottom in the following diagram.
 
 ![policy processing](/img/calico-cloud/policy-processing.png)
 
@@ -135,11 +139,13 @@ The following diagrams show the relationship between all of the elements that af
 
 ### Implicit default deny
 
-As shown in the following diagram, at the end of each tier is an implicit default deny. This is a safeguard that helps mitigate against unsecured policy. Because of this safeguard, you must explicitly apply the **Pass** action rule when you want traffic evaluation to continue. In the following example, the Pass action in a policy ensures that traffic evaluation continues, and overrides the implicit default deny.
+As shown in the following diagram, at the end of each tier is an implicit default deny. This is a safeguard that helps mitigate against unsecured policy.
+Because of this safeguard, you must either explicitly update tier's default action to **Pass** or apply a Pass action rule when you want traffic evaluation to continue.
+In the following example, the Pass action in a policy ensures that traffic evaluation continues, and overrides the implicit default deny.
 
-![implicit deny](/img/calico-cloud/implicit-deny.svg)
+![implicit-deny](/img/calico-cloud/implicit-deny.svg)
 
-Let’s look at a Dev/Ops global network policy in a high precedence tier (Platform). The policy denies ingress and egress traffic to workloads that match selector, `env != "stage"`. To ensure that policies continue to evaluate traffic after this policy, the policy adds a Pass action for both ingress and egress.
+Let’s look at a Dev/Ops global network policy in a high precedence tier (Platform). The policy denies ingress and egress traffic to workloads that match selector, `env == "stage"`. To ensure that policies continue to evaluate traffic after this policy, the policy adds a Pass action for both ingress and egress.
 
 **Pass action rule example**
 
@@ -167,11 +173,25 @@ spec:
     - Egress
 ```
 
+The other option, is to update tier's default action to **Pass** to override the implicit default deny.
+
+**Pass default action tier example**
+
+```yaml
+apiVersion: projectcalico.org/v3
+kind: Tier
+metadata:
+  name: devops
+spec:
+  order: 300
+  defautlAction: Pass
+```
+
 ### Policy endpoint matching across tiers
 
 Whoever is responsible for tier creation, also needs to understand how policy selects matching endpoints across tiers. For normal policy processing (without apply-on-forward, pre-DNAT, and do-not-track), if no policies within a tier apply to endpoints, the tier is skipped, and the tier's implicit deny behavior is not executed.
 
-In the following example, policy D in the Security tier includes a **Pass action** rule because we want traffic evaluation to continue to the next tier in sequence. In the Platform tier, there are no selectors in policies that match endpoints so the tier is skipped, including the end of tier deny. Evaluation continues to the Application tier. **Policy J** is the first policy with a matching endpoint.
+In the following example, **policy D** in the Security tier includes a Pass action rule because we want traffic evaluation to continue to the next tier in sequence. In the Platform tier, there are no selectors in policies that match endpoints so the tier is skipped, including the end of tier deny. Evaluation continues to the Application tier. **Policy J** is the first policy with a matching endpoint.
 
 ![endpoint match](/img/calico-cloud/endpoint-match.svg)
 
@@ -203,3 +223,7 @@ We recommend:
   For example, you may need to update Pass action rules to policies before or after the new tier. Intervening tiers may require changes to policies before and after, depending on the endpoints.
 
 - Use the **policy preview** feature to see effects of policy in action before enforcing it, and use the **staged network policy** feature to test the entire tier workflow before pushing it to production
+
+## Additional resources
+
+- For details on using RBAC for fine-grained access to tiers and policies, see [Configure RBAC for tiered policies](rbac-tiered-policies.mdx).
diff --git a/calico-cloud/reference/resources/tier.mdx b/calico-cloud/reference/resources/tier.mdx
@@ -28,11 +28,9 @@ Policies in each Tier are then processed in order.
 - If a [NetworkPolicy](networkpolicy.mdx) or [GlobalNetworkPolicy](globalnetworkpolicy.mdx) in the Tier `Allow`s or `Deny`s the packet, then evaluation is done: the packet is handled accordingly.
 - If a [NetworkPolicy](networkpolicy.mdx) or [GlobalNetworkPolicy](globalnetworkpolicy.mdx) in the Tier `Pass`es the packet, the next Tier containing a Policy that applies to the endpoint processes the packet.
 
-If the Tier applies to the endpoint, but takes no action on the packet the packet is dropped.
+If the Tier applies to the endpoint, but takes no action on the packet the packet is dropped. This behaviour can be changed by setting the `defaultAction` of a tier to `Pass`.
 
-<!--TODO-XREF-CC
-If the last Tier applying to the endpoint `Pass`es the packet, that endpoint's [Profiles](/reference/resources/profile) are evaluated.
--->
+If the last Tier applying to the endpoint `Pass`es the packet, that endpoint's [Profiles] (profile.mdx) are evaluated.
 
 ## Sample YAML
 
@@ -43,6 +41,7 @@ metadata:
   name: internal-access
 spec:
   order: 100
+  defaultAction: Deny
 ```
 
 ## Definition
@@ -55,8 +54,9 @@ spec:
 
 ### Spec
 
-| Field | Description                                                                                                                          | Accepted Values | Schema | Default               |
-|-------|--------------------------------------------------------------------------------------------------------------------------------------|-----------------|--------|-----------------------|
-| order | (Optional) Indicates priority of this Tier, with lower order taking precedence. No value indicates highest order (lowest precedence) |                 | float  | `nil` (highest order) |
+| Field         | Description                                                                                                                          | Accepted Values | Schema | Default               |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------- | ------ | --------------------- |
+| order         | (Optional) Indicates priority of this Tier, with lower order taking precedence. No value indicates highest order (lowest precedence) |                 | float  | `nil` (highest order) |
+| defaultAction | (Optional) Indicates the default action, when this Tier applies to an endpoint, but takes not action on the packet                   | `Deny`, `Pass`  | string | `Deny`                |
 
 All Policies created by {{prodname}} orchestrator integrations are created in the default (last) Tier.
diff --git a/calico-enterprise/network-policy/policy-tiers/policy-tutorial-ui.mdx b/calico-enterprise/network-policy/policy-tiers/policy-tutorial-ui.mdx
@@ -1,5 +1,5 @@
 ---
-description: Covers the basics of Calico Cloud network policy.
+description: Covers the basics of Calico Enterprise network policy.
 ---
 
 # Network policy tutorial

diff --git a/calico-enterprise/network-policy/policy-tiers/tiered-policy.mdx b/calico-enterprise/network-policy/policy-tiers/tiered-policy.mdx
@@ -50,9 +50,9 @@ spec:
 kubectl apply -f security.yaml
 ```
 
-## The default tier: always last
+## The default tier:
 
-The default tier is created during installation and is always the last tier.
+The default tier is created during installation and has the order of 1,000,000. This value is fixed, and cannot be changed. The desire is to evaluate policies in the default tier as last.
 
 ![default-tier](/img/calico-enterprise/default-tier.png)
 
@@ -62,6 +62,10 @@ The default tier is where:
 - Network and global network policies are placed when you upgrade from Project Calico to {{prodname}}
 - Recommended policies are placed when you use the **Recommend a policy** feature
 
+## AdminNetworkPolicy tier:
+
+The AdminNetworkPolicy tier is where all [Kubernetes admin network policies](https://network-policy-api.sigs.k8s.io/reference/examples/) reside. It is automatically created during installation and has the order of 1,000. This value is fixed, and cannot be changed.
+
 ## System tiers
 
 System tiers are added during installation and are hidden by default.
@@ -86,21 +90,21 @@ Now you can reorder tiers by dragging and moving them.
 
 ## Tier order
 
-Tiers are ordered from left to right, starting with the highest priority (also called highest precedence) tiers.
+Tiers are sorted by their orders (from left to right), starting from the lowest order (the highest priority) tiers.
 
 ![tier-order](/img/calico-enterprise/tier-order.png)
 
 In the example above, tier priorities are as follows:
 
 - **security tier** - is higher priority than platform tier
 - **platform tier** - is higher priority than default tier
-- **default tier** - is always the last tier and cannot be reordered
+- **default tier** - is the lowest priority
 
 The tier you put as the highest priority (after system tiers), depends on your environment. In compliance-driven environments, the security tier may be the highest priority (as shown above). There is no one-size-fits-all order.
 
 ## Policy processing
 
-Policies are processed in sequential order from top to bottom.
+Policies are processed in sequential order from lowest order (highest priority) to highest order (lowest priority), which is from top to bottom in the following diagram.
 
 ![policy-processing](/img/calico-enterprise/policy-processing.png)
 
@@ -133,7 +137,9 @@ The following diagrams show the relationship between all of the elements that af
 
 ### Implicit default deny
 
-As shown in the following diagram, at the end of each tier is an implicit default deny. This is a safeguard that helps mitigate against unsecured policy. Because of this safeguard, you must explicitly apply the **Pass** action rule when you want traffic evaluation to continue. In the following example, the Pass action in a policy ensures that traffic evaluation continues, and overrides the implicit default deny.
+As shown in the following diagram, at the end of each tier is an implicit default deny. This is a safeguard that helps mitigate against unsecured policy.
+Because of this safeguard, you must either explicitly update tier's default action to **Pass** or apply a Pass action rule when you want traffic evaluation to continue.
+In the following example, the Pass action in a policy ensures that traffic evaluation continues, and overrides the implicit default deny.
 
 ![implicit-deny](/img/calico-enterprise/implicit-deny.svg)
 
@@ -165,6 +171,20 @@ spec:
     - Egress
 ```
 
+The other option, is to update tier's default action to **Pass** to override the implicit default deny.
+
+**Pass default action tier example**
+
+```yaml
+apiVersion: projectcalico.org/v3
+kind: Tier
+metadata:
+  name: devops
+spec:
+  order: 300
+  defautlAction: Pass
+```
+
 ### Policy endpoint matching across tiers
 
 Whoever is responsible for tier creation, also needs to understand how policy selects matching endpoints across tiers. For normal policy processing (without apply-on-forward, pre-DNAT, and do-not-track), if no policies within a tier apply to endpoints, the tier is skipped, and the tier's implicit deny behavior is not executed.

diff --git a/calico-enterprise/reference/resources/tier.mdx b/calico-enterprise/reference/resources/tier.mdx
@@ -28,7 +28,7 @@ Policies in each Tier are then processed in order.
 - If a [NetworkPolicy](networkpolicy.mdx) or [GlobalNetworkPolicy](globalnetworkpolicy.mdx) in the Tier `Allow`s or `Deny`s the packet, then evaluation is done: the packet is handled accordingly.
 - If a [NetworkPolicy](networkpolicy.mdx) or [GlobalNetworkPolicy](globalnetworkpolicy.mdx) in the Tier `Pass`es the packet, the next Tier containing a Policy that applies to the endpoint processes the packet.
 
-If the Tier applies to the endpoint, but takes no action on the packet the packet is dropped.
+If the Tier applies to the endpoint, but takes no action on the packet the packet is dropped. This behaviour can be changed by setting the `defaultAction` of a tier to `Pass`.
 
 If the last Tier applying to the endpoint `Pass`es the packet, that endpoint's [Profiles](profile.mdx) are evaluated.
 
@@ -41,6 +41,7 @@ metadata:
   name: internal-access
 spec:
   order: 100
+  defaultAction: Deny
 ```
 
 ## Definition
@@ -53,8 +54,9 @@ spec:
 
 ### Spec
 
-| Field | Description                                                                                                                          | Accepted Values | Schema | Default               |
-| ----- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------- | ------ | --------------------- |
-| order | (Optional) Indicates priority of this Tier, with lower order taking precedence. No value indicates highest order (lowest precedence) |                 | float  | `nil` (highest order) |
+| Field         | Description                                                                                                                          | Accepted Values | Schema | Default               |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------- | ------ | --------------------- |
+| order         | (Optional) Indicates priority of this Tier, with lower order taking precedence. No value indicates highest order (lowest precedence) |                 | float  | `nil` (highest order) |
+| defaultAction | (Optional) Indicates the default action, when this Tier applies to an endpoint, but takes not action on the packet                   | `Deny`, `Pass`  | string | `Deny`                |
 
 All Policies created by {{prodname}} orchestrator integrations are created in the default (last) Tier.
diff --git a/calico/network-policy/policy-tiers/index.mdx b/calico/network-policy/policy-tiers/index.mdx
@@ -0,0 +1,11 @@
+---
+description: Learn how policy tiers allow diverse teams to securely manage Kubernetes policy.
+hide_table_of_contents: true
+---
+
+# Policy tiers
+
+import DocCardList from '@theme/DocCardList';
+import { useCurrentSidebarCategory } from '@docusaurus/theme-common';
+
+<DocCardList items={useCurrentSidebarCategory().items} />