Network Policy Resource (NetworkPolicy)

A network policy resource (NetworkPolicy) represents an ordered set of rules which are applied to a collection of endpoints that match a label selector.

NetworkPolicy is a namespaced resource. NetworkPolicy in a specific namespace only applies to workload endpoint resources in that namespace. Two resources are in the same namespace if the namespace value is set the same on both. See global network policy resource for non-namespaced network policy.

NetworkPolicy resources can be used to define network connectivity rules between groups of Calico endpoints and host endpoints, and take precedence over profile resources if any are defined.

For calicoctl commands that specify a resource type on the CLI, the following aliases are supported (all case insensitive): networkpolicy, networkpolicies, policy, np, policies, pol, pols.

Sample YAML

This sample policy allows TCP traffic from frontend endpoints to port 6379 on database endpoints.

apiVersion: projectcalico.org/v3
kind: NetworkPolicy
metadata:
  name: allow-tcp-6379
  namespace: production
spec:
  selector: role == 'database'
  types:
  - Ingress
  - Egress
  ingress:
  - action: Allow
    protocol: TCP
    source:
      selector: role == 'frontend'
    destination:
      ports:
      - 6379
  egress:
  - action: Allow

Definition

Metadata

Field Description Accepted Values Schema Default
name The name of the network policy. Required. Alphanumeric string with optional ., _, or -. string  
namespace Namespace provides an additional qualification to a resource name.   map “default”

Spec

Field Description Accepted Values Schema Default
order Controls the order of precedence. Calico applies the policy with the lowest value first.   float  
selector Selects the endpoints to which this policy applies.   selector all()
types Applies the policy based on the direction of the traffic. To apply the policy to inbound traffic, set to Ingress. To apply the policy to outbound traffic, set to Egress. To apply the policy to both, set to Ingress, Egress. Ingress, Egress List of strings Depends on presence of ingress/egress rules*
ingress Ordered list of ingress rules applied by policy.   List of Rule  
egress Ordered list of egress rules applied by this policy.   List of Rule  

* If types has no value, Calico defaults as follows.

Ingress Rules Present Egress Rules Present Types value
No No Ingress
Yes No Ingress
No Yes Egress
Yes Yes Ingress, Egress

Rule

Field Description Accepted Values Schema Default
action Action to perform when matching this rule. Allow, Deny, Log, Pass string  
protocol Positive protocol match. TCP, UDP, ICMP, ICMPv6, SCTP, UDPLite, 1-255 string | integer  
notProtocol Negative protocol match. TCP, UDP, ICMP, ICMPv6, SCTP, UDPLite, 1-255 string | integer  
icmp ICMP match criteria.   ICMP  
notICMP Negative match on ICMP.   ICMP  
ipVersion Positive IP version match. 4, 6 integer  
source Source match parameters.   EntityRule  
destination Destination match parameters.   EntityRule  
http Match HTTP request parameters. Application layer policy must be enabled to use this field.   HTTPMatch  

An action of Pass will skip over the remaining policies and jump to the first profile assigned to the endpoint, applying the policy configured in the profile; if there are no Profiles configured for the endpoint the default applied action is Deny.

ICMP

Field Description Accepted Values Schema Default
type Match on ICMP type. Can be integer 0-254 integer  
code Match on ICMP code. Can be integer 0-255 integer  

EntityRule

