A cluster is a powerful machine room, but it is useless if you cannot give it instructions.

The problem

Kubernetes runs applications across many computers. Those computers may sit in data centres far away, and there may be dozens or thousands of them. You will never sit in front of each one. You need a single, consistent way to say “run this application”, “show me what is running” and “something is broken, tell me why”.

Kubernetes solves this by placing one central front desk, called the API server, in charge of everything. All requests go through it. But the API server speaks a technical language over the network, and typing raw network requests by hand would be painful. We need a friendly translator, and that translator is kubectl.

Other ways exist, but kubectl is the everyday tool

There are graphical dashboards, web consoles and automation tools that also talk to a cluster. But the command line tool remains the common denominator. It works on every cluster, in every cloud, over any connection, and it can be automated in scripts. Nearly every tutorial, troubleshooting guide and job description assumes you know it.

A quick tour of the building blocks that kubectl talks about.

The most important idea for this guide is the resource. Kubernetes thinks of everything as a resource with a type and a name. Kubectl is essentially a tool for listing, creating, changing and deleting resources.

A plain definition, a note on the name, and what makes the tool special.

The definition

Kubectl is the official command line tool for working with Kubernetes clusters. You type short commands in a terminal, kubectl converts each one into a request to the cluster’s API server, and then it prints the answer in a readable form. It can show you what is running, create new things, change or remove existing things, and help you find out why something is not working.

How do you say it?

There is no single official pronunciation. People say “kube control”, “kube cuttle” or spell out the letters. All of them are understood. The name simply means the control tool for Kubernetes.

Where does it run?

Kubectl runs on your own computer, or on a server you log into, or inside an automation pipeline. It does not run inside the cluster. It is a client, which means it starts on your side and reaches out to the cluster over the network. As long as it can reach the API server and prove who you are, it works.

Let us follow one simple command from your keyboard to the cluster and back.

Step one: reading your settings

When you run a command, kubectl first looks for a settings file, known as the kubeconfig. This file tells it which cluster to contact, where the cluster is, and how you prove your identity. Without this information, kubectl would not know where to send anything.

Step two: building the request

Kubectl translates your command into a standard web request. Asking to list pods, for example, becomes a request to read the pod resources in a certain namespace. Creating something becomes a request to store a new resource. Everything is done through a well-defined interface called the Kubernetes API.

Step three: proving who you are

The request travels over an encrypted connection and carries your credentials. The API server first checks who you are, which is authentication. It then checks whether you are allowed to do what you asked, which is authorization. Some clusters add a third check, called admission, where policies may adjust or reject the request.

Step four: the answer comes back

If everything passes, the API server reads from or writes to its database, called etcd, and sends back a response. Kubectl receives the response and prints it in a friendly table, or in another format you asked for. If you asked it to watch, it keeps the connection open and shows updates as they happen.

sequenceDiagram
    participant You as You in a terminal
    participant K as kubectl
    participant Cfg as kubeconfig file
    participant API as API Server
    participant DB as etcd
    You->>K: Type a command
    K->>Cfg: Read cluster address and credentials
    K->>API: Send request over encrypted connection
    API->>API: Authenticate, authorise and run admission checks
    API->>DB: Read or write resource data
    DB-->>API: Result
    API-->>K: Response
    K-->>You: Print readable answer
        

The settings file that decides where your commands go and who you are when you send them.

The kubeconfig is a plain settings file, usually stored in a hidden folder in your home directory. You can also point kubectl to a different file, or merge several files. It holds three kinds of information that work together.

flowchart LR
    CTX["Current context"] --> CL["Cluster: where to send requests"]
    CTX --> US["User: who you are"]
    CTX --> NS["Namespace: default section to work in"]
    CL --> API["API server of that cluster"]
    US --> API
        

Why contexts matter so much

Most engineers work with more than one cluster: a small one for learning, one for testing and one for real customers. A context is a saved shortcut for each. Switching context is like changing the channel on a television. The remote is the same, but everything you now control is different.

