Before we look at the command, we need to meet five simple words: cluster, resource, API server, kubectl and namespace.

So what exactly is kubectl get?

kubectl get is a command that asks the cluster to list resources, or to show one particular resource, and prints the answer as a neat table in your terminal. For example, asking for pods lists every pod in your current namespace with its name, readiness, status, number of restarts and age.

The most important property of this command is that it is read-only. You can run it a thousand times and nothing in the cluster changes. That is why engineers use it constantly, even in production, as a safe first step to look around before deciding what to do.

A short history

Google released Kubernetes as open source in 2014. From the beginning, it needed a command-line tool so that people could work with the cluster without writing programs. That tool grew into kubectl. Its “get” verb has been there from the earliest days, and it has stayed almost unchanged, because the idea is so simple and so useful: list the things, show their state.

Over the years, the output became richer. Today kubectl can print results in many shapes, filter them by labels, sort them, and even keep watching for changes live. We will meet all of these.

A cluster is busy and mostly invisible. Applications start, stop and move around all day. Without a way to look, you would be working blind.

Why we need to look inside

A running cluster might hold hundreds of pods, dozens of services and many nodes. Pods are temporary. Kubernetes can stop one and start another in its place without asking you. The list of what exists right now is different from the list an hour ago.

So the very first questions in any situation are the same. What is running? Is it healthy? Where is it? How old is it? Did it restart? Is the new version rolled out? Every one of these begins with a “get”.

Other ways to look, and their limits

Web dashboards from cloud providers or add-on tools show pretty charts and clickable lists. They are wonderful for exploring, but they take time to open, often need extra setup and permissions, and cannot easily be used in scripts.

Monitoring systems such as Prometheus and Grafana collect numbers over time. They tell you how a system behaved yesterday and warn you of trouble. They are not the tool for the simple question “what exists right now?”.

Reading raw configuration files tells you what you asked for, not what is actually running. The two can differ, for example when a rollout has stalled halfway.

kubectl get answers the “right now” question in a second, from any terminal, in a form that both humans and scripts can read.

flowchart LR
  Q["Question: what is running right now?"] --> D["Web dashboard"]
  Q --> M["Monitoring charts"]
  Q --> F["Configuration files"]
  Q --> G["kubectl get"]
  D --> R1["Good view, slow to open"]
  M --> R2["Good history, not live inventory"]
  F --> R3["Shows intent, not reality"]
  G --> R4["Live answer in seconds"]
    

The command looks short, but it has a clear anatomy. Learn these building blocks and you can read or write almost any variation.

The anatomy of the command

Resource types and their short names

Typing long names all day would be tiring, so many resource types have short nicknames. You can use either. The results are identical.

Namespaces: where to look

By default, kubectl get looks only in your current namespace, which is usually one called “default” unless you or your team changed it. To look in another, you add a namespace flag. To look in every namespace at once, you add the all-namespaces flag, usually written as a capital letter A. When a resource seems to be missing, this is the first thing to check.

Labels and selectors: filtering the crowd

A label is a small tag, a key and a value, attached to a resource, such as “app equals shop” or “tier equals frontend”. A selector is a filter that picks resources by their labels. With a label selector flag, kubectl get shows only the matching resources. This is how you narrow hundreds of pods down to the six you care about.

Output formats: how to see the answer

Contexts: which cluster am I talking to?

A context is a saved combination of three things: a cluster, a user identity, and an optional default namespace. Your kubeconfig can hold many contexts, one for each cluster you work with, such as a test cluster, a staging cluster and a production cluster. Exactly one is “current” at any time, and every command you type goes to that one. Switching context is like changing the channel on a television: the same remote control now shows a different programme.

Reading a full record: metadata, spec and status

When you ask for YAML or JSON output, you see the complete stored record. Almost every Kubernetes record has the same three parts, and knowing them makes any record readable.

The clue to remember is this: spec is the wish, status is the reality. Much of troubleshooting is reading both and asking why they differ.

One short command touches several parts of the system. Let us meet each part, in the order your question meets it.

flowchart LR
  YOU["You type kubectl get pods"] --> KC["kubectl program on your computer"]
  CFG["kubeconfig file with cluster address and credentials"] --> KC
  KC -->|"HTTPS request"| API["Kubernetes API Server"]
  API --> AUTHN["Authentication: who are you?"]
  AUTHN --> AUTHZ["Authorization: may you list pods here?"]
  AUTHZ --> CACHE["Watch cache in API server memory"]
  CACHE -.-> ETCD["etcd: the cluster database"]
  CACHE --> RESP["Answer sent back as a table"]
  RESP --> OUT["Printed in your terminal"]
    

