How to Use kubectl More Effectively: A Detailed Guide

Let's look at a simple example:

$ kubectl get pods -o custom-columns='NAME:metadata.name'

NAME
engine-544b6b6467-22qr6
engine-544b6b6467-lw5t8
engine-544b6b6467-tvgmg
web-ui-6db964458-8pdw4

The output contains one column with the pod names.

The expression in the option selects the pod names from the field metadata.name. This is because the pod name is defined in the child field name of the metadata in the pod resource description. You can read more in the API documentation or type the command kubectl explain pod.metadata.name.

Now suppose you want to add an additional column to the output, for example, showing the node on which each pod is running. To do this, you can simply add the appropriate column specification to the custom columns option:

$ kubectl get pods 
  -o custom-columns='NAME:metadata.name,NODE:spec.nodeName'

NAME                       NODE
engine-544b6b6467-22qr6    ip-10-0-80-67.ec2.internal
engine-544b6b6467-lw5t8    ip-10-0-36-80.ec2.internal
engine-544b6b6467-tvgmg    ip-10-0-118-34.ec2.internal
web-ui-6db964458-8pdw4     ip-10-0-118-34.ec2.internal

The expression selects the node name from spec.nodeName — when the pod is assigned to a node, its name is recorded in the field spec.nodeName of the pod's resource specification. More detailed information can be found in the output of kubectl explain pod.spec.nodeName.

Note that Kubernetes resource fields are case-sensitive.

You can view any resource field as a column. Just review the resource specification and try it with any fields you like.

But first, let's take a closer look at field selection expressions.

JSONPath expressions

Expressions for selecting resource fields are based on JSONPath.

JSONPath is a language for querying data from JSON documents. Selecting a single field is the simplest use case of JSONPath. It has much more capabilities, including selectors, filters, and so on.

Kubectl explain supports a limited number of JSONPath capabilities. Below are the capabilities and examples of their usage:

# Выбрать все элементы списка
$ kubectl get pods -o custom-columns='DATA:spec.containers[*].image'
# Выбрать специфический элемент списка
$ kubectl get pods -o custom-columns='DATA:spec.containers[0].image'
# Выбрать элементы списка, попадающие под фильтр
$ kubectl get pods -o custom-columns='DATA:spec.containers[?(@.image!="nginx")].image'
# Выбрать все поля по указанному пути, независимо от их имени
$ kubectl get pods -o custom-columns='DATA:metadata.*'
# Выбрать все поля с указанным именем, вне зависимости от их расположения
$ kubectl get pods -o custom-columns='DATA:..image'

The operator [] is particularly important. Many Kubernetes resource fields are lists, and this operator allows you to select elements from these lists. It is often used with a wildcard like [*] to select all elements of the list.

Application examples

The possibilities for using custom column output formats are limitless, as you can display any field or combination of resource fields in the output. Here are some examples of applications, but feel free to explore them yourself and find useful applications for you.

1. Displaying container images for pods:

   $ kubectl get pods 
     -o custom-columns='NAME:metadata.name,IMAGES:spec.containers[*].image'
   
   NAME                        IMAGES
   engine-544b6b6467-22qr6     rabbitmq:3.7.8-management,nginx
   engine-544b6b6467-lw5t8     rabbitmq:3.7.8-management,nginx
   engine-544b6b6467-tvgmg     rabbitmq:3.7.8-management,nginx
   web-ui-6db964458-8pdw4      wordpress

   This command displays the names of the container images for each pod.

   Remember that a pod can contain multiple containers; in this case, the image names will be listed in one line, separated by commas.

