snap collector plugin - kubestate

This plugin collects metrics from Kubernetes about the state of pods, nodes and deployments.

It's used in the snap framework.

1. Getting Started

• System Requirements
• Installation
• Configuration and Usage

2. Documentation

• Collected Metrics
• Examples
• Roadmap

3. Contributing
4. License
5. Acknowledgements

Getting Started

System Requirements

• golang 1.5+ (needed only for building)

Operating systems

All OSs currently supported by snap:

• Linux/amd64
• Darwin/amd64

Installation

This plugin monitors Kubernetes so you need a Kubernetes cluster to monitor. A quick way to get a local test cluster installed is to use Minikube.

This plugin is included in the Raintank Docker image for Kubernetes if you want to see an example of how to easily deploy it as pod to Kubernetes.

This plugin and the above Docker image are used to collect metrics for the Grafana Kubernetes App.

Download kubestate plugin binary:

You can get the pre-built binaries at GitHub Releases page.

To build the plugin binary:

Fork https://github.com/grafana/snap-plugin-collector-kubestate Clone repo into $GOPATH/src/github.com/grafana/:

$ git clone https://github.com/<yourGithubID>/snap-plugin-collector-kubestate.git

Build the plugin by running make within the cloned repo:

$ ./build.sh

This builds the plugin binary in /build/

This plugin uses govendor to manage dependencies. If you want to add a dependency, then:

1. Install govendor with: go get -u github.com/kardianos/govendor
2. govendor fetch <dependency path> e.g. govendor fetch k8s.io/client-go/tools/clientcmd/[email protected] The ... means install all sub dependencies.
3. govendor install to update the vendor.json file.
4. Check in the new dependency that will be in the vendor directory.

Configuration and Usage

• Set up the snap framework

• Ensure $SNAP_PATH is exported export SNAP_PATH=$GOPATH/src/github.com/intelsdi-x/snap/build

