Edge router
Problem and purpose
As long as the machines in a VDC (virtual data center) only need their own network, they do not need a router. Once traffic needs to flow between networks and outside the VDC, and individual services need to be published at a different address and port, a connection point is needed: a router that knows about multiple networks and maintains traffic filtering and address translation rules.
Edge, a software-defined router (Edge), provides this connection point. It runs inside the cluster, connects to networks through its ports, and is managed through the same API calls as other vStack Center objects. It needs no separate hardware appliance or administration console: SDN (software-defined networking) means that the router is a managed cluster object, just like a VM or a network.
Model and entities
Edge is a virtual machine managed by vStack Center. The edge-create method builds
a synthetic vms-create request and passes it to the VM agent. The edge-start,
edge-stop, and edge-restart methods map to vms-start, vms-stop, and
vms-restart, and edge-remove maps to vms-remove. The practical implication:
the router consumes cluster resources as a VM and is subject to the same
restrictions. For example, a port can only be added when the machine is stopped.
Only the Cluster master role can see the VM identifier (vm_id) in API responses.
The Edge object itself is described by these fields:
| Field | Meaning |
|---|---|
edge_id | Router UUID. The key in all Edge methods |
owner | Owner. Returned to all roles |
vdc_id | The VDC to which the shared Edge belongs |
vm_id | Router VM identifier. Only available to the Cluster master role |
oper_status, oper_progress, oper_ts | Status of the last operation, its progress as a percentage, and its time |
deploy_ts | Timestamp of rule application on the router |
modified | Time of the last record change |
base_version, ctrl_version, GI_object | Internal versioning and GI federation fields |
Edge connects to networks through ports, with a maximum of four. A port describes the relationship between a network, a slot, and addresses:
| Port field | What it specifies |
|---|---|
port_id | Port identifier. Accepted by edge-ratelimit and edge-remove-nic; rules refer to the port through rule_ifname |
slot | Slot number (no greater than 4) |
network_id | Network to which the port is connected |
ifname | Port interface number |
address | Port IPv4 address, or null if no IPv4 address is assigned |
address_v6 | List of port IPv6 addresses (up to 8). An empty list if no IPv6 addresses are assigned |
mac | Port MAC address |
ip_guard | IP guard flag: 0 to disable, 1 to enable. Default: 1 |
ratelimit_mbits | Bandwidth limit in Mbps. 0 means no limit |
Edge rules are stored in two numbered sets: nat for address translation and
fw for traffic filtering (firewall). The key within a set is the rule number;
for firewall rules, the number is in the range 100–32767. The incarnation field
is returned alongside the sets: it is a set marker sent to the router with the rules.
How it works
Rule configuration and execution are separate. The edge-add-fw-rule,
edge-add-nat-rule, edge-remove-fw-rule, and edge-remove-nat-rule methods
are synchronous and work only with the vStack Center database: a rule appears in
the set or is removed from it, but does not yet affect traffic. A separate call,
edge-deploy-rules, performs deployment: it assembles the complete set
(incarnation, nat, fw) from the database and sends it in full to the Edge agent.
This separation has two consequences. First, until the set is applied, the set in the database differs from the set on the router, so editing rules ends with application, rather than with adding a rule. Second, application replaces the entire set instead of adding individual changes: the set in the database always holds the complete desired state.
Asynchronous Edge operations go through agents, and the agent depends on the
operation type. Machine lifecycle operations (start, stop, restart, remove) go to
the VM agent, port operations (edge-add-nic, edge-remove-nic) go to the Storage
agent, and rules and the packet filter log go to the Edge agent. Such a call first
returns an intermediate response, {"message": "relayed"}. This acknowledges
forwarding, rather than providing the result. The final response arrives as a
callback from the agent.
The lifecycle works as follows. edge-create creates the router VM, registers
Edge in the database, and starts the machine; a separate start after creation is
not required. The operating phase follows: ports are added and removed, port
bandwidth is limited, and rule sets are edited and applied. Stopping and starting
move the router between states without changing its configuration. edge-remove
removes Edge and all its rules from the database, then deletes the VM.
Access is based on scoped privileges. The Cluster master role can work with any
Edge in the cluster. A VDC administrator creates routers in their own VDC, sees
every router there, and reads their rule sets. They can manage only the routers
they created: ports, bandwidth, starting and stopping, editing and applying rules,
and removal. Each of these operations returns -403 for a router in their VDC
that belongs to someone else, including removal.
VDC users and observers can read the list of routers in their own VDC, their cards, and their rule sets. Router ownership is not required for this access.
The packet filter log provides visibility into rule behavior. The
edge-get-pfloggs method retrieves the log from the router as a PCAP file. Open
it in a traffic analyzer to see which packets the rules actually matched.
Limitations
- An Edge can have no more than four ports; the slot number cannot exceed 4.
- A port can only be added when the router VM is stopped (or in an error or
creation state). The
edge-add-niccall is rejected on a running Edge. - Firewall rule numbers are limited to the range 100–32767. No range is defined for NAT rule numbers.
- Up to 8 IPv6 addresses can be assigned manually per port. Each address is
checked for format, membership in the network's IPv6 subnet (
net_cidr_v6), absence from reserved (ippool_reserved_v6) and already allocated (ippool_port_allocations) addresses, and uniqueness within the request. - The
rule_action,rule_proto, andrule_directionvalues are numeric identifiers from the cluster reference lists, rather than action and protocol names. - Applying rules requires a running Edge with 100% progress and completed bootstrap. A stopped router or one that is still starting will not accept rules.
- The packet filter log is retained for 24 hours, and the agent limits exports
to 3000 packets. The method itself is gated by the
feature.edge_log_pcapfeature flag in the cluster settings. - All Edge functionality is gated by the overarching
feature.edgefeature flag in the cluster settings. While it is disabled, any router request returns code-25030, "The edge feature has not been enabled". Read operations are also blocked: the router list, router card, and rule sets. Each such denial is recorded in the security log as afeature.gate-deniedevent.