La API y kubectl
Todo lo que se hace en Kubernetes pasa por su API. Los ficheros YAML son los formularios donde describes lo que quieres, y kubectl es el programa con el que los entregas.
Una sola ventanilla para todo
En la lección 02 viste que el clúster tiene un recepcionista central, el kube-apiserver. Ahora toca ver cómo se habla con él. La regla es sencilla: nadie toca el clúster directamente. Ni las personas, ni las herramientas, ni las propias piezas de Kubernetes. Todo el mundo hace sus peticiones a la API, y la API decide si las acepta y las guarda en etcd.
Piensa en la ventanilla única de un ayuntamiento. Da igual que vayas en persona, por la web o mandes a un gestor: todos los trámites entran por la misma ventanilla, se comprueba que tengas permiso y se registran en el mismo archivo. Nadie entra al archivo por la puerta de atrás.
La API funciona por internet con HTTPS, como cualquier web. Eso quiere decir que podrías hablar con ella con cualquier programa, pero lo normal es usar kubectl, la herramienta oficial de línea de comandos.
El formulario: un fichero YAML
Para pedirle algo a Kubernetes rellenas un formulario. Ese formulario se escribe en un formato de texto llamado YAML: líneas de «nombre: valor» donde la sangría (los espacios del principio) indica qué va dentro de qué.
Todos los objetos de Kubernetes, sean del tipo que sean, tienen las mismas cuatro partes que rellenas tú, y una quinta que rellena Kubernetes:
| Campo | Qué es | En el formulario del ayuntamiento |
|---|---|---|
| apiVersion | Qué versión de la API entiende este formulario. | El modelo del impreso (versión 2024) |
| kind | Qué tipo de objeto pides: Pod, Deployment, Service… | Qué trámite es: licencia de obra, empadronamiento… |
| metadata | Los datos que lo identifican: nombre, namespace, etiquetas. | Nombre y datos del solicitante |
| spec | Lo que quieres: el estado deseado. | Lo que solicitas |
| status | Lo que hay de verdad ahora: el estado real. Lo escribe Kubernetes, no tú. | El sello de «en trámite» o «concedido» |
Este formulario pide «quiero siempre tres copias de mi tienda web en marcha». Los comentarios (lo que va detrás de #) son explicaciones, Kubernetes los ignora.
apiVersion: apps/v1 # los Deployment viven en el grupo «apps», versión 1 kind: Deployment # el tipo de objeto que pido metadata: name: tienda-web # cómo se llama namespace: ventas # en qué «carpeta» del clúster va labels: app: tienda # una etiqueta para encontrarlo luego spec: # LO QUE QUIERO replicas: 3 # tres copias en marcha, siempre selector: matchLabels: app: tienda # las copias son los Pods con esta etiqueta template: # el modelo de cada copia metadata: labels: app: tienda spec: containers: - name: web image: tienda-web:2.1 # la imagen de la lección 01 # No escribo «status»: lo rellena Kubernetes cuando ya está funcionando
Lo que pides y lo que hay
La pareja spec y status es el corazón de Kubernetes. Tú escribes el spec. Los controladores (los vigilantes de la lección 02) miran todo el rato el status, lo comparan con el spec y trabajan hasta que coinciden.
Grupos y versiones de la API
La API de Kubernetes es enorme, así que está ordenada en grupos (API groups), como los departamentos de un ayuntamiento. Por eso el campo apiVersion suele tener dos partes: grupo/versión.
| apiVersion | Grupo | Objetos que viven ahí |
|---|---|---|
| v1 | El grupo principal (core), que no tiene nombre | Pod, Service, ConfigMap, Secret, Namespace, Node |
| apps/v1 | apps | Deployment, ReplicaSet, StatefulSet, DaemonSet |
| batch/v1 | batch | Job, CronJob |
| networking.k8s.io/v1 | networking.k8s.io | Ingress, NetworkPolicy |
| rbac.authorization.k8s.io/v1 | rbac.authorization.k8s.io | Role, ClusterRole, RoleBinding |
El grupo core es el más antiguo y por eso se escribe sólo v1, sin nombre de grupo delante. Todo lo que se añadió después lleva su grupo.
Alfa, beta y estable
Cada funcionalidad nueva pasa por tres etapas antes de considerarse terminada, y se nota en el nombre de la versión:
Dos comandos te dicen qué hay en tu clúster sin tener que memorizar nada: kubectl api-resources lista todos los tipos de objeto con su grupo, y kubectl explain deployment.spec te explica cada campo del formulario.
kubectl: el mando a distancia
kubectl (se pronuncia «cube-control» o «cube-cuddle», hay división de opiniones) es el programa que convierte lo que escribes en peticiones a la API. Casi todos sus comandos siguen el mismo patrón:
kubectl <verbo> <tipo> <nombre> # por ejemplo: kubectl describe pod tienda-web-7d9f
| Comando | Para qué sirve |
|---|---|
| kubectl get pods | Lista los objetos de un tipo, en una tabla corta. |
| kubectl describe pod X | Ficha completa de un objeto, con los eventos recientes al final. Lo primero que se mira cuando algo falla. |
| kubectl apply -f fichero.yaml | Entrega un formulario: crea el objeto si no existe y lo actualiza si ya existe. |
| kubectl create -f fichero.yaml | Crea el objeto. Si ya existe, da error. |
| kubectl delete -f fichero.yaml | Borra el objeto descrito en el fichero (también vale kubectl delete pod X). |
| kubectl logs X | Muestra lo que ha escrito la aplicación de un Pod: su «diario». |
Entregas el formulario de la tienda y miras cómo queda:
$ kubectl apply -f tienda.yaml deployment.apps/tienda-web created $ kubectl get pods -n ventas NAME READY STATUS RESTARTS AGE tienda-web-7d9f8c6b5-4kx2p 1/1 Running 0 20s tienda-web-7d9f8c6b5-9wq7z 1/1 Running 0 20s tienda-web-7d9f8c6b5-tm5rh 1/1 Running 0 20s
Tres copias, todas en marcha (Running). La opción -n ventas le dice a kubectl en qué namespace mirar.
Dos formas de pedir las cosas
Con kubectl se puede trabajar de dos maneras, y el examen pregunta por la diferencia:
- Imperativa (imperative): das órdenes paso a paso. «Crea esto», «escala a cinco», «borra aquello». Ejemplos: kubectl run, kubectl create deployment, kubectl scale.
- Declarativa (declarative): describes cómo quieres que quede todo en un fichero y lo entregas con kubectl apply. Kubernetes calcula él solo qué tiene que cambiar.
Imperativo es ir en taxi dando indicaciones: «a la derecha, ahora recto, en la rotonda la segunda». Si te despistas o hay obras, te pierdes.
Declarativo es darle la dirección al GPS. Tú dices adónde quieres llegar y él calcula el camino, y si hay un corte, recalcula solo.
En el trabajo real se prefiere la forma declarativa: los ficheros se guardan en Git, se revisan como cualquier documento y siempre se sabe qué hay en el clúster y por qué. Esa idea, llevada al extremo, se llama GitOps y la verás en la lección 11.
kubectl apply es la forma declarativa: crea o actualiza. kubectl create es imperativa: sólo crea, y falla si el objeto ya existe.
Y el campo status no se escribe en el YAML: lo rellena Kubernetes.
kubeconfig: el llavero
¿Cómo sabe kubectl a qué clúster hablar y quién eres? Lo lee de un fichero llamado kubeconfig, que por defecto está en tu carpeta personal, en ~/.kube/config. Se puede indicar otro con la variable KUBECONFIG o con la opción --kubeconfig.
Dentro hay tres listas:
- clusters: las direcciones de los clústeres (dónde está cada ventanilla).
- users: tus credenciales para cada uno (tu carné o tu certificado).
- contexts: combinaciones ya preparadas de clúster + usuario + namespace, con un nombre corto.
El kubeconfig es un llavero. Los clusters son las casas, los users son las llaves y cada contexto es una etiqueta en el llavero que dice «esta llave, para esta casa, y entro directo a la cocina». Cambiar de contexto es coger otra llave del llavero.
kubectl config get-contexts # qué contextos tengo y cuál está activo kubectl config use-context prod # cambiar al contexto «prod»
El kubeconfig no lo usa sólo kubectl: cualquier herramienta que hable con la API (Helm, por ejemplo) lo lee igual. Y un error clásico en la vida real: creer que estás en el clúster de pruebas cuando el contexto activo es el de producción.
Ampliar la API: CRD y Operators
Kubernetes trae de serie sus tipos de objeto: Pod, Deployment, Service… Pero ¿y si quieres que entienda algo nuevo, como «base de datos» o «certificado web»? Para eso existen los CRD (CustomResourceDefinition): sirven para añadir un tipo de formulario nuevo a la ventanilla. Una vez registrado, puedes escribir YAML con kind: Database y la API lo acepta y lo guarda como cualquier otro objeto.
Pero un formulario guardado no hace nada por sí solo. Hace falta alguien que lo lea y actúe. Ese alguien es un controlador personalizado, y la combinación de CRD más controlador se llama Operator.
Un Operator es como tener a un técnico experto metido dentro del clúster. El experto en bases de datos sabe cómo instalarla, cómo hacer copias de seguridad, cómo actualizarla sin perder datos y qué hacer si se cae. El Operator es ese conocimiento escrito como programa: tú rellenas «quiero una base de datos PostgreSQL con copia diaria» y él hace todo lo que haría el experto, día y noche.
Ejemplos reales: el Prometheus Operator (monta el sistema de métricas que verás en la lección 13), cert-manager (pide y renueva certificados HTTPS solo) o los operators de bases de datos como PostgreSQL.
Un CRD por sí solo sólo amplía la API: permite guardar objetos nuevos, pero no hace nada con ellos. Lo que actúa es el controlador. Si una pregunta habla de «automatizar el conocimiento de un operador humano», la respuesta es el patrón Operator.
Resumen en cinco frases
- Todo en Kubernetes pasa por la API (el kube-apiserver), que es la única que escribe en etcd.
- Los objetos se describen en YAML con apiVersion, kind, metadata y spec; el status lo rellena Kubernetes.
- La API está ordenada en grupos (core v1, apps/v1, batch/v1…) y cada versión madura de alfa a beta y a estable.
- kubectl es el mando: lo imperativo da órdenes sueltas y lo declarativo (apply) entrega el estado final.
- El kubeconfig guarda clústeres, usuarios y contextos; los CRD amplían la API y un Operator añade el controlador que la atiende.
Términos del examen
- API server
- La ventanilla única del clúster (kube-apiserver).
- Manifest
- El fichero YAML que describe un objeto.
- apiVersion
- Grupo y versión de la API del objeto, como apps/v1.
- kind
- El tipo de objeto: Pod, Deployment, Service…
- metadata
- Nombre, namespace, etiquetas y anotaciones.
- spec
- El estado deseado, lo que pides.
- status
- El estado real, lo que escribe Kubernetes.
- API group
- Cada «departamento» de la API. El principal se llama core.
- alpha · beta · GA
- Las etapas de madurez: experimental, probada y estable.
- kubectl
- La herramienta oficial de línea de comandos.
- Imperative
- Dar órdenes paso a paso (create, scale, run).
- Declarative
- Describir el estado final y entregarlo (apply).
- kubeconfig
- El llavero: clústeres, usuarios y contextos. Por defecto en ~/.kube/config.
- Context
- Combinación de clúster, usuario y namespace.
- CRD
- Forma de añadir tipos de objeto nuevos a la API.
- Operator
- CRD más un controlador que automatiza lo que haría un experto.
Comprueba que lo has entendido
1. Which field of a Kubernetes object is written by the system and describes its current state?
- spec
- metadata
- status
- kind
Ver respuesta
C. El status lo rellena Kubernetes con lo que hay de verdad. Tú escribes el spec, que es lo que quieres.
2. What is the correct apiVersion for a Deployment?
- v1
- apps/v1
- batch/v1
- core/v1
Ver respuesta
B. Los Deployment viven en el grupo apps. v1 a secas es para el grupo principal (Pod, Service…), batch/v1 es para Job y CronJob, y core/v1 no se escribe así.
3. Which command is an example of the declarative approach?
- kubectl apply -f app.yaml
- kubectl scale deployment web --replicas=5
- kubectl run nginx --image=nginx
- kubectl create deployment web --image=nginx
Ver respuesta
A. Con apply entregas un fichero con el estado final y Kubernetes calcula qué cambiar. Las otras tres son órdenes sueltas, es decir, imperativas.
4. In a kubeconfig file, what does a context combine?
- A cluster, a user and a namespace
- A pod, a service and a deployment
- An image, a tag and a registry
- A node, a kubelet and a runtime
Ver respuesta
A. Un contexto junta en un nombre corto el clúster, el usuario y, si quieres, el namespace por defecto. Es la etiqueta del llavero.
5. What is a Kubernetes Operator?
- A person with admin rights on the cluster
- A custom controller that uses custom resources to automate the management of an application
- A command-line tool that replaces kubectl
- A special type of node that runs the control plane
Ver respuesta
B. Un Operator combina CRD (los tipos nuevos) con un controlador que hace el trabajo de un experto: instalar, hacer copias, actualizar o reparar. No es una persona, aunque el nombre viene de ahí.