The kubectl command

Exam guide§2.1

kubectl is the command-line utility administrators use to control a Kubernetes cluster. It talks to the kube-APIserver on the control plane: it turns your command-line entries into Kubernetes API calls, sends them to the kube-APIserver, and figures out which part of the control plane to reach. Before it can do any of that, it has to be pointed at a cluster and given credentials.

How a command reaches the cluster

Say an administrator wants to list the Pods in a cluster. Once kubectl is connected with valid credentials, they run kubectl get pods:

An admin runs "kubectl get pods"; kubectl sends an API call over HTTPS to the cluster control plane's kube-apiserver, which queries etcd and returns an API response over HTTPS that kubectl renders as the results.

1. kubectl converts the command into an API call and sends it over HTTPS to the kube-APIserver on the cluster's control plane.
2. The kube-APIserver processes the request by querying etcd for the state.
3. It returns the results to kubectl over HTTPS.
4. kubectl interprets the response and prints it at the command prompt.

Configuration

kubectl stores its own configuration in $HOME/.kube/config, a hidden file in your home directory. That file holds the list of clusters and the credentials attached to each one. The credentials themselves come from GKE, delivered by the gcloud command.

To connect kubectl to a GKE cluster, first fetch the credentials with gcloud container clusters get-credentials (see Working with clusters for the full command set). This works in any environment where both gcloud and kubectl are installed - both ship by default in Cloud Shell.

≡Factskubeconfig facts

• Config path: $HOME/.kube/config (hidden .kube folder in the home directory).
• Contents: the list of clusters + the credentials attached to each.
• Credentials source: GKE, delivered through the gcloud command.
• View the config: open the file, or run kubectl config view.
• get-credentials only needs to run once per cluster in Cloud Shell - the .kube directory persists in $HOME. Rerunning it for a different cluster updates the file with that cluster's credentials.

⚠Gotcha`kubectl config` describes kubectl, not the cluster

kubectl config view shows the configuration of the kubectl command itself (clusters, contexts, credentials). Every other kubectl command (get, describe, …) shows the configuration of the cluster and its workloads. Don't confuse the two.

⚠Gotchakubectl administers, gcloud provisions

kubectl manages the internal state of an existing cluster. It cannot create new clusters or change the shape (node count, machine type) of existing ones - that is done through the GKE control plane, which gcloud and the Google Cloud console talk to. After the kubeconfig is written, kubectl references it automatically and connects to the default cluster without prompting.

Command syntax

A kubectl command has four parts: command, type, name, and optional flags.

Every kubectl command reads left to right as kubectl [command] [TYPE] [NAME] [flags]: the verb (get, describe, logs, exec, …), the object type (pods, deployments, nodes, …), its name, then any flags - e.g. kubectl get pod my-test-app -o=yaml.

• command - the action to perform: get, describe, logs, exec, … Some commands show information; others change the cluster's configuration.
• TYPE - the kind of object the command acts on: pods, deployments, nodes, or other objects (including the cluster itself).
• NAME - the specific object. Optional for listing commands: kubectl get pods lists every Pod, while kubectl get pod my-test-app returns just that one.
• flags - optional "special requests" appended to the end.

≡FactsHandy flags

• -o=yaml - print an object's full state as YAML: kubectl get pod my-test-app -o=yaml. Useful for recreating an object elsewhere.
• -o=wide - wider listing: kubectl get pods -o=wide also shows which node each Pod runs on.
• --kubeconfig / --context - override which config file or cluster the command targets, when you have not configured a default.