kubectl Skill

Execute Kubernetes cluster management operations using the kubectl command-line tool.

Overview

This skill enables agents to:

• Query Resources — List and get details about pods, deployments, services, nodes, etc.
• Deploy & Update — Create, apply, patch, and update Kubernetes resources
• Debug & Troubleshoot — View logs, execute commands in containers, inspect events
• Manage Configuration — Update kubeconfig, switch contexts, manage namespaces
• Monitor Health — Check resource usage, rollout status, events, and pod conditions
• Perform Operations — Scale deployments, drain nodes, manage taints and labels

Prerequisites

1. kubectl binary installed and accessible on PATH (v1.20+)
2. kubeconfig file configured with cluster credentials (default: ~/.kube/config)
3. Active connection to a Kubernetes cluster

Quick Setup

Install kubectl

macOS:

brew install kubernetes-cli

Linux:

apt-get install -y kubectl  # Ubuntu/Debian
yum install -y kubectl      # RHEL/CentOS

Verify:

kubectl version --client
kubectl cluster-info  # Test connection

Essential Commands

Query Resources

kubectl get pods                    # List all pods in current namespace
kubectl get pods -A                 # All namespaces
kubectl get pods -o wide            # More columns
kubectl get nodes                   # List nodes
kubectl describe pod POD_NAME        # Detailed info with events

View Logs

kubectl logs POD_NAME                # Get logs
kubectl logs -f POD_NAME             # Follow logs (tail -f)
kubectl logs POD_NAME -c CONTAINER   # Specific container
kubectl logs POD_NAME --previous     # Previous container logs

Execute Commands

kubectl exec -it POD_NAME -- /bin/bash   # Interactive shell
kubectl exec POD_NAME -- COMMAND         # Run single command

Deploy Applications

kubectl apply -f deployment.yaml         # Apply config
kubectl create -f deployment.yaml        # Create resource
kubectl apply -f deployment.yaml --dry-run=client  # Test

Update Applications

kubectl set image deployment/APP IMAGE=IMAGE:TAG  # Update image
kubectl scale deployment/APP --replicas=3          # Scale pods
kubectl rollout status deployment/APP              # Check status
kubectl rollout undo deployment/APP                # Rollback

Manage Configuration

kubectl config view                  # Show kubeconfig
kubectl config get-contexts          # List contexts
kubectl config use-context CONTEXT   # Switch context

Common Patterns

Debugging a Pod

# 1. Identify the issue
kubectl describe pod POD_NAME

# 2. Check logs
kubectl logs POD_NAME
kubectl logs POD_NAME --previous

# 3. Execute debug commands
kubectl exec -it POD_NAME -- /bin/bash

# 4. Check events
kubectl get events --sort-by='.lastTimestamp'

Deploying a New Version

# 1. Update image
kubectl set image deployment/MY_APP my-app=my-app:v2

# 2. Monitor rollout
kubectl rollout status deployment/MY_APP -w

# 3. Verify
kubectl get pods -l app=my-app

# 4. Rollback if needed
kubectl rollout undo deployment/MY_APP

Preparing Node for Maintenance

# 1. Drain node (evicts all pods)
kubectl drain NODE_NAME --ignore-daemonsets

# 2. Do maintenance
# ...

# 3. Bring back online
kubectl uncordon NODE_NAME

Output Formats

The --output (-o) flag supports multiple formats:

• table — Default tabular format
• wide — Extended table with additional columns
• json — JSON format (useful with jq)
• yaml — YAML format
• jsonpath — JSONPath expressions
• custom-columns — Define custom output columns
• name — Only resource names

Examples:

kubectl get pods -o json | jq '.items[0].metadata.name'
kubectl get pods -o jsonpath='{.items[*].metadata.name}'
kubectl get pods -o custom-columns=NAME:.metadata.name,STATUS:.status.phase

Global Flags (Available to All Commands)

-n, --namespace=\x3Cns>           # Operate in specific namespace
-A, --all-namespaces           # Operate across all namespaces
--context=\x3Ccontext>            # Use specific kubeconfig context
-o, --output=\x3Cformat>          # Output format (json, yaml, table, etc.)
--dry-run=\x3Cmode>               # Dry-run mode (none, client, server)
-l, --selector=\x3Clabels>        # Filter by labels
--field-selector=\x3Cselector>    # Filter by fields
-v, --v=\x3Cint>                  # Verbosity level (0-9)

Dry-Run Modes

• --dry-run=client — Fast client-side validation (test commands safely)
• --dry-run=server — Server-side validation (more accurate)
• --dry-run=none — Execute for real (default)

Always test with --dry-run=client first:

kubectl apply -f manifest.yaml --dry-run=client

Advanced Topics

For detailed reference material, command-by-command documentation, troubleshooting guides, and advanced workflows, see:

• references/REFERENCE.md — Complete kubectl command reference
• scripts/ — Helper scripts for common tasks

Helpful Tips

1. Use label selectors for bulk operations:

   kubectl delete pods -l app=myapp
   kubectl get pods -l env=prod,tier=backend
   

2. Watch resources in real-time:

   kubectl get pods -w  # Watch for changes
   

3. Use -A flag for all namespaces:

   kubectl get pods -A  # See pods everywhere
   

4. Save outputs for later comparison:

   kubectl get deployment my-app -o yaml > deployment-backup.yaml
   

5. Check before you delete:

   kubectl delete pod POD_NAME --dry-run=client
   

Getting Help

kubectl help                      # General help
kubectl COMMAND --help            # Command help
kubectl explain pods              # Resource documentation
kubectl explain pods.spec         # Field documentation

Environment Variables

• KUBECONFIG — Path to kubeconfig file (can include multiple paths separated by :)
• KUBECTL_CONTEXT — Override default context

Resources

• Official kubectl Docs
• kubectl Cheat Sheet
• Kubernetes API Reference
• Agent Skills Specification

Version: 1.0.0
License: MIT
Compatible with: kubectl v1.20+, Kubernetes v1.20+