Sebastian Gomez

Apr 23, 2023

Updated: Jun 25, 2026

The kubectl command

First of all, kubectl is our trusty command line tool for controlling Kubernetes clusters. It talks to the kube-apiserver in our cluster's control plane.

In the following Mermaid diagram we show how the communication process works between kubectl, the Kubernetes control plane (which includes kube-apiserver and etcd), and the administrator.

sequenceDiagram
    participant Admin as Administrator
    participant kubectl
    participant API as kube-apiserver
    participant etcd
    Admin->>kubectl: runs a kubectl command
    kubectl->>API: turns the command into an API call
    API->>etcd: queries or makes changes
    etcd-->>API: returns the information
    API-->>kubectl: answers the API call
    kubectl-->>Admin: shows the result

Let's walk through that flow step by step:

1. The administrator runs a kubectl command.
2. kubectl turns the command into an API call and talks to kube-apiserver in the control plane.
3. kube-apiserver queries etcd to read information or make changes.
4. kube-apiserver returns the API response to the administrator through kubectl.

This diagram simplifies the workflow of using kubectl to interact with a Kubernetes cluster.

Configuring kubectl

Before we can use kubectl, we need to configure it. The configuration is stored in a file inside our hidden folder called .kube, in our home directory. This file contains the list of clusters and the credentials we'll use to connect to each one of them.

Where do we get the credentials? If we're using Google Kubernetes Engine (GKE), the service provides them through the gcloud tool. We'll use the gcloud container clusters get-credentials command to fetch the credentials and connect to our GKE cluster:

gcloud container clusters get-credentials <CLUSTER_NAME> --region <REGION>

If your cluster is zonal rather than regional, replace --region <REGION> with --zone <ZONE>. This command automatically writes the matching entry into your .kube/config file.

Note: gcloud container clusters get-credentials takes the cluster name with --region (regional cluster), --zone (zonal cluster) or --location, and the active project is controlled by the global --project flag. Adjust the cluster name, region or zone, and project to your GKE environment.

The kubectl syntax

Now let's talk about how to use the kubectl command. The syntax is made up of several parts: the command, the type, the name, and the optional flags:

kubectl COMMAND TYPE NAME [FLAGS]

• COMMAND: specifies the action we want to perform, such as get, describe, logs, or exec.
• TYPE: defines the Kubernetes object the command acts on, such as pods, deployments, nodes, or other objects.
• NAME: specifies the object defined in the type.
• FLAGS: some instructions accept optional additional flags that we can include at the end of the command.

For example, to see the list of pods in our cluster, we can run:

kubectl get pods

We can also filter the list by specifying the name of a pod:

kubectl get pod my-test-app

Handy tip: using the -o yaml flag to get the output in YAML format is really valuable. It lets us capture the current state of a Kubernetes object in a YAML file, for example to recreate it in a different cluster:

>

``bash kubectl get pod my test app -o yaml ``

Suggested exercises

1. Connect to a GKE cluster with gcloud container clusters get-credentials and verify the entry was written to your .kube/config file.
2. List all the pods in your cluster, then filter by a single pod's name using kubectl get pod <NAME>.
3. Export an object's definition to YAML with -o yaml and save the output to a file so you can recreate it later.
4. Practice using --context to switch between two different clusters without touching the rest of your configuration.

3-point summary

1. kubectl is the command line tool that talks to kube-apiserver in the control plane, which in turn reads and writes to etcd.
2. The configuration lives in ~/.kube/config, and for GKE the credentials are fetched with gcloud container clusters get-credentials <CLUSTER> --region <REGION>.
3. The kubectl COMMAND TYPE NAME [FLAGS] syntax covers almost everything: create, view, delete, and export objects with -o yaml; use --kubeconfig or --context to point at the right cluster.

That's all, I hope this post is useful to you and that you can apply it to a project you have in mind. Now it's your turn to put your Kubernetes cluster management skills into practice.

Leave me a comment if it helped, if you want to add an opinion, or if you have any questions. And remember, if you liked it, you can also share it using the social links below. Good luck.