What Does kubectl Command Reference Mean?
Also known as: kubectl, kubectl command reference, kubernetes CLI, CKA exam, kubectl commands
On This Page
Quick Definition
kubectl is a program you run in a terminal or command prompt to control a Kubernetes cluster. You use it to deploy applications, inspect and manage cluster resources, and view logs. Think of it as a remote control that lets you talk to your cluster using simple text commands. It is the primary way most administrators and developers work with Kubernetes day to day.
Must Know for Exams
The CNCF CKA (Certified Kubernetes Administrator) exam tests your ability to perform real-world Kubernetes administration tasks in a live cluster environment. The entire exam is hands-on. There are no multiple-choice questions. You are given a terminal and a set of tasks. You must use kubectl to complete them. The CKA exam objectives explicitly state that you should be able to use kubectl to create and manage resources, troubleshoot issues, and configure cluster components. The exam environment is designed to mimic a production cluster, and you must demonstrate proficiency with kubectl commands without relying on internet searches or pre-written notes.
Specific exam objectives that rely heavily on kubectl include: deploying applications using kubectl run and kubectl create deployment, exposing applications as services with kubectl expose, scaling applications with kubectl scale, performing rolling updates and rollbacks with kubectl set image and kubectl rollout undo, managing labels and selectors with kubectl label and kubectl get --selector, and troubleshooting with kubectl logs, kubectl describe, and kubectl exec. The exam also tests your ability to use kubectl to manage ConfigMaps and Secrets, to set resource quotas and limits, and to configure persistent volumes and claims.
Beyond the CKA, kubectl is also central to the CKAD (Certified Kubernetes Application Developer) exam. CKAD focuses on designing and deploying applications on Kubernetes. Candidates must use kubectl to create pods, deployments, services, and ConfigMaps, and they must understand how to use kubectl to debug application issues. The CKS (Certified Kubernetes Security Specialist) exam also requires kubectl commands for managing security contexts, network policies, and RBAC configurations.
In the exams, speed and accuracy matter. You cannot afford to fumble with syntax. You must know common flags by heart, such as --image, --replicas, --port, --selector, -o yaml, and --dry-run=client. You should be comfortable using kubectl run and kubectl create interchangeably, knowing that kubectl run creates a pod directly while kubectl create creates from a file. The exam also expects you to use kubectl explain to look up resource field definitions without internet access. This is a skill that many candidates overlook. Practicing with kubectl in a local environment, such as using minikube or kind, is the best way to prepare. The official kubectl cheat sheet from Kubernetes documentation is an excellent study resource.
Simple Meaning
Imagine you are the manager of a large apartment building. Tenants come and go, maintenance needs to happen, and utilities must be managed. You do not personally fix every leak or paint every wall. Instead, you have a set of keys and a master control panel. kubectl is like that master control panel for a Kubernetes cluster. A cluster is a group of computers (called nodes) that work together to run your applications. These computers could be on your desk, in a data center, or in the cloud. kubectl lets you send instructions to the cluster without having to log in to each computer individually.
When you type a kubectl command, you are essentially telling the cluster what you want to happen. For example, you might say "run three copies of my web application" or "show me the health of all my services." kubectl packages your request, sends it to the Kubernetes API server (the brain of the cluster), and returns the result to you. It uses a configuration file called kubeconfig to know which cluster to talk to and how to authenticate. This is similar to how a librarian uses a catalogue system. The librarian does not need to search every shelf personally. They type a book title into the catalogue, and the system tells them exactly where to find it. kubectl works the same way with cluster resources.
The commands in kubectl are structured like a simple language. A typical command looks like: kubectl <action> <resource> <name> <flags>. The action tells the cluster what to do, for example get, create, delete, or describe. The resource tells the cluster what you are working with, for example pods, services, deployments, or nodes. This structure makes it predictable and easy to learn. Even if you have never seen a particular command before, you can often guess its pattern. kubectl also provides extensive help documentation built right into the tool. If you type kubectl help, you will see a list of all available commands. If you type kubectl <command> --help, you get detailed options for that specific command. This self-documenting nature makes it a powerful learning aid for certification candidates.
Full Technical Definition
kubectl is the official command-line interface for Kubernetes. It communicates with the Kubernetes API server, which is the central management entity in a Kubernetes cluster. The API server validates and processes RESTful HTTP requests. Every kubectl command translates into an API call. Under the hood, kubectl uses a client-go library to construct and send these requests. The request includes authentication credentials, usually from a kubeconfig file. The kubeconfig file contains cluster endpoint URLs, user certificates or tokens, and context definitions that let you switch between multiple clusters and namespaces.
When you run kubectl get pods, the tool reads your kubeconfig to determine the target cluster, then sends a GET request to the /api/v1/namespaces/{namespace}/pods endpoint. The API server authenticates you, authorizes the action (for example using Role-Based Access Control, RBAC), and then queries the etcd key-value store where cluster state is persisted. The response is typically JSON, but kubectl formats it into human-readable text. You can also request YAML or JSON output using flags like -o yaml or -o json.
kubectl supports a wide range of operations. For day-to-day management, you use imperative commands like kubectl run, kubectl expose, and kubectl delete. For declarative management, you use kubectl apply with a YAML file. This is the recommended approach for production environments because it allows infrastructure-as-code. You can also use kubectl to troubleshoot: kubectl logs fetches container logs, kubectl exec runs commands inside a running container, and kubectl describe shows detailed state of any resource. Advanced users leverage kubectl port-forward to access services locally, kubectl cp to copy files to and from containers, and kubectl top to view resource usage.
In real-world environments, kubectl is often used in conjunction with CI/CD pipelines. For example, after a build succeeds, a pipeline script runs kubectl set image deployment/myapp myapp=myapp:v2 to update the container image. kubectl also integrates with plugins. The kubectl plugin mechanism allows extending its functionality. Tools like kubectx (to switch contexts) and kubens (to switch namespaces) are popular plugins. The command reference for kubectl is maintained in the official Kubernetes documentation. It lists every command, every flag, and every available resource type. For the CNCF CKA exam, you must know how to use kubectl without relying on internet access. The exam environment provides a command-line terminal where you type kubectl commands directly. Familiarity with kubectl help and kubectl explain (which describes resource fields) is essential.
Real-Life Example
Think of a large office building with many departments. Each department has its own floor, its own resources, and its own tasks. The building manager is like the Kubernetes cluster. The manager does not go to every desk to check if work is done. Instead, the manager uses a radio system to communicate with department heads. kubectl is that radio system. When the manager wants to know how many employees are in the marketing department, they say "get employees in department marketing." The radio operator sends the request, and the department head replies with the count. Similarly, when you type kubectl get pods -n default, you are asking the cluster for a list of pods in the default namespace.
Now imagine the manager wants to add three new employees to the sales team. They do not physically hire and seat each person. Instead, they radio an instruction: "create three new seats in the sales department." The department head handles the details. In Kubernetes, you say kubectl create deployment sales-team --replicas=3 --image=myapp. kubectl sends that instruction to the API server, which then creates the deployment. The cluster's scheduler finds room for those three replicas on available nodes.
Sometimes a faulty light bulb needs replacing. The manager radios a specific instruction: "replace the bulb in office 4B." This is like kubectl delete pod faulty-pod. The cluster immediately removes the old pod and, if it was part of a deployment, creates a new one to maintain the desired count. The manager can also inspect the state of any room remotely. They ask "describe room 4B" and get a full report. kubectl describe pod faulty-pod gives you detailed information about that pod's current state, events, and conditions.
Finally, consider security. The building manager has a master key card that works on every floor. But the manager can also give limited key cards to security guards. Those guards can only open doors on their assigned floors. In kubectl, this is managed through the kubeconfig file and RBAC. Each user or service account has a key card (a certificate or token) that permits only certain actions. This prevents someone from accidentally or maliciously deleting critical resources.
Why This Term Matters
kubectl is the primary tool for anyone working with Kubernetes. Without it, managing a cluster would require manually SSH-ing into each node and editing configuration files directly. That approach is slow, error-prone, and does not scale. kubectl provides a consistent, auditable, and automated way to interact with clusters. In real IT work, you use kubectl for almost every daily task: deploying new software, scaling services up or down, rolling out updates, checking health, debugging issues, and cleaning up unused resources.
In a typical day, a DevOps engineer might use kubectl to check the status of a deployment after a CI/CD pipeline finishes. If the new version crashes, they use kubectl rollout undo deployment/myapp to roll back. They might use kubectl logs --tail=50 -f to follow real-time logs from a misbehaving pod. They might use kubectl exec -it mypod -- /bin/sh to get a shell inside a container for deep debugging. These actions are fast and do not require leaving the terminal.
kubectl also matters because it enforces best practices. When you use kubectl apply with a YAML file, you are using declarative configuration. This means the cluster state is defined in code, which can be version-controlled, reviewed, and tested. Imperative commands like kubectl run are fine for learning and quick tests, but production environments rely on declarative files. kubectl also supports dry-run mode with the --dry-run=client flag, which lets you see what would happen without making changes. This is invaluable for safe experimentation.
In terms of security, kubectl respects access controls. If your kubeconfig uses a certificate that lacks delete permissions, kubectl delete will produce an error. This prevents unauthorized actions. Audit logs capture every kubectl command, so you can trace who did what and when. For organizations that must comply with regulations like SOC 2 or HIPAA, this audit trail is essential. kubectl is also the basis for many higher-level tools. For example, the Helm package manager runs kubectl commands internally. The Kubernetes dashboard also uses the same API that kubectl talks to. Mastering kubectl means you understand the fundamental way Kubernetes is managed, which makes learning more advanced tools easier.
How It Appears in Exam Questions
Exam questions in the CKA and CKAD are performance-based. You are given a scenario and must execute a series of kubectl commands to achieve a desired outcome. The questions are structured as task descriptions. For example, a question might state: "Create a new namespace named 'production'. Deploy an nginx pod with the image nginx:1.23. Expose the pod on port 80 as a ClusterIP service. Confirm the pod is running and the service endpoints are populated." This type of question tests your ability to chain multiple kubectl commands in sequence.
Configuration questions ask you to modify existing resources. For instance: "The deployment 'web-frontend' has three replicas. Scale the deployment to five replicas. Then, update the image to nginx:1.24. Perform a rolling update and verify the rollout status." You would use kubectl scale and kubectl set image, followed by kubectl rollout status deployment/web-frontend. Another common pattern is troubleshooting. The question might say: "A pod named 'api-gateway' is in CrashLoopBackOff. Investigate the pod's logs and events. Identify the error and correct the environment variable that is causing the failure." You would use kubectl logs, kubectl describe, and then kubectl edit or kubectl set env.
Architecture questions might ask you to examine cluster components. For example: "Identify the node that is not ready. Drain the node and cordon it so that no new pods are scheduled onto it." You would use kubectl get nodes, kubectl describe node, kubectl drain, and kubectl cordon. Some questions test your understanding of YAML manifest generation. For instance: "Generate a YAML file for a pod with a busybox container that runs the command 'sleep 3600'. Use dry-run to create the file without actually creating the pod." This tests kubectl run --dry-run=client -o yaml.
There are also questions that require you to switch contexts between clusters. The exam environment provides multiple clusters, and you must use the correct kubeconfig context to access each one. A question might say: "Use the cluster context named 'k8s-cluster-admin' to create a ConfigMap for the database configuration." You would use kubectl config use-context k8s-cluster-admin and then proceed with the ConfigMap creation. The ability to navigate between contexts and namespaces efficiently is a key skill tested in the exams.
Finally, there are questions that combine declarative and imperative approaches. For example: "Write a deployment YAML that uses the image 'myapp:v1' with three replicas. Apply it to the cluster. Then, patch the deployment to set the image to 'myapp:v2' using a strategic merge patch." This tests kubectl apply and kubectl patch. The exam expects you to be comfortable with both methods and to choose the right one for the scenario.
Study cncf-cka
Test your understanding with exam-style practice questions.
Example Scenario
You are a new junior administrator at a company that runs its e-commerce website on a Kubernetes cluster. Your senior colleague asks you to deploy a simple test application called 'hello-server' that listens on port 8080. The colleague wants you to use the image 'hello-world:latest' and ensure there are two copies running for high availability. You have never deployed anything on Kubernetes before, but you have studied kubectl commands.
You open your terminal. First, you check which cluster you are connected to by typing kubectl config current-context. It shows you are on the correct development cluster. You then create a deployment using an imperative command: kubectl create deployment hello-server --image=hello-world:latest --replicas=2. You get a confirmation that the deployment was created. Next, you check that the pods are running: kubectl get pods. You see two pods in Running state. Your colleague then says they need to access the application internally from other services. You expose the deployment: kubectl expose deployment hello-server --port=8080 --target-port=8080 --name=hello-svc --type=ClusterIP. You verify the service exists with kubectl get svc. Finally, you check that the endpoints are populated: kubectl get endpoints hello-svc. Everything looks good. You have successfully used kubectl to deploy and expose an application. This scenario mirrors the kinds of basic tasks you will perform in the CKA exam.
Common Mistakes
Using kubectl run to create a deployment instead of a pod.
kubectl run creates a pod directly, not a deployment. A deployment provides replication and self-healing; a single pod does not. In production or exam scenarios, you almost always want a deployment.
Use kubectl create deployment instead of kubectl run. If you must use run, add the --dry-run=client -o yaml flag to generate a deployment YAML and then edit it.
Forgetting to specify the namespace when working outside the default namespace.
Many commands default to the 'default' namespace. If your resources exist in another namespace, the command returns nothing or an error, causing confusion and wasted time.
Use the --namespace or -n flag explicitly. For example, kubectl get pods -n production. You can also set a default namespace with kubectl config set-context --current --namespace=production.
Typing kubectl delete on a deployment when only a single pod should be removed.
Deleting a deployment removes all its replicas and the deployment controller. If you only need to restart a pod, deleting it causes the deployment to recreate it, but deleting the whole deployment is excessive and destroys the configuration.
If you want to restart a pod, delete only the pod: kubectl delete pod pod-name. The deployment will automatically create a new one. If you want to scale down, use kubectl scale deployment deploy-name --replicas=0 and later scale up.
Misusing the --image flag with the wrong image name or tag.
Using an incorrect image name or tag causes the pod to fail pulling the image. The pod may go into ImagePullBackOff state. This wastes time during an exam and is a common error.
Always double-check the exact image name and tag. Use familiar images like nginx, busybox, or httpd for practice. In an exam, the image name will be provided. Type it carefully and avoid typos.
Forgetting to use the -o yaml flag when asked to generate YAML output.
Without the flag, kubectl prints a summary table, not the YAML configuration. The exam may require you to output configuration for review or editing.
Always add -o yaml when you need the full resource definition. For JSON, use -o json. You can also combine with --dry-run=client to generate YAML without creating the resource.
Exam Trap — Don't Get Fooled
The exam presents a question that says 'Create a pod named 'my-pod' using the image nginx.' Candidates type kubectl run my-pod --image=nginx which is correct. But then the next question says 'Create a deployment named 'my-deploy' with the image nginx and 3 replicas.'
Many candidates type kubectl run my-deploy --image=nginx --replicas=3, which is invalid because kubectl run does not support the --replicas flag. Remember the specific commands: kubectl run is for pods only. For deployments, use kubectl create deployment.
Study the command patterns early. Practice generating a deployment YAML with kubectl create deployment --dry-run=client -o yaml, and you will see there is no --replicas flag for run. Always check kubectl <command> --help if unsure.
Commonly Confused With
kubeadm is a tool for bootstrapping and initializing a Kubernetes cluster (installing the control plane and joining nodes). kubectl is for managing the cluster after it is running. You use kubeadm once or a few times; you use kubectl every day.
kubeadm init sets up the cluster. After that, you use kubectl get nodes to see the cluster state.
kubens is a third-party plugin for switching namespaces quickly. kubectl has a built-in way to do this using contexts or the --namespace flag. kubens is a convenience tool, not part of the core kubectl command reference.
Without kubens, you type kubectl get pods -n mynamespace. With kubens, you first type kubens mynamespace, then kubectl get pods works automatically.
kubectl config is a subcommand of kubectl used to manage kubeconfig files. It is not a separate tool. It allows you to set contexts, view cluster info, and modify credentials. The full 'kubectl Command Reference' covers all subcommands including config.
kubectl config use-context prod-cluster switches to the production cluster. This is part of kubectl, not an external tool.
kubectl apply is a specific subcommand within kubectl used for declarative management. The 'kubectl Command Reference' is the entire set of commands including apply, get, describe, delete, run, create, and more. People sometimes say 'kubectl command reference' when they mean 'kubectl apply cheat sheet,' but they are not the same.
kubectl apply -f deployment.yaml applies a YAML file. That is one single command among hundreds in the reference.
Step-by-Step Breakdown
Install and Set Up kubectl
Before you can use kubectl, you need to install it on your local machine (Linux, macOS, or Windows). Download the binary from the official Kubernetes release page or use a package manager. Then, set up a kubeconfig file that contains the cluster address, credentials, and context. Without this step, kubectl does not know which cluster to talk to.
Verify Cluster Connectivity
Run kubectl cluster-info to confirm you can reach the API server. This command returns the URLs for the control plane and other core services. If it fails, check network connectivity, firewall rules, and the kubeconfig file. This step is essential before attempting any other commands.
Choose a Namespace and Context
Use kubectl config get-contexts to list available contexts. Use kubectl config use-context <name> to switch to the correct cluster. Use kubectl get namespaces to list available namespaces. Use the --namespace flag or set a default namespace to ensure you are working in the right scope. This prevents accidentally modifying resources in the wrong environment.
Create or Apply a Resource
Decide whether to use an imperative command (kubectl create deployment, kubectl run) or a declarative command (kubectl apply -f file.yaml). For exam purposes, both are acceptable. The imperative approach is faster for simple tasks. The declarative approach is safer for complex configurations. Type the command and press enter. kubectl sends an API request and waits for a response.
Verify the Resource State
Run kubectl get <resource> to see a list of resources. Use kubectl describe <resource> <name> for detailed information including events. Use kubectl logs <pod-name> to check container logs. Verification is critical to ensure the resource was created correctly and is healthy. In exams, you must confirm your work.
Modify or Scale Resources
Use kubectl edit <resource> <name> to open the YAML in an editor and make changes. Use kubectl scale deployment <name> --replicas=<number> to change the number of copies. Use kubectl set image deployment <name> <container>=<new-image> to update the container image. These commands change the desired state, and Kubernetes works to match it.
Clean Up Resources
Use kubectl delete <resource> <name> to remove resources you no longer need. For example, kubectl delete deployment hello-server. Remember that deleting a deployment deletes its pods too. Always confirm what you are deleting to avoid accidental removal of important services.
Practical Mini-Lesson
kubectl is the single most important tool for a Kubernetes administrator. To become proficient, you must practice commands until they become second nature. Start by installing kubectl on your local machine. On Linux, you can download the binary with curl -LO https://dl.k8s.io/release/v1.29.0/bin/linux/amd64/kubectl and then make it executable. On macOS, use brew install kubectl or download the binary directly. On Windows, use chocolatey or download the exe. Once installed, verify with kubectl version --client. This should show the client version.
Next, set up a test cluster. The easiest way is to use minikube (for a single-node cluster) or kind (Kubernetes in Docker). For example, install kind with brew install kind, then run kind create cluster. This creates a cluster and automatically sets up your kubeconfig. Run kubectl cluster-info to see the cluster is healthy.
Now practice the core commands. Start with kubectl get all which shows pods, services, deployments, and replicasets in the default namespace. Then create a pod: kubectl run test-pod --image=busybox --restart=Never --command -- sleep 3600. This creates a pod that runs a sleep command. Check it: kubectl get pods. Describe it: kubectl describe pod test-pod. You will see details like the node it runs on, its IP address, and any events. Delete it: kubectl delete pod test-pod.
Next, practice deployments. Create one: kubectl create deployment web --image=nginx --replicas=3. Check the replicaset is created: kubectl get replicaset. Scale it: kubectl scale deployment web --replicas=5. Check the pods increased. Update the image: kubectl set image deployment web nginx=nginx:1.24-alpine. Check rollout status: kubectl rollout status deployment web. If an update fails, undo it: kubectl rollout undo deployment web.
Practice with services. Expose the deployment: kubectl expose deployment web --port=80 --type=NodePort. Check the service: kubectl get svc. Note the NodePort assigned. If using minikube, run minikube service web to open it in a browser. Delete the service: kubectl delete svc web.
Learn to use labels and selectors. Add a label: kubectl label pod test-pod environment=production. Query pods with that label: kubectl get pods -l environment=production. Remove a label: kubectl label pod test-pod environment-. This is useful for grouping and selecting resources.
Practice troubleshooting commands. Start a pod that crashes: kubectl run fail-pod --image=busybox --restart=Never --command -- false. It will show CrashLoopBackOff. Use kubectl logs fail-pod to see exit codes. Use kubectl describe pod fail-pod to see reason and events. Fix by deleting and recreating with a correct command.
Master the --dry-run=client -o yaml pattern. Run kubectl create deployment demo --image=nginx --dry-run=client -o yaml > demo.yaml. This generates a YAML file without creating anything. Edit the file to add environment variables, then apply: kubectl apply -f demo.yaml. This workflow is how production deployments are done in code review pipelines.
Finally, learn kubectl explain. Run kubectl explain pod.spec.containers. It shows the fields available for containers, including required fields like name and image. This is your offline documentation during the CKA exam. Use it whenever you forget a field name or format.
Memory Tip
Remember the verb-noun pattern: kubectl [action] [resource] [name] as in kubectl get pod mypod or kubectl delete svc myservice. The action always comes first.
Covered in These Exams
Related Glossary Terms
Two-factor authentication (2FA) is a security method that requires two different types of proof before granting access to an account or system.
5G is the fifth generation of cellular network technology, designed to deliver faster speeds, lower latency, and support for many more connected devices than previous generations.
802.1X is a network access control standard that authenticates devices before they are allowed to connect to a wired or wireless network.
An A record is a DNS record that maps a domain name to the IPv4 address of the server hosting that domain.
Frequently Asked Questions
What is the difference between kubectl run and kubectl create?
kubectl run is an older command that creates a pod directly. kubectl create is used with resource types like deployment and service. For exam purposes, use kubectl create deployment for deployments and kubectl run for quick test pods.
Do I need to install kubectl on every node in the cluster?
No. You install kubectl on your local machine or a jump box. It communicates with the cluster over the network using the API server. The individual nodes do not need kubectl.
What is the kubeconfig file and where is it located?
The kubeconfig file stores cluster, user, and context information. By default, it is located at ~/.kube/config. You can set the KUBECONFIG environment variable to point to a different file.
How do I switch between multiple clusters using kubectl?
Use kubectl config use-context <context-name>. First list available contexts with kubectl config get-contexts. Each context maps to a specific cluster and user.
What does the --dry-run=client flag do?
It simulates the command locally without sending any request to the API server. Combined with -o yaml, it generates a YAML file that you can inspect or apply later. This is safe for learning and designing configurations.
Can I use kubectl to edit resources in a text editor?
Yes. kubectl edit <resource> <name> opens the resource definition in your default text editor (like vim or nano). When you save and exit, kubectl applies the changes. You can set the editor with the KUBE_EDITOR environment variable.
Why do some kubectl commands require a hyphen like --image?
Flags with two hyphens are long flags. Single hyphens like -i are shorthand. Long flags are more readable and are standard in kubectl. Always use long flags in exam answers to avoid confusion.
Summary
kubectl is the command-line tool that serves as the primary interface for managing Kubernetes clusters. It translates human-readable commands into API calls to the Kubernetes control plane, allowing you to create, read, update, and delete resources such as pods, deployments, services, and ConfigMaps. Understanding the kubectl command reference is essential for any IT professional working with containers and orchestration, and it is the foundation of the CNCF CKA exam.
The tool follows a simple verb-noun pattern that makes it easy to learn, but mastering it requires practice. You should be comfortable with imperative commands for quick tasks and declarative commands for reliable, repeatable deployments. Common pitfalls include confusing kubectl run with kubectl create, forgetting namespaces, and misusing flags.
For exam success, practice with dry-run generation, use kubectl explain for documentation, and drill the most common scenarios like deployments, scaling, updates, and troubleshooting. kubectl is not just a certification topic; it is the everyday tool that real-world Kubernetes administrators rely on to keep systems running smoothly.