← Volver al listado de tecnologías ← Índice de K3s

Capitulo 4: kubectl Esencial

1 de marzo de 2026 Por: Artiko

k3skuberneteskubectlcli

Capitulo 4: kubectl Esencial

kubectl en K3s

K3s incluye kubectl integrado en el mismo binario. Puedes usarlo de dos formas:

# Opcion 1: kubectl integrado
sudo k3s kubectl get nodes

# Opcion 2: symlink (creado por el instalador)
sudo kubectl get nodes

Si prefieres usar kubectl como herramienta independiente (para gestionar multiples clusters), puedes instalarlo por separado:

# Instalar kubectl standalone
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

Configurar KUBECONFIG

kubectl necesita saber donde esta el cluster. K3s genera el archivo de configuracion en /etc/rancher/k3s/k3s.yaml.

Opcion 1: Variable de entorno

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

Agrega esta linea a tu ~/.bashrc o ~/.zshrc para que persista.

Opcion 2: Copiar al directorio estandar

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config

Opcion 3: Acceso remoto

Para gestionar K3s desde tu maquina local, copia el kubeconfig y cambia la IP:

# En el servidor
sudo cat /etc/rancher/k3s/k3s.yaml

# En tu maquina local, pegar el contenido y cambiar:
# server: https://127.0.0.1:6443 → server: https://IP-SERVIDOR:6443

El server debe tener el TLS SAN configurado para la IP o dominio externo:

curl -sfL https://get.k3s.io | sh -s - --tls-san IP-PUBLICA

Comandos de Informacion

get - Listar recursos

# Pods en el namespace actual
kubectl get pods

# Pods en todos los namespaces
kubectl get pods -A

# Pods con mas detalle
kubectl get pods -o wide

# Nodos del cluster
kubectl get nodes

# Services
kubectl get svc

# Todos los recursos comunes
kubectl get all

describe - Detalle de un recurso

# Detalle de un pod (eventos, condiciones, volumenes)
kubectl describe pod mi-pod

# Detalle de un nodo (capacidad, pods asignados)
kubectl describe node mi-nodo

# Detalle de un servicio
kubectl describe svc mi-servicio

logs - Ver logs de contenedores

# Logs de un pod
kubectl logs mi-pod

# Logs en tiempo real
kubectl logs -f mi-pod

# Logs de un contenedor especifico en pod multi-contenedor
kubectl logs mi-pod -c nombre-contenedor

# Ultimas 50 lineas
kubectl logs --tail=50 mi-pod

# Logs de la ultima hora
kubectl logs --since=1h mi-pod

top - Uso de recursos

# CPU y RAM por nodo
kubectl top nodes

# CPU y RAM por pod
kubectl top pods

# Top en todos los namespaces
kubectl top pods -A

Requiere metrics-server (incluido en K3s por defecto).

Comandos CRUD

create - Crear recursos imperativamente

# Crear un namespace
kubectl create namespace staging

# Crear un deployment
kubectl create deployment nginx --image=nginx:alpine

# Crear un servicio
kubectl create service clusterip nginx --tcp=80:80

apply - Aplicar configuracion declarativa

# Aplicar un archivo YAML
kubectl apply -f mi-deployment.yaml

# Aplicar todos los YAML de un directorio
kubectl apply -f ./manifests/

# Aplicar desde URL
kubectl apply -f https://ejemplo.com/manifest.yaml

apply es el metodo recomendado. Crea el recurso si no existe o lo actualiza si ya existe.

delete - Eliminar recursos

# Eliminar un pod
kubectl delete pod mi-pod

# Eliminar un deployment (y sus pods)
kubectl delete deployment mi-app

# Eliminar desde archivo YAML
kubectl delete -f mi-deployment.yaml

# Eliminar todos los pods de un namespace
kubectl delete pods --all -n staging

# Forzar eliminacion (pod atascado en Terminating)
kubectl delete pod mi-pod --force --grace-period=0

edit - Editar recursos en vivo

# Abre el recurso en $EDITOR
kubectl edit deployment mi-app

# Editar un servicio
kubectl edit svc mi-servicio

Los cambios se aplican inmediatamente al guardar y cerrar el editor.

Comandos de Debugging

exec - Ejecutar comandos dentro de un pod

# Abrir una shell interactiva
kubectl exec -it mi-pod -- /bin/sh

# Ejecutar un comando puntual
kubectl exec mi-pod -- ls /app

# En un contenedor especifico
kubectl exec -it mi-pod -c sidecar -- /bin/sh

