A Quick Introduction to KubeMacro

KubeMacro is a kubectl plugin used to run kube macro (macro for short) that wraps multiple kubectl calls or Kubernetes API calls into one command that you can run from command line. It is an open source project hosted on GitHub.

This is my first post of KubeMacro series. In this post, I will give you a quick introduction to KubeMacro, including what KubeMacro is, the idea behind it, how to install it, and run it by examples.

What is KubeMacro?

KubeMacro is designed as a kubectl plugin to run kube macro (or macro for short) that wraps a set of kubectl calls or Kubernetes API calls into one command that you can run from the command line as many times as you want. Let’s see some examples how KubeMacro can help when you work with Kubernetes clusters by using kubectl.

Example 1: Restart pods associated with a Kubernetes service

If you want to restart all pods that are associated with a Kubernetes service, you may have to do the following steps one after another:

• Inspect the Kubernetes service and check the .spec.selector field.
• Use the labels defined in the .spec.selector field to query the pods associated with the service.
• Delete the pods so that Kubernetes can spin up new pods for you.

It is tedious, also inefficient, to repeat these steps manually every time when you need to restart such pods.

Example 2: Delete a namespace stuck in terminating status

To delete a namespace that is stuck in Terminating status is not a trivial task as you might imagine. You will need to understand:

• Why the namespace keeps terminating.
• Whether you should enumerate API resources in this namespace and delete them at first before you try to force delete the namespace.
• If we decide to force delete, how to get it done by removing the namespace finalizers.

All the above topics deserve a dedicated document including step by step instructions with caveats.

Using KubeMacro

As you can see, when work with clusters using kubectl to complete routine tasks, it is common that many of these tasks can not be done by just executing one or two kubectl commands. Some of them are complicated enough that require to be documented.

The idea of KubeMacro is quite straightforward. It encapsulates one or more kubectl calls or Kubernetes API calls into an executable block, such as a shell function, with some best practices embedded, and call it as kube macro (or macro for short). Each macro is aimed to address a specific problem and usually one or more kubectl calls or Kubernetes API calls will be involved with additional code logic around in order to complete the task.

By using a macro, you can run it as a single unit of work as many times as you want. This allows you to work with your Kubernetes cluster more efficiently and less error prone.

Install KubeMacro

KubeMacro 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 KubeMacro just as normal kubectl <command>.

To install KubeMacro, you can download it from the GitHub repository then make it executable as below:

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

Place the script anywhere in your PATH. For example:

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

You may now invoke KubeMacro as a kubectl command:

kubectl macro

As a result, you will see the general help information of KubeMacro.

Install a kube macro

KubeMacro is essentially a runner that executes kube macros. By default, there is no macro distributed along with KubeMacro. After install KubeMacro, you need to install specific macro to complete Kubernetes routine tasks. This can be done by visiting KubeMacro Hub, a website that hosts awesome macros shared by other people, you can explore these macros and install any one as you like.

Below are some recommended macros that you can start with:

• get-apires: Get API resources in a namespace.
• get-by-owner-ref: Get resource in a namespace along with its ancestors via owner references.
• get-pod-by-svc: Get all pods associated with a service.
• get-pod-not-ready: Get the pods that are not ready.
• get-pod-restarts: Get the pods that the restart number matches specified criteria.
• get-pod-status: Get the pods that pod status matches specified criteria.

Here let’s use get-pod-by-svc as an example to demonstrate how to install a macro.

To install a macro is fairly easy. You can go to the macro page on KubeMacro Hub, in this case, it is get-pod-by-svc, then, switch to the Code tab, follow the instructions on the tab to click the download link, or to copy the code into a local file named as get-pod-by-svc.sh, put it in $HOME/.kubemacro directory. That’s it. KubeMacro will scan the directory and pick up all macros installed underneath.

After install the macro, to validate the installation:

kubectl macro get-pod-by-svc --help

You will see the help information that is specific to this macro. Besides the help information displayed from the command line, you can also check the Description tab on the macro page on KubeMacro Hub where it gives you more information on what this macro is for and how to use it.

For the macro get-pod-by-svc , as it describes above, it is used to get all pods associated with a Kubernetes service. As an example, below command is to list all pods associated with prometheus-adapter service in openshift-monitoring namespace and output only the pod names.

kubectl macro get-pod-by-svc prometheus-adapter -n openshift-monitoring -o name

Summary

Now that you have learned how to install KubeMacro, install and run macros, it is recommended to go to KubeMacro Hub, look around for the macros that you are interested in, then pick up one or two to give a try. Enjoy yourself!

In next post, I will share with you more on KubeMacro Hub and some interesting macros that can help you manage your Kubernetes cluster effectively.

You can learn more on KubeMacro 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.