Skip to content

Node API Architecture#

Goals#

The aim of the Node API is to:

  • provide a clean abstraction to interact with compute nodes,
  • make the interface well-testable without requiring a full SCL deployment, and
  • allow for isolating most of the SCL components in a dedicated, unprivileged security domain / virtual machine.

Architecture#

A slightly adapted figure from the specification with available endpoints is shown below:

Node API high level overview

The depicted reverse proxy part that terminates mTLS is realized by the OpenAPI Proxy.

The endpoints behind the reverse proxy are implemented by independent REST services. This has the advantage that they (e.g., the Compute API) can be used, configured, assembled, and secured independently and for other use cases than the SCL. For the same reasons, the services are designed in such a way that they don't require SCL semantics and that they don't rely on each other or on other SCL components.

Constituent Services#

Node L2 Network API#

See also: OpenAPI specification of the L2 Network API.

The Node L2 Network API is a service that allows users to manage VLANs and interconnected tap devices (designated for attaching VMs created via the Compute API) within the VLANs on the host where the service is running on.

The networking functionality is realized via regular Linux networking. In principle, it can be ported to another technological basis such as accessing a smart network card that provides interfaces using SR-IOV or a software switch like Open vSwitch in the future without breaking changes to the API. In this regard, it is also possible to replace the IEEE 802.1Q VLAN functionality with another basis for the logical separation of networks, e.g., VxLAN, as long as numeric identifiers for the individual sub-networks can be leveraged.

The next figure shows how the network setup of a Node looks like, when the following resources have been created via the Node L2 Network API:

  • a VLAN with the ID 3000,
  • two tap devices within VLAN 3000 named tap123 and tap456.

Network architecture of the Node L2 Network API

Dashed boxes and lines indicate optional network infrastructure for multi-node setups that is created when the service is configured with a VLAN gateway interface (in this example with a value of eth0). Given that multiple Nodes use VLAN gateways that can communicate with each other, the tap devices within a VLAN can reach each other, regardless of on which Node they are.

The generation of MAC addresses for the managed interfaces is an implementation matter and is currently taken care of by the underlying Linux system.

Compute API#

See also: OpenAPI specification of the Compute API.

The Compute API is a service that allows users to manage volumes and virtual machines on the host where the service is running. It uses the cloud-hypervisor as a virtual machine monitor.

Volumes and VMs are identified via user-specified UUIDs. In order to create a VM, one must also specify the amount of vCPU and RAM the VM gets assigned. In addition, block storage devices (volume UUIDs) and network devices (currently limited to tap devices) to be bound to the VM can be specified.

Concerning block storage options, several use-cases are supported:

  • Already existing volumes referenced via a local path,
  • Volumes initialized by the Compute API:
    • (Initially) Empty volumes,
    • Non-empty volumes that are filled with initial data obtained from a URL,
    • Images created from a cloud-init configuration that can be used in conjunction with cloud-init-enabled OS images to e.g. setup users and networking configuration after the OS has booted.

For tap devices, one can optionally specify a network namespace. In that case, the VM will be started in the specified namespace.