fawkes-discovery

Application for discovering hardware and bmc info on baremetal nodes.

Components

fawkes-discovery server is containerized. The http frontend and mongo backend run as individual podman pods. The pods are brought up via systemd.

  • discovery server application

    • http frontend

      • Frontend application written in Go, providing a REST interface to the database. This handles all PUT and GET requests; new/updated metadata, and queries.

      • Classification definitions

      • single podman pod

    • mongo database backend

      • Hardware meta storage.

      • single podman pod

fawkes-discovery client is not containerized and runs via systemd.

  • Client

    • Go application for discovering bmc info

    • existing linux utilities for discovering hardware

Description

fawkes-discovery server is intended to run in a centralized location that can be reached over a network by baremetal nodes during initial boot. fawkes-discovery client is intended to run on baremetal nodes. The client collects hardware/bmc info by utilizing a small Golang application (included in this repo) and several existing linux utilities (lshw, lsblk). A json document including all of the hardware/bmc info is created and pushed to the server via http. The server receives the json document, validates it and stores it in a mongodb collection while adding user-defined classifiers. See Classification. If a given node already exists in the database, the existing record is updated with the incoming document. Note that no historical data is maintained.

Classification

fawkes-discovery server provides the ability to "classify" nodes based on data acquired from the fawkes discovery client. Classifying a node adds additional fields to the json document based on data found in the existing document. The classifiers are user-defined mongodb aggregation pipelines. For example, we currently add a field named nodeClass which classifies a node as a hypervisor node or storage node depending on the number of disks discovered by the client. The current classifiers can be found here: classifiers. Classifiers can be added or removed from fawkes-discovery-classes.json while the service is running (i.e. "live"). Classification occurs during the following events:

  • When a new document is sent by a client to the discovery application; a new node is created, or an existing node is updated

    • The new payload is updated as it’s written to the database with a list of matching classifiers

  • When a new classifier is added, changed, or removed from the discovery application

    • The existing nodes in the database are updated; classifiers are added or dropped

  • When the discovery application starts

Json schema validation

A minimal json schema is utilized to ensure only top-level keys are present in incoming json documents. There is a large amount of variability in hardware and in the document, so very specific schemas may be difficult. mongo/json schema

Distribution

fawkes-discovery is distributed in two packages: fawkes-discovery and fawkes-discovery-client.

Configuration

fawkes-discovery server is configured via a yaml file located at /etc/fawkes-discovery/fawkes-discovery.yml All of the user configurable fields are outlined below.

---
######################
# Discovery Server api
######################
bind: ":8080" # address:port for the discovery server api to listen on

######################
# MongoDB
######################
mongoserver: "mongodb-pod:27017" # mongo database hostname:port
database: "discovery" # target mongo database name
collection: "discovery" # target mongo collection name

######################
# Mongo classifiers
######################
class: "/etc/fawkes-discovery/fawkes-discovery-classes.json" # classification definitions

All of the fields in fawkes-discovery.yml can be overidden:

Usage
Usage of fawkes-discovery:
  -b, --bind string          Bind address (default ":8080")
  -t, --class string         Path to class file
  -c, --collection string    Mongo collection name
  -f, --config string        Path to configuration file
  -d, --database string      Mongo database name
  -s, --mongoserver string   Mongo ip:port

Query operators

  • qfields

    • prints only the user specified fields

  • count

    • prints only the count of matching documents

Query examples

# print all documents in collection
curl -s http://127.0.0.1:8080

# search for a specific serial number and print the whole document
curl -s 'http://127.0.0.1:8080/filter?serial=MXQ14808WM'

# search for a specific serial number and print just the bmc field
curl -s 'http://127.0.0.1:8080/filter?qfields&bmc&serial=MXQ14808WM'

# search for nodes that have 3 disks and print the whole document for each node
curl -s 'http://127.0.0.1:8080/filter?diskCount=3'

# print the total number of nodes that have 6 disks
curl -s 'http://127.0.0.1:8080/filter?diskCount=6&count'

TODO’s

  • cleanup client/fawkes-discovery-client.sh

    • probably involves writing our own client data collectors and not using lshw/lsblk

  • write unit tests

  • use https instead of http

  • create database backup / restore functionality

  • improve logging

    • indicate when/why a specific classifier matches or doesn’t match

  • make writing classifiers easier

    • writing mongo aggregation pipelines can be tricky

  • general code cleanup