freeleaps-ops/docs/examples/kubectl-quick-reference.md

# kubectl Quick Reference Guide

## 🚀 **Essential Commands for Junior Engineers**

### **Basic Resource Management**

```bash
# Get resources
kubectl get pods
kubectl get deployments
kubectl get services
kubectl get namespaces
kubectl get configmaps
kubectl get secrets
kubectl get pvc
kubectl get ingress

# Get all resources in namespace
kubectl get all -n <namespace>

# Get resources with labels
kubectl get pods -l app=web-app
kubectl get pods -l environment=production

# Get resources in wide format
kubectl get pods -o wide
kubectl get nodes -o wide
```

### **Resource Creation**

```bash
# Create from YAML file
kubectl apply -f <file.yaml>

# Create from directory
kubectl apply -f <directory>/

# Create from URL
kubectl apply -f https://raw.githubusercontent.com/...

# Create resources directly
kubectl create namespace my-app
kubectl create deployment nginx --image=nginx:latest
kubectl create service clusterip nginx --tcp=80:80
kubectl create configmap app-config --from-literal=DB_HOST=postgres
kubectl create secret generic db-secret --from-literal=DB_PASSWORD=secret123
```

### **Resource Inspection**

```bash
# Describe resources
kubectl describe pod <pod-name>
kubectl describe deployment <deployment-name>
kubectl describe service <service-name>
kubectl describe namespace <namespace-name>

# Get resource YAML
kubectl get pod <pod-name> -o yaml
kubectl get deployment <deployment-name> -o yaml

# Get resource in specific format
kubectl get pod <pod-name> -o json
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[0].image}'
```

### **Logs and Debugging**

```bash
# View logs
kubectl logs <pod-name>
kubectl logs <pod-name> -f  # Follow logs
kubectl logs <pod-name> --previous  # Previous container
kubectl logs <pod-name> --tail=100  # Last 100 lines

# Execute commands in pods
kubectl exec -it <pod-name> -- /bin/bash
kubectl exec <pod-name> -- ls /app
kubectl exec <pod-name> -- cat /etc/passwd

# Port forwarding
kubectl port-forward <pod-name> 8080:80
kubectl port-forward service/<service-name> 8080:80
kubectl port-forward deployment/<deployment-name> 8080:80
```

### **Scaling and Updates**

```bash
# Scale deployments
kubectl scale deployment <deployment-name> --replicas=5
kubectl scale deployment <deployment-name> --replicas=0  # Scale to zero

# Update deployments
kubectl set image deployment/<deployment-name> <container-name>=<new-image>
kubectl set image deployment/nginx nginx=nginx:1.21

# Rollout management
kubectl rollout status deployment/<deployment-name>
kubectl rollout history deployment/<deployment-name>
kubectl rollout undo deployment/<deployment-name>
kubectl rollout pause deployment/<deployment-name>
kubectl rollout resume deployment/<deployment-name>
```

### **Resource Deletion**

```bash
# Delete resources
kubectl delete pod <pod-name>
kubectl delete deployment <deployment-name>
kubectl delete service <service-name>
kubectl delete namespace <namespace-name>

# Delete from YAML file
kubectl delete -f <file.yaml>

# Delete all resources in namespace
kubectl delete all --all -n <namespace>

# Force delete (use with caution)
kubectl delete pod <pod-name> --force --grace-period=0
```

### **Context and Namespace Management**

```bash
# View current context
kubectl config current-context

# List contexts
kubectl config get-contexts

# Switch context
kubectl config use-context <context-name>

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

# View cluster info
kubectl cluster-info
kubectl cluster-info dump
```

### **Resource Monitoring**

```bash
# Check resource usage
kubectl top pods
kubectl top nodes
kubectl top pods --containers

# Check events
kubectl get events
kubectl get events -n <namespace>
kubectl get events --sort-by='.lastTimestamp'

# Check resource quotas
kubectl get resourcequota
kubectl describe resourcequota <quota-name>
```

### **Troubleshooting Commands**

```bash
# Check node status
kubectl get nodes
kubectl describe node <node-name>

# Check service endpoints
kubectl get endpoints <service-name>
kubectl describe endpoints <service-name>

# Check persistent volumes
kubectl get pv
kubectl get pvc
kubectl describe pv <pv-name>

# Check ingress
kubectl get ingress
kubectl describe ingress <ingress-name>

# Check jobs and cronjobs
kubectl get jobs
kubectl get cronjobs
kubectl describe job <job-name>
kubectl describe cronjob <cronjob-name>
```

### **Useful Aliases**

```bash
# Add to your .bashrc or .zshrc
alias k='kubectl'
alias kg='kubectl get'
alias kd='kubectl describe'
alias kl='kubectl logs'
alias ke='kubectl exec -it'
alias kp='kubectl port-forward'
alias ka='kubectl apply -f'
alias kdel='kubectl delete'
alias kctx='kubectl config use-context'
alias kns='kubectl config set-context --current --namespace'
```

### **Common Patterns**