• If running the task outside of a kubernetes cluster rather than in a pod, then the following two config variables must be set:

  • incluster expects a boolean, default is true.
  • kubeconfigpath expects a string path to the Kubernetes config file, default is empty string.

  Example of how to configure it in a json task manifest:

  "workflow": {
    "collect": {
      "metrics": {
        "/grafanalabs/kubestate/*":{}
      },
      "config": {
        "/grafanalabs/kubestate": {
          "incluster": false,
          "kubeconfigpath": "/home/user/.kube/config"
        }
      },

Documentation

There are a number of other resources you can review to learn to use this plugin:

• The Kubernetes API spec. All the metrics are fetched via the API.

Collected Metrics

This plugin has the ability to gather the following metrics:

Pods

Namespace	Description (optional)
/grafanalabs/kubestate/pod/[NODE]/[NAMESPACE]/[POD]/status/condition/ready	specifies if the pod is ready to serve requests
/grafanalabs/kubestate/pod/[NODE]/[NAMESPACE]/[POD]/status/condition/scheduled	status of the scheduling process for the pod
/grafanalabs/kubestate/pod/[NODE]/[NAMESPACE]/[POD]/status/phase/Pending	This includes time before being bound to a node, as well as time spent pulling images onto the host.
/grafanalabs/kubestate/pod/[NODE]/[NAMESPACE]/[POD]/status/phase/Running	The pod has been bound to a node and all of the containers have been started.
/grafanalabs/kubestate/pod/[NODE]/[NAMESPACE]/[POD]/status/phase/Succeeded	All containers in the pod have voluntarily terminated with a container exit code of 0, and the system is not going to restart any of these containers.
/grafanalabs/kubestate/pod/[NODE]/[NAMESPACE]/[POD]/status/phase/Failed	All containers in the pod have terminated, and at least one container has terminated in a failure.
/grafanalabs/kubestate/pod/[NODE]/[NAMESPACE]/[POD]/status/phase/Unknown	For some reason the state of the pod could not be obtained, typically due to an error in communicating with the host of the pod.
/grafanalabs/kubestate/container/[NAMESPACE]/[NODE]/[POD]/[CONTAINER]/limits/cpu/cores	The limit on cpu cores to be used by a container.
/grafanalabs/kubestate/container/[NAMESPACE]/[NODE]/[POD]/[CONTAINER]/limits/memory/bytes	The limit on memory to be used by a container in bytes.
/grafanalabs/kubestate/container/[NAMESPACE]/[NODE]/[POD]/[CONTAINER]/requested/cpu/cores	The number of requested cpu cores by a container.
/grafanalabs/kubestate/container/[NAMESPACE]/[NODE]/[POD]/[CONTAINER]/requested/memory/bytes	The number of requested memory bytes by a container.
/grafanalabs/kubestate/container/[NAMESPACE]/[NODE]/[POD]/[CONTAINER]/status/ready	specifies whether the container has passed its readiness probe
/grafanalabs/kubestate/container/[NAMESPACE]/[NODE]/[POD]/[CONTAINER]/status/restarts	number of times the container has been restarted
/grafanalabs/kubestate/container/[NAMESPACE]/[NODE]/[POD]/[CONTAINER]/status/running	value 1 if container is running else value 0
/grafanalabs/kubestate/container/[NAMESPACE]/[NODE]/[POD]/[CONTAINER]/status/terminated	value 1 if container is terminated else value 0
/grafanalabs/kubestate/container/[NAMESPACE]/[NODE]/[POD]/[CONTAINER]/status/waiting	value 1 if container is waiting else value 0

Nodes

Namespace	Description (optional)
/grafanalabs/kubestate/node/[NODE]/spec/unschedulable	Whether a node can schedule new pods.
/grafanalabs/kubestate/node/[NODE]/status/allocatable/cpu/cores	The CPU resources of a node that are available for scheduling.
/grafanalabs/kubestate/node/[NODE]/status/allocatable/memory/bytes	The memory resources of a node that are available for scheduling.
/grafanalabs/kubestate/node/[NODE]/status/allocatable/pods	The pod resources of a node that are available for scheduling.
/grafanalabs/kubestate/node/[NODE]/status/capacity/cpu/cores	The total CPU resources of the node.
/grafanalabs/kubestate/node/[NODE]/status/capacity/memory/bytes	The total memory resources of the node.
/grafanalabs/kubestate/node/[NODE]/status/capacity/pods	The total pod resources of the node.

Deployments

Namespace	Description (optional)
/grafanalabs/kubestate/deployment/[NAMESPACE]/[DEPLOYMENT]/metadata/generation	The desired generation sequence number for deployment. If a deployment succeeds should be the same as the observed generation.
/grafanalabs/kubestate/deployment/[NAMESPACE]/[DEPLOYMENT]/status/observedgeneration	The generation sequence number after deployment.
/grafanalabs/kubestate/deployment/[NAMESPACE]/[DEPLOYMENT]/status/targetedreplicas	Total number of non-terminated pods targeted by this deployment (their labels match the selector).
/grafanalabs/kubestate/deployment/[NAMESPACE]/[DEPLOYMENT]/status/availablereplicas	Total number of available pods (ready for at least minReadySeconds) targeted by this deployment.
/grafanalabs/kubestate/deployment/[NAMESPACE]/[DEPLOYMENT]/status/unavailablereplicas	Total number of unavailable pods targeted by this deployment.
/grafanalabs/kubestate/deployment/[NAMESPACE]/[DEPLOYMENT]/spec/desiredreplicas	Number of desired pods.
/grafanalabs/kubestate/deployment/[NAMESPACE]/[DEPLOYMENT]/status/deploynotfinished	If desired and observed generation are not the same, then either an ongoing deploy or a failed deploy.

Examples

Roadmap

1. Disk capacity for the cluster

Contributing

See our recommended process in CONTRIBUTING.md.

License

This plugin is released under the Apache 2.0 License.

Acknowledgements

• Author: @daniellee