Writing a Kube Macro
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.
As the third post of KubeMacro series, in this post, I will show you how to write a kube macro.
When to Write Your Own Kube Macro
KubeMacro is essentially runner of kube macro. It does not bundle any pre-defined macros by default. You can explore and install macro shared by other people from KubeMacro Hub.
If the existing macros can not fulfill your requirement, you can also write your own macro. In this post, I will work you through the steps to write a macro to print a list of pods with their containers. Also, you are very welcome to submit your macro to KubeMacro Hub so other people can get benefit from your work too.
Create a shell script file
First, Let’s create a shell script file called
get-pod-containers.sh and put it into
$HOME/.kubemacro directory. This is where KubeMacro loads the macros. Each time when KubeMacro is started, it finds all
.sh files in this directory and load them as macros.
The macro in the file is implemented as a shell function. In your case, it is the function
get-pod-containers and right now the function body is empty:
#!/bin/bashfunction get-pod-containers {
:
}
To test the macro, run
kubectl macro, specify the function name
get-pod-containers as the macro name:
kubectl macro get-pod-containers
You will see nothing returned. This is expected. Next, let’s add something real to the function.
Implement the Macro
Here is the logic added to the
get-pod-containers function:
#!/bin/bashfunction get-pod-containers {
local args=()
local ns=''
# Parse the arguments input from command line
while [[ $# -gt 0 ]]; do
case "$1" in
-n|--namespace|-n=*|--namespace=*)
ns=$2
args+=("$1 $2")
shift
shift ;;
-A|--all-namespaces)
ns="all namespaces"
args+=("$1")
shift ;;
*)
args+=("$1")
shift ;;
esac
done
# Run kubectl get and define custom columns to include pod container names
local custom_columns="NAME:.metadata.name,CONTAINERS:.spec.containers[*].name"
if [[ $ns == "all namespaces" ]]; then
custom_columns="NAMESPACE:.metadata.namespace,$custom_columns"
fi
kubectl get pods ${args[@]} -o custom-columns=$custom_columns
}
Basically, it does two things:
- Parse the arguments input from command line.
- Run
kubectl getand define custom columns to include the pod container names extracted from pod definition by specifying the JSONPath.
Now let’s run the macro. This will list all pods with their containers in current namespace:
kubectl macro get-pod-containers
Add Comment to The Macro
So far you have implemented your macro. Pretty easy right? But there is one more thing left. To make the macro visible in the installed macro list when you run KubeMacro with
-h/--help option or without any option, you need to add one special comment ahead of the macro function.
Also, when you run
kubectl macro <macro> with
-h/--help option to print the help information for your macro, you need to prepare the information beforehand. This is also defined in the comment.
Moreover, if you want to share your macro to other people via KubeMacro Hub, to define more detailed help information for your macro is also a must-have.
The comment should start with
## and end with
##, inside which there are a few fields where the field names are all started with
@. Below is a template with detailed explanation for each field:
##
# @Name: <Input your single-line macro name here>
# @Description: <Input your single-line macro description here>
# <Input detailed description for your macro started from here>
# <It supports multiple lines and markdown syntax>
# @Author: <Input single-line author name here, support markdown syntax>
# @Usage: <Input your single-line macro usage information here>
# @Options:
# <Input help information for all your options started from here>
# <It supports multiple lines>
# @Examples:
# <Input detailed information for all examples started from here>
# <It supports multiple lines>
# @Dependencies: <Input single-line comma-separated dependencies of your macro here>
##
Here is the comment for the
get-pod-containers macro:
##
# @Name: get-pod-containers
# @Description: List the pods with their containers.
#
# This is a sample macro to demonstrate how to write a macro by your own.
# It can be used to list pods and their containers. For example, to list
# all pods and their containers in `kube-system` namespace:
# ```shell
# kubectl macro get-pod-containers -n kube-system
# NAME CONTAINERS
# coredns-6955765f44-gtx2q coredns
# coredns-6955765f44-tz96m coredns
# etcd-kind-control-plane etcd
# kindnet-4pzm7 kindnet-cni
# kube-apiserver-kind-control-plane kube-apiserver
# kube-controller-manager-kind-control-plane kube-controller-manager
# kube-proxy-b6wn8 kube-proxy
# kube-scheduler-kind-control-plane kube-scheduler
# ```
#
# @Author: [morningspace]()
# 
# @Dependencies: kubectl
##
function cluster {
...
}
To validate, run the following command to see if the macro is included in the installed macro list:
kubectl macro --help
If all goes as expected, you will see
get-pod-containers appeared in the list. Run below command to print the help information for the macro:
kubectl macro get-pod-containers --help
You will see below output which is exactly what we define in the comment as above:
get-pod-containers: List the pods with their containers
Macro Dependencies
You may notice the
@Dependencies definition in the above comment. Macro may have dependencies. For example, some macro needs
jq to parse JSON data, some macro may depend on other macro to complete the work. To run a macro, it requires its dependencies to be available at first.
When you write a macro, you can define its dependencies as needed. When KubeMacro runs a macro, it will check if it has any dependency. If it does, KubeMacro will then check the existence of the dependencies and report error if any dependency is not available.
Summary
To put all things together, the final version of the
get-pod-containers macro can be found here.
Now you see how easily and quickly to write a kube macro. Again, if you see the existing macros can not fulfill your requirement, write your own one, then submit a pull request to the GitHub repository of KubeMacro Hub. After it gets merged, all people will get benefit from your work.
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.