2. Displaying availability zones of nodes:

   $ kubectl get nodes 
     -o 
   custom-columns='NAME:metadata.name,ZONE:metadata.labels.failure-domain.beta.kubernetes.io/zone'
   
   NAME                          ZONE
   ip-10-0-118-34.ec2.internal   us-east-1b
   ip-10-0-36-80.ec2.internal    us-east-1a
   ip-10-0-80-67.ec2.internal    us-east-1b

   This command is useful if your cluster is hosted in a public cloud. It shows the availability zone for each node.

   An availability zone is a cloud concept that restricts the replication zone to a geographical region.

   Availability zones for each node are obtained via a special label — failure-domain.beta.kubernetes.io/zone. If the cluster is running in a public cloud, this label is automatically created and filled with the names of availability zones for each node.

   Labels are not a part of the Kubernetes resource specifications, so you won't find information about them in API documentation. However, they can be seen (like any other labels) if you request information about nodes in YAML or JSON format:

   $ kubectl get nodes -o yaml
   # or
   $ kubectl get nodes -o json

   This is a great way to learn more about resources, in addition to studying resource specifications.

4. Easy Switching Between Clusters and Namespaces

When kubectl makes a request to the Kubernetes API, it first reads the kubeconfig file to get all the necessary parameters for the connection.

By default, the kubeconfig file is ~/ .kube / config. Usually, this file is created or updated by a special command.

When working with multiple clusters, your kubeconfig file contains connection parameters for all these clusters. You need a way to specify to the kubectl command which cluster you are working with.

Within a cluster, you can create multiple namespaces — a type of virtual cluster within a physical cluster. Kubectl determines which namespace to use based on the kubeconfig file data. This means you also need a way to specify to the kubectl command which namespace to work with.

In this chapter, we will explain how this works and how to achieve effective operation.

Note that you can have multiple kubeconfig files listed in the KUBECONFIG environment variable. In this case, all these files will be merged into a single shared configuration during execution. You can also change the default kubeconfig file by running kubectl with the parameter --kubeconfig. See the official documentation.

Kubeconfig files

Let's take a look at what the kubeconfig file actually contains:

As you can see, the kubeconfig file contains a set of contexts. A context consists of three elements:

• Cluster — the API server URL for the cluster.
• User — the authentication credentials for the user in the cluster.
• Namespace — the namespace used when connecting to the cluster.

In practice, it is common to use one context per cluster in your kubeconfig file. However, you can have multiple contexts for a cluster that differ by user or namespace. Such a multi-context configuration is rare, so usually, there is a one-to-one mapping between clusters and contexts.

At any given time, one of the contexts is current:

When kubectl reads the configuration file, it always takes information from the current context. In the example above, kubectl will connect to the Hare cluster.

Therefore, to switch to a different cluster, you need to change the current context in the kubeconfig file:

Now kubectl will connect to the Fox cluster.

To switch to another namespace in the same cluster, you need to change the value of the namespace element for the current context:

In the example above, kubectl will use the Prod namespace of the Fox cluster (the Test namespace was previously set).

Note that kubectl also provides parameters --cluster, --user, --namespace and --context, which allow you to override individual elements and the current context itself, regardless of what is set in the kubeconfig file. See kubectl options.

In theory, you can manually change parameters in the kubeconfig file. But this is inconvenient. To simplify these operations, there are various utilities that allow you to change parameters automatically.

Use kubectx

A very popular utility for switching between clusters and namespaces.

The utility provides commands kubectx and kubens to change the current context and namespace accordingly.

As mentioned, changing the current context means changing the cluster if you have only one context per cluster.

Here is an example of executing these commands:

Essentially, these commands simply edit the kubeconfig file as described above.

To install kubectx, follow the instructions on Github.

Both commands support autocompletion of context and namespace names, allowing you not to type them fully. Instructions for setting up autocompletion here.

Another useful feature kubectx is interactive mode. It works together with the utility fzf, which needs to be installed separately. Installing fzf automatically makes the interactive mode available in kubectx. In interactive mode, you can choose the context and namespace through the interactive fuzzy-search interface provided by fzf.

Using shell command aliases

You don’t need separate tools to change the current context and namespace because kubectl also provides commands for this. Thus, the command kubectl config provides subcommands to edit kubeconfig files.

