A Quick Introduction to KubeAssert

KubeAssert is a kubectl plugin used to make assertions against resources on your Kubernetes cluster from command line. It is an open source project that I created on GitHub.

This is my first post of KubeAssert series. In this post, I will give you a quick introduction to KubeAssert is, how to install it, and what types of assertions it supports out of the box. At the end, I will show you examples on how to use assertions to help you manage your Kubernetes cluster.

What is KubeAssert

KubeAssert is designed as a kubectl plugin to provide a set of assertions that can be used to effectively assert Kubernetes resources from the command line against your working cluster.

Using KubeAssert can help you validate cluster status, application installation, deployment healthiness, and trouble shoot problems existed in your cluster. For example, you can validate:

• If a resource should or should not exist in the cluster;
• If the status of a resource should or should not include an expected value;
• if the instance number of a resource should be less than or no more than an expected value;

To make assertions using KubeAssert is as same as you make assertions using xUnit in your code. Further more, a set of assertions can be put together in a script, which can be integrated into CI/CD pipeline as part of the automated verification test to your cluster.

Install KubeAssert

KubeAssert can be run as a standalone command from the command line since essentially it is a script. But it can also be installed as a kubectl plugin so that you can run KubeAssert just as normal kubectl <command>.

KubeAssert has been submitted to krew as a kubectl plugin distributed on the centralized krew-index, so the easiest way to install KubeAssert is using krew:

krew install assert

If you do not have krew installed, you can also install KubeAssert separately which is also very easy. You can download it from the GitHub repository then make it executable as below:

curl -L https://raw.githubusercontent.com/morningspace/kubeassert/master/kubectl-assert.sh -o kubectl-assert
chmod +x kubectl-assert

Place the script anywhere in your PATH. For example:

mv ./kubectl-assert /usr/local/bin

You may now invoke KubeAssert as a kubectl command:

kubectl assert

As a result, you will see the general help information and a list of assertions that are supported by KubeAssert out of the box. Run the command with a specified assertion along with --help option, you will see more information on how to use each assertion. For example:

kubectl assert exist --help

Using KubeAssert

Below is a list of all available assertions that are supported by KubeAssert out of the box:

• exist: Assert resource should exist.
• not-exist: Assert resource should not exist.
• exist-enhanced: Assert resource should exist using enhanced field selector.
• not-exist-enhanced: Assert resource should not exist using enhanced field selector.
• num: Assert the number of resource should match specified criteria.
• pod-ready: Assert pod should be ready.
• pod-not-terminating: Assert pod should not keep terminating.
• pod-restarts: Assert pod restarts should match specified criteria.
• apiservice-available: Assert API service should be available.

Here are some examples to demonstrate how to use these assertions to help manage your Kubernetes cluster on a daily basis.

To verify if there is any pod with app label equal to echo existed in foo namespace, you can run below command:

kubectl assert exist pods -l app=echo -n foo

To verify if all pods on your cluster are ready to serve requests:

kubectl assert pod-ready --all-namespaces

To verify the restarts of your pods are less than a specified value:

kubectl assert restarts pods -n foo -lt 10

Summary

You see it is very easy to use KubeAssert, isn’t? Just try it out and have fun! In next post, I will show you more tips and traps on how to use KubeAssert in an effective way.

You can learn more on KubeAssert by reading its online documents. If you like it, you can consider to give star to this project . Also, any contributions such as bug report and code submission are very welcome.