Configuring egress IPs for a project

As a cluster administrator, you can configure the OpenShift SDN Container Network Interface (CNI) cluster network provider to assign one or more egress IP addresses to a project.

Egress IP address architectural design and implementation

The OKD egress IP address functionality allows you to ensure that the traffic from one or more pods in one or more namespaces has a consistent source IP address for services outside the cluster network.

For example, you might have a pod that periodically queries a database that is hosted on a server outside of your cluster. To enforce access requirements for the server, a packet filtering device is configured to allow traffic only from specific IP addresses. To ensure that you can reliably allow access to the server from only that specific pod, you can configure a specific egress IP address for the pod that makes the requests to the server.

An egress IP address assigned to a namespace is different from an egress router, which is used to send traffic to specific destinations.

In some cluster configurations, application pods and ingress router pods run on the same node. If you configure an egress IP address for an application project in this scenario, the IP address is not used when you send a request to a route from the application project.

An egress IP address is implemented as an additional IP address on the primary network interface of a node and must be in the same subnet as the primary IP address of the node. The additional IP address must not be assigned to any other node in the cluster.

Platform support

Support for the egress IP address functionality on various platforms is summarized in the following table:

Public cloud platform considerations

For clusters provisioned on public cloud infrastructure, there is a constraint on the absolute number of assignable IP addresses per node. The maximum number of assignable IP addresses per node, or the IP capacity, can be described in the following formula:

IP capacity = public cloud default capacity - sum(current IP assignments)

While the Egress IPs capability manages the IP address capacity per node, it is important to plan for this constraint in your deployments. For example, for a cluster installed on bare-metal infrastructure with 8 nodes you can configure 150 egress IP addresses. However, if a public cloud provider limits IP address capacity to 10 IP addresses per node, the total number of assignable IP addresses is only 80. To achieve the same IP address capacity in this example cloud provider, you would need to allocate 7 additional nodes.

To confirm the IP capacity and subnets for any node in your public cloud environment, you can enter the oc get node <node_name> -o yaml command. The cloud.network.openshift.io/egress-ipconfig annotation includes capacity and subnet information for the node.

The annotation value is an array with a single object with fields that provide the following information for the primary network interface:

• interface: Specifies the interface ID on AWS and Azure and the interface name on GCP.

• ifaddr: Specifies the subnet mask for one or both IP address families.

• capacity: Specifies the IP address capacity for the node. On AWS, the IP address capacity is provided per IP address family. On Azure and GCP, the IP address capacity includes both IPv4 and IPv6 addresses.

The following examples illustrate the annotation from nodes on several public cloud providers. The annotations are indented for readability.

Example cloud.network.openshift.io/egress-ipconfig annotation on AWS

cloud.network.openshift.io/egress-ipconfig: [
  {
    "interface":"eni-078d267045138e436",
    "ifaddr":{"ipv4":"10.0.128.0/18"},
    "capacity":{"ipv4":14,"ipv6":15}
  }
]

Example cloud.network.openshift.io/egress-ipconfig annotation on GCP

cloud.network.openshift.io/egress-ipconfig: [
  {
    "interface":"nic0",
    "ifaddr":{"ipv4":"10.0.128.0/18"},
    "capacity":{"ip":14}
  }
]

The following sections describe the IP address capacity for supported public cloud environments for use in your capacity calculation.

Amazon Web Services (AWS) IP address capacity limits

On AWS, constraints on IP address assignments depend on the instance type configured. For more information, see IP addresses per network interface per instance type

Google Cloud Platform (GCP) IP address capacity limits

On GCP, the networking model implements additional node IP addresses through IP address aliasing, rather than IP address assignments. However, IP address capacity maps directly to IP aliasing capacity.

The following capacity limits exist for IP aliasing assignment:

• Per node, the maximum number of IP aliases, both IPv4 and IPv6, is 10.

• Per VPC, the maximum number of IP aliases is unspecified, but OKD scalability testing reveals the maximum to be approximately 15,000.

For more information, see Per instance quotas and Alias IP ranges overview.

Microsoft Azure IP address capacity limits

On Azure, the following capacity limits exist for IP address assignment:

• Per NIC, the maximum number of assignable IP addresses, for both IPv4 and IPv6, is 256.

• Per virtual network, the maximum number of assigned IP addresses cannot exceed 65,536.

For more information, see Networking limits.

Limitations

The following limitations apply when using egress IP addresses with the OpenShift SDN cluster network provider:

• You cannot use manually assigned and automatically assigned egress IP addresses on the same nodes.

• If you manually assign egress IP addresses from an IP address range, you must not make that range available for automatic IP assignment.

• You cannot share egress IP addresses across multiple namespaces using the OpenShift SDN egress IP address implementation.

If you need to share IP addresses across namespaces, the OVN-Kubernetes cluster network provider egress IP address implementation allows you to span IP addresses across multiple namespaces.

IP address assignment approaches

You can assign egress IP addresses to namespaces by setting the egressIPs parameter of the NetNamespace object. After an egress IP address is associated with a project, OpenShift SDN allows you to assign egress IP addresses to hosts in two ways:

• In the automatically assigned approach, an egress IP address range is assigned to a node.

• In the manually assigned approach, a list of one or more egress IP address is assigned to a node.

Namespaces that request an egress IP address are matched with nodes that can host those egress IP addresses, and then the egress IP addresses are assigned to those nodes. If the egressIPs parameter is set on a NetNamespace object, but no node hosts that egress IP address, then egress traffic from the namespace will be dropped.

High availability of nodes is automatic. If a node that hosts an egress IP address is unreachable and there are nodes that are able to host that egress IP address, then the egress IP address will move to a new node. When the unreachable node comes back online, the egress IP address automatically moves to balance egress IP addresses across nodes.

