Policy recommendation scope

The policy recommendation scope configures Calico Enterprise's policy-recommendation engine. It controls both namespace policy recommendations (configured under namespaceSpec) and host policy recommendations (configured under hostEndpointSpec). Namespace and host recommendations are enabled and scoped independently.

To apply changes to this resource, use the following format:

$ kubectl patch policyrecommendationscope default -p '{"spec":{"<parameter>":"<value>"}}'

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 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 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 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.

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
( <expression> )	Matches if and only if <expression> matches. (Parentheses are used for grouping expressions.)
! <expression>	Matches if and only if <expression> 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.
<expression 1> && <expression 2>	"And": matches if and only if both <expression 1>, and, <expression 2> matches
<expression 1> || <expression 2>	"Or": matches if and only if either <expression 1>, or, <expression 2> 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

! has(my-label) || my-label starts with 'prod' && role in {'frontend','business'}

Would be "bracketed" like this:

((!(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".