OPA Gatekeeper est l'admission controller officiel pour appliquer des policies OPA dans Kubernetes, projet CNCF sous l'ombrelle d'Open Policy Agent. Il expose la puissance du langage Rego d'OPA via des CRDs Kubernetes natifs : les ConstraintTemplates (qui définissent un type de règle réutilisable) et les Constraints (instances concrètes avec paramètres). Chaque admission de ressource est évaluée en temps réel, et Gatekeeper dispose d'un mode audit qui vérifie en continu les ressources déjà déployées.

La différence avec Kyverno : Gatekeeper offre plus de flexibilité pour des logiques complexes grâce à Rego, au prix d'une courbe d'apprentissage plus élevée.

Informations essentielles

Origine : Open Policy Agent / CNCF · Licence : Apache 2.0 · Architectures : x86_64, ARM64

Liens : Site officiel · Documentation · GitHub · Releases

Support : Projet actif sous l'ombrelle CNCF OPA (Graduated depuis 2021). Compatible Kubernetes 1.20+.

Stack par défaut

Composant	Valeur
Langage des policies	Rego (Open Policy Agent)
Primitives K8s	ConstraintTemplate (type), Constraint (instance)
Modes	`deny` (bloque) ou `warn` (avertissement)
Audit	Continu, configurable (intervalle, violations max)
Library officielle	60+ ConstraintTemplates prêts dans gatekeeper-library

Concepts clés

Concept	Description
ConstraintTemplate	Définit un nouveau type de CRD avec la logique Rego
Constraint	Instance d'un ConstraintTemplate avec paramètres et scope
OPA (Open Policy Agent)	Moteur d'évaluation des policies Rego (embarqué dans Gatekeeper)
Audit	Vérifie les ressources existantes selon les Constraints actives
Exemption	`config.gatekeeper.sh/v1alpha1` pour exclure namespaces/ressources

Prérequis

Ressource	Valeur
Kubernetes	1.20+
Helm	3.x
Droits	`cluster-admin`

Installation

Via Helm (recommandé)

helm repo add gatekeeper https://open-policy-agent.github.io/gatekeeper/charts
helm repo update

helm install gatekeeper gatekeeper/gatekeeper \
  --namespace gatekeeper-system --create-namespace

kubectl rollout status deploy/gatekeeper-controller-manager -n gatekeeper-system

Via manifest (alternative)

kubectl apply -f https://raw.githubusercontent.com/open-policy-agent/gatekeeper/release-3.17/deploy/gatekeeper.yaml

Vérification de l'installation

# 1. Pods Gatekeeper (controller + audit)
kubectl get pods -n gatekeeper-system
# gatekeeper-controller-manager-* (3/3 recommandé) et gatekeeper-audit-*

# 2. Webhooks enregistrés
kubectl get validatingwebhookconfigurations | grep gatekeeper
# gatekeeper-validating-webhook-configuration

# 3. CRDs disponibles
kubectl get crd | grep constraints.gatekeeper
# constrainttemplates.templates.gatekeeper.sh

# 4. Installer un ConstraintTemplate de test
kubectl apply -f - <<EOF
apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8srequiredlabels
spec:
  crd:
    spec:
      names:
        kind: K8sRequiredLabels
      validation:
        openAPIV3Schema:
          type: object
          properties:
            labels:
              type: array
              items: {type: string}
  targets:
  - target: admission.k8s.gatekeeper.sh
    rego: |
      package k8srequiredlabels
      violation[{"msg": msg}] {
        provided := {label | input.review.object.metadata.labels[label]}
        required := {label | label := input.parameters.labels[_]}
        missing := required - provided
        count(missing) > 0
        msg := sprintf("Labels manquants: %v", [missing])
      }
EOF

kubectl get constrainttemplate k8srequiredlabels
# AGE doit être présent et STATUS CREATED

# 5. Nettoyage
kubectl delete constrainttemplate k8srequiredlabels

Pièges courants à l'installation

Symptôme	Cause	Correction
Pods bloqués dans le namespace `gatekeeper-system`	Gatekeeper s'applique à lui-même	Ajouter le namespace en exemption dans la config
`ConstraintTemplate` en erreur	Syntaxe Rego incorrecte	Tester la règle sur le Rego Playground
Audit lent sur grand cluster	Trop de ressources à auditer	Réduire `auditInterval` ou limiter avec `--audit-chunk-size`
`webhook timeout`	Controller Gatekeeper surchargé	Passer à 3 replicas du controller

