README
¶
Hawk API Server
HTTPS API server / minimalist web proxy for Hawk.
Table of content
Rationale
This project currently provides a minimalistic web server which handles SSL certificate termination, proxying and static file serving for Hawk, a HA cluster dashboard and control interface written in Ruby on Rails.
The primary goal for this project is to provide the minimal web server
needed by Hawk while consuming as few system resources as
possible. Second, it provides the /monitor API endpoint which
handles long-lived connections from the frontend to enable instant
updates of the interface on cluster events.
In the future, the API server will provide a complete and documented REST API for Pacemaker and Pacemaker-based HA clusters, including the ability to provide status information and metrics for inclusion in other dashboards or for monitoring tools like Prometheus.
Build
Dependencies:
- GO >= 1.9
- following pkgs:
libqb-devel libpacemaker-devel.
go get -u github.com/ClusterLabs/hawk-apiserver
The rest of the instructions assume that the current working directory
is $GOPATH/src/github.com/ClusterLabs/hawk-apiserver.
Devel
Generating the API structures
For generating api_structs.go use tools/api-go-structs-generation.py
Install the pkg requirements with pip install -r /tools/api-go-structs-requirements.txt
This file is generated from the pacemaker schema, so a new schema version in Pacemaker requires regenerating this file.
Since a version of api_structs.go is already checked into the
repository, running this utility is only necessary if this file hasn't
been updated to match the current version of Pacemaker.
Using the enter script
The /enter script can be used to set up a build and test environment
inside a Docker container, so that all the dependencies are in place
and there is no need to install things in the host system. If Docker
is installed and the user has the necessary permissions to run
containers, /enter should bring you to a prepared environment ready
to run the rest of the commands.
Generating an SSL certificate
SSLGEN_KEY=hawk.key SSLGEN_CERT=hawk.pem ./tools/generate-ssl-cert
Building the server
go generate
go build
Testing
go test
Configuration
Pass -config <config> as an argument to give the server a
configuration file. The format is a json dictionary with key / value
pairs.
The available configuration values are described below. If a value is set both in the configuration file and in a command line argument, the command line argument takes precedence.
-
key: Path to SSL key. (argument: -key) -
cert: Path to SSL certificate. (argument: -cert) -
port: TCP port to listen to for connections. (argument: -port) -
route: List of json maps that configure the routing table.
The route format is very limited and adapted to serving hawk, but enable reconfiguration of the exact paths to certificates, files and sockets.
Example:
{
"key": "/etc/hawk/hawk.key",
"cert": "/etc/hawk/hawk.pem",
"port": 7630,
"route": [
{
"handler": "api/v1",
"path": "/api/v1"
},
{
"handler": "monitor",
"path": "/monitor"
},
{
"handler": "file",
"path": "/",
"target": "/usr/share/hawk/public"
},
{
"handler": "proxy",
"path": "/",
"target": "unix:///var/run/hawk/app.sock"
}
]
}
API
Testing using curl:
curl --insecure -u hacluster:<pass> https://<server>:<port>/api/v1/cib
Authentication
-
Basic auth: Get user:password from HTTP headers. Map to system user. Verify that system user is a member of the haclient group.
-
Cookie auth (cookie created by hawk rails app): If a valid cookie is found in the HTTP headers, this is accepted as authentication. Session cookie is stored in attrd.
-
TODO: SAML2
Endpoints
HTTP verbs:
- POST: Create new resources
- GET: Retrieve resource
- PUT: Update resource (should be idempotent)
- PATCH: Update resource (not yet supported)
- DELETE: Delete a resource
GET /api/v1/features
GET/POST/PUT/DELETE /api/v1/cib
GET/POST/PUT/DELETE /api/v1/cib/attributes
GET /api/v1/cib/status
GET/POST/PUT/DELETE /api/v1/cib/configuration
GET/POST/PUT/DELETE /api/v1/cib/configuration/crm_config
GET/POST/PUT/DELETE /api/v1/cib/configuration/crm_config/{id}
GET/POST/PUT/DELETE /api/v1/cib/configuration/nodes
GET/POST/PUT/DELETE /api/v1/cib/configuration/nodes/{id}
GET/POST/PUT/DELETE /api/v1/cib/configuration/resources
GET/POST/PUT/DELETE /api/v1/cib/configuration/resources/{id}
GET/POST/PUT/DELETE /api/v1/cib/configuration/constraints
GET/POST/PUT/DELETE /api/v1/cib/configuration/constraints/{id}
GET/POST/PUT/DELETE /api/v1/cib/configuration/fencing
GET/POST/PUT/DELETE /api/v1/cib/configuration/acls
GET/POST/PUT/DELETE /api/v1/cib/configuration/acls/{id}
GET/POST/PUT/DELETE /api/v1/cib/configuration/tags
GET/POST/PUT/DELETE /api/v1/cib/configuration/tags/{id}
GET/POST/PUT/DELETE /api/v1/cib/configuration/alerts
GET/POST/PUT/DELETE /api/v1/cib/configuration/alerts/{id}
GET/POST/PUT/DELETE /api/v1/cib/configuration/op_defaults
GET/POST/PUT/DELETE /api/v1/cib/configuration/op_defaults/{id}
GET/POST/PUT/DELETE /api/v1/cib/configuration/rsc_defaults
GET/POST/PUT/DELETE /api/v1/cib/configuration/rsc_defaults/{id}
Shadow CIBs and simulation
The web server SHOULD support the Shadow CIB feature, which includes
the simulator interface. If the Shadow CIB feature is supported, the
object returned by GET /api/v1/features MUST include shadow: true.
All endpoints can also receive these extra arguments to determine which CIB is being accessed:
CIB_file: (DEV only) Refers to a path on the server.CIB_shadow: Identifier for the shadow CIB residing on the server.
Adds the following API endpoints which creates or deletes the server shadow CIB identifier. Use the CIB_shadow parameter together with the regular configuration API to modify the actual contents of the shadow CIB.
GET/POST/PUT/DELETE /api/v1/shadow
GET/POST/PUT/DELETE /api/v1/shadow/{id}
PUT /api/v1/shadow/{id}
Adds the following API endpoints to invoke the simulator:
POST/PUT /api/v1/shadow/{id}/simulate
The simulator accepts the special identifier live as ID to simulate
using the live CIB as input.
The simulator run and the results are returned as part of the request body.
Openapi
This project support the openapi specification V2.0, via go-swagger
Documentation
¶
Overview ¶
Copyright 2019 Kristoffer Grönlund <kgronlund@suse.com>
HTTPS API server / minimalist web proxy for Hawk.
This project currently provides a minimalistic web server which handles SSL certificate termination, proxying and static file serving for Hawk, a HA cluster dashboard and control interface written in Ruby on Rails.
The primary goal for this project is to provide the minimal web server needed by Hawk while consuming as few system resources as possible. Second, it provides the `/monitor` API endpoint which handles long-lived connections from the frontend to enable instant updates of the interface on cluster events.
Source Files
Directories