README.md

kubespy: tools for observing Kubernetes resources in real time

What happens when you boot up a Pod? What happens to a Service before it is allocated a public IP address? How often is a Deployment's status changing?

kubespy is a small tool that makes it easy to observe how Kubernetes resources change in real time, derived from the work we did to make Kubernetes deployments predictable in Pulumi's CLI. Run kubespy at any point in time, and it will watch and report information about a Kubernetes resource continuously until you kill it.

Examples

kubespy status v1 Pod nginx will wait for a Pod called nginx to be created, and then continuously emit changes made to its .status field,as syntax-highlighted JSON diffs:

kubespy trace service nginx will "trace" the complex changes a complex Kubernetes resource makes in the cluster (in this case, a Service called nginx), and aggregate them into a high-level summary, which is updated in real time.

Installation

kubespy depends on:

• Go
• dep

Once installed, run the following:

go get github.com/pulumi/kubespy/...
cd "$(go env GOPATH)/src/github.com/pulumi/kubespy"
dep ensure

# If $GOBIN is not on your path, you'll need to install the library elsewhere.
go install github.com/pulumi/kubespy/cmd/kubespy

From here you can simply run kubespy.

Usage

kubespy has two commands:

• status <apiVersion> <kind> [<namespace>/]<name>, which in real time emits all changes made to the .status field of an arbitrary Kubernetes resource, as a JSON diff.
• changes <apiVersion> <kind> [<namespace>/]<name>, which in real time emits all changes to any field in a Kubernetes resource, as a JSON diff.
• trace <kind> [<namespace>/]<name>, which "traces" the changes a complex Kubernetes resource makes throughout a cluster, and aggregates them into a high-level summary, which is updated in real time.

Several more commands are planned as well.

Examples

For a concrete example you can run using either Pulumi or kubectl, check out examples/trivial-pulumi-example.

Features

• Supports any resources the API server knows about, including CRDs (i.e., uses the discovery client to discover the available API resources, and allows users to query any of them).
• Displays changes to API objects in real time.
• Supports case-insensitive aliases (e.g. kubespy status v1 pod <name> instead of kubespy status v1 Pod <name>).
• Supports status updates from regex and/or fuzzy matching (i.e., make it easy to watch the status of Pods generated by Deployments and ReplicaSets).