Piece by piece

The kubectl program runs on your own laptop or on a server you control. It does no thinking about the cluster itself. Its job is to translate your short command into a proper web request, send it, and then print the answer nicely.

The kubeconfig file is kubectl’s address book. It usually lives in a hidden folder in your home directory. It lists the clusters you can reach, the identities you can use, and a “context” that pairs one cluster with one identity and, optionally, a default namespace. The current context decides where every command goes.

On Amazon EKS, for example, a helper command from AWS writes the cluster entry into your kubeconfig, and kubectl asks the AWS command-line tool for a short-lived token each time, so your AWS identity becomes your Kubernetes identity.

The API server is the only door into the cluster’s records. It runs on the control plane, which is the group of computers that manage the cluster. It receives your request over an encrypted web connection.

Authentication is the check “who are you?”. It looks at your certificate or token. Authorization is the check “are you allowed to do this?”. Most clusters use role-based access control here, where roles list which actions on which resources are permitted.

The watch cache and etcd hold the truth. Etcd is a small, reliable database where Kubernetes stores every resource. To avoid overloading it, the API server keeps a copy in memory and answers many read requests from there.

Here is what really happens in the second between pressing Enter and seeing the table.

sequenceDiagram
  participant U as You
  participant K as kubectl
  participant C as kubeconfig
  participant A as API Server
  participant E as etcd
  U->>K: kubectl get pods
  K->>C: Read cluster address and credentials
  K->>A: HTTPS request to list pods in the namespace
  A->>A: Check identity and permissions
  A->>E: Read the pod records if not cached
  E-->>A: Stored records
  A-->>K: Answer prepared as a table
  K-->>U: Print the table
    

Getting one thing versus getting a list

Fetching one named resource is a direct lookup, which is fast and cheap. Listing every pod in a big cluster is a much larger request. The API server must find, filter and send potentially thousands of records. Label selectors and namespace flags shrink that work, because the server does the filtering before sending anything.

The watch mode

With the watch flag, kubectl prints the table once and then keeps the connection open. Whenever a matching resource changes, the API server pushes an update line, and kubectl prints it. You see a pod move from Pending to Running in real time without re-running the command. This works because the API server keeps a stream of change events that clients can subscribe to.

Why big clusters need care

In a small test cluster, listing everything is instant. In a large production cluster, the same request may ask the API server to gather and send tens of thousands of records. Every extra record costs memory on the server, network time, and printing time on your screen. Several people doing it at once can noticeably slow the cluster for everyone else.

Kubernetes protects itself in a few ways. Answers are sent in pages instead of one giant block. The server keeps popular data in memory, so it does not always need to bother the database. And a fairness system limits how much any one noisy client can take, so that critical internal components are never starved. You can help by asking narrower questions: pick a namespace, add a label selector, and ask only for the type you need.

Why custom resources fit so easily

Because the server prepares the table, anyone who adds a new resource type to Kubernetes can also tell the server which columns to show for it. That is why a certificate object from a certificate tool, or a database object from a database operator, shows sensible columns just like a built-in pod. The get command does not need to know about them in advance. It simply prints whatever table the server sends.

A table is only useful if you can read it. Let us decode the columns you will see most, and follow one pod through its life.

The pod table, column by column

What common statuses mean

One pod through its life

flowchart LR
  A["Pending"] --> B["ContainerCreating"]
  B --> C["Running"]
  C --> D["Terminating"]
  D --> E["Gone from the list"]
  C -->|"container crashes"| F["CrashLoopBackOff"]
  F -->|"restart after a delay"| C
    

If you run get with the watch flag while a new deployment rolls out, you can watch this story unfold: new pods appear as Pending, become ContainerCreating, then Running, while old pods change to Terminating and vanish. It is a live movie of your update.

Most day-to-day use of the command falls into a small set of patterns. Learn to recognise them and you can answer nearly any “what is going on?” question.

A worked investigation, told in words

Let us walk through a realistic morning. A colleague says the search page of the shop is failing. You open a terminal and first confirm you are pointed at the right cluster and the right namespace. Then you list the pods in the shop’s namespace, filtering by the search application’s label.