Here are some of them:

• kubectl config get-contexts: list all contexts;
• kubectl config current-context: get the current context;
• kubectl config use-context: change the current context;
• kubectl config set-context: change the context item.

However, using these commands directly is not very convenient because they are long. You can create shell command aliases for them that are easy to execute.

I created a set of aliases based on these commands that provide functionality similar to kubectx. Here you can see them in action:

Note that the aliases utilize fzf to provide an interactive fuzzy-search interface (like in the interactive mode of kubectx). This means you need to install fzf, to use these aliases.

Here are the alias definitions themselves:

# Получить текущий контекст
alias krc='kubectl config current-context'
# Список всех контекстов
alias klc='kubectl config get-contexts -o name | sed "s/^/  /;|^  $(krc)$|s/ /*/"'
# Изменить текущий контекст
alias kcc='kubectl config use-context "$(klc | fzf -e | sed "s/^..//")"'

# Получить текущее пространство имен
alias krn='kubectl config get-contexts --no-headers "$(krc)" | awk "{print $5}" | sed "s/^$/default/"'
# Список всех пространств имен
alias kln='kubectl get -o name ns | sed "s|^.*/|  |;|^  $(krn)$|s/ /*/"'
# Изменить текущее пространство имен
alias kcn='kubectl config set-context --current --namespace "$(kln | fzf -e | sed "s/^..//")"'

To set up these aliases, you need to add the definitions above to your file ~/ .bashrc or ~/ .zshrc and restart your shell.

Using plugins

Kubectl allows loading plugins that are executed similarly to the main commands. For example, you can install the kubectl-foo plugin and run it by executing the command kubectl foo.

It would be convenient to change the context and namespace this way, for example, to run kubectl ctx to change the context and kubectl ns to change the namespace.

I wrote two plugins that do this:

• kubectl-ctx
• kubectl-ns

The plugins work based on the aliases from the previous section.

Here's how they work:

Note that the plugins use fzf to provide an interactive fuzzy search interface (like in the interactive kubectx mode). This means you need install fzf, to use these aliases.

To install the plugins, you need to download the shell scripts named kubectl-ctx and kubectl-ns to any directory in your PATH variable and make them executable, for example, using chmod +x. Right after that, you will be able to use kubectl ctx and kubectl ns.

5. Input Shortcut with Auto-Aliases

Shell command aliases are a good way to speed up input. The project kubectl-aliases contains about 800 shortcuts for the main kubectl commands.

You may wonder—how to remember 800 aliases? But you don’t need to remember them all, as they are built on a simple pattern outlined below:

For example:

1. kgpooyaml — kubectl get pods oyaml
2. ksysgsvcw — kubectl -n kube-system get svc w
3. ksysrmcm — kubectl -n kube-system rm cm
4. kgdepallsl — kubectl get deployment all sl

As you can see, aliases consist of components, each representing a specific part of the kubectl command. Each alias can have one component for the base command, operation, and resource, and several components for parameters. You simply 'fill' these components from left to right according to the pattern provided above.

The current detailed pattern can be found at GitHub. There, you can also find the full list of aliases..

For example, the alias kgpooyamlall is equivalent to the command kubectl get pods -o yaml --all-namespaces.

The relative order of options does not matter: the command kgpooyamlall is equivalent to the command kgpoalloyaml.

You can choose not to use all components as aliases. For example, k, kg, klo, ksys, kgpo can also be used. Moreover, you can combine aliases and regular commands or options in the command line:

For example:

1. Instead of kubectl proxy can be written as k proxy.
2. Instead of kubectl get roles can be written as kg roles (currently, there is no alias for the resource Roles).
3. To get data for a specific pod, you can use the command kgpo my-pod — kubectl get pod my-pod.

Keep in mind that some aliases require arguments in the command line. For example, the alias kgpol means kubectl get pods -l. The option -l requires an argument — a label specification. If you use an alias, it will look like kgpol app=ui.