Field Description Accepted Values Schema Default
nets Match packets with IP in any of the listed CIDRs. List of valid IPv4 or IPv6 CIDRs list of cidrs  
notNets Negative match on CIDRs. Match packets with IP not in any of the listed CIDRs. List of valid IPv4 or IPv6 CIDRs list of cidrs  
selector Positive match on selected endpoints. If a namespaceSelector is also defined, the set of endpoints this applies to is limited to the endpoints in the selected namespaces. Valid selector selector  
notSelector Negative match on selected endpoints. If a namespaceSelector is also defined, the set of endpoints this applies to is limited to the endpoints in the selected namespaces. Valid selector selector  
namespaceSelector Positive match on selected namespaces. If specified, only workload endpoints in the selected Kubernetes namespaces are matched. Matches namespaces based on the labels that have been applied to the namespaces. Defines the context that selectors will apply to, if not defined then selectors apply to the NetworkPolicy’s namespace. Valid selector selector  
ports Positive match on the specified ports   list of ports  
notPorts Negative match on the specified ports   list of ports  
serviceAccounts Match endpoints running under service accounts. If a namespaceSelector is also defined, the set of service accounts this applies to is limited to the service accounts in the selected namespaces. Application layer policy must be enabled to use this field.   ServiceAccountMatch  

Selector

A label selector is an expression which either matches or does not match a resource based on its labels.

Calico label selectors support a number of syntactic primitives. Each of the following primitive expressions can be combined using the logical operator &&.

Syntax Meaning
all() Match all resources.
k == ‘v’ Matches any resource with the label ‘k’ and value ‘v’.
k != ‘v’ Matches any resource with the label ‘k’ and value that is not ‘v’.
has(k) Matches any resource with label ‘k’, independent of value.
!has(k) Matches any resource that does not have label ‘k’
k in { ‘v1’, ‘v2’ } Matches any resource with label ‘k’ and value in the given set
k not in { ‘v1’, ‘v2’ } Matches any resource without label ‘k’ or any with label ‘k’ and value not in the given set

Ports

Calico supports the following syntaxes for expressing ports.

Syntax Example Description
int 80 The exact (numeric) port specified
start:end 6040:6050 All (numeric) ports within the range start <= x <= end
string named-port A named port, as defined in the ports list of one or more endpoints

An individual numeric port may be specified as a YAML/JSON integer. A port range or named port must be represented as as a string. For example, this would be a valid list of ports:

ports: [8080, "1234:5678", "named-port"]
Named ports

Using a named port in an EntityRule, instead of a numeric port, gives a layer of indirection, allowing for the named port to map to different numeric values for each endpoint.

For example, suppose you have multiple HTTP servers running as workloads; some exposing their HTTP port on port 80 and others on port 8080. In each workload, you could create a named port called http-port that maps to the correct local port. Then, in a rule, you could refer to the name http-port instead of writing a different rule for each type of server.

NOTE: Since each named port may refer to many endpoints (and Calico has to expand a named port into a set of endpoint/port combinations), using a named port is considerably more expensive in terms of CPU than using a simple numeric port. We recommend that they are used sparingly, only where the extra indirection is required.

ServiceAccountMatch

A ServiceAccountMatch matches service accounts in an EntityRule.

Field Description Schema
names Match service accounts by name list of strings
selector Match service accounts by label selector

Application layer policy

Application layer policy is an optional feature of Calico and must be enabled in order to use the following match criteria.

NOTE: Application layer policy match criteria are supported with the following restrictions.

  • Only ingress policy is supported. Egress policy must not contain any application layer policy match clauses.
  • Rules must have the action Allow if they contain application layer policy match clauses.

HTTPMatch

An HTTPMatch matches attributes of an HTTP request. The presence of an HTTPMatch clause on a Rule will cause that rule to only match HTTP traffic. Other application layer protocols will not match the rule.

Example:

http:
  methods: ["GET", "PUT"]
  paths:
    - exact: "/projects/calico"
    - prefix: "/users"
Field Description Schema
methods Match HTTP methods. Case sensitive. Standard HTTP method descriptions. list of strings
paths Match HTTP paths. Case sensitive. list of HTTPPathMatch

HTTPPathMatch

Syntax Example Description
exact exact: "/foo/bar" Matches the exact path as written, not including the query string or fragments.
prefix prefix: "/keys" Matches any path that begins with the given prefix.

Supported operations

Datastore type Create/Delete Update Get/List Notes
etcdv3 Yes Yes Yes  
Kubernetes API datastore No No Yes NetworkPolicy is determined from Kubernetes NetworkPolicy resources.