Popular Searches

Getting Started With Kubectl to Manage Kubernetes Clusters

Graphic showing the Kubernetes logo

Kubernetes is a container orchestration engine that lets you deploy containerised workloads in a scalable way. The official command-line utility, kubectl, provides control over your clusters and the resources within.

Installing Kubectl

kubectl is supported on Linux, macOS and Windows. Several distribution formats are offered depending on the platform. Precompiled binaries are produced for all supported operating systems and made available via direct download links.

You’ll also find kubectl within the Snap, Homebrew, Chocolatey and Scoop package managers. It can be installed via apt and yum by adding the Google Cloud repository to your system. Finally, kubectl is also provided with the Google Cloud SDK – if you already have that installed, run gcloud components install kubectl to download the tool.

You should refer to the official installation guide to see the available options for your system. Installation steps can change over time so review the documentation before reinstalling kubectl.


Configuration is stored within the .kube directory in your home folder. The default configuration file is ~/.kube/config.

You can add additional files to this folder. They’ll be merged together into the final configuration used during runtime. If you want to use a specific configuration file, or a different set of files, you need to set the --kubeconfig flag or the KUBECONFIG environment variable.

kubectl --kubeconfig=/example/file get pods
# OR
KUBECONFIG=/example/file kubectl get pods

All paths written within configuration files are resolved relative to the file’s own location. Paths passed to command-line flags are resolved relative to your working directory. You can view the final configuration which will be used by kubectl by running kubectl config view.

Command line flags are supported for some settings. These let you override your configuration files. Available flags include --server (cluster URL), --username (username to connect as), --password, --token (API token) and --namespace (select the cluster namespace to interact with).


Within configuration files, you can define multiple “contexts.” These allow you to group frequently used “access parameters,” such as cluster URL and user accounts, under a named reference.

To configure per-context settings, use kubectl config set-context my-context --cluster=my-app --namespace=production. This example would create a new context called my-context that defines default settings for the Kubernetes cluster and namespace to work with.

Contexts are applied using the kubectl config use-context my-context command. Any further invocations of kubectl would use the parameters of the my-context context, so you’d be connected to the my-app cluster in the production namespace.

Effective use of contexts considerably simplifies interactions with kubectl. Without them, you have to manually create unique configuration files that are switched using the KUBECONFIG flag or environment variable.

Interacting With Your Cluster

Most kubectl commands use the same basic format:

kubectl command type name

The command is the operation you want to perform – usually create, get, describe or delete. The type is the kind of resource you’re going to interact with, such as pod or deployment. You may use either the singular or plural form.

The name component should be the name of the resource you’re referencing. You can specify multiple names, separated by spaces, to get output in bulk. It’s also possible to use the -f flag to specify the path to a JSON or YAML file containing a list of resource names.

Here’s some example commands, all of which work against your currently selected context:

  • kubectl get pods – Get the details of all your pods
  • kubectl get pod my-pod – Get the details of the pod called my-pod
  • kubectl get pod my-pod another-pod – Get the details of the pods named my-pod and another-pod
  • kubectl get pod/my-pod deployment/my-deployment – Retrieve the details of the pod called my-pod and the deployment called my-deployment – this syntax variation allows you to retrieve multiple resource types with one command
  • kubectl delete pod my-pod – Delete the pod called my-pod
  • kubectl logs my-pod – Get log output from the my-pod pod
  • kubectl apply -f ./manifest.yml – Apply a patch to your cluster from the Kubernetes manifest stored in manifest.yml

Commands are available for all the resource types offered by your Kubernetes cluster. This even extends to custom resource definitions; they integrate with the Kubernetes API and get their own RESTful endpoints which kubectl can access.

A complete kubectl command reference is available within the Kubernetes documentation. There’s also a cheat sheet of commonly used commands when working with typical resource types.

Output Formats

Output is usually emitted as a formatted list or table. This presents information in a human-readable style which you can quickly skim through.

Several alternative output options are available. You can switch to a different formatter using the -o (or --output) flag.

The json output style displays the JSON representation of the Kubernetes API resource you’re accessing. Similarly, yaml gives you the resource’s data as a YAML representation.

When using the human-readable style, you can specify the table columns to include using the custom-columns style. Provide a comma-separated list of column name and value reference pairs:

kubectl get pods -o custom-columns=NAME:.metadata.name,NAMESPACE:.metadata.namespace

This would display the name and namespace of each pod in columns labelled NAME and NAMESPACE respectively. Instead of writing columns inline in your command, you can define them in a file and pass it to --custom-columns-file.

There’s built-in support for sorting output by the value of a particular field. Use --sort-by, passing the field’s reference:

kubectl get pods --sort-by=.metadata.name

Sorting supports JSONPath expressions. These can also be used to construct filtered queries using the jsonpath formatter. JSONPath is a query language for JSON objects which lets you more directly manipulate Kubernetes API queries in kubectl.

Using Within Scripts

kubectl is intended for both direct human interaction and programmatic invocation via scripts. There are some best practices you should follow when scripting kubectl to ensure predictable output.

Fully qualify references to resource types so that they’re pinned to a particular version – e.g. pods.v1.core/my-job instead of pods my-job. This minimises the risk of Kubernetes updates breaking your script.

Access configuration should be passed directly from your script to kubectl, ensuring you’re not dependent on the outside environment. This further reduces the risk of breakage due to kubectl updates – features such as contexts may change over time, while it’s less likely core command-line arguments will.

Finally, make sure you disable human-readable output and use the JSON or YAML formatter instead. This gives your script machine-oriented data to work with, so you won’t need to parse tables yourself.


kubectl is the go-to solution for managing a Kubernetes cluster. It’s a comprehensive tool with full support for the platform’s capabilities.

The breadth of functionality makes for a lengthy command list but the clear separation between action type, resource type and resource name helps keep usage simple and memorable. If in doubt, you can install shell autocompletion to help you find an appropriate command.

James Walker James Walker
James Walker is a contributor to CloudSavvy IT. He is the founder of Heron Web, a UK-based digital agency providing bespoke software development services to SMEs. He has experience of managing complete end-to-end web development workflows, using technologies including Linux, GitLab, Docker and Kubernetes. Read Full Bio »

The above article may contain affiliate links, which help support CloudSavvy IT.