```bash
# Get all pods with their IPs
kubectl get pods -o wide

# Get all services with their endpoints
kubectl get services -o wide

# Get all resources in a namespace
kubectl get all -n <namespace>

# Get resources by label
kubectl get pods -l app=web-app,environment=production

# Get resources sorted by creation time
kubectl get pods --sort-by=.metadata.creationTimestamp

# Get resources in custom columns
kubectl get pods -o custom-columns=NAME:.metadata.name,STATUS:.status.phase,AGE:.metadata.creationTimestamp
```

### **Advanced Commands**

```bash
# Patch resources
kubectl patch deployment <deployment-name> -p '{"spec":{"replicas":5}}'

# Edit resources
kubectl edit deployment <deployment-name>
kubectl edit configmap <configmap-name>

# Copy files
kubectl cp <local-file> <pod-name>:/path/in/pod
kubectl cp <pod-name>:/path/in/pod <local-file>

# Run temporary pods
kubectl run test-pod --image=busybox --rm -it --restart=Never -- wget -O- <service-name>:<port>

# Check API resources
kubectl api-resources
kubectl explain <resource-type>
```

### **Context-Specific Commands**

```bash
# For debugging network issues
kubectl run test-pod --image=busybox --rm -it --restart=Never -- wget -O- <service-name>:<port>

# For checking storage
kubectl run test-pod --image=busybox --rm -it --restart=Never -- ls /data

# For testing DNS
kubectl run test-pod --image=busybox --rm -it --restart=Never -- nslookup <service-name>

# For checking secrets
kubectl run test-pod --rm -it --restart=Never --image=busybox -- env | grep DB_
```

## ⚠️ **Bad Practices to Avoid**

### **❌ DON'T DO THIS**

```bash
# ❌ NEVER use kubectl run for production applications
kubectl run my-app --image=my-app:latest --port=8080

# ❌ NEVER create standalone Pods for services
kubectl run database --image=postgres:13 --port=5432

# ❌ NEVER use imperative commands for production
kubectl run nginx --image=nginx:latest

# ❌ NEVER delete Pods directly (they'll be recreated by Deployment)
kubectl delete pod <pod-name>

# ❌ NEVER use --force without understanding the consequences
kubectl delete pod <pod-name> --force --grace-period=0
```

### **✅ DO THIS INSTEAD**

```bash
# ✅ Use Deployments for applications
kubectl create deployment my-app --image=my-app:latest

# ✅ Use Helm charts for complex applications
helm install my-app ./my-app-chart --namespace my-app

# ✅ Use kubectl apply for declarative deployments
kubectl apply -f deployment.yaml

# ✅ Use StatefulSets for databases
kubectl apply -f statefulset.yaml

# ✅ Delete Deployments, not Pods
kubectl delete deployment <deployment-name>

# ✅ Use proper resource management
kubectl scale deployment <deployment-name> --replicas=0
```

### **🔧 When `kubectl run` is Acceptable**

```bash
# ✅ OK: One-time debugging pods
kubectl run debug-pod --image=busybox --rm -it --restart=Never -- nslookup my-service

# ✅ OK: Temporary testing
kubectl run test-pod --image=nginx --rm -it --restart=Never -- curl http://my-service:80

# ✅ OK: Quick experiments (development only)
kubectl run temp-pod --image=nginx --port=80

# ✅ OK: Troubleshooting network issues
kubectl run test-pod --image=busybox --rm -it --restart=Never -- wget -O- my-service:80
```

## 🏭 **Your Codebase Best Practices**

### **Your Actual Commands**
```bash
# 🏭 REAL COMMANDS FROM YOUR CODEBASE
# From freeleaps-devops-reconciler/scripts/deploy.sh

# Helm deployment (primary method)
helm install/upgrade "$RELEASE_NAME" . \
  --namespace "$NAMESPACE" \
  --create-namespace \
  -f "$VALUES_FILE" \
  --set "image.tag=$IMAGE_TAG"

# kubectl apply (secondary method)
kubectl apply -f <directory>/

# Status checking
kubectl get pods -n "$NAMESPACE" -l "app.kubernetes.io/name=freeleaps-devops-reconciler"
kubectl logs -n "$NAMESPACE" deployment/"$RELEASE_NAME"
```

### **Best Practices**

1. **Always use namespaces** to organize resources
2. **Use labels** for better resource management
3. **Set resource limits** on all containers
4. **Use health checks** for reliability
5. **Use ConfigMaps and Secrets** for configuration
6. **Test changes** in a staging environment first
7. **Keep kubectl updated** to match your cluster version
8. **Use Deployments, not standalone Pods**
9. **Use Helm charts for complex applications**
10. **Use declarative YAML files**

### **Common Mistakes to Avoid**

```bash
# ❌ Don't do this
kubectl run nginx --image=nginx  # Creates a pod, not a deployment

# ✅ Do this instead
kubectl create deployment nginx --image=nginx

# ❌ Don't do this
kubectl delete pod <pod-name>  # Pod will be recreated by deployment

# ✅ Do this instead
kubectl delete deployment <deployment-name>

# ❌ Don't do this
kubectl exec <pod-name> -- rm -rf /  # Dangerous command

# ✅ Do this instead
kubectl exec <pod-name> -- ls /  # Safe inspection command
```