Because some aliases require arguments, the aliases a, f, and l should be used last.

In general, once you master this scheme, you'll be able to intuitively derive aliases from the commands you want to execute, saving you a lot of time on input.

Installation

To install kubectl-aliases, you need to download the file .kubectl_aliases from GitHub and source it in your file ~/ .bashrc or ~/ .zshrc:

source ~/.kubectl_aliases

Autocomplete

As we mentioned, you often add additional words to the alias in the command line. For example:

$ kgpooyaml test-pod-d4b77b989

If you use kubectl command autocompletion, you have probably used autocompletion for things like resource names. But can this be done when using aliases?

This is a very important question because if autocompletion doesn't work, you'll lose some of the benefits of aliases.

The answer depends on which command shell you are using:

1. For Zsh, autocompletion for aliases works out of the box.
2. For Bash, unfortunately, some actions are required to make autocompletion work.

Enabling autocompletion for aliases in Bash

The issue with Bash is that it tries to complete the alias (every time you press Tab) instead of the command the alias points to (as Zsh does). Since you don't have completion scripts for all 800 aliases, autocompletion does not work.

Project complete-alias provides a general solution to this issue. It hooks into the completion mechanism for aliases, internally completes the alias to the command, and returns completion options for the completed command. This means that completion for an alias behaves exactly like for a full command.

Next, I will first explain how to install complete-alias, and then how to configure it to enable completion for all kubectl aliases.

Installing complete-alias

First of all, complete-alias depends on bash-completion. So before installing complete-alias, ensure that bash-completion is installed. Installation instructions were provided earlier for Linux and MacOS.

An important note for MacOS users: like the kubectl autocompletion script, complete-alias does not work with Bash 3.2, which is the default on MacOS. In particular, complete-alias depends on bash-completion v2.brew install bash-completion@2), which requires at least Bash 4.1. This means that to use complete-alias on MacOS, you need to install a newer version of Bash.

You need to download the script bash_completion.sh from from the GitHub repository and include it in your file ~/ .bashrc:

source ~/bash_completion.sh

After restarting the command shell, complete-alias will be fully installed.

Enabling autocompletion for kubectl aliases

Technically, complete-alias provides the shell function _complete_alias. This function checks the alias and returns completion suggestions for the alias command.

To bind the function to a specific alias, you need to use the built-in Bash mechanism complete, to set _complete_alias as the alias completion function.

As an example, let's take the alias k, which represents the command kubectl. To set _complete_alias as the completion function for this alias, you should run the following command:

$ complete -F _complete_alias k

The result of this is that whenever you autocomplete the alias k, the function _complete_alias, which checks the alias and returns completion suggestions for the command, gets called. kubectl.

As a second example, let's take the alias kg, which represents kubectl get:

$ complete -F _complete_alias kg

Just like in the previous example, when you autocomplete kg, you receive the same completion suggestions that you would for kubectl get.

Note that complete-alias can be used for any alias in your system.

Therefore, to enable autocompletion for all kubectl aliases, you need to run the command above for each of them. The following snippet does exactly that, assuming you have installed kubectl-aliases in ~/ .kubectl-aliases:

for _a in $(sed '/^alias /!d;s/^alias //;s/=.*$//' ~/ .kubectl_aliases); 
do
  complete -F _complete_alias "$_a"
done

This piece of code needs to be placed in your ~/ .bashrc, restart the command shell and autocompletion will be available for all 800 kubectl aliases.

6. Extending kubectl with plugins

to load the favicon via HTTP if the current page is opened via HTTPS. since version 1.12, kubectl supports the plugin mechanism, which allows you to extend its functionality with additional commands.

If you are familiar with Git's plugin mechanisms, then kubectl plugins are built on the same principle.

In this chapter, we will explain how to install plugins, where to find them, and how to create your own plugins.

Installing plugins

