Simple and extensible monitoring agent / library for Kubernetes:
Branch: master
Clone or download
Latest commit 5786940 Feb 14, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
agent Detect client closed situations and reinit the client. (#95) Jan 25, 2019
build.assets/grpc update to golang 1.10.7 to avoid cve-2018-16875 (#92) Jan 2, 2019
charts/healthz Add HTTPS support for kubernetes API May 12, 2017
cmd Dmitri/3180 node status (#83) Oct 1, 2018
healthz Dmitri/3180 node status (#83) Oct 1, 2018
lib Update module checker to take builtin modules into account on Linux. (#… Jan 9, 2019
monitoring Fix darwin build Jan 11, 2019
scripts Add script which checks for license presence in sourcefiles, more lic… Jan 28, 2017
utils essential preflight checks (#20) Sep 28, 2017
vendor Kubernetes v1.13.3. (#97) Feb 14, 2019
.dockerignore Dockerfile, build target for healthz and docker image Jan 28, 2017
.gitignore IP forward checks Jul 30, 2017
Dockerfile Fixed license in Dockerfile Jan 29, 2017
Gopkg.toml Kubernetes v1.13.3. (#97) Feb 14, 2019
LICENSE Initial commit Feb 27, 2016
Makefile Dmitri/3180 node status (#83) Oct 1, 2018 sqlite backend: fixed deleteOlderThan to use datetime conversion Feb 8, 2017


Satellite is an agent written in Go for collecting health information in a kubernetes cluster. It is both a library and an application. As a library, it can be used as a basis for a custom monitoring solution. The health status information is collected in the form of a time series and persisted to the sqlite backend. Additional backends are supported via an interface.

The original design goals are:

  • lightweight periodic testing
  • high availability and resilience to network partitions
  • no single point of failure
  • history of health data as a time series

The agents communicate over a [Gossip] protocol implemented by serf.



There are currently no binary distributions available.

Building from source

Satellite manages dependencies via godep which is also a prerequisite for building. Another prerequisite is Go version 1.7+.

  1. Install Go
  2. Install godep
  3. Setup GOPATH
  4. Run go get
  5. Run cd $GOPATH/src/
  6. Run make

How to use it

$ satellite help
usage: satellite [<flags>] <command> [<args> ...]

Cluster health monitoring agent

  --help   Show help (also see --help-long and --help-man).
  --debug  Enable verbose mode

  help [<command>...]
    Show help.

  agent [<flags>]
    Start monitoring agent

  status [<flags>]
    Query cluster status

    Display version

$ satellite agent help
usage: satellite agent [<flags>]

Start monitoring agent

  --help                         Show context-sensitive help (also try --help-long and --help-man).
  --debug                        Enable verbose mode
  --rpc-addr=      List of addresses to bind the RPC listener to (host:port), comma-separated
                                 Address of the kubernetes API server
                                 Address of the kubelet
                                 Path to the docker daemon socket
                                 Name of the image to use for networking test
  --name=NAME                    Agent name. Must be the same as the name of the local serf node
                                 RPC address of the local serf node
                                 Initial cluster configuration as a comma-separated list of peers
  --state-dir=STATE-DIR          Directory to store agent-specific state
  --tags=TAGS                    Define a tags as comma-separated list of key:value pairs
                                 List of etcd endpoints (http://host:port), comma separated
  --etcd-cafile=ETCD-CAFILE      SSL Certificate Authority file used to secure etcd communication
  --etcd-certfile=ETCD-CERTFILE  SSL certificate file used to secure etcd communication
  --etcd-keyfile=ETCD-KEYFILE    SSL key file used to secure etcd communication
                                 Database to connect to
  --influxdb-user=INFLUXDB-USER  Username to use for connection
                                 Password to use for connection
  --influxdb-url=INFLUXDB-URL    URL of the InfluxDB endpoint

$ satellite agent --name=my-host --tags=role:master

$ satellite help status
usage: satellite status [<flags>]

Query cluster status

  --help           Show context-sensitive help (also try --help-long and --help-man).
  --debug          Enable verbose mode
  --rpc-port=7575  Local agent RPC port
  --pretty         Pretty-print the output
  --local          Query the status of the local node

You can then query the status of the cluster or that of the local node by issuing a status query:

$ satellite status --pretty

resulting in:

   "status": "degraded",
   "nodes": [
         "name": "example.domain",
         "member_status": {
            "name": "example.domain",
            "addr": "",
            "status": "alive",
            "tags": {
               "role": "node"
         "status": "degraded",
         "probes": [
               "checker": "docker",
               "status": "running"
   "timestamp": "2016-03-03T12:19:44.757110373Z",
   "summary": "master node unavailable"

Out of the box, the agent requires at least a single master node (agent with role:master). The test will mark the cluster as degraded if no master is available.

Connect the agent to InfluxDB database monitoring:

$ satellite agent --tags=role:master \
	--state-dir=/var/run/satellite \
	--influxdb-database=monitoring \