Cada vez que escribimos en la consola kubectl apply -f deployment.yaml, parece que ocurre algo muy simple: la utilidad se conecta por HTTPS al nodo maestro, entrega el manifiesto y este queda guardado ordenadamente en la base de datos etcd. Pero si todo fuera tan elemental, los sistemas distribuidos no darían tantos quebraderos de cabeza al hacer troubleshooting.
En realidad, tras la fachada de un comando sencillo se esconde un pipeline estrictamente determinista de comprobaciones y transformaciones. kube-apiserver es el único componente del control plane de Kubernetes que tiene acceso directo a etcd. Ni el planificador, ni los controladores, ni los agentes kubelet en los nodos trabajadores se atreven a leer o escribir directamente en la base de datos. Todos ellos son exactamente igual de clientes del API server que tu terminal local.
Recorramos toda la ruta del paquete de red desde que lanzas el comando hasta la confirmación transaccional de la clave en el registro Raft de etcd.
Fase 0: Del terminal al manejador HTTP
Todo empieza en tu portátil. La utilidad kubectl lee el contexto desde ~/.kube/config, analiza el manifiesto y construye la petición HTTP. En los clústeres modernos, el cliente suele enviar una petición PATCH usando el protocolo Server-Side Apply o un POST al endpoint del recurso:
POST /apis/apps/v1/namespaces/default/deployments HTTP/2
Host: k8s-master.corp.local:6443
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
Cuando la petición llega al puerto 6443, kube-apiserver termina la conexión TLS. El servidor está escrito en Go y estructurado como una cadena de middlewares anidados. Primero se ejecutan los filtros internos: se asigna un audit ID, se arrancan los temporizadores de métricas y se comprueban los límites de API Priority and Fairness (APF). Si el servidor está sobrecargado, APF puede devolver de inmediato un estado 429 Too Many Requests. Si hay recursos suficientes, la petición pasa a autenticación.
Fase 1: Autenticación — «¿Quién eres?»
El objetivo principal de la fase de Authentication es identificar a quien ha llamado a la API. Por diseño, Kubernetes no almacena cuentas de usuario (Users) en su propia base de datos: un usuario es simplemente un nombre y una lista de grupos confirmados por una fuente de confianza externa.
El servidor hace pasar la petición entrante por una cadena de autenticadores configurados:
- Certificados de cliente X.509: el nombre de usuario se extrae del Common Name (CN) y los grupos, de Organization (O).
- Tokens Bearer: verificación de tokens de cuentas de servicio mediante las claves públicas del clúster.
- OpenID Connect (OIDC): validación de tokens JWT externos emitidos por proveedores corporativos (Keycloak, Okta).
- Webhook Token Authenticator: delegación de la verificación a un servicio externo a través de la TokenReview API.
En cuanto uno de los autenticadores identifica al cliente con éxito, construye la estructura user.Info (nombre de usuario, UID, grupos) y la adjunta al contexto de la petición. Si ningún plugin reconoce al cliente, la petición se corta con un error 401 Unauthorized.
Fase 2: Autorización — «¿Tienes permiso?»
Ahora el servidor ya sabe el nombre del visitante. La siguiente pregunta es: ¿tiene permiso ese usuario para ejecutar la operación create sobre el recurso deployments en el namespace default?
De esto se encarga el pipeline de autorización. Los autorizadores se consultan de forma secuencial:
- Node: autorizador especial que limita los permisos de kubelet exclusivamente a los recursos de su propio nodo.
- RBAC: compara la tupla
{user, groups, verb, resource, namespace}con las reglas deClusterRoleBindingyRoleBinding. - Webhook: consulta a servicios externos de autorización.
La regla funciona por primera coincidencia (first-match allow): si al menos un módulo autoriza la acción, la petición sigue adelante. Si todos los módulos responden con un rechazo, el cliente recibe el estado 403 Forbidden.
Fase 3: Controladores de admisión (Admission Controllers)
Después de RBAC, la petición llega a los controladores de admisión, divididos en dos fases.
Esquema de funcionamiento del Admission Webhook en Kubernetes: modificación secuencial del manifiesto por un webhook mutador y validación paralela de políticas por un webhook validador.
Admisión mutadora (Mutating Admission)
Los controladores mutadores completan el manifiesto con valores por defecto o lo modifican. Aquí intervienen tanto plugins integrados como webhooks externos MutatingAdmissionWebhook. Por ejemplo, un Service Mesh (Istio) intercepta la definición del pod e inyecta contenedores sidecar.
Aquí tienes un ejemplo mínimo de manejador de webhook en Go que añade una etiqueta de servicio:
package main
import (
"encoding/json"
"net/http"
admissionv1 "k8s.io/api/admission/v1"
)
func handleMutate(w http.ResponseWriter, r *http.Request) {
var review admissionv1.AdmissionReview
if err := json.NewDecoder(r.Body).Decode(&review); err != nil {
http.Error(w, "bad request", http.StatusBadRequest)
return
}
patchOps := []map[string]interface{}{
{"op": "add", "path": "/metadata/labels/audit-verified", "value": "true"},
}
patchBytes, _ := json.Marshal(patchOps)
patchType := admissionv1.PatchTypeJSONPatch
response := admissionv1.AdmissionResponse{
UID: review.Request.UID,
Allowed: true,
Patch: patchBytes,
PatchType: &patchType,
}
review.Response = &response
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(review)
}
Los webhooks mutadores se invocan de forma secuencial. Si un webhook se queda colgado o responde lento por red, todo el pipeline de creación de recursos se bloquea.
Validación del esquema y Validating Admission
Tras las mutaciones, el servidor comprueba que el esquema del objeto cumpla con los tipos de Go o con OpenAPI v3 en el caso de los CRD. Si algún campo contiene un valor incorrecto, la petición se rechaza con el código 422 Unprocessable Entity.
Después se ejecutan los webhooks validadores (ValidatingAdmissionWebhook), como OPA Gatekeeper o Kyverno. Trabajan en paralelo y comprueban las políticas de seguridad:
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
name: security-policy-checker
webhooks:
- name: check-privileged.corp.local
rules:
- apiGroups: [""]
apiVersions: ["v1"]
operations: ["CREATE", "UPDATE"]
resources: ["pods"]
clientConfig:
service:
name: policy-engine
namespace: security
path: "/validate-pods"
admissionReviewVersions: ["v1"]
sideEffects: None
timeoutSeconds: 3
failurePolicy: Fail
Con failurePolicy: Fail, un fallo del webhook bloquea el despliegue por completo.
Fase 4: Serialización y escritura en etcd
El manifiesto ha superado todos los puestos de control. El almacenamiento interno RESTStorage convierte la estructura Go del recurso en su versión de almacenamiento persistente (storage version) y la serializa en Protocol Buffers.
La escritura se realiza mediante una llamada gRPC a etcd bajo la clave:
/registry/deployments/default/my-awesome-app
La transacción se ejecuta con bloqueo optimista: se verifica resourceVersion. Si durante el procesamiento el objeto llegó a cambiar, etcd rechaza la transacción y el API server devuelve 409 Conflict. Ya tratamos aparte cómo la propiedad declarativa de campos en Server-Side Apply reduce al mínimo este tipo de conflictos.
Una vez confirmada la transacción en el registro Raft, el servidor responde al cliente con 201 Created. Y es justo en ese instante cuando, a través del mecanismo Watch API, los controladores en kube-controller-manager y el planificador se enteran del nuevo recurso y comienzan a arrancar físicamente los pods en los nodos.


