// Module included in the following assemblies:
//
// * networking/network_security/configuring-egress-firewall-ovn.adoc

:_mod-docs-content-type: CONCEPT
[id="nw-egress-firewall-about_{context}"]
= How an egress firewall works in a project

[role="_abstract"]
As a cluster administrator, you can use an _egress firewall_ to limit the external hosts that some or all pods can access from within the cluster. 

An egress firewall supports the following scenarios:

- A pod can only connect to internal hosts and cannot initiate connections to
the public internet.
- A pod can only connect to the public internet and cannot initiate connections
to internal hosts that are outside the {product-title} cluster.
- A pod cannot reach specified internal subnets or hosts outside the {product-title} cluster.
- A pod can only connect to specific external hosts.

For example, you can allow one project access to a specified IP range but deny the same access to a different project. Or, you can restrict application developers from updating from Python pip mirrors, and force updates to come only from approved sources.

You configure an egress firewall policy by creating an `EgressFirewall` custom resource (CR). The egress firewall matches network traffic that meets any of the following criteria:

- An IP address range in CIDR format
- A DNS name that resolves to an IP address
- A port number
- A protocol that is one of the following protocols: TCP, UDP, and SCTP

[id="limitations-of-an-egress-firewall-ovn-k_{context}"]
== Limitations of an egress firewall

An egress firewall has the following limitations:

* No project can have more than one `EgressFirewall` CR.

* Egress firewall rules do not apply to traffic that goes through routers. Any user with permission to create a `Route` CR object can bypass egress firewall policy rules by creating a route that points to a forbidden destination.

* Egress firewall does not apply to the host network namespace. Pods with host networking enabled are unaffected by egress firewall rules.

* If your egress firewall includes a deny rule for `0.0.0.0/0`, access to your {product-title} API servers is blocked. You must either add allow rules for each IP address or use the `nodeSelector` type allow rule in your egress policy rules to connect to API servers.
+
The following example illustrates the order of the egress firewall rules necessary to ensure API server access:
+
[source,yaml,subs="attributes+"]
----
apiVersion: k8s.ovn.org/v1
kind: EgressFirewall
metadata:
  name: default
  namespace: <namespace>
spec:
  egress:
  - to:
      cidrSelector: <api_server_address_range>
    type: Allow
# ...
  - to:
      cidrSelector: 0.0.0.0/0
    type: Deny
----
+
where:

<namespace>:: Specifies the namespace for the egress firewall.
<api_server_address_range>:: Specifies the IP address range that includes your {product-title} API servers.
<cidrSelector>:: Specifies a value of `0.0.0.0/0` to set a global deny rule that prevents access to the {product-title} API servers.

To find the IP address for your API servers, run `oc get ep kubernetes -n default`.

* A maximum of one `EgressFirewall` object with a maximum of 8,000 rules can be defined per project.

* If you are using the OVN-Kubernetes network plugin with shared gateway mode in Red{nbsp}Hat OpenShift Networking, return ingress replies are affected by egress firewall rules. If the egress firewall rules drop the ingress reply destination IP, the traffic is dropped.

* In general, using Domain Name Server (DNS) names in your egress firewall policy does not affect local DNS resolution through CoreDNS. However, if your egress firewall policy uses domain names and an external DNS server handles DNS resolution for an affected pod, you must include egress firewall rules that permit access to the IP addresses of your DNS server.

Violating any of these restrictions results in a broken egress firewall for the project. Consequently, all external network traffic is dropped, which can cause security risks for your organization.

An `EgressFirewall` resource is created in the `kube-node-lease`, `kube-public`, `kube-system`, `openshift` and `openshift-` projects.

[id="policy-rule-order-ovn-k_{context}"]
== Matching order for egress firewall policy rules

OVN-Kubernetes evaluates egress firewall policy rules in the order they are defined in, from first to last. The first rule that matches an egress connection from a pod applies. Any subsequent rules are ignored for that connection.

[id="domain-name-server-resolution-ovn-k_{context}"]
== How Domain Name Server (DNS) resolution works

If you use DNS names in any of your egress firewall policy rules, proper resolution of the domain names is subject to the following restrictions:

* Domain name updates are polled based on a time-to-live (TTL) duration. By default, the duration is 30 minutes. When the egress firewall controller queries the local name servers for a domain name, if the response includes a TTL and the TTL is less than 30 minutes, the controller sets the duration for that DNS name to the returned value. Each DNS name is queried after the TTL for the DNS record expires.

* The pod must resolve the domain from the same local name servers when necessary. Otherwise the IP addresses for the domain known by the egress firewall controller and the pod can be different. If the IP addresses for a hostname differ, the egress firewall might not be enforced consistently.

* Because the egress firewall controller and pods asynchronously poll the same local name server, the pod might obtain the updated IP address before the egress controller does, which causes a race condition. Due to this current limitation, domain name usage in `EgressFirewall` objects is only recommended for domains with infrequent IP address changes.