Considerations when using automatically assigned egress IP addresses

When using the automatic assignment approach for egress IP addresses the following considerations apply:

• You set the egressCIDRs parameter of each node’s HostSubnet resource to indicate the range of egress IP addresses that can be hosted by a node. OKD sets the egressIPs parameter of the HostSubnet resource based on the IP address range you specify.

If the node hosting the namespace’s egress IP address is unreachable, OKD will reassign the egress IP address to another node with a compatible egress IP address range. The automatic assignment approach works best for clusters installed in environments with flexibility in associating additional IP addresses with nodes.

Considerations when using manually assigned egress IP addresses

This approach allows you to control which nodes can host an egress IP address.

When using the manual assignment approach for egress IP addresses the following considerations apply:

• You set the egressIPs parameter of each node’s HostSubnet resource to indicate the IP addresses that can be hosted by a node.

• Multiple egress IP addresses per namespace are supported.

If a namespace has multiple egress IP addresses and those addresses are hosted on multiple nodes, the following additional considerations apply:

• If a pod is on a node that is hosting an egress IP address, that pod always uses the egress IP address on the node.

• If a pod is not on a node that is hosting an egress IP address, that pod uses an egress IP address at random.

Configuring automatically assigned egress IP addresses for a namespace

In OKD you can enable automatic assignment of an egress IP address for a specific namespace across one or more nodes.

Prerequisites

• You have access to the cluster as a user with the cluster-admin role.

• You have installed the OpenShift CLI (oc).

Procedure

1. Update the NetNamespace object with the egress IP address using the following JSON:

    $ oc patch netnamespace <project_name> --type=merge -p \
     '{
       "egressIPs": [
         "<ip_address>"
       ]
     }'

   where:

   <project_name>

   Specifies the name of the project.

   <ip_address>

   Specifies one or more egress IP addresses for the egressIPs array.

   For example, to assign project1 to an IP address of 192.168.1.100 and project2 to an IP address of 192.168.1.101:

   $ oc patch netnamespace project1 --type=merge -p \
     '{"egressIPs": ["192.168.1.100"]}'
   $ oc patch netnamespace project2 --type=merge -p \
     '{"egressIPs": ["192.168.1.101"]}'

   Because OpenShift SDN manages the NetNamespace object, you can make changes only by modifying the existing NetNamespace object. Do not create a new NetNamespace object.

2. Indicate which nodes can host egress IP addresses by setting the egressCIDRs parameter for each host using the following JSON:

   $ oc patch hostsubnet <node_name> --type=merge -p \
     '{
       "egressCIDRs": [
         "<ip_address_range>", "<ip_address_range>"
       ]
     }'

   where:

   <node_name>

   Specifies a node name.

   <ip_address_range>

   Specifies an IP address range in CIDR format. You can specify more than one address range for the egressCIDRs array.

   For example, to set node1 and node2 to host egress IP addresses in the range 192.168.1.0 to 192.168.1.255:

   $ oc patch hostsubnet node1 --type=merge -p \
     '{"egressCIDRs": ["192.168.1.0/24"]}'
   $ oc patch hostsubnet node2 --type=merge -p \
     '{"egressCIDRs": ["192.168.1.0/24"]}'

   OKD automatically assigns specific egress IP addresses to available nodes in a balanced way. In this case, it assigns the egress IP address 192.168.1.100 to node1 and the egress IP address 192.168.1.101 to node2 or vice versa.

Configuring manually assigned egress IP addresses for a namespace

In OKD you can associate one or more egress IP addresses with a namespace.

Prerequisites

• You have access to the cluster as a user with the cluster-admin role.

• You have installed the OpenShift CLI (oc).

Procedure

1. Update the NetNamespace object by specifying the following JSON object with the desired IP addresses:

    $ oc patch netnamespace <project_name> --type=merge -p \
     '{
       "egressIPs": [
         "<ip_address>"
       ]
     }'

   where:

   <project_name>

   Specifies the name of the project.

   <ip_address>

   Specifies one or more egress IP addresses for the egressIPs array.

   For example, to assign the project1 project to the IP addresses 192.168.1.100 and 192.168.1.101:

   $ oc patch netnamespace project1 --type=merge \
     -p '{"egressIPs": ["192.168.1.100","192.168.1.101"]}'

   To provide high availability, set the egressIPs value to two or more IP addresses on different nodes. If multiple egress IP addresses are set, then pods use all egress IP addresses roughly equally.

   Because OpenShift SDN manages the NetNamespace object, you can make changes only by modifying the existing NetNamespace object. Do not create a new NetNamespace object.

2. Manually assign the egress IP address to the node hosts.

   If your cluster is installed on public cloud infrastructure, you must confirm that the node has available IP address capacity.

   Set the egressIPs parameter on the HostSubnet object on the node host. Using the following JSON, include as many IP addresses as you want to assign to that node host:

   $ oc patch hostsubnet <node_name> --type=merge -p \
     '{
       "egressIPs": [
         "<ip_address>",
         "<ip_address>"
         ]
     }'

   where:

   <node_name>

   Specifies a node name.

   <ip_address>

   Specifies an IP address. You can specify more than one IP address for the egressIPs array.

   For example, to specify that node1 should have the egress IPs 192.168.1.100, 192.168.1.101, and 192.168.1.102:

   $ oc patch hostsubnet node1 --type=merge -p \
     '{"egressIPs": ["192.168.1.100", "192.168.1.101", "192.168.1.102"]}'

   In the previous example, all egress traffic for project1 will be routed to the node hosting the specified egress IP, and then connected through Network Address Translation (NAT) to that IP address.

Additional resources

• If you are configuring manual egress IP address assignment, see Platform considerations for information about IP capacity planning.