4. Developer’s Guide

Note

We acknowledge that users and developers are two different groups of people, so the documents should eventually be separated. However, since these are still very early days of the project, this section is kept in the Stork ARM for convenience only.

4.1. Generating Documentation

To generate documentation, simply type rake doc. You need to have Sphinx and rtd-theme installed. The generated documentation will be available in the doc/singlehtml directory.

4.2. Agent API

The connection between the server and the agents is established using gRPC over http/2. The agent API definition is kept in the backend/api/agent.proto file. For debugging purposes, it is possible to connect to the agent using grpcurl tool. For example, you can retrieve a list of currently provided gRPC calls by using this command:

$ grpcurl -plaintext -proto backend/api/agent.proto localhost:8888 describe
agentapi.Agent is a service:
service Agent {
  rpc detectServices ( .agentapi.DetectServicesReq ) returns ( .agentapi.DetectServicesRsp );
  rpc getState ( .agentapi.GetStateReq ) returns ( .agentapi.GetStateRsp );
  rpc restartKea ( .agentapi.RestartKeaReq ) returns ( .agentapi.RestartKeaRsp );
}

You can also make specific gRPC calls. For example, to get the machine state, the following command can be used:

$ grpcurl -plaintext -proto backend/api/agent.proto localhost:8888 agentapi.Agent.getState
{
  "agentVersion": "0.1.0",
  "hostname": "copernicus",
  "cpus": "8",
  "cpusLoad": "1.68 1.46 1.28",
  "memory": "16",
  "usedMemory": "59",
  "uptime": "2",
  "os": "darwin",
  "platform": "darwin",
  "platformFamily": "Standalone Workstation",
  "platformVersion": "10.14.6",
  "kernelVersion": "18.7.0",
  "kernelArch": "x86_64",
  "hostID": "c41337a1-0ec3-3896-a954-a1f85e849d53"
}

4.3. Installing git hooks

There’s a simple git hook that inserts the issue number in the commit message automatically. If you want to use it, go to utils directory and run git-hooks-install script. It will copy the necessary file to .git/hooks directory.

4.4. ReST API

The primary user of ReST API is Stork UI in web browser. The definition of ReST API is located in api folder and is described in Swagger 2.0 format.

The description in Swagger is split into multiple files. 2 files comprise a tag group:

  • *-paths.yaml - defines URLs
  • *-defs.yaml - contains entity definitions

All these files are combined by yamlinc tool into signle swagger file swagger.yaml. Then from swagger.yaml there are generated code for:

  • UI fronted by swagger-codegen
  • backend in Go lang by go-swagger

All these steps are realized in Rakefile.