--- title: "Policy recommendation scope" description: "Reference for the PolicyRecommendation resource in Calico Enterprise that drives policy recommendations generated from observed namespace flows." product: "Calico Enterprise" version: "3.23 (latest)" section: "Reference" canonical_url: "https://docs.tigera.io/calico-enterprise/latest/reference/resources/policyrecommendations" --- # Policy recommendation scope The policy recommendation scope configures Calico Enterprise's policy-recommendation engine. It controls both [namespace policy recommendations](https://docs.tigera.io/calico-enterprise/latest/network-policy/recommendations/policy-recommendations.md) (configured under `namespaceSpec`) and [host policy recommendations](https://docs.tigera.io/calico-enterprise/latest/network-policy/recommendations/hep-policy-recommendations.md) (configured under `hostEndpointSpec`). Namespace and host recommendations are enabled and scoped independently. To apply changes to this resource, use the following format: ```text $ kubectl patch policyrecommendationscope default -p '{"spec":{"":""}}' ``` **Example** `$ kubectl patch policyrecommendationscope default -p '{"spec":{"interval":"5m"}}'` ## Definition ### ### Metadata | Field | Description | Accepted Values | Schema | Default | | ----- | -------------------------------------------- | --------------- | ------ | ------- | | name | The name of the policy recommendation scope. | `default` | string | | ### Spec | Field | Description | Accepted Values | Schema | Default | | --------------------- | ------------------------------------------------------------------------------------------------ | --------------- | ------ | ------- | | `interval` | The frequency to create and refine policy recommendations. | | | 2m30s | | `initialLookback` | Start time to look at flow logs when first creating a policy recommendation. | | | 24h | | `stabilizationPeriod` | Time that a recommended policy should remain unchanged so it is stable and ready to be enforced. | | | 10m | #### NamespaceSpec | Field | Description | Accepted Values | Schema | Default | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `recStatus` | Defines the namespace policy recommendation engine status. | Enabled/Disabled | | Disabled | | `selector` | Selects the namespaces for generating recommendations. Accepts any [label selector](#selectors) expression. | | | `!(projectcalico.org/name starts with ''tigera-'') && !(projectcalico.org/name starts with ''calico-'') && !(projectcalico.org/name starts with ''kube-'')` | | `intraNamespacePassThroughTraffic` | When true, sets all intra-namespace traffic to Pass | true/false | | false | | `tierName` | Tier where the generated staged network policies are created. The tier must already exist. | | string | `namespace-isolation` | #### HostEndpointSpec | Field | Description | Accepted Values | Schema | Default | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------ | ------------------------ | | `recommendationStatus` | Defines the host policy recommendation engine status. | Enabled/Disabled | | Disabled | | `selector` | Selects which HostEndpoints the engine generates recommendations for. If omitted, every HostEndpoint is eligible. Accepts any [label selector](#selectors) expression. | | string | (all HostEndpoints) | | `tierName` | Tier where the generated staged global network policies are created. The tier must already exist. | | string | `hostendpoint-isolation` | ## Annotations on generated recommendations The engine annotates each staged network policy and staged global network policy it generates so you can inspect its progress and source without re-reading the spec. Annotations live under the `policyrecommendation.tigera.io/` prefix. | Annotation | Description | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `policyrecommendation.tigera.io/status` | Engine's readiness signal for this recommendation. See [Recommendation status lifecycle](#recommendation-status-lifecycle) below. | | `policyrecommendation.tigera.io/lastUpdated` | RFC 3339 timestamp of the engine's last modification to the generated staged policy's spec (the recommendation itself, not the PolicyRecommendationScope spec). Drives the `Learning → Stabilizing → Stable` transitions. | | `policyrecommendation.tigera.io/scope` | Scope the recommendation was generated for. One of `namespace` (namespace recommendations) or `hostEndpoint` (host recommendations). Individual rules can also carry per-rule `scope` annotations such as `Domains`, `Private`, `Public`, `Service`, `NetworkSet`. | | `policyrecommendation.tigera.io/name` | Name of the source object (namespace for namespace recommendations, HostEndpoint for host recommendations). | | `policyrecommendation.tigera.io/namespace` | For namespace recommendations: the namespace the recommendation applies to. | ### Recommendation status lifecycle The `policyrecommendation.tigera.io/status` annotation moves through the following values as the engine refines a recommendation. The transitions are driven by `lastUpdated`: the longer the generated staged policy's spec has remained unchanged, the further the recommendation has progressed. | Status | When it is set | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Learning` | Initial value for every new recommendation. Reset to this whenever the engine modifies the spec. | | `Stabilizing` | Set when the spec has been unchanged for more than `2 × interval` but no more than `stabilizationPeriod`. Rules look settled but are still being watched. | | `Stable` | Set when the spec has been unchanged for more than `stabilizationPeriod`. Treat as ready to accept and enforce. | `interval` and `stabilizationPeriod` are the top-level fields on this resource. Adjusting them directly controls how quickly a recommendation can reach `Stable`. See [Spec](#spec). The engine resets the status to `Learning` and bumps `lastUpdated` any time it adds, removes, or changes a rule, so a recommendation that absorbs new traffic late in its life cycle returns to `Learning` until it next stabilizes. ## Selectors The `selector` fields on `namespaceSpec` and `hostEndpointSpec` accept the same label-selector expression language used elsewhere in Calico network policy. A label selector is an expression which either matches or does not match a resource based on its labels. Calico Enterprise label selectors support a number of operators, which can be combined into larger expressions using the boolean operators and parentheses. | Expression | Meaning | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Logical operators** | | | `( )` | Matches if and only if `` matches. (Parentheses are used for grouping expressions.) | | `! ` | Matches if and only if `` does not match. **Tip:** `!` is a special character at the start of a YAML string, if you need to use `!` at the start of a YAML string, enclose the string in quotes. | | ` && ` | "And": matches if and only if both ``, and, `` matches | | ` \|\| ` | "Or": matches if and only if either ``, or, `` matches. | | **Match operators** | | | `all()` | Match all in-scope resources. To match *no* resources, combine this operator with `!` to form `!all()`. | | `global()` | Match all non-namespaced resources. Useful in a `namespaceSelector` to select global resources such as global network sets. | | `k == 'v'` | Matches resources with the label 'k' and value 'v'. | | `k != 'v'` | Matches resources without label 'k' or with label 'k' and value *not* equal to `v` | | `has(k)` | Matches resources with label 'k', independent of value. To match pods that do not have label `k`, combine this operator with `!` to form `!has(k)` | | `k in { 'v1', 'v2' }` | Matches resources with label 'k' and value in the given set | | `k not in { 'v1', 'v2' }` | Matches resources without label 'k' or with label 'k' and value *not* in the given set | | `k contains 's'` | Matches resources with label 'k' and value containing the substring 's' | | `k starts with 's'` | Matches resources with label 'k' and value starting with the substring 's' | | `k ends with 's'` | Matches resources with label 'k' and value ending with the substring 's' | Operators have the following precedence: - **Highest**: all the match operators - Parentheses `( ... )` - Negation with `!` - Conjunction with `&&` - **Lowest**: Disjunction with `||` For example, the expression ```text ! has(my-label) || my-label starts with 'prod' && role in {'frontend','business'} ``` Would be "bracketed" like this: ```text ((!(has(my-label)) || ((my-label starts with 'prod') && (role in {'frontend','business'})) ``` It would match: - Any resource that did not have label "my-label". - Any resource that both: - Has a value for `my-label` that starts with "prod", and, - Has a role label with value either "frontend", or "business".