Introducing the fleet API

The fleet API is built on top of the Infrastructure API and relies on sites and networks to be configured appropriately.

The registration of on-prem equipment is done through device resources.

Device concept

The fleet API supports the use of MediaKind software running on on-prem equipment by allowing the equipment to be registered with MK.IO. Once registered, the software can be monitored and controlled from MK.IO, simplifying and centralizing the management of MediaKind appliance and software fleets.

When a project with SaaS access is first created, it will contain a simple starting layout of sites, networks and routes similar to below.

The registration of on-prem equipment is done through device resources.

A Device refers to a VM or bare-metal server running MediaKind media processing software that is registered for control by MK.IO. The device can be either a pre-installed MediaKind appliance or appliances hosting MediaKind software. Devices are added to on-prem sites such as 'world'.

Once added and securely registered in MK.IO, devices provide detailed information about their status and configuration, including:

• Alarm/contact status: facilitates centralized monitoring
• Software versions: enables centralized software upgrade
• Network interfaces: displays IP and ASI/SDI interfaces

For MediaKind devices with a local web user interface, MK.IO provides access to it from anywhere through a secure connection. Simply log in to MK.IO and access the remote device UI with a single click.

To learn more about device on-boarding, read On-board fleet devices.

Available networks

From Sites and Networks we know that sites are associated with a set of networks. When we add a device to a site, the base assumption is that the device has access to all of the networks that the site is routed to, this is true when no available networks are configured on the device.

Sometimes it is necessary to:

• Constrain a device's network access to a subset of the site's networks, and/or
• Associate some or all of the site's networks to specific device interfaces, e.g. eth0, enp2s0.

Available networks on a device support this additional level of network association control. For example, the following device resource states that:

• The 'internet' network is available, let the host OS (Linux) on the device do the network routing.
• The 'wan-primary' network is available, use the 'enp1s0' interface to send/receive traffic on it.
• The 'wan-secondary' network is available, use the 'enp2s0' interface to send/receive traffic on it.

PUT https://app.mk.io/api/projects/myproject/v1/fleet/devices/d1

{
    "metadata": {
        "displayName": "Device 1"
    },
    "spec": {
        "siteName": "southampton",
        "availableNetworks": [
            {
                "networkName": "internet"
            },
            {
                "networkName": "wan-primary",
                "interfaceName": "enp1s0"
            },
            {
                "networkName": "wan-secondary",
                "interfaceName": "enp2s0"
            }
        ]
    }
}

📘

If any available networks are specified, all desired available networks must be specified. However, it is not necessary to specify an interface for all of them and a device does not need to make all of the networks routed from the site available.

An example of where it can be useful to specify the interfaceName field is when there are specific network path redundancy requirements that must be met, such as a primary and secondary network.

🚧

Network guarantees

As stated below in Sites and Networks, MK.IO API network resources are not precise representations of real-world network topologies. By applying available networks on the device, we are not guaranteeing that traffic will not flow over other networks, we are restricting which routes will we look for default transport settings on.

The inclusion of the interface field does help to make the traffic output more specific and predictable, but it still does not guarantee to restrict traffic to specific real-world networks, only the network interface is guaranteed.

Remote device UI access

Once a device is on-board in MK.IO, the device's local web UI can be accessed through MK.IO. To learn more, read Access the remote device UI.

Whitelisting

On-prem devices need to call out to specific URLs on the public internet:

• api.mk.io - to access MK.IO