# open-policy-agent/gatekeeper architecture

> Architecture diagram of the GitHub repository open-policy-agent/gatekeeper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/open-policy-agent/gatekeeper
- Repository: https://github.com/open-policy-agent/gatekeeper

## Overview

Gatekeeper extends Kubernetes admission control with constraint-template-defined policies and constraint instances, alongside mutation, audit, and external-data capabilities. Administrators configure these resources through the Kubernetes API; Gatekeeper controllers reconcile them, while admission webhooks evaluate and mutate incoming requests. Audit checks existing resources and reports violations. The gator CLI provides local verification and policy-library management. The graph reflects README capabilities and sampled controller, cache, audit, and webhook paths; some subsystem wiring is inferred from module names and is intentionally not shown where call ownership is uncertain.

Main entry points: [`pkg/cachemanager/cachemanager.go`](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/cachemanager/cachemanager.go) (Resource cache), [`pkg/webhook/webhook.go`](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/webhook/webhook.go) (Admission webhook), [`pkg/webhook/mutation.go`](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/webhook/mutation.go) (Mutation webhook), [`pkg/gator/policy/client/client.go`](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/gator/policy/client/client.go) (Policy management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Policy configuration"]
  node_api_types["Gatekeeper CRDs"]
  node_template_controller["Template controller"]
  node_constraint_controller["Constraint controller"]
  node_controllers["Controller setup<br/>[controller.go]"]
end

subgraph group_runtime["Admission runtime"]
  node_cache_manager["Resource cache<br/>[cachemanager.go]"]
  node_watch_manager["Resource watches<br/>[manager.go]"]
  node_webhook["Admission webhook<br/>[webhook.go]"]
  node_policy_webhook["Policy evaluation<br/>[policy.go]"]
  node_mutation_webhook["Mutation webhook<br/>[mutation.go]"]
  node_mutation_engine["Mutation engine<br/>[system.go]"]
  node_targeting["Resource targeting<br/>[target.go]"]
end

subgraph group_operations["Audit and integrations"]
  node_audit_manager["Audit manager<br/>[manager.go]"]
  node_external_controller["External-data controller"]
  node_expansion_controller["Expansion controller"]
  node_export_controller["Export controller"]
  node_export_system["Export system<br/>[system.go]"]
end

subgraph group_cli["Policy CLI"]
  node_gator["gator CLI<br/>[gator.go]"]
  node_verify["Policy verification<br/>[runner.go]"]
  node_policy_client["Policy management<br/>[client.go]"]
  node_policy_catalog["Policy catalog<br/>[fetch.go]"]
end

node_admin(("Administrator"))
node_kube_api[("Kubernetes API")]
node_external_provider(("External provider"))

node_admin -->|"applies resources"| node_kube_api
node_kube_api -->|"sends events"| node_template_controller
node_kube_api -->|"sends events"| node_constraint_controller
node_template_controller -->|"reconciles templates"| node_kube_api
node_constraint_controller -->|"reconciles constraints"| node_kube_api
node_controllers -->|"starts"| node_cache_manager
node_cache_manager -->|"manages watches"| node_watch_manager
node_watch_manager -->|"replays changes"| node_cache_manager
node_kube_api -->|"sends admission requests"| node_webhook
node_webhook -->|"dispatches evaluation"| node_policy_webhook
node_webhook -->|"dispatches mutation"| node_mutation_webhook
node_policy_webhook -->|"reads policy data"| node_cache_manager
node_mutation_webhook -->|"applies mutators"| node_mutation_engine
node_mutation_webhook -->|"matches resources"| node_targeting
node_audit_manager -->|"reads resources"| node_kube_api
node_audit_manager -.->|"exports violations"| node_export_system
node_kube_api -->|"sends events"| node_external_controller
node_external_controller -->|"queries data"| node_external_provider
node_kube_api -->|"sends events"| node_expansion_controller
node_kube_api -->|"sends events"| node_export_controller
node_export_controller -->|"configures connections"| node_export_system
node_gator -->|"runs verification"| node_verify
node_verify -.->|"loads policy inputs"| node_policy_catalog
node_gator -->|"manages policies"| node_policy_client
node_policy_client -->|"fetches catalog"| node_policy_catalog
node_policy_client -->|"installs policies"| node_kube_api

click node_api_types "https://github.com/open-policy-agent/gatekeeper/tree/master/apis"
click node_template_controller "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/controller/constrainttemplate/constrainttemplate_controller.go"
click node_constraint_controller "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/controller/constraint/constraint_controller.go"
click node_controllers "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/controller/controller.go"
click node_cache_manager "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/cachemanager/cachemanager.go"
click node_watch_manager "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/watch/manager.go"
click node_webhook "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/webhook/webhook.go"
click node_policy_webhook "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/webhook/policy.go"
click node_mutation_webhook "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/webhook/mutation.go"
click node_mutation_engine "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/mutation/system.go"
click node_targeting "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/target/target.go"
click node_audit_manager "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/audit/manager.go"
click node_external_controller "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/controller/externaldata/externaldata_controller.go"
click node_expansion_controller "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/controller/expansion/expansion_controller.go"
click node_export_controller "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/controller/export/export_connection_controller.go"
click node_export_system "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/export/system.go"
click node_gator "https://github.com/open-policy-agent/gatekeeper/blob/master/cmd/gator/gator.go"
click node_verify "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/gator/verify/runner.go"
click node_policy_client "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/gator/policy/client/client.go"
click node_policy_catalog "https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/gator/policy/catalog/fetch.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_types,node_template_controller,node_constraint_controller,node_controllers toneBlue
class node_cache_manager,node_watch_manager,node_webhook,node_policy_webhook,node_mutation_webhook,node_mutation_engine,node_targeting,node_kube_api toneAmber
class node_audit_manager,node_external_controller,node_expansion_controller,node_export_controller,node_export_system toneMint
class node_gator,node_verify,node_policy_client,node_policy_catalog toneRose
class node_admin,node_external_provider toneIndigo
```

## Components

### Policy configuration

- [Gatekeeper CRDs](https://github.com/open-policy-agent/gatekeeper/tree/master/apis): `apis`
- [Template controller](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/controller/constrainttemplate/constrainttemplate_controller.go): `pkg/controller/constrainttemplate/constrainttemplate_controller.go`
- [Constraint controller](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/controller/constraint/constraint_controller.go): `pkg/controller/constraint/constraint_controller.go`
- [Controller setup](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/controller/controller.go): `pkg/controller/controller.go`

### Admission runtime

- [Resource cache](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/cachemanager/cachemanager.go): `pkg/cachemanager/cachemanager.go`
- [Resource watches](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/watch/manager.go): `pkg/watch/manager.go`
- [Admission webhook](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/webhook/webhook.go): `pkg/webhook/webhook.go`
- [Policy evaluation](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/webhook/policy.go): `pkg/webhook/policy.go`
- [Mutation webhook](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/webhook/mutation.go): `pkg/webhook/mutation.go`
- [Mutation engine](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/mutation/system.go): `pkg/mutation/system.go`
- [Resource targeting](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/target/target.go): `pkg/target/target.go`

### Audit and integrations

- [Audit manager](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/audit/manager.go): `pkg/audit/manager.go`
- [External-data controller](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/controller/externaldata/externaldata_controller.go): `pkg/controller/externaldata/externaldata_controller.go`
- [Expansion controller](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/controller/expansion/expansion_controller.go): `pkg/controller/expansion/expansion_controller.go`
- [Export controller](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/controller/export/export_connection_controller.go): `pkg/controller/export/export_connection_controller.go`
- [Export system](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/export/system.go): `pkg/export/system.go`

### Policy CLI

- [gator CLI](https://github.com/open-policy-agent/gatekeeper/blob/master/cmd/gator/gator.go): `cmd/gator/gator.go`
- [Policy verification](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/gator/verify/runner.go): `pkg/gator/verify/runner.go`
- [Policy management](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/gator/policy/client/client.go): `pkg/gator/policy/client/client.go`
- [Policy catalog](https://github.com/open-policy-agent/gatekeeper/blob/master/pkg/gator/policy/catalog/fetch.go): `pkg/gator/policy/catalog/fetch.go`

### Other components

- **Administrator**
- **Kubernetes API**
- **External provider**

## Connections

- Administrator → Kubernetes API: applies resources
- Kubernetes API → Template controller: sends events
- Kubernetes API → Constraint controller: sends events
- Template controller → Kubernetes API: reconciles templates
- Constraint controller → Kubernetes API: reconciles constraints
- Controller setup → Resource cache: starts
- Resource cache → Resource watches: manages watches
- Resource watches → Resource cache: replays changes
- Kubernetes API → Admission webhook: sends admission requests
- Admission webhook → Policy evaluation: dispatches evaluation
- Admission webhook → Mutation webhook: dispatches mutation
- Policy evaluation → Resource cache: reads policy data
- Mutation webhook → Mutation engine: applies mutators
- Mutation webhook → Resource targeting: matches resources
- Audit manager → Kubernetes API: reads resources
- Audit manager → Export system: exports violations
- Kubernetes API → External-data controller: sends events
- External-data controller → External provider: queries data
- Kubernetes API → Expansion controller: sends events
- Kubernetes API → Export controller: sends events
- Export controller → Export system: configures connections
- gator CLI → Policy verification: runs verification
- Policy verification → Policy catalog: loads policy inputs
- gator CLI → Policy management: manages policies
- Policy management → Policy catalog: fetches catalog
- Policy management → Kubernetes API: installs policies