KCNA en ruta
Lección 04 · Fundamentos de Kubernetes (44 %)

La API y kubectl

Tema del examen: AdministrationLectura: 15 min

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.

Imagínatelo así

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.

kubectl, un panel web y una herramienta de despliegue hablan todos con el kube-apiserver, que es el único que guarda en etcd kubectl (tu terminal) Panel web Herramienta de despliegue kube-apiserver comprueba quién eres y si tienes permiso etcd el archivo
Tres caminos distintos, una sola ventanilla. Sólo la API escribe en etcd.

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:

CampoQué esEn el formulario del ayuntamiento
apiVersionQué versión de la API entiende este formulario.El modelo del impreso (versión 2024)
kindQué tipo de objeto pides: Pod, Deployment, Service…Qué trámite es: licencia de obra, empadronamiento…
metadataLos datos que lo identifican: nombre, namespace, etiquetas.Nombre y datos del solicitante
specLo que quieres: el estado deseado.Lo que solicitas
statusLo que hay de verdad ahora: el estado real. Lo escribe Kubernetes, no tú.El sello de «en trámite» o «concedido»
Ejemplo

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.

El spec dice tres copias, el status dice dos; el controlador arranca una más hasta que coinciden spec lo que pides (tú) replicas: 3 status lo que hay (Kubernetes) readyReplicas: 2 controlador compara «Falta una»: arranca otra copia
Si se cae una copia, el status baja a 2 y el controlador vuelve a dejarlo en 3. Sin que nadie se lo diga.

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.

apiVersionGrupoObjetos que viven ahí
v1El grupo principal (core), que no tiene nombrePod, Service, ConfigMap, Secret, Namespace, Node
apps/v1appsDeployment, ReplicaSet, StatefulSet, DaemonSet
batch/v1batchJob, CronJob
networking.k8s.io/v1networking.k8s.ioIngress, NetworkPolicy
rbac.authorization.k8s.io/v1rbac.authorization.k8s.ioRole, 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:

Las versiones de la API maduran de alfa a beta y de beta a estable Alfa v1alpha1 experimental desactivada por defecto puede desaparecer Beta v1beta1 bien probada aún puede cambiar algún detalle Estable (GA) v1, v2 lista para producción se mantiene durante muchas versiones
Como un coche nuevo: prototipo, prueba en carretera y modelo a la venta.
Para recordar

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
ComandoPara qué sirve
kubectl get podsLista los objetos de un tipo, en una tabla corta.
kubectl describe pod XFicha completa de un objeto, con los eventos recientes al final. Lo primero que se mira cuando algo falla.
kubectl apply -f fichero.yamlEntrega un formulario: crea el objeto si no existe y lo actualiza si ya existe.
kubectl create -f fichero.yamlCrea el objeto. Si ya existe, da error.
kubectl delete -f fichero.yamlBorra el objeto descrito en el fichero (también vale kubectl delete pod X).
kubectl logs XMuestra lo que ha escrito la aplicación de un Pod: su «diario».
Ejemplo

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:

Imagínatelo así

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.

Imperativo: una lista de órdenes; declarativo: un fichero con el estado final que se entrega con apply Imperativo: órdenes kubectl create deployment web kubectl scale deployment web kubectl set image ... rápido para pruebas · no queda escrito Declarativo: el destino tienda.yaml replicas: 3 image: 2.1 … apply clúster queda guardado · se repite igual siempre
Las órdenes sueltas se olvidan; el fichero se puede guardar, revisar y volver a aplicar.

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.

Ojo en el examen

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:

Imagínatelo así

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.

Un kubeconfig con dos clústeres, dos usuarios y dos contextos que los combinan; el contexto activo es pruebas ~/.kube/config clusters produccion laboratorio users ana-admin ana-dev contexts prod pruebas ★ activo «pruebas» = clúster laboratorio + usuario ana-dev + namespace ventas
Cada contexto junta una casa y una llave. kubectl usa siempre el contexto activo.
kubectl config get-contexts          # qué contextos tengo y cuál está activo
kubectl config use-context prod      # cambiar al contexto «prod»
Ojo en el examen

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.

Imagínatelo así

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.

El CRD añade un tipo nuevo; el usuario crea un objeto de ese tipo; el controlador del Operator lo vigila y crea las piezas necesarias 1 · CRDnuevo tipo: Database 2 · Tu YAMLkind: Database APIlo acepta y guarda 3 · Controladordel Operator: crea Pods,discos, copias de seguridad CRD + controlador = Operator
El CRD es el formulario nuevo; el controlador es el experto que lo atiende.

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.

Ojo en el examen

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

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?

  1. spec
  2. metadata
  3. status
  4. 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?

  1. v1
  2. apps/v1
  3. batch/v1
  4. 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?

  1. kubectl apply -f app.yaml
  2. kubectl scale deployment web --replicas=5
  3. kubectl run nginx --image=nginx
  4. 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?

  1. A cluster, a user and a namespace
  2. A pod, a service and a deployment
  3. An image, a tag and a registry
  4. 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?

  1. A person with admin rights on the cluster
  2. A custom controller that uses custom resources to automate the management of an application
  3. A command-line tool that replaces kubectl
  4. 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í.