This agent acts as a controller service for managing deployments of Metrictank clusters inside of a Kubernetes cluster. It is also referred to as hm-api.


  • Creating/Updating/Deleting of hosted metrics instances, containing metrictank, graphite and tsdb-gw.
  • Interaction via HTTP API
  • Diff functionality which verifies if an existing HM instance is matching the present configuration
  • Control over rollout concurrency, to not overload Kafka by restarting all Metrictank services at once
  • Colored deployments to deploy two clusters of Metrictanks with different configurations and then switch between them
  • Customizable plans to deploy many instances of Metrictank clusters according to preset configurations


  • Only one deployment per instance may be rolling out at any given point in time, concurrent deployments in multiple waves are not allowed
  • There is currently no graphical/web based interface to edit instance settings yet, but this is planned.
  • HM-API does not manage the Kafka/Zookeeper and storage (Cassandra or Bigtable) clusters which are used by Metrictank and its surrounding services
  • HM-API does not manage the agents that collect the data which gets fed into the Metrictank clusters


Explanation of terms used in the documentation

Term Explanation
Instance A hosted metrics instance. Includes Kubernetes deployments, services and ingresses for Tsdb-Gw, Graphite, Metrictank, Carbon-Relay-Ng
Partition All the data is partitioned into partitions. In Kafka those partitions refer to Kafka partitions, in the backend stores (Cassandra / BigTable) the data is keyed by a partition key
Partitioning policy Each Metrictank handles multiple partitions. Partition assignment to Metrictanks is defined by the partitioning policy chosen for the instance. By default, the ConstantWithNoOverlap policy is used with 8 partitions per Metrictank read and write deployment and a replicationFactor set to 2, only affecting read deployments, to achieve high availability. See Concepts/Partitioning Policy for more details.
Deployment A Kubernetes Deployment, it typically manages one or more pods
Pod A Kubernetes pod, typically containing one or more docker containers
API Endpoint A URL in the HM-API HTTP API that has a specific function, as explained here
Crng Short for Carbon-Relay-Ng, the project on GitHub
Graphite The Graphite project
Tsdb-Gw The Tsdb-Gw project
Metrictank The Metrictank project