The most important idea in using kubectl well is the difference between telling the cluster how and telling it what.

You do not need to memorise hundreds of commands. Most daily work comes from a small handful.

The same information can be shown in many shapes. Choosing the right one saves time.

By default, kubectl prints a compact table that is easy for a person to scan. But sometimes you need more detail, or a format that another program can read. Kubectl supports several output styles.

Filtering what you see

Clusters can hold thousands of resources. Kubectl lets you narrow the list in several ways. You can choose a namespace, or ask for all namespaces at once. You can select resources by their labels, which is the standard way to say “only the pods of this application”. You can also sort the results or ask kubectl to keep watching and print changes as they occur.

When something breaks, experienced engineers follow a steady sequence rather than guessing.

flowchart TD
    S["Something looks wrong"] --> A["List resources and read status"]
    A --> B["Describe the problem resource and read events"]
    B --> C{"Did the application start?"}
    C -- "No" --> D["Check image, storage, scheduling and settings"]
    C -- "Yes" --> E["Read logs, including the previous attempt"]
    D --> F["Fix the description file and apply"]
    E --> G["Step inside or tunnel in to test"]
    G --> F
    F --> H["Watch rollout until healthy"]
        

Three small ideas that decide which resources your commands touch.

Namespaces

Namespaces divide a cluster into named sections. Your context can carry a default namespace, and you can override it for a single command. Being clear about the namespace is the easiest way to avoid touching something that belongs to another team.

Labels

Labels are short tags attached to resources, such as the application name or the environment. They are the standard way to group things. A single command can act on all pods carrying a certain label, which is far safer and quicker than naming them one by one.

Selectors

A selector is the question you ask about labels: “give me everything tagged with this application and this environment”. Kubectl accepts selectors on many commands, including listing, deleting and reading logs. Services and deployments use the same idea internally to find their pods.

Kubectl gives you ways to preview a change before it happens. Good engineers use them constantly.

flowchart LR
    F["Description file"] --> DR["Dry run: does it look valid?"]
    DR --> DF["Diff: what will change?"]
    DF --> AP["Apply the change"]
    AP --> RO["Watch rollout status"]
    RO --> OK["Confirm healthy"]
        

Kubectl has no special powers of its own. It carries your identity, and the cluster decides what that identity may do.

Authentication

Your credentials in the kubeconfig prove who you are. They may be certificates, tokens, or a helper program that fetches a short-lived login from a cloud provider or an identity system. Short-lived credentials are safer because a stolen one soon becomes useless.

Authorization

After you are identified, the cluster checks your permissions using role-based access control. A role lists which actions are allowed on which resources, and a binding connects the role to a person or group. Kubectl even has a built-in way to ask “am I allowed to do this?”, which is very useful when you meet a permission error.

Protect the kubeconfig

The kubeconfig can be as powerful as a master key. Anyone who copies it can act as you. Keep it private, restrict its file permissions, avoid emailing or pasting it, and prefer short-lived logins over permanent tokens.

Least privilege for everyone

People should hold only the permissions they need. Many engineers work with read-only access most of the time and gain change rights only when needed. Automation pipelines should use their own limited accounts, not a personal administrator login.

flowchart TD
    U["You run a kubectl command"] --> A1["Authentication: who are you?"]
    A1 --> A2["Authorization: are you allowed?"]
    A2 --> A3["Admission policies: is the request acceptable?"]
    A3 --> OK["Request carried out"]
    A1 -. "Fails" .-> X1["Unauthorized"]
    A2 -. "Fails" .-> X2["Forbidden"]
    A3 -. "Fails" .-> X3["Rejected by policy"]
        

A short guide to getting kubectl and keeping it compatible with your cluster.

Getting it

Kubectl is a single program file with no complicated setup. It is available for the main operating systems and can be installed through the standard package managers of each, or downloaded directly from the Kubernetes project. Many cloud command line tools and desktop container tools also install it for you.

Version compatibility

