Kubectl

kubectl (pronounced “kube-control”, “kube-cuttle”, or “kube-cuddle”) is the official command-line interface (CLI) tool for Kubernetes. It allows users to interact with Kubernetes clusters to deploy applications, inspect and manage cluster resources, and view logs. kubectl is your primary tool for day-to-day management of Kubernetes resources and workloads.

How Kubectl Works

kubectl follows a client-server architecture:

  1. Client: The kubectl command-line tool running on your local machine
  2. Server: The Kubernetes API server running in your cluster

When you run a kubectl command, the following process takes place:

  1. kubectl reads your configuration from the kubeconfig file (typically located at ~/.kube/config)
  2. It authenticates with the Kubernetes API server using credentials from kubeconfig
  3. It sends an HTTP request to the API server with your desired operation
  4. The API server processes the request, interacts with the cluster state stored in etcd, and returns a response
  5. kubectl formats and displays the response in your terminal

Configuring Kubectl

Before using kubectl, you need to configure it to communicate with your Kubernetes cluster:

# View current configuration
kubectl config view

# Set a specific context (cluster)
kubectl config use-context <context-name>

# Get current context
kubectl config current-context

For AKS clusters, you can configure kubectl using:

az aks get-credentials --resource-group <resource-group> --name <cluster-name>

Common Kubectl Commands

Viewing Resources

# List all resources of a specific type in the current namespace
kubectl get <resource-type>

# List all pods
kubectl get pods

# List all deployments
kubectl get deployments

# List all services
kubectl get services

# List all resources in all namespaces
kubectl get <resource-type> --all-namespaces

# Get detailed information about a specific resource
kubectl describe <resource-type> <resource-name>

Creating and Modifying Resources

# Create resources from a file
kubectl apply -f <filename.yaml>

# Create resources from a directory of files
kubectl apply -f <directory>

# Create resources from a URL
kubectl apply -f https://example.com/resource.yaml

# Edit a resource directly
kubectl edit <resource-type> <resource-name>

# Delete a resource
kubectl delete <resource-type> <resource-name>

# Delete resources from a file
kubectl delete -f <filename.yaml>

Working with Namespaces

# List all namespaces
kubectl get namespaces

# Create a new namespace
kubectl create namespace <namespace-name>

# Set the default namespace for kubectl
kubectl config set-context --current --namespace=<namespace-name>

# View resources in a specific namespace
kubectl get <resource-type> -n <namespace-name>

Working with Pods

# Get logs from a pod
kubectl logs <pod-name>

# Get logs from a specific container in a pod
kubectl logs <pod-name> -c <container-name>

# Stream logs from a pod
kubectl logs -f <pod-name>

# Execute a command in a pod
kubectl exec -it <pod-name> -- <command>

# Open a shell in a pod
kubectl exec -it <pod-name> -- /bin/bash

# Copy files to/from a pod
kubectl cp <pod-name>:/path/to/pod/file /path/to/local/file
kubectl cp /path/to/local/file <pod-name>:/path/to/pod/file

Working with Deployments

# Scale a deployment
kubectl scale deployment <deployment-name> --replicas=<number>

# Rollout status of a deployment
kubectl rollout status deployment/<deployment-name>

# Rollback a deployment
kubectl rollout undo deployment/<deployment-name>

# Pause a deployment rollout
kubectl rollout pause deployment/<deployment-name>

# Resume a deployment rollout
kubectl rollout resume deployment/<deployment-name>

# View rollout history
kubectl rollout history deployment/<deployment-name>

Labels and Selectors

# List resources with specific labels
kubectl get <resource-type> -l key1=value1,key2=value2

# Add a label to a resource
kubectl label <resource-type> <resource-name> key=value

# Remove a label from a resource
kubectl label <resource-type> <resource-name> key-

Resource Management

# View resource usage of pods
kubectl top pod

# View resource usage of nodes
kubectl top node

# Set resource quotas for a namespace
kubectl create quota <quota-name> --hard=cpu=1,memory=1G,pods=10 -n <namespace-name>

Configuration and Context

# View merged kubeconfig settings
kubectl config view

# Use a specific context
kubectl config use-context <context-name>

# Get the current context
kubectl config current-context

# List all contexts
kubectl config get-contexts

Output Formatting

kubectl supports various output formats:

# Output in JSON format
kubectl get pods -o json

# Output in YAML format
kubectl get pods -o yaml

# Custom output format using jsonpath
kubectl get pods -o jsonpath='{.items[0].metadata.name}'

# Table format with custom columns
kubectl get pods -o custom-columns=NAME:.metadata.name,STATUS:.status.phase

# Sort output
kubectl get pods --sort-by=.metadata.name

Kubectl Plugins

kubectl can be extended with plugins:

# Install kubectl-krew (plugin manager)
# See https://krew.sigs.k8s.io/docs/user-guide/setup/install/

# List available plugins
kubectl krew list

# Install a plugin
kubectl krew install <plugin-name>

# Use a plugin
kubectl <plugin-name>

Best Practices

  1. Use kubectl apply instead of kubectl create: This allows for declarative management of resources
  2. Always specify namespaces: Use -n <namespace> to avoid accidental changes to resources
  3. Use labels and selectors: For efficient resource management and organization
  4. Set resource limits: Always specify CPU and memory limits for your containers
  5. Use version control: Store your YAML files in a version control system
  6. Use kubectl aliases: Create aliases for frequently used commands to save time, e.g. alias kgp="kubectl get pods" allows you to run kgp to list pods in your cluster

Further Reading