Kubectl plugins are distributed as simple executable files named kubectl-xin the build name means that it will now be produced regularly based on the current state of the repository. In fact, prototypes have been showcased recently at the kubectl- is mandatory, followed by a new kubectl subcommand that allows you to invoke the plugin.

For example, the hello plugin would be distributed as a file named kubectl-hello.

To install the plugin, you need to copy the file kubectl-x to any directory in your PATH variable and make it executable, for example using chmod +x. Right after that, you can invoke the plugin using kubectl x.

You can use the following command to list all the plugins currently installed on your system:

$ kubectl plugin list

This command also displays warnings if you have multiple plugins with the same names, or if there is a plugin file that is not executable.

Searching and installing plugins using Krew

Kubectl plugins are suitable for sharing or reuse like software packages. But where can you find plugins shared by others?

The Krew project aims to provide a unified solution for sharing, searching, installing, and managing kubectl plugins. The project calls itself the 'package manager for kubectl plugins' (Krew is similar to Brew).

Krew is a list of kubectl plugins that you can choose and install. Moreover, Krew is also a plugin for kubectl.

This means that installing Krew works essentially like installing any other kubectl plugin. You can find detailed instructions on the GitHub page.

The most important Krew commands:

# Поиск в списке плагинов
$ kubectl krew search [<query>]
# Посмотреть информацию о плагине
$ kubectl krew info <plugin>
# Установить плагин
$ kubectl krew install <plugin>
# Обновить все плагины до последней версии
$ kubectl krew upgrade
# Посмотреть все плагины, установленные через Krew
$ kubectl krew list
# Деинсталлировать плагин
$ kubectl krew remove <plugin>

Keep in mind that installing plugins using Krew does not interfere with installing plugins in the standard way described above.

Note that the command kubectl krew list displays only those plugins that were installed using Krew, while the command kubectl plugin list lists all plugins, including those installed by Krew and those installed in other ways.

Searching for plugins elsewhere

Krew is a young project, currently in its list of about 30 plugins. If you cannot find what you need, you can look for plugins elsewhere, such as on GitHub.

I recommend checking the GitHub section kubectl-plugins. There you will find several dozen available plugins worth checking out.

Writing your own plugins

You can create your own Creating plugins — is not difficult. You need to create an executable file that does what is needed, name it like kubectl-x and install it as described above.

The file can be a bash script, python script, or a compiled go application — it doesn’t matter. The only requirement is that it must be directly executable in the operating system.

Let's create a sample plugin right now. In the previous section, you used the kubectl command to output a list of containers for each pod. You can easily turn this command into a plugin that you can call, for example, using kubectl img.

Create a file kubectl-img with the following content:

#!/bin/bash
kubectl get pods -o custom-columns='NAME:metadata.name,IMAGES:spec.containers[*].image'

Now make the file executable with chmod +x kubectl-img and move it to any directory in your PATH. Immediately after that, you can use the plugin kubectl img.

As mentioned before, kubectl plugins can be written in any programming or scripting language. If you use shell scripts, the advantage is the ability to easily call kubectl from the plugin. However, you can write more complex plugins in real programming languages using the Kubernetes client library. If you use Go, you can also use the cli-runtime library, which exists specifically for writing kubectl plugins.

How to share your plugins

If you think your plugins might be useful to others, feel free to share them on GitHub. Be sure to add them to the thread kubectl-plugins.

You can also request to add your plugin to the Krew list. Instructions on how to do this are available in the GitHub repository.

Command Autocompletion

Currently, plugins do not support autocompletion. This means you must type the full name of the plugin and the full names of the arguments.

In the GitHub repository for kubectl, there is an open request. So, it is possible that this feature will be implemented sometime in the future.

Good luck!!!

What else to read on the topic:

1. Three Levels of Auto-Scaling in Kubernetes and How to Effectively Use Them.
2. Kubernetes in Pirate Style with an Implementation Template.
3. Our Telegram channel Around Kubernetes.

Source: habr.com