Implementación paso a paso de OPA Gatekeeper para reemplazar PodSecurityPolicies en Kubernetes
Introducción
Desde la versión 1.25 de Kubernetes, PodSecurityPolicy (PSP) está marcada como deprecated y será eliminada en futuras versiones. Para mantener un control granular sobre la configuración de los pods, la comunidad recomienda usar OPA (Open Policy Agent) junto con su controlador Gatekeeper. Este artículo muestra, paso a paso, cómo instalar Gatekeeper en un clúster y crear políticas de compliance que sustituyan a las PSP tradicionales.
1. Preparación del entorno
1.1 Requisitos previos
- Un clúster Kubernetes 1.22+ (preferiblemente 1.26 o superior).
- kubectl configurado con permisos de
cluster-admin. - Conexión a internet para descargar los manifests de Gatekeeper.
1.2 Verificar la versión de Kubernetes
kubectl version --short
Salida esperada:
Client Version: v1.28.0
Server Version: v1.28.0
1.3 Desactivar PSP (si sigue activa)
Si tu clúster todavía tiene PSP habilitado, elimina los objetos existentes para evitar conflictos:
kubectl get psp -A
kubectl delete psp --all --all-namespaces
2. Instalación de OPA Gatekeeper
2.1 Usar el manifiesto oficial
Gatekeeper se distribuye como un conjunto de objetos CustomResourceDefinition (CRD) y un controlador deployment. El método más sencillo es aplicar el manifest gatekeeper.yaml directamente desde el repositorio oficial:
kubectl apply -f https://raw.githubusercontent.com/open-policy-agent/gatekeeper/master/deploy/gatekeeper.yaml
Este comando crea los siguientes componentes clave:
- gatekeeper-system namespace.
- CRDs:
ConstraintTemplateyConstraint. - Deployment
gatekeeper-controller-managercon 2 réplicas por alta disponibilidad.
2.2 Verificar la instalación
kubectl get pods -n gatekeeper-system
kubectl get crd | grep gatekeeper
Deberías ver algo como:
NAME READY STATUS RESTARTS AGE
gatekeeper-controller-manager-5d8c9b7c7c-9j4z8 2/2 Running 0 2m
...
customresourcedefinition.apiextensions.k8s.io/constrainttemplates.templates.gatekeeper.sh
customresourcedefinition.apiextensions.k8s.io/constraints.constraints.gatekeeper.sh
3. Creación de políticas de seguridad (ConstraintTemplates y Constraints)
3.1 Conceptos clave
Gatekeeper opera con dos objetos:
- ConstraintTemplate: define la lógica Rego que será reutilizada.
- Constraint: instancia del template con parámetros concretos (por ejemplo, listas de imágenes permitidas).
3.2 Ejemplo: Política que prohíbe el uso de privilegios elevados
Este template reemplaza la PSP privileged: false.
apiVersion: templates.gatekeeper.sh/v1 kind: ConstraintTemplate metadata: name: k8srequiredprivileged spec: crd: spec: names: kind: K8sRequiredPrivileged validation: openAPIV3Schema: type: object properties: {} targets: - target: admission.k8s.gatekeeper.sh rego: | package k8srequiredprivilegedviolation[{"msg": msg}] { input.review.object.spec.containers[_].securityContext.privileged == true msg := sprintf("El contenedor %s está ejecutándose como privileged", [input.review.object.metadata.name]) }
Aplicamos el template:
kubectl apply -f k8srequiredprivileged_template.yaml
3.3 Instanciar la restricción (Constraint)
En este caso no necesitamos parámetros, solo habilitarla:
apiVersion: constraints.gatekeeper.sh/v1
kind: K8sRequiredPrivileged
metadata:
name: disallow-privileged
spec:
match:
kinds:
- apiGroups: [""]
kinds: ["Pod"]
kubectl apply -f disallow-privileged_constraint.yaml
3.4 Política de runAsNonRoot (equivalente a PSP)
apiVersion: templates.gatekeeper.sh/v1 kind: ConstraintTemplate metadata: name: k8srequiredrunasnonroot spec: crd: spec: names: kind: K8sRequiredRunAsNonRoot targets: - target: admission.k8s.gatekeeper.sh rego: | package k8srequiredrunasnonrootviolation[{"msg": msg}] { container := input.review.object.spec.containers[_] not container.securityContext.runAsNonRoot msg := sprintf("El contenedor %s no tiene runAsNonRoot=true", [container.name]) }
apiVersion: constraints.gatekeeper.sh/v1
kind: K8sRequiredRunAsNonRoot
metadata:
name: enforce-runasnonroot
spec:
match:
kinds:
- apiGroups: [""]
kinds: ["Pod"]
Aplicar ambos objetos:
kubectl apply -f k8srequiredrunasnonroot_template.yaml
kubectl apply -f enforce-runasnonroot_constraint.yaml
4. Validación y pruebas
4.1 Crear un pod que viole la política
apiVersion: v1
kind: Pod
metadata:
name: test-privileged
spec:
containers:
- name: nginx
image: nginx:latest
securityContext:
privileged: true
kubectl apply -f test-privileged.yaml
Resultado esperado:
Error from server (Forbidden): error when creating "test-privileged.yaml": admission webhook "validation.gatekeeper.sh" denied the request: [disallow-privileged] El contenedor test-privileged está ejecutándose como privileged
4.2 Ver logs del controlador
kubectl logs -n gatekeeper-system -l control-plane=controller-manager -c manager --tail=20
4.3 Auditar recursos existentes
Gatekeeper provee un audit que revisa objetos ya creados:
kubectl apply -f https://raw.githubusercontent.com/open-policy-agent/gatekeeper/master/deploy/gatekeeper.yaml
kubectl get auditreports -A
5. Troubleshooting y errores comunes
5.1 El webhook no se dispara
- Síntoma: Los pods se crean aunque violen la política.
- Causas habituales:
- El
ValidatingWebhookConfigurationapunta a un servicio inexistente. - El namespace donde se aplica la constraint no está incluido en
match.namespace.
- El
- Solución:
Verifica que elkubectl get validatingwebhookconfigurations gatekeeper-validating-webhook-configuration -o yaml | grep serviceserviceNameseagatekeeper-webhook-servicey que elnamespaceseagatekeeper-system. Si falta, reaplica el manifiesto oficial.
5.2 Error “no matches for kind … in version …”
Este error ocurre cuando intentas aplicar un ConstraintTemplate antes de que el CRD correspondiente exista.
- Solución: Espera a que los CRDs se hayan creado:
kubectl wait --for condition=established crd/constrainttemplates.templates.gatekeeper.sh --timeout=30s
5.3 Problemas de performance en clústers grandes
Gatekeeper evalúa cada objeto en cada admisión. En entornos con miles de pods por segundo, puedes:
- Ajustar
--audit-intervaly--audit-from-cacheen el deployment del manager. - Habilitar
mutationsolo donde sea necesario y usarexemptNamespacespara namespaces de pruebas.
5.4 Mensajes de error poco claros
Los mensajes de violation provienen del bloque msg en Rego. Si no aparecen, verifica que la regla esté retornando el objeto correcto:
violation[{"msg": msg}] { … }
Asegúrate de no estar usando deny (obsoleto) y de que el input.review.object sea el esperado.
Conclusión
OPA Gatekeeper es la solución recomendada para sustituir PodSecurityPolicies y llevar el control de compliance a un nivel declarativo y extensible. Al seguir los pasos descritos—instalación, definición de ConstraintTemplate, creación de Constraint, pruebas y auditoría—los administradores pueden garantizar que todos los pods cumplan con requisitos críticos como runAsNonRoot o la ausencia de privilegios elevados.
Además, la arquitectura basada en Rego permite evolucionar las políticas sin tocar el código de la aplicación, facilitando auditorías y certificaciones. Mantén siempre actualizado Gatekeeper a la última versión estable y revisa periódicamente los audit reports para detectar desviaciones que puedan haber escapado al proceso de admisión.