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.
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
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
Configuration is stored within the
.kube directory in your home folder. The default configuration file is
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),
--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
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
kubectl commands use the same basic format:
kubectl command type name
command is the operation you want to perform – usually
type is the kind of resource you’re going to interact with, such as
deployment. You may use either the singular or plural form.
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
kubectl get pod my-pod another-pod– Get the details of the pods named
kubectl get pod/my-pod deployment/my-deployment– Retrieve the details of the pod called
my-podand 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
kubectl logs my-pod– Get log output from the
kubectl apply -f ./manifest.yml– Apply a patch to your cluster from the Kubernetes manifest stored in
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.
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
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
NAMESPACE respectively. Instead of writing columns inline in your command, you can define them in a file and pass it to
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
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.