Créer des policies (ConstraintTemplate + Constraint)

ConstraintTemplate - Interdire les images latest

apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
  name: k8sdisallowedtags
spec:
  crd:
    spec:
      names:
        kind: K8sDisallowedTags
      validation:
        openAPIV3Schema:
          type: object
          properties:
            tags:
              type: array
              items: {type: string}
  targets:
  - target: admission.k8s.gatekeeper.sh
    rego: |
      package k8sdisallowedtags
      violation[{"msg": msg}] {
        container := input.review.object.spec.containers[_]
        tag := input.parameters.tags[_]
        endswith(container.image, concat(":", ["", tag]))
        msg := sprintf("Container '%v' utilise le tag interdit '%v'", [container.name, tag])
      }

Constraint - Appliquer la règle

apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sDisallowedTags
metadata:
  name: no-latest-tag
spec:
  enforcementAction: deny        # ou "warn" pour mode permissif
  match:
    kinds:
    - apiGroups: [""]
      kinds: [Pod]
    namespaces: [production, staging]
  parameters:
    tags: [latest, dev, test]

kubectl apply -f constrainttemplate-disallowed-tags.yaml
kubectl apply -f constraint-no-latest.yaml

# Tester
kubectl run bad-pod --image=nginx:latest -n production
# Error: Container 'bad-pod' utilise le tag interdit 'latest'

Audit des violations existantes

# Voir les violations des ressources déjà déployées
kubectl get k8sdisallowedtags no-latest-tag -o yaml
# status.violations: liste des ressources non conformes

# Toutes les violations de toutes les Constraints
kubectl get constraints -A -o json | \
  jq '.items[].status.violations[]? | {name: .name, namespace: .namespace, message: .message}'

Utiliser la gatekeeper-library

La library officielle contient 60+ ConstraintTemplates prêts à l'emploi :

# Cloner la library
git clone https://github.com/open-policy-agent/gatekeeper-library.git
cd gatekeeper-library/library

# Installer le template "requiredlabels"
kubectl apply -f general/requiredlabels/template.yaml

# Créer la Constraint associée
kubectl apply -f - <<EOF
apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredLabels
metadata:
  name: require-app-label
spec:
  enforcementAction: warn
  match:
    kinds:
    - apiGroups: ["apps"]
      kinds: [Deployment]
  parameters:
    message: "Le label 'app' est requis sur les Deployments"
    labels:
    - key: app
EOF

Mise à jour

helm repo update

helm upgrade gatekeeper gatekeeper/gatekeeper \
  --namespace gatekeeper-system \
  --reuse-values

kubectl rollout status deploy/gatekeeper-controller-manager -n gatekeeper-system

Troubleshooting

# Logs du controller
kubectl logs -n gatekeeper-system -l control-plane=controller-manager --tail=100

# Logs de l'audit
kubectl logs -n gatekeeper-system -l control-plane=audit-controller --tail=100

# Vérifier l'état d'une Constraint
kubectl describe <constraint-kind> <nom>
# status.byPod: état par replica du controller

# Toutes les violations actuelles
kubectl get constraints -A

Constraint qui ne bloque pas

# Vérifier l'enforcementAction
kubectl get <constraint-kind> <nom> -o yaml | grep enforcementAction
# deny = bloque, warn = avertit, dryrun = audit uniquement

# Vérifier le scope match (namespaces, kinds)
kubectl describe <constraint-kind> <nom> | grep -A10 "Match:"

Commandes utiles

kubectl get constrainttemplate                       # Templates disponibles
kubectl get constraints -A                           # Toutes les constraints actives
kubectl describe <constraint-kind> <nom>             # Violations + état
kubectl get config -n gatekeeper-system              # Configuration globale (exemptions)

Ressources

Documentation officielle : https://open-policy-agent.github.io/gatekeeper/website/docs/
Gatekeeper Library (60+ templates) : https://github.com/open-policy-agent/gatekeeper-library
Rego Playground : https://play.openpolicyagent.org/
GitHub : https://github.com/open-policy-agent/gatekeeper
Releases : https://github.com/open-policy-agent/gatekeeper/releases