The table shows four pods. Three are Running and Ready. One shows CrashLoopBackOff with eleven restarts and an age of forty minutes. That single row already tells you a lot: the problem is not the whole application, only one pod, and it began around forty minutes ago, which might match a recent release.

Next you ask for the wide output and notice the failing pod is on a node that hosts nothing else from this application. You list the nodes and see that node has been up only an hour, a fresh computer added by the autoscaler. Now you have a theory: something about the new computer differs, perhaps a missing setting or a network rule.

Only now do you move to the deeper tools. You describe the failing pod, read its events, and read its logs. You find the application cannot reach its database from that computer. A quick message to the networking team, a fixed rule, and a new get with the watch flag shows the pod turning Running and Ready. Five minutes, four get commands, and you never guessed blindly.

Because the command only reads, many beginners think it cannot cause harm. That is not quite true. Reading can leak secrets, and running commands against the wrong cluster can lead to costly mistakes.

Who is allowed to look?

Access to resources is governed by role-based access control. A role lists actions, called verbs, that are permitted on named resource types. Three verbs matter for reading. The get verb allows fetching one named resource. The list verb allows listing many. The watch verb allows the live streaming mode.

When you run the plain listing form, the cluster checks that you have the list permission. When you fetch one named resource, it checks the get permission. If a check fails, you see a “forbidden” message that names the missing permission. That message is helpful: it tells your administrator exactly what to grant.

The wrong-cluster problem

The most common danger is not an attack but a slip. Your terminal remembers the last context you selected. If you switched to the production cluster this morning and forgot, a command you believed was going to a test cluster reaches production instead. With a read-only get, this only confuses you. With other verbs, it can be a disaster. Healthy habits include showing the current context in your shell prompt, using separate identities with different permissions for production, and checking the context before any risky command.

The get command gives you the summary. Other commands give you reasons, logs and numbers. A good engineer knows which to reach for.

A sensible order for investigating a problem

Choosing an output format

No tool is perfect. A good engineer knows both what the command gives and what it costs.

The trade-offs behind the lists

Convenience versus load. Listing everything in every namespace is easy to type but expensive for the cluster. Selectors and namespaces cost you a few extra characters and save the server real work. In small clusters the difference is invisible. In clusters with tens of thousands of pods it is not.

Human view versus machine view. The default table is friendly, but its columns and wording can change between versions. Scripts that cut and slice that text can break. Reading JSON is more stable, at the price of a little more effort.

Breadth of access versus safety. Giving everyone permission to list everything makes life easy for engineers and also makes leaks easier. Namespace-scoped, read-only roles are slightly more work to manage but far safer.

Manual looking versus automation. Typing commands is quick for a person. For continuous checking, alerts and dashboards do the job better, and tools that manage the cluster from version control show desired versus actual state without anyone typing anything.

Get versus dashboards and GitOps tools

Many teams also use visual tools that show the cluster as a picture of boxes and arrows, and tools that keep the cluster in step with configuration stored in version control. These tools are helpful, and they do not replace the get command. A dashboard may be slow to reach, may be unavailable during an outage, or may hide the exact field you need. The command line works from anywhere you can reach the API server, even when everything else is broken.

Think of the command as the pocket torch you always carry. The dashboard is the floodlight on the building: brighter, but not always switched on when you need it. Skilled engineers use both, and they trust the torch most when the lights go out.

The get command is not a monitoring system, but it is the quickest health check you have. It also has its own failure messages that are worth understanding.

Get as a quick health check

When the command itself fails

Seeing what kubectl does behind the scenes

kubectl has a verbosity flag that prints the web requests it makes. At a moderate level you see each address it calls and the response code, which is very useful when a command misbehaves. At higher levels, you even see request and response bodies. Use it to learn, but remember the output can contain sensitive data.

Watching the API server itself

Operations teams watch the API server’s own metrics: how many read requests per second, how long they take, and how many return errors. A sudden surge of list requests, often caused by a script that polls too often, can slow down the whole cluster. Audit logs record who made the calls, so the source is easy to find.

A pattern is a proven way of working. An anti-pattern is a habit that looks sensible at first and causes pain later.

Patterns that work

Anti-patterns to avoid

These habits come from many engineers using the command every day. Follow them and you will save yourself a great deal of confusion.

Common mistakes and their cures

Engineers in organisations of every size use this command all day. The stories below are simplified illustrations of common situations, not descriptions of any one company’s private setup.