Skip to main content

​
Introduction

An application instance can have several network interfaces: virtual interfaces attached to a virtual network, and direct-attach interfaces that pass a physical adapter through to the guest. The guest operating system sees them as a list of network devices, and many applications bind to a device by its position in that list rather than by name or MAC address. Interface Ordering is a project setting that makes EVE-OS (Edge Virtualization Engine) present an instance’s interfaces to the guest in the order defined for that instance, the same way on every node it deploys to. When the setting is off, EVE-OS uses a default order that can differ from the order in the app definition.

​
Why the order matters

Consider a firewall app with two interfaces, int1 and int2. You deploy it and connect int1 to the management network, which faces the outside world, and int2 to an internal network. The firewall allows traffic from its second device to its first device but not the other way around. The guest sees two devices, A and B, and the firewall’s rules only make sense if int1 is A and int2 is B. If EVE-OS presents them in the other order, the firewall opens the wrong direction. Interface Ordering is how you guarantee the mapping.

​
Prerequisites

  • The nodes run EVE-OS 13.8.0 or greater. On older EVE-OS versions, the default order applies even when the project setting is on.
  • The nodes use the KVM hypervisor (the software layer that runs the application instance on the node). On nodes that use the Xen or KubeVirt hypervisor, EVE-OS ignores the setting and the interface order is undefined.
  • You deploy the instance to edge nodes. The deploy wizard does not offer the App Interfaces step when the deployment target is an Edge Node Cluster.
  • You have the SysManager or SysAdmin role in your enterprise. See Manage Roles.
  • The application instance is a Virtual Machine or Container type. Docker Compose, Module, and other app types do not have an editable interface set.

​
Default Order Without Interface Ordering

When the project does not have Interface Ordering enabled, EVE-OS presents interfaces to the guest in the following order:
  1. Virtual interfaces first, ordered by the lowest access control rule (ACL) ID assigned to each interface. Because Edge Infrastructure Services assigns ACL IDs as it processes the app definition, this usually matches the order of virtual interfaces in the definition, but it is not guaranteed. EVE-OS treats a virtual interface with no ACL rules as ID 0 and places it first.
  2. Direct-attach interfaces after all virtual interfaces, in the order the direct-attach interfaces appear in the app definition.
The net result is that every virtual interface comes before every direct-attach interface, regardless of how you interleaved them in the app definition. If your application expects a direct-attach adapter as its first device, the default order does not deliver that.

​
Enable Interface Ordering on a Project

To turn on Interface Ordering when you create a project, turn on Interface Ordering in the Basic Info step of the project wizard. See Create a Project. To change the setting on an existing project in the console:
  1. Open the project and click Configure project.
  2. Select Administration.
  3. Turn Interface Ordering on or off.
  4. Click Save Administration.
To change the setting with ZCLI, run the following command:
See Manage Projects with ZCLI. The setting applies to every application instance in the project. Changing it does not reorder the interfaces of instances that are already running. Instead, EVE-OS reports an error on each deployed instance stating that a restart is needed. Restart each affected instance to apply the new setting and clear the error.

​
Set the Order for an Instance

With Interface Ordering enabled on the project, and on nodes that support changing an instance’s interface set, the deploy wizard shows an App Interfaces step. The interface numbers on that step are the order the guest sees. Drag a card to a new position, or use Move up and Move down. If you do not set an order, Edge Infrastructure Services assigns one that follows the app definition. See Adjust the App Interfaces. On a deployed instance running EVE-OS 17.3.0 LTS or greater, the Interfaces tab offers Edit App Interfaces. Interfaces that already exist keep their position; interfaces you add are placed after them. Saving restarts the application instead of purging it, so the instance’s volumes are preserved. See Edit the interface set. Edge Infrastructure Services rejects an order where two interfaces claim the same position.

​
Limitations

  • Interfaces of different device types, for example a Wi-Fi adapter and an Ethernet adapter, usually receive different name prefixes in the guest (such as wlan0 and eth0). Interface Ordering cannot change the order across those prefixes.
  • A multifunction PCI (Peripheral Component Interconnect) device is a physical adapter that presents several functions, such as several ports, as one device. All of its functions must stay together in the order. If you place a virtual interface or another adapter between two functions of the same multifunction device, EVE-OS returns an error and does not deploy the application.

​
Guest Operating System Behavior

Interface Ordering controls the order in which EVE-OS presents devices to the guest. How the guest names them is up to the guest operating system.
  • Most current Linux distributions run systemd with predictable interface naming enabled. They name interfaces from their PCI position, so the names follow the order you configured.
  • A guest that uses the legacy naming scheme (net.ifnames=0, giving names like eth0 and eth1) can label interfaces in an order that depends on driver probing and timing rather than PCI position. In that case, the configured order might not match the names inside the guest.
If your application identifies an interface by MAC address instead of position, set a MAC address on the interface when you deploy the instance so that it stays the same across restarts and interface changes. Automatically generated MAC addresses are not guaranteed to survive a change to the interface set.

​
Verify the Order

  1. Open the application instance and select the Interfaces tab. The table lists each interface with its network, MAC address, and IP address in the configured order.
  2. Inside the guest, list the network devices, for example with ip link, and compare the MAC addresses with the table to confirm which device received which interface.

​
Next Steps

Deploy an Application Instance

Set the interface order in the App Interfaces step of the deploy wizard.

Application Instance Details

Edit the interface set of a deployed instance.

Create a Project

Turn on Interface Ordering when you create a project.

EVE-OS application connectivity

The upstream EVE-OS description of interface order.