port-forward - Tunel a un pod o servicio

# Forward local:8080 → pod:80
kubectl port-forward pod/mi-pod 8080:80

# Forward a un servicio
kubectl port-forward svc/mi-servicio 8080:80

# Escuchar en todas las interfaces (no solo localhost)
kubectl port-forward --address 0.0.0.0 svc/mi-servicio 8080:80

Util para acceder a servicios que no estan expuestos externamente.

cp - Copiar archivos desde/hacia pods

# Copiar archivo local al pod
kubectl cp archivo.txt mi-pod:/tmp/archivo.txt

# Copiar archivo del pod a local
kubectl cp mi-pod:/var/log/app.log ./app.log

Formatos de Output

-o wide

Muestra columnas adicionales (IP del pod, nodo donde corre):

kubectl get pods -o wide

-o yaml

Output completo en YAML (util para ver toda la configuracion):

kubectl get deployment mi-app -o yaml

-o json

Output en JSON:

kubectl get pods -o json

-o jsonpath

Extraer campos especificos:

# IP de un pod
kubectl get pod mi-pod -o jsonpath='{.status.podIP}'

# Imagenes de todos los pods
kubectl get pods -o jsonpath='{.items[*].spec.containers[*].image}'

# Nombres y estados
kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end}'

-o name

Solo nombres de recursos (util para scripting):

kubectl get pods -o name
# pod/nginx-abc123
# pod/redis-xyz789

Autocompletado

Bash

echo 'source <(kubectl completion bash)' >> ~/.bashrc
source ~/.bashrc

Zsh

echo 'source <(kubectl completion zsh)' >> ~/.zshrc
source ~/.zshrc

Despues de configurar, presiona Tab para autocompletar nombres de recursos, namespaces y subcomandos.

Aliases Utiles

Agrega estos aliases a tu ~/.bashrc o ~/.zshrc:

# Alias basico
alias k='kubectl'

# Pods
alias kgp='kubectl get pods'
alias kgpa='kubectl get pods -A'
alias kgpw='kubectl get pods -o wide'

# Services
alias kgs='kubectl get svc'

# Deployments
alias kgd='kubectl get deployments'

# Logs
alias kl='kubectl logs'
alias klf='kubectl logs -f'

# Aplicar y eliminar
alias ka='kubectl apply -f'
alias kd='kubectl delete -f'

# Contexto y namespace
alias kns='kubectl config set-context --current --namespace'

Uso:

kgp              # kubectl get pods
kgpa             # kubectl get pods -A
klf mi-pod       # kubectl logs -f mi-pod
ka deploy.yaml   # kubectl apply -f deploy.yaml
kns staging      # cambiar al namespace staging

Cheat Sheet

Comando	Descripcion
`kubectl get pods`	Listar pods
`kubectl get pods -A`	Pods en todos los namespaces
`kubectl get nodes`	Listar nodos
`kubectl get svc`	Listar services
`kubectl get ingress`	Listar ingress
`kubectl get all`	Listar recursos principales
`kubectl describe pod <nombre>`	Detalle de un pod
`kubectl logs <pod>`	Ver logs
`kubectl logs -f <pod>`	Logs en tiempo real
`kubectl exec -it <pod> -- /bin/sh`	Shell en un pod
`kubectl apply -f <archivo>`	Aplicar manifiesto
`kubectl delete -f <archivo>`	Eliminar por manifiesto
`kubectl port-forward svc/<svc> 8080:80`	Tunel a un servicio
`kubectl top pods`	Uso de CPU/RAM por pod
`kubectl rollout status deploy/<nombre>`	Estado del rollout
`kubectl rollout undo deploy/<nombre>`	Rollback del deployment
`kubectl scale deploy/<nombre> --replicas=3`	Escalar replicas
`kubectl config get-contexts`	Ver contextos configurados
`kubectl config use-context <nombre>`	Cambiar de cluster/contexto
`kubectl api-resources`	Listar tipos de recursos disponibles

Labels y Selectors

Los labels son pares clave-valor que etiquetan recursos. Los selectors filtran por labels:

# Filtrar pods por label
kubectl get pods -l app=nginx

# Multiples labels
kubectl get pods -l app=nginx,env=prod

# Agregar label a un recurso
kubectl label pod mi-pod env=staging

# Eliminar un label
kubectl label pod mi-pod env-

Los labels son fundamentales en Kubernetes. Los Services usan selectors para encontrar sus pods y los Deployments para gestionar sus ReplicaSets.

Siguiente: Capitulo 5: Pods y Deployments —>