# Network Interface A **Virtual Network Interface (vNIC)** is the network interface that connects a Zenlayer Elastic Compute (ZEC) instance to its VPC. Each vNIC is implemented as an [**SR-IOV**](https://en.wikipedia.org/wiki/Single-root_input/output_virtualization) **Virtual Function (VF)** on the host's physical network adapter — the guest OS owns a hardware-isolated PCIe function and moves packets in and out of it without going through a software path in the hypervisor. The platform manages the control plane (attach/detach, MAC assignment, QoS, mirroring); the data plane runs at hardware speed. Every vNIC is bound, at creation, to exactly one subnet — and through that subnet to exactly one VPC in one region. That placement is fixed for the life of the vNIC. *** ## How a vNIC Maps to the Host ![A vNIC is an SR-IOV Virtual Function on the host adapter](/files/nQCc2wp5W4z6GJn1I3l9) * The host's physical NIC exposes itself as a **Physical Function (PF)** plus a pool of **Virtual Functions (VFs)**. * When you attach a vNIC to an instance, the platform hands one VF to the guest. The VF is the vNIC. * Packets move between the guest driver and the VF's hardware queues directly — the hypervisor does not copy bytes in the fast path. * The PF stays host-private. It enforces per-VF QoS, applies MAC and VLAN policy, and gates traffic mirroring. This backing is why instance size caps vNIC count, queue depth, and per-vNIC IP count (see [vNIC capacity by instance size](#vnic-capacity-by-instance-size)) — each vNIC consumes one VF and one queue set on the host adapter, and the adapter has a finite number of each. *** ## Primary vs Elastic Network Interfaces ZEC distinguishes two kinds of vNIC. They share the same data plane; they differ in lifecycle. ![Primary vNICs stay with their instance; elastic vNICs move within their subnet](/files/KZOVlu4FVDjmJA4p1Ofn) | Property | Primary vNIC | Elastic vNIC | | ------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------- | | Created with the instance? | Yes, automatically. | No — allocated separately and attached on demand. | | Detach from its instance? | No. The primary vNIC exists as long as the instance does. | Yes — can be detached and re-attached to another instance in the same subnet. | | Tied to one subnet? | Yes, the instance's subnet. | Yes, the subnet chosen at vNIC creation. | | Carries the instance's default route? | Yes. | Typically no — a secondary interface for additional connectivity. | ### Primary vNIC When you launch an instance, ZEC creates and attaches a primary vNIC in the instance's subnet. It holds the instance's primary private IPv4 address, its MAC, and — if the subnet is IPv6-enabled and IPv6 is turned on for the instance — its primary IPv6 address. The primary vNIC cannot be detached, and it is released together with the instance. ### Elastic vNIC Beyond the primary, you can allocate additional **elastic vNICs** and attach them to instances as a separate step. An elastic vNIC carries its own private IPs, its own MAC, its own security identity, and any EIPs bound to those private IPs. Detaching and re-attaching moves that whole identity from one instance to another. An elastic vNIC can be detached and re-attached to another instance **in the same subnet**. It cannot move across subnets, VPCs, availability zones, or regions. *** ## Elastic vNIC Use Cases Elastic vNICs earn their keep whenever network identity — private IPs, bound EIPs, a security-group boundary — needs to **outlive a single instance**, or when a single instance needs to **sit on more than one network**. The three patterns below cover most real deployments. ![Three patterns for elastic vNICs: management split, multi-subnet appliance, IP-portable worker](/files/wgx3UzFheTU4MTBXa1SN) ### Scenario 1 — Management / Data-Plane Separation **What you're doing:** An instance carries two classes of traffic — operator/management (SSH, metrics scraping, backups) and high-rate application traffic — and you want them on separate interfaces so security group, QoS, and telemetry can be applied independently. **How to lay it out:** 1. The primary vNIC, in the application subnet, carries application traffic with a permissive security group on the service ports. 2. Attach an elastic vNIC in a dedicated management subnet. Apply a tight security group — bastion CIDR only, for example. 3. Route outbound management traffic through the management vNIC at the OS level. **Why two vNICs and not two IPs on one vNIC:** each vNIC is its own security, QoS, and audit boundary — its own security group, its own link-state telemetry, its own MAC. Separation by private IP alone does not give that. ### Scenario 2 — Multi-Subnet Network Appliance **What you're doing:** A firewall, reverse proxy, NAT helper, or VPN concentrator needs to sit between two subnets and forward packets between them. **How to lay it out:** 1. Attach one elastic vNIC per subnet the appliance should sit on — one in the untrusted/DMZ subnet, one in the trusted/internal subnet. 2. Disable source/destination check on the appliance's vNICs so the instance can forward packets whose source or destination is not its own address. 3. Configure the guest OS to route between the interfaces. **Trade-off:** vNIC count is capped by instance size (see [vNIC capacity by instance size](#vnic-capacity-by-instance-size)). An appliance that needs many legs consumes many vNIC slots. ### Scenario 3 — IP-Portable Workers **What you're doing:** A worker process holds a private IP that external systems reference — allow-lists, sticky sessions, node-locked licensing. The worker may be rescheduled onto a different instance during maintenance, but its private IP must not change. **How to lay it out:** 1. Assign the worker's "identity" IP as the primary IP on an elastic vNIC, not on the instance's primary vNIC. 2. During migration, detach the vNIC from the old instance and attach it to the replacement; the worker reappears with the same private IP. **Why a vNIC is the only way:** a primary vNIC's private IPs cannot move across instances. An elastic vNIC is the only way to keep a *private* IP stable across instance replacements. *** ## Private IP Addresses ![Primary and secondary private IPs on a vNIC; EIPs bind 1:1 to private IPs](/files/laXdsixyTz9MkkaLr6j6) ### Primary private IPv4 Every vNIC has exactly one primary private IPv4 address. It is assigned when the vNIC is created, either auto-selected by the platform from the subnet's CIDR or explicitly requested if the address is free. The primary IPv4 cannot be removed from the vNIC. ### Secondary private IPv4s You can assign additional private IPv4 addresses to a vNIC up to the per-vNIC cap (see [vNIC capacity by instance size](#vnic-capacity-by-instance-size)). Secondary IPs are useful for: * Hosting multiple services, each identified by its own IP, on a single instance. * Binding multiple EIPs to the same vNIC — each EIP pairs 1:1 with a private IP. * Keeping a stable address for a service independent of the instance it happens to be running on today. Assignment can be automatic (specify a count and let the platform pick) or explicit (specify the exact IPs, which must be free within the subnet). ### IPv6 If the subnet has IPv6 enabled, each vNIC can hold one IPv6 address, allocated from the subnet's IPv6 CIDR at vNIC creation or when IPv6 is enabled on the vNIC. By default the platform assigns **the first address of the subnet's /96** as the vNIC's IPv6 address. > **IPv6 cannot be turned off once enabled on a vNIC.** Enabling IPv6 is a one-way operation. To remove IPv6 from a workload, replace the vNIC. Public IPv6, when used, is delivered directly to the guest without NAT. See [Public IPv6](https://github.com/zenlayer/zenlayer-documentation/blob/main/elastic-compute/overview/eip/README.md#ipv6) in the EIP documentation. *** ## Binding an Elastic IP An Elastic IP (EIP) binds to a **specific private IP on a vNIC**, not to the vNIC as a whole. The binding is 1:1 — one EIP maps to one private IP. To expose multiple private IPs on a single vNIC publicly, allocate one EIP per private IP. All EIPs bound to the same vNIC must use the same forwarding mode (Standard or Bypass); do not mix modes on the same vNIC. See [**Standard vs Bypass EIP**](https://github.com/zenlayer/zenlayer-documentation/blob/main/elastic-compute/overview/eip/README.md) for the two forwarding modes and in-guest configuration. *** ## vNIC Capacity by Instance Size The number of vNICs an instance can hold, the number of hardware queues per vNIC, and the number of private IPv4 addresses per vNIC all scale with the instance's vCPU count. The same scaling applies across all instance families ([z2a, z4a, z2i, z3a, z4i](https://github.com/zenlayer/zenlayer-documentation/blob/main/elastic-compute/overview/instance/instance_sku.md)). | vCPU Count | Max vNICs | vNIC Multi-Queue | Private IPv4 per vNIC | | ---------- | --------- | ---------------- | --------------------- | | 1–2 | 2 | 1 | 6–10 | | 4–8 | 2 | 2–4 | 15 | | 16 | 4 | 8 | 30 | | 32 | 8 | 16 | 30 | | 64 | 16 | 32 | 30 | * **Max vNICs** — total vNICs attached to the instance, including the primary. An elastic vNIC counts toward this cap only while it is attached; detaching it frees a slot. * **vNIC Multi-Queue** — number of transmit (Tx) and receive (Rx) queues per vNIC. Multi-queue lets the guest spread packet processing across CPUs; higher queue counts raise throughput and reduce contention for packet-heavy workloads. * **Private IPv4 per vNIC** — the maximum number of IPv4 addresses (primary + secondaries) that can be assigned to a single vNIC. *** *** ## Advanced: net\_failover and Live Migration ZEC instances run on hosts that may be live-migrated for maintenance — moving a running VM from one host to another without shutting it down. The vNIC's SR-IOV VF is hardware-bound to its current host's physical adapter, so the VF cannot follow the VM across hosts. Without help, that detach would interrupt the network for the duration of the migration. To eliminate that interruption, ZEC instances use the Linux kernel's [**net\_failover**](https://www.kernel.org/doc/html/latest/networking/net_failover.html) driver. Each vNIC exposes itself to the guest as **three** logical network devices that work together as one bonded link. ![net\_failover gives the guest a master plus a VF and virtio slave](/files/vQR9hRQLRNp5GIjz9Hrn) | Device | Role | Behavior | | ----------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------- | | Failover master (e.g. `eth0`) | The interface you configure | Owns the IP address, MAC, routes, and firewall rules. The only one apps and config tooling should target. | | SR-IOV VF (primary slave) | Fast path | Carries traffic in steady state at line rate. Detached during migration, re-attached on the new host. | | virtio-net (standby slave) | Slow-path fallback | Idle in steady state. Carries traffic for the brief window during migration when the VF is gone. | In normal operation, packets flow through the VF — the virtio device is enslaved but unused. When the host begins a live migration, the VF is detached and the kernel transparently switches traffic to the virtio standby. Once the migration completes on the new host, a new VF is hot-plugged in and traffic switches back. Applications see no IP change and no interface flap on the master. What this means for you: * `ip link` (or `ip addr`) on a ZEC instance shows three devices per vNIC. This is expected — most users only ever interact with one. * **Configure only the failover master.** Binding applications, firewall rules, or static routes to the underlying VF or virtio device will break during migration when that device disappears. * Most modern distros' udev / systemd-networkd rules already promote the failover master and hide the slaves from default config tooling. If yours does not, the master is the device that owns the IP and shows the `failover` flag in its link state. *** ## Learn More * [**Elastic IP: Standard vs Bypass Mode**](https://github.com/zenlayer/zenlayer-documentation/blob/main/elastic-compute/overview/eip/README.md) — how an EIP binds to a private IP on a vNIC, and the two per-vNIC forwarding modes. * [**Instance Families and Sizes**](https://github.com/zenlayer/zenlayer-documentation/blob/main/elastic-compute/overview/instance/instance_sku.md) — how vCPU count determines vNIC, queue, and IP limits. * [**NAT Gateway**](https://github.com/zenlayer/zenlayer-documentation/blob/main/elastic-compute/overview/natgw/README.md) — outbound translation for instances that do not carry their own EIP. * [**Cross-Region Network**](https://github.com/zenlayer/zenlayer-documentation/blob/main/elastic-compute/overview/cross-region/README.md) — how subnets in the same VPC but different regions reach each other. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.console.zenlayer.com/welcome/elastic-compute/networking/network-interface.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.