Policy Enforcement Modes

The configuration of the Cilium agent and the Cilium Network Policy determines whether an endpoint accepts traffic from a source or not. The agent can be put into the following three policy enforcement modes:

default

This is the default behavior for policy enforcement when Cilium is launched without any specified value for the policy enforcement configuration. The following rules apply:

  • If any rule selects an Endpoint and the rule has an ingress section, the endpoint goes into default deny at ingress.
  • If any rule selects an Endpoint and the rule has an egress section, the endpoint goes into default deny at egress.

This means that endpoints will start without any restrictions and as soon as a rule restricts their ability to receive traffic on ingress or to transmit traffic on egress, then the endpoint goes into whitelisting mode and all traffic must be explicitly allowed.

always

With always mode, policy enforcement is enabled on all endpoints even if no rules select specific endpoints.

never

With never mode, policy enforcement is disabled on all endpoints, even if rules do select specific endpoints. In other words, all traffic is allowed from any source (on ingress) or destination (on egress).

To configure the policy enforcement mode at runtime for all endpoints managed by a Cilium agent, use:

  1. $ cilium config PolicyEnforcement={default,always,never}

If you want to configure the policy enforcement mode at start-time for a particular agent, provide the following flag when launching the Cilium daemon:

  1. $ cilium-agent --enable-policy={default,always,never} [...]

Similarly, you can enable the policy enforcement mode across a Kubernetes cluster by including the parameter above in the Cilium DaemonSet.

  1. - name: CILIUM_ENABLE_POLICY
  2.   value: always

Rule Basics

All policy rules are based upon a whitelist model, that is, each rule in the policy allows traffic that matches the rule. If two rules exist, and one would match a broader set of traffic, then all traffic matching the broader rule will be allowed. If there is an intersection between two or more rules, then traffic matching the union of those rules will be allowed. Finally, if traffic does not match any of the rules, it will be dropped pursuant to the Policy Enforcement Modes.

Policy rules share a common base type which specifies which endpoints the rule applies to and common metadata to identify the rule. Each rule is split into an ingress section and an egress section. The ingress section contains the rules which must be applied to traffic entering the endpoint, and the egress section contains rules applied to traffic coming from the endpoint matching the endpoint selector. Either ingress, egress, or both can be provided. If both ingress and egress are omitted, the rule has no effect.

  1. type Rule struct {
  2.         // EndpointSelector selects all endpoints which should be subject to
  3.         // this rule. EndpointSelector and NodeSelector cannot be both empty and
  4.         // are mutually exclusive.
  5.         //
  6.         // +optional
  7.         EndpointSelector EndpointSelector `json:"endpointSelector,omitempty"`
  9.         // NodeSelector selects all nodes which should be subject to this rule.
  10.         // EndpointSelector and NodeSelector cannot be both empty and are mutually
  11.         // exclusive. Can only be used in CiliumClusterwideNetworkPolicies.
  12.         //
  13.         // +optional
  14.         NodeSelector EndpointSelector `json:"nodeSelector,omitempty"`
  16.         // Ingress is a list of IngressRule which are enforced at ingress.
  17.         // If omitted or empty, this rule does not apply at ingress.
  18.         //
  19.         // +optional
  20.         Ingress []IngressRule `json:"ingress,omitempty"`
  22.         // Egress is a list of EgressRule which are enforced at egress.
  23.         // If omitted or empty, this rule does not apply at egress.
  24.         //
  25.         // +optional
  26.         Egress []EgressRule `json:"egress,omitempty"`
  28.         // Labels is a list of optional strings which can be used to
  29.         // re-identify the rule or to store metadata. It is possible to lookup
  30.         // or delete strings based on labels. Labels are not required to be
  31.         // unique, multiple rules can have overlapping or identical labels.
  32.         //
  33.         // +optional
  34.         Labels labels.LabelArray `json:"labels,omitempty"`
  36.         // Description is a free form string, it can be used by the creator of
  37.         // the rule to store human readable explanation of the purpose of this
  38.         // rule. Rules cannot be identified by comment.
  39.         //
  40.         // +optional
  41.         Description string `json:"description,omitempty"`
  42. }

endpointSelector / nodeSelector

Selects the endpoints or nodes which the policy rules apply to. The policy rules will be applied to all endpoints which match the labels specified in the selector. See the Endpoint Selector and Node Selector sections for additional details.

ingress

List of rules which must apply at ingress of the endpoint, i.e. to all network packets which are entering the endpoint.

egress

List of rules which must apply at egress of the endpoint, i.e. to all network packets which are leaving the endpoint.

labels

Labels are used to identify the rule. Rules can be listed and deleted by labels. Policy rules which are imported via kubernetes automatically get the label io.cilium.k8s.policy.name=NAME assigned where NAME corresponds to the name specified in the NetworkPolicy or CiliumNetworkPolicy resource.

description

Description is a string which is not interpreted by Cilium. It can be used to describe the intent and scope of the rule in a human readable form.

Endpoint Selector

The Endpoint Selector is based on the Kubernetes LabelSelector. It is called Endpoint Selector because it only applies to labels associated with an Endpoint.

Node Selector

The Node Selector is also based on the Endpoint Selector, although rather than matching on labels associated with an Endpoint, it instead applies to labels associated with a node in the cluster.

Node Selectors can only be used in CiliumClusterwideNetworkPolicy. See Host Policies for details on the scope of node-level policies.