Vault Agent Injector · Admission Webhook

El corazon de la integracion Vault-Kubernetes. Un Mutating Admission Webhook que intercepta la creacion de pods, detecta annotations de Vault y modifica el pod spec para inyectar un init container que recupera secrets antes de que la app arranque.

Que Es y Como Funciona

El Vault Agent Injector es un Mutating Admission Webhook de Kubernetes. Cuando el API Server recibe una solicitud de creacion de pod, antes de persistirla, envia el pod spec al Injector. Si el pod tiene annotations de Vault, el Injector modifica el spec agregando un init container. Si no, lo deja pasar sin cambios.

El Injector no tiene acceso a los secrets. Solo modifica el pod spec para agregar el init container. Es el Vault Agent (init container) quien se autentica con Vault usando el ServiceAccount token del pod y recupera los secrets. El Injector orquesta, no accede.

Las Annotations

Cinco annotations controlan el comportamiento del Injector. Tres son obligatorias: sin ellas, el Injector no interviene.

vault.hashicorp.com/agent-inject true obligatorio

Activa la inyeccion del Vault Agent en este pod. Sin esta annotation, el Injector ignora el pod completamente.

vault.hashicorp.com/agent-inject-secret-[name] secret/data/... obligatorio

Define un secret a inyectar. El nombre despues de 'secret-' es el archivo donde se escribe. Ej: agent-inject-secret-db escribe en /vault/secrets/db.

vault.hashicorp.com/role [role-name] obligatorio

Rol de Vault que asigna politicas al ServiceAccount del pod. Define que secrets puede leer este pod.

vault.hashicorp.com/agent-inject-template-[name] [template] opcional

Template Go para formatear el secret. Util cuando se necesita un formato especifico (JSON, YAML, env file) en lugar del valor crudo.

vault.hashicorp.com/auth-path auth/kubernetes opcional

Path del metodo de autenticacion Kubernetes en Vault. Default: auth/kubernetes.

  annotations:
    vault.hashicorp.com/agent-inject: "true"
    vault.hashicorp.com/agent-inject-secret-admin: "secret/data/grafana"
    vault.hashicorp.com/role: "grafana"
    vault.hashicorp.com/agent-inject-template-admin: |
      {{- with secret "secret/data/grafana" -}}
      GF_SECURITY_ADMIN_USER={{ .Data.data.admin_user }}
      GF_SECURITY_ADMIN_PASSWORD={{ .Data.data.admin_password }}
      {{- end }}

Componentes del Injector

Seis recursos de Kubernetes forman el Injector. Cada uno tiene una responsabilidad especifica.

ServiceAccount

Identidad del Injector ante Kubernetes. Necesita permisos para leer pods y mutation webhooks.

serviceaccount.yml

ClusterRole

Define permisos RBAC: get/list/watch sobre pods y mutation webhooks. Sin esto, el Injector no puede interceptar la creacion de pods.

clusterrole.yml

ClusterRoleBinding

Vincula el ServiceAccount con el ClusterRole. Es la autorizacion que permite al Injector actuar.

clusterrolebinding.yml

Deployment

El Injector en si: un pod escuchando en el puerto 8080. Expone /mutate que el API Server llama cuando se crea un pod con annotations de Vault.

injector-deployment.yml

Service

Service ClusterIP que expone el Injector dentro del cluster. El API Server necesita alcanzarlo para enviar AdmissionReview requests.

service.yml

MutatingWebhookConfiguration

Registra el webhook ante el API Server. Define que pods se interceptan y a que URL se envian.

mutatingwebhook.yml

Que Inyecta el Webhook

Cuando el Injector detecta annotations de Vault, modifica el pod spec agregando tres elementos.

1. Volumen compartido

emptyDir: vault-secrets

Mount point /vault/secrets/ compartido entre el init container y el contenedor principal. Vive mientras el pod existe.

2. Init container

vault-agent-init

Se autentica con Vault usando el ServiceAccount token. Recupera los secrets declarados en las annotations. Los escribe como archivos en /vault/secrets/.

3. Sidecar (opcional)

vault-agent

Renueva el token de Vault periodicamente. Actualiza los secrets si cambiaron en Vault. Util para pods long-running que no pueden reiniciarse.

Init container vs sidecar. El init container se ejecuta una vez y termina. El sidecar corre toda la vida del pod. Para secrets estaticos (no rotan), el init container es suficiente. Para secrets dinamicos (rotacion automatica), se necesita el sidecar.

Siguiente: Kubernetes Auth

El Injector necesita que Vault confie en los ServiceAccounts de Kubernetes. La pagina siguiente explica como se configura el metodo de autenticacion Kubernetes en Vault.

Kubernetes Auth