Global network policy
A global network policy resource (GlobalNetworkPolicy
) represents an ordered set of rules which are applied to a collection of endpoints that match a label selector.
GlobalNetworkPolicy
is not a namespaced resource. GlobalNetworkPolicy
applies to workload endpoint resources in all namespaces, and to host endpoint resources. Select a namespace in a GlobalNetworkPolicy
in the standard selector by using projectcalico.org/namespace
as the label name and a namespace
name as the value to compare against, e.g., projectcalico.org/namespace == "default"
. See network policy resource for namespaced network policy.
GlobalNetworkPolicy
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.
Sample YAML
This sample policy allows TCP traffic from frontend
endpoints to port 6379 on database
endpoints.
apiVersion: projectcalico.org/v3
kind: GlobalNetworkPolicy
metadata:
name: allow-tcp-6379
spec:
selector: role == 'database'
types:
- Ingress
- Egress
ingress:
- action: Allow
metadata:
annotations:
from: frontend
to: database
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 |
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() | |
serviceAccountSelector | Selects the service account(s) to which this policy applies. Select all service accounts in the cluster with a specific name using the projectcalico.org/name label. | selector | all() | |
namespaceSelector | Selects the namespace(s) to which this policy applies. Select a specific namespace by name using the projectcalico.org/name label. | 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 | ||
doNotTrack | Indicates to apply the rules in this policy before any data plane connection tracking, and that packets allowed by these rules should not be tracked. | true, false | boolean | false |
preDNAT | Indicates to apply the rules in this policy before any DNAT. | true, false | boolean | false |
applyOnForward* | Indicates to apply the rules in this policy on forwarded traffic as well as to locally terminated traffic. | true, false | boolean | false |
* If types
has no value, Calico defaults as follows.
Ingress Rules Present Egress Rules Present Types
valueNo No Ingress
Yes No Ingress
No Yes Egress
Yes Yes Ingress, Egress
** The doNotTrack
and preDNAT
and applyOnForward
fields are meaningful only when applying policy to a host endpoint.
Only one of doNotTrack
and preDNAT
may be set to true
(in a given policy). If they are both false
, or when applying the policy to a workload endpoint, the policy is enforced after connection tracking and any DNAT.
applyOnForward
must be set to true
if either doNotTrack
or preDNAT
is true
because for a given policy, any untracked rules or rules before DNAT will in practice apply to forwarded traffic.
See Policy for hosts for how doNotTrack
and preDNAT
and applyOnForward
can be useful for host endpoints.
Rule
A single rule matches a set of packets and applies some action to them. When multiple rules are specified, they are executed in order.
Field | Description | Accepted Values | Schema | Default |
---|---|---|---|---|
metadata | Per-rule metadata. | RuleMetadata | ||
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 |
After a Log
action, processing continues with the next rule; Allow
and Deny
are immediate and final and no further rules are processed.
An action
of Pass
in a NetworkPolicy
or GlobalNetworkPolicy
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
.
RuleMetadata
Metadata associated with a specific rule (rather than the policy as a whole). The contents of the metadata does not affect how a rule is interpreted or enforced; it is simply a way to store additional information for use by operators or applications that interact with Calico.
Field | Description | Schema | Default |
---|---|---|---|
annotations | Arbitrary non-identifying metadata. | map of string to string |
Example:
metadata:
annotations:
app: database
owner: devops
Annotations follow the same rules as Kubernetes for valid syntax and character set.
On Linux with the iptables dataplane, rule annotations are rendered as comments in the form -m comment --comment "<key>=<value>"
on the iptables rule(s) that correspond to the Calico rule.
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
Entity rules specify the attributes of the source or destination of a packet that must match for the rule as a whole to match. Packets are matched on their IPs and ports. If the rule contains multiple match criteria (for example, an IP and a port) then all match criteria must match for the rule as a whole to match.
Selectors offer a powerful way to select the source or destination to match based on labels. Selectors can match workload endpoints, host endpoint and (namespaced or global) network sets.
Field | Description | Accepted Values | Schema | Default |
---|---|---|---|---|
nets | Match packets with IP in any of the listed CIDRs. | List of valid IPv4 CIDRs or list of valid IPv6 CIDRs (IPv4 and IPv6 CIDRs shouldn’t be mixed in one rule) | list of cidrs | |
notNets | Negative match on CIDRs. Match packets with IP not in any of the listed CIDRs. | List of valid IPv4 CIDRs or list of valid IPv6 CIDRs (IPv4 and IPv6 CIDRs shouldn’t be mixed in one rule) | 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 scope that selectors will apply to, if not defined then selectors apply to the NetworkPolicy’s namespace. Match a specific namespace by name using the projectcalico.org/name label. Select the non-namespaced resources like GlobalNetworkSet(s), host endpoints to which this policy applies by using global() selector. | 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. | ServiceAccountMatch | ||
services | Match the specified service(s). If specified on egress rule destinations, no other selection criteria can be set. If specified on ingress rule sources, only positive or negative matches on ports can be specified. | ServiceMatch |
When using selectors in network policy, remember that selectors only match (known) resources, but rules match packets. A rule with a selector all()
won’t match “all packets”, it will match “packets from all in-scope endpoints and network sets”. To match all packets, do not include a selector in the rule at all.
note
notSelector
is somewhat subtle because the not
in notSelector
negates the packet match rather than the selector:
selector: !has(foo)
matches packets from/to endpoints and network sets that do not have the label “foo”.notSelector: has(foo)
matches packets from/to anywhere (including outside the cluster), except traffic from/to endpoints and network sets that have the label “foo”.
Selectors
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 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”.
- Has a value for
Understanding scopes and the all()
and global()
operators: selectors have a scope of resources that they are matched against, which depends on the context in which they are used. For example:
The
nodeSelector
in anIPPool
selects overNode
resources.The top-level selector in a
NetworkPolicy
selects over the workloads in the same namespace as theNetworkPolicy
.The top-level selector in a
GlobalNetworkPolicy
doesn’t have the same restriction, it selects over all endpoints including namespacedWorkloadEndpoint
s and non-namespacedHostEndpoint
s.The
namespaceSelector
in aNetworkPolicy
(orGlobalNetworkPolicy
) rule selects over the labels on namespaces rather than workloads.The
namespaceSelector
determines the scope of the accompanyingselector
in the entity rule. If nonamespaceSelector
is present then the rule’sselector
matches the default scope for that type of policy. (This is the same namespace forNetworkPolicy
and all endpoints/network sets forGlobalNetworkPolicy
)The
global()
operator can be used (only) in anamespaceSelector
to change the scope of the mainselector
to include non-namespaced resources such as GlobalNetworkSet. This allows namespacedNetworkPolicy
resources to refer to global non-namespaced resources, which would otherwise be impossible.
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 |
ServiceMatch
A ServiceMatch matches a service in an EntityRule.
Field | Description | Schema |
---|---|---|
name | The service’s name. | string |
namespace | The service’s namespace. | string |
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 | Yes | Yes | Yes |