README ¶
HostDB Server
HostDB (hostdb.pdxfixit.com) is a metadata store of hosts and host-like devices. It is stored in a MariaDB instance, and accessed through either a GUI or a REST-ish API.
Configuration
A default configuration can be found in config.yaml
.
A JSON file can be substituted if desired.
Connection details (such as app port, and db host/port) will be silently overridden in a k8s cluster.
Testing
There are integration tests in hostdb_test.go
. Those tests will create a fresh database for testing.
The tests expect a MariaDB instance (currently v10.3) to be accessible at 127.0.0.1:3306
, with no password for the root
user.
$ make mariadb_start
$ make test
$ make mariadb_stop
Data Format
The v0
API data format consists of the following fields:
id
– A unique GUID, generated by the server if not provided. (typically 40 chars, must be less than 64)type
– The source from where the record was collected. Usuallyopenstack
,aws
, etc. Cannot contain spaces.hostname
ip
timestamp
– Timestamp for when the record was collected from the source. If not supplied by the collector/client, it will be generated by the server.committer
– Optional, but recommended. Defaults to remote IP and User-Agent string.context
– Related totype
; provides information about the record (e.g. what origin endpoint was used).data
– JSON data. Often referred to as the 'payload.' This should be unmodified from the source.hash
– A SHA256 hash of the data/payload, generated by the server. This can be used to quickly determine if the payload has changed. If a hash is provided during a PUT/POST, it will be discarded!
Using the API
Currently, the only supported API version is v0
. All write requests must use Basic auth.
There are four primary endpoints for the service;
catalog
– Provides a list of unique values for a requested data point (e.g.flavor
).detail
– Returns detailed information about the requested records.list
– Returns a list of the requested records, omitting thedata
payload.records
– Used for write operations and record management; acceptsGET
,PUT
(single record),POST
(multiple/bulk),DELETE
verbs.
For examples on interacting with the API, please see EXAMPLES.md.
CI Builds & Deployment
Builds ran in CircleCI, and were defined in .circleci/config.yml
.
A successful build should result in the updated application getting deployed to k8s.
Required Environment Variables
KUBE_CONFIG
-- contents of a valid~/.kube/config
file, in JSON formatNEWRELIC_APIKEY
-- a New Relic API key used for deployment notificationsREGISTRY_USER
-- user with write permissions to the image repositoryREGISTRY_PASS
-- password for the user
Optional Environment Variables
REGISTRY_HOST
-- defaults toregistry.pdxfixit.com
Build
hostdb-server is written in go, and is compiled using gox.
The app is compiled in such a way that it does not require a base operating system to run, and can be placed into a scratch
container.
A database is required for the integration tests, so the first step is to stand up a database instance. After running tests, the binary is compiled.
Next, we run the binary, and post the contents of the sample_data
folder to it.
Containerize
In this step we simply run docker build
to create a container image, and docker push
it up to the registry.
Please ensure REGISTRY_USER
and REGISTRY_PASS
environment variables have valid credentials with write permissions to the container registry.
Deploy
Deployment of hostdb-server is accomplished by installing a Helm chart into a Kubernetes cluster, into a dedicated namespace. A MariaDB replication pair are also installed in the namespace, using the public Bitnami chart.
Configuration for kubectl should be provided in an environment variable named KUBE_CONFIG
, which gets written into the user space of the build.
Please be aware, build systems like CircleCI don't support multi-line environment variables, so you may need to convert the kube config to JSON.
The project hostdb-server-chart gets cloned into the workspace, config.yaml is copied from this project into the chart, and then make
commands are invoked from within that project.
Finally, upon a successful deployment, a notification is sent to New Relic. Please ensure the environment variable NEWRELIC_APIKEY
is set.
Development
If you need to run a local instance to test the API, ensure you have a current installation of Docker and Go, then run the following commands:
$ make run
$ curl http://localhost:8080/health
This will clear the workspace, compile the binary, build it into a local container image, start MariaDB, and then start the service. Finally, we run curl to verify the status of the service.
make
is your friend.
The Makefile
can be used for the following tasks:
get
– Retrieves any golang dependencies.test
– Runs the golang tests.compile
– Compiles the source code into a binary.build
andpush
– Build a container image, and push it to the registry, respectively.deploy
– Installskubectl
andhelm
, cloneshostdb-server-chart
, and then upgrades the existing deployment. RequiresKUBECONFIG
env var to be set.clean
– Removes junk from previous builds, stops any running containers, and removes any locally-built hostdb containers.run
andstop
– Will run the container, including a MariaDB instance. Note thatstop
will halt the app, but not MariaDB.sample_data
– Import sample data for testing. Override the destination by settingREMOTE_HOST
andREMOTE_PORT
.validate
– Aftersample_data
has been imported, examine each of the sample files, and ensure that what is returned matches.mariadb_start
,mariadb_stop
andmariadb_restart
– Start/stop a MariaDB container, fully configured for HostDB.mariadb_client
– Starts a MariaDB container, and starts a client session. Will start a database instance if one is not already running.
Populating a database with sample data
In the sample-data
folder, you'll find example datasets which can be imported for use during development and testing.
To import sample data into a local instance, simply run make sample_data
.
Remote destinations are possible too.
For example, if one wishes to load sample OpenStack data into a local instance of the service, one might run a command similar to this:
$ make sample_data_openstack REMOTE_HOST=10.10.10.10 REMOTE_PORT=80 REMOTE_PASS=password
The following environment variables are supported for sample_data
recipes:
REMOTE_HOST
REMOTE_PASS
REMOTE_PORT
REMOTE_USER
Prerequisites
Please ensure that you have the following apps ready for use.
- Golang
- Docker Desktop
If you're working with deployments of hostdb, you'll also need:
- Kubernetes and
kubectl
- Helm
Dependencies (partial list)
- https://github.com/pdxfixit/hostdb (shared golang code)
- https://github.com/gin-gonic/gin (HTTP server)
- https://github.com/go-sql-driver/mysql (MariaDB)
- https://github.com/spf13/viper (configuration)
- https://github.com/satori/go.uuid (uuids)
- https://github.com/bitnami/charts/tree/master/bitnami/mariadb
See Also
- https://github.com/pdxfixit/hostdb-collector-aws
- https://github.com/pdxfixit/hostdb-collector-oneview
- https://github.com/pdxfixit/hostdb-collector-openstack
- https://github.com/pdxfixit/hostdb-collector-ucs
- https://github.com/pdxfixit/hostdb-collector-vrops
- https://github.com/pdxfixit/hostdb-server-chart
TODO
- richer auth for writes, reads
- expose historical data thru the api
- Provide method to export/dump database
Documentation ¶
There is no documentation for this package.