Kubernetes releases new versions several times a year, and kubectl is versioned alongside it. The general rule is that kubectl should be within one minor version, either older or newer, of the cluster’s API server. A much older or much newer kubectl may behave oddly or lack support for newer resource fields.

Shell comfort features

Kubectl can generate completion scripts for common shells, so pressing the tab key completes command names, resource types and even resource names. Many engineers also create short aliases for the commands they type dozens of times a day. These small comforts make long sessions faster and reduce typing mistakes.

Kubectl is small on purpose, but it has clever ways to grow.

Every kubectl action leaves a trail, and smart teams read it.

Auditing who did what

The API server can record every request it receives: who sent it, what they asked for and whether it succeeded. Since every kubectl command becomes such a request, the audit log is a complete history of human and automated actions. When something changes unexpectedly, the audit log answers “who did this, and when?”.

What to watch for

Metrics and the top command

The top command reads live resource use from a metrics component. It is great for a quick look at which pods or nodes are busy. If it reports that metrics are unavailable, the metrics component is probably not installed. For long-term trends and alerts, a proper monitoring system is needed, since kubectl only shows the present moment.

Patterns are proven habits. Anti-patterns are popular mistakes that keep hurting teams.

Patterns worth adopting

Anti-patterns to avoid

An honest look at what kubectl gives you, and where it falls short.

The lesson is that kubectl is powerful in proportion to the care of its user. It is a sharp tool. Used with previews, clear context and limited permissions, it is safe and productive. Used carelessly, it is one of the quickest ways to cause an outage.

A checklist of habits that separate calm engineers from panicked ones.

Best practices

• Always know your context — display the current context and namespace in your terminal prompt.
• Prefer declarative files — keep descriptions in version control and apply them, rather than typing one-off orders.
• Preview before applying — use dry runs and diffs for every change that matters.
• Use labels and selectors — act on groups safely instead of naming resources one by one.
• Apply least privilege — give people and automation only the permissions they need, and use short-lived logins.
• Protect the kubeconfig — treat it as a secret, restrict file permissions and never share it in chat.
• Learn the debugging routine — status, describe, logs, events, and only then step inside.
• Keep versions aligned — stay within one minor version of the cluster, and update regularly.

Common mistakes

How kubectl shows up in everyday engineering.

No. It is a separate client program that runs on your computer or pipeline and talks to the cluster’s API server over the network. The cluster runs fine without it.

It reads the kubeconfig file, which lists clusters, users and contexts. The active context decides the cluster, the identity and the default namespace.

Create makes a new resource and fails if it already exists. Apply describes the desired state and creates or updates as needed, so it can be run repeatedly with the same result.

Most often you are looking at a different namespace or context. Check the active namespace, or ask kubectl to look at all namespaces.

Check its status, then describe it and read the events at the bottom. If it started, read its logs, including those of the previous attempt if it keeps restarting.

No. It may contain credentials that let others act as you. Keep it private and prefer short-lived logins that expire on their own.

It should be within one minor version, older or newer, of the cluster’s API server. Larger gaps can cause odd behaviour or missing features.

Yes. It works entirely from the command line, and can print structured output that scripts can read. Many delivery pipelines run kubectl behind the scenes.

The metrics component that gathers resource use is probably not installed or not working in that cluster. Once it is running, the command shows live figures.

Always check which context and namespace are active before you run anything that changes or deletes. It is a tiny step that prevents the most common and costly mistakes.

Kubectl is the official command line tool for working with Kubernetes. It runs outside the cluster, reads a kubeconfig to learn where to go and who you are, turns each command into a request to the API server, and prints the answer in a readable form. You can use it to look, change and debug, in a quick direct style or in a careful declarative style driven by saved files. It carries your identity and nothing more, so the cluster’s permission rules decide what it may do.

Treat kubectl as a sharp and honest tool. Know your context, preview your changes, keep your descriptions in version control, protect your credentials and follow a steady debugging routine. With those habits, kubectl becomes the calm, reliable remote control for your cluster rather than a source of surprises.