Kubectl is a command line tool for managing Kubernetes. You tell it to do things on the cluster, and it does them by calling the cluster's REST API.

Installing kubectl on mac

If you've installed Rancher Desktop, then it comes with kubectl. Test to see if you have it by running kubectl version --client.

Otherwise, the best way to install kubectl is via Homebrew. If you don't have Homebrew, install it by running the command on the Homebrew site. Once you have Homebrew, install kubectl by running brew install kubectl.

Installing kubectl on Windows

If you've installed Rancher Desktop, then it comes with kubectl. Test to see if you have it by running kubectl version --client.

If you don't have it, follow the instructions under the Windows section on this page.

Commonly used commands with kubectl

kubectl get

kubectl get displays info about objects on the cluster. For example, to get a list of Pods and their statuses, use kubectl get pods. Below is an example of what the output could look like once Pods have been created:

$ kubectl get pods
NAME                           READY   STATUS    RESTARTS   AGE
apigateway-67755dc74c-hkr7c    1/1     Running   0          37d
rev-proxy-7c7655d946-fd8rb     1/1     Running   0          40d
zipkin-6d66f9b57b-k4tgq        1/1     Running   0          2d18h

Note: The columns displayed will vary between objects—a Pod will show different columns than a Service, for example.

If you don't want to limit your responses to a specific object type, you can use kubectl get all.

-l

A useful option to use with kubectl get is -l. This allows you to filter the results on labels, which are pieces of metadata that Kubernetes objects can have. The argument follows the structure -l <label-key>=<label-value>. For example:

kubectl get pods -l category=microservice

This will only show in the results Pods that have "microservice" as the value for the label "category". Most labels will be the ones you designate when configuring your objects, but there are some that Kubernetes will attach to an object by default.

-o

The -o argument has many different flavors, and each of these changes the output of kubectl get in its own way.

  • -o wide: this adds extra columns to the output. The exact columns added vary depending on what object you're querying. For example: kubectl get pods -o wide
  • -o json: this shows instead a detailed, JSON-format output. This is useful for feeding the output of kubectl get into programs that can parse JSONs. For example: kubectl get pods -o json
  • -o yaml: this is like -o json, except the output format is YAML instead of JSON. For example: kubectl get pods -o yaml

Note: They are beyond the scope of this document, and unnecessary for using Kubernetes, but if you want to customize the output of kubectl get even more, check out the -o jsonpath and -o custom-columns flavors.

kubectl apply

kubectl apply is the command you'll use to add new object configurations to the cluster, or to change existing configuration.

When writing object configurations, you'll typically do it in YAML files known as manifests. These files will contain all the details the cluster needs in order to implement the objects they specify. Once you've written this file, use the following to send it to the Kubernetes cluster:

kubectl apply -f <manifest-file-path>

For example, if the manifest is called "my-pod.yml" and it's in a "manifests" subfolder of your current folder, you can use kubectl apply -f manifests/my-pod.yml

Once kubectl apply is run, it will send the manifests to the cluster. The cluster will create these objects if they don't already exist, or will create/update/delete fields and values if they do.

Note: There also exists a kubectl create command that works similarly to kubectl apply. It's recommended to stick with kubectl apply because it won't fail if the object already exists.

kubectl delete

kubectl delete will remove object configurations from the cluster. There are two ways to use this.

The first is kubectl delete <object-type> <object-name>. For example, if you want to remove a Pod with the name "my-pod", you'd use kubectl delete pod my-pod.

The second is kubectl delete -f <manifest-file-path>. This will cause the cluster to delete the object(s) specified in the manifest. For example, if you have a manifest called "my-pod.yml" that defines a Pod you now want to delete, use kubectl delete -f my-pod.yml