Use Cumulus HTTP API to help automate common network tasks

Cumulus Linux includes a RESTful programming interface for accessing network devices running that OS. It’s called HTTP API, and it implements an API to access the OpenStack ML2 driver and Network Command Line Utility, or NCLU. Understanding exactly what this means, and how it works, is essential before digging into the possibilities it presents. Here’s an overview to get this going.

The OpenStack ML2 Driver

The ML2 Driver, a.k.a. (in OpenStack’s terms) the Modular Layer 2 neutron plug-in, provides a framework. It enables OpenStack-based networking to use a variety of Layer 2 networking technologies, including those from Cumulus (for which a specific ML2 driver is available and ready to use). To use the OpenStack ML2 driver with Cumulus Linux switches, two essential ingredients must be present:

The REST API, which comes installed in Cumulus Linux. This includes an ML2 HTTP Server, which recognizes and responds to such requests. This runs on Cumulus-based network nodes to which management consoles or nodes will attach to interrogate, configure, or otherwise interact underlying devices.

Elsewhere on the network, the Cumulus ML2 Mechanism Driver should be installed on a VM or system running Cumulus Linux. This is called a “controller node.” The driver uses REST API calls to establish a VLAN link to permit the controller node to access and interact with Cumulus Linux switches (see “OpenStack Neutron MLS and Cumulus Linux” for set-up and configuration details). Once a connection is configured, established and working, admins can use it to interact with Cumulus switches at the command line or through a web browser.

Numerous parameters become accessible through the ML2 driver once the proper plumbing is in place. These permit switches to be identified, access URLs set up, and for device polling and bridge settings to be managed. Cumulus also offers a demo of the environment, where you can try open networking at no cost, and preview Cumulus Linux and Cumulus NetQ. You can also access all the open networking tools you need to do a virtual proof of concept for your web-scale network and get a guided tour of open networking technology or experiment with features to your heart’s content.

The Network Command Line Utility

The NCLU defines a common CLI for Cumulus products, and is specifically designed to simplify and streamline the network configuration process. NCLU is resident in the Linux user space. It provides network command access through bash. With NCLU, there’s no need to edit files, or enter modes and sub-modes to put commands to work. In fact, NCLU integrates help into the CLI, so that help, examples, and command checks (with suggestions) occur as you type input.

Because it runs as part of bash, NCLU works seamlessly for accessing configuration files and running automation. Best of all, NCLU configures dependent files automatically without requiring user oversight or explicit action. See the NCLU docs for more information. It includes the helpful function diagram you can see in Figure 1.

Figure 1. Network Command Line Utility (NCLU) architecture overview.

Using the net wrapper utility for NCLU, it can configure Layer 2 and 3 features of the networking stack. It can also install ACLs and VXLANs, and roll back and delete snapshots. It also provides monitoring and troubleshooting capability for all such features. One can configure networking interfaces and frr policy-based routing through the net wrapper as well.

Exploiting the Power of the HTTP API

Instead of accessing Cumulus Linux on a switch using SSH, the HTTP API offers numerous other methods of interaction. Unsurprisingly, these methods rely on an underlying HTTP client, as the API’s name indicates. This means admins and DevOps staff can use clients such as cURL or HTTPie, or even a web browser, to configure, interrogate and manage such switches. It also means that running scripts for automation or using web-based applications can extend or enhance admin capability and productivity. Most of these HTTP interfaces use JSON typed applications (MIMETYPE: application\json) under the hood.
cURL is an open source computer software project that supports a library and a command-line tool for transferring data. Among many other protocols, it works with many forms of HTTP (including HTTP/2, HTTP POST, HTTP PUT, HTTP proxy tunneling and HTTPS). Its library support file URIs, SFTP and TFTP, Telnet, file transfer resume, HTTP form-based upload, HTTPS certificates, and more. Thus, cURL provides direct methods for retrieving HTTP endpoints through the API, for any of which it can show counters and status values. cURL can even add a bridge using the ML2 driver (see the end of the Cumulus HTTP API document for syntax details).

HTTPie is a cURL alternative. It’s sometimes defined as “a CLI, cURL-like tool for humans.” The impetus behind this open source project is to make CLI interaction with web services (like Cumulus’ HTTP API) human-friendly. HTTPie supports an HTTP command that can accommodate sending arbitrary HTTP requests with simple and straightforward syntax. It also displays colorized output to help users easily see what’s what. The HTTPie.org DOC spells out installation and use in nice, readable detail.

Unless one has access to a native web-based application written to the Cumulus HTTP API, interaction with Cumulus switches via that API will primarily occur at the command line, or through a tool such as cURL or HTTPie. According to Cumulus, some of its users have already built custom management tools using the API. Also, sFlow has an automated DDOS detection and protection tool they’ve built using the API. They’ve also used the API to create a tool to add and remove ACLs as well.

Indeed, the HTTP-API is purpose-built to making creating such applications as simple as possible. Interested parties will also want to check out the Cumulus Networking automation page, which includes an automation knowledge base and other useful infographics and reference materials. The Cumulus Linux 3.7 User Guide documents the full suite of commands that the HTTP API supports.