# github/policy-controller architecture

> Architecture diagram of the GitHub repository github/policy-controller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/github/policy-controller
- Repository: https://github.com/github/policy-controller

## Overview

##### Project type and purpose
- This is an open-source Kubernetes admission controller (the “policy-controller”) plus supporting CLI tools (e.g., policy-tester) for enforcing supply-chain policies on container images via Sigstore (cosign) attestations. It is not a traditional full-stack web application but a control-plane extension and CLI toolkit.

##### File-structure highlights
- cmd/…: Five Go entrypoints:
- webhook: runs the admission-webhook server
- policy-tester: CLI for offline policy testing
- api-docs, schema: generate API documentation and CRD schema
- local-dev: convenience setup tool
- pkg/apis/…: CustomResourceDefinition (CRD) types (ClusterImagePolicy, TrustRoot)
- pkg/client, pkg/informers, pkg/injection: Kubernetes client-gen, informers, injection code for controller runtime
- pkg/reconciler: two controllers (clusterimagepolicy, trustroot) implementing the operator pattern
- pkg/webhook: validation logic, cache, registry auth modules
- config/: Kubernetes YAML to install CRDs, RBAC, webhook configuration, leader-election, logging, observability
- examples/, test/: sample policies, end-to-end scripts, policy test data
- hack/, release/: tooling scripts for codegen, dependency updates, packaging, CI workflows

##### Key components
- Kubernetes API Server & etcd
- CRDs: ClusterImagePolicy and TrustRoot stored in etcd
- Reconcilers (controllers):
- ClusterImagePolicy controller: watches CIP CRs → generates ConfigMap(s) with compiled policies
- TrustRoot controller: watches TrustRoot CRs → generates ConfigMap(s) for trusted roots
- Admission webhook Deployment:
- webhook server container → HTTP endpoint registered in Mutating/ValidatingWebhookConfiguration
- registry-auth subsystem (Azure, AWS, GCP, etc.)
- policy engine (pkg/policy) + verifier (pkg/policy/verifier.go)
- cache layer for attestation data
- External Sigstore services:
- Fulcio (certificate authority), Rekor (transparency log), Timestamp Authority (TSA)
- Container Registries: DockerHub, GHCR, ACR, GCR, etc.
- CLI plane (outside cluster):
- policy-tester: loads a policy CRD YAML + image reference → simulates validation
- api-docs & schema: generate docs for CRDs
- local-dev: bootstraps a dev cluster/environments

##### Relationships and data flows
- Administrators define CRDs (kubectl apply ClusterImagePolicy + TrustRoot) → API server
- Controllers (in-cluster) watch CRDs → compile and write ConfigMaps → webhook reads ConfigMaps
- A user creates a Pod or Deployment → kube-apiserver → dispatch to ValidatingWebhook
- Webhook server loads policy from ConfigMap + trust roots → fetches image index/attestations from registries → verifies signatures via Sigstore (calls Fulcio, Rekor, TSA) → returns “admit/deny”
- Policy-tester CLI reads policy YAML + pulls image locally → runs same policy/verifier logic → returns pass/fail

##### Architectural patterns and principles
- Kubernetes controller/operator pattern (reconciler loops, informer factories, workqueues)
- Admission webhook extension point (ValidatingAdmissionWebhook)
- CRD-driven configuration-as-data → Controllers produce derived configuration (ConfigMaps)
- Separation of concerns:
- Policy definition (CRDs)
- Policy compilation (controllers)
- Policy enforcement (webhook)
- Offline testing (policy-tester CLI)
- Pluggable registry authentication modules (Azure, AWS, GCP, service principal, MSI)

##### Final checklist
- Clear labels on:
- Controllers (clusterimagepolicy, trustroot)
- CRDs and ConfigMaps
- Webhook server (with key sub-components)
- External Sigstore (Fulcio, Rekor, TSA)
- Container registries
- CLI tools

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Definitions and Data Store
    subgraph "Kubernetes Control Plane"
        direction TB
        APIServer["API Server"]:::control
        etcd[(etcd)]:::data
        APIServer -->|"Reads/Writes CRDs & ConfigMaps"| etcd
    end

    %% CRD Types
    subgraph "CRD Definitions" 
        direction TB
        CIPTypes["ClusterImagePolicy CRD Types"]:::data
        TRTypes["TrustRoot CRD Types"]:::data
    end

    CIPTypes -->|Applied by Admin| APIServer
    TRTypes -->|Applied by Admin| APIServer

    %% Controllers
    subgraph "Controllers (Operator Pattern)" 
        direction TB
        subgraph "ClusterImagePolicy Controller" 
            direction TB
            CIPCtrl["Reconciler"]:::control
            CIPCtrl -->|List/Watch CIP CRs| APIServer
            CIPCtrl -->|Write ConfigMaps| etcd
        end
        subgraph "TrustRoot Controller"
            direction TB
            TRCtrl["Reconciler"]:::control
            TRCtrl -->|List/Watch TrustRoot CRs| APIServer
            TRCtrl -->|Write ConfigMaps| etcd
        end
    end

    %% ConfigMaps
    ConfigMaps[(ConfigMaps)]:::data
    CIPCtrl --> ConfigMaps
    TRCtrl --> ConfigMaps
    APIServer -->|Read ConfigMaps| ConfigMaps

    %% Webhook Enforcement Plane
    subgraph "Admission Webhook Deployment"
        direction TB
        WebhookPod["Webhook Server Pod"]:::enforce
        WebhookPod -->|HTTP AdmissionReview| APIServer
        WebhookPod -->|Load policies & trust roots| ConfigMaps
        subgraph "Webhook Logic"
            direction TB
            Validation["validation.go"]:::enforce
            Validator["validator.go"]:::enforce
            ValidatorResult["validator_result.go"]:::enforce
            CacheLayer["cache / nocache"]:::enforce
            RegistryAuth["registryauth modules"]:::enforce
            PolicyEngine["Policy Engine & Verifier"]:::enforce
        end
        WebhookPod --> Validation
        Validation --> Validator
        Validator --> ValidatorResult
        Validator --> CacheLayer
        Validator --> RegistryAuth
        Validator --> PolicyEngine
        PolicyEngine -->|Verify Signature| ExternalSigstore
    end

    %% External Dependencies
    subgraph "External Systems"
        direction TB
        ExternalSigstore{{"Sigstore Services\n(Fulcio, Rekor, TSA)"}}:::external
        Registries{{"Container Registries\n(DockerHub, GHCR, ACR, GCR)"}}:::external
    end
    RegistryAuth --> Registries
    PolicyEngine --> Registries

    ExternalSigstore -->|Provide Certs/Log| Validator

    %% CLI Tools
    subgraph "CLI Plane" 
        direction TB
        PolicyTester["policy-tester CLI"]:::cli
        APIDocs["api-docs Generator"]:::cli
        SchemaGen["schema Generator"]:::cli
        LocalDev["local-dev Bootstrap"]:::cli
    end
    PolicyTester -->|Reads CRD YAML| CIPTypes
    PolicyTester -->|Pulls image & verifies| Registries
    APIDocs --> CIPTypes
    APIDocs --> TRTypes
    SchemaGen --> CIPTypes
    SchemaGen --> TRTypes
    LocalDev --> APIServer

    %% Click Events
    click CIPTypes "https://github.com/github/policy-controller/blob/release/pkg/apis/policy/v1alpha1/clusterimagepolicy_types.go"
    click TRTypes "https://github.com/github/policy-controller/blob/release/pkg/apis/policy/v1alpha1/trustroot_types.go"
    click CIPCtrl "https://github.com/github/policy-controller/blob/release/pkg/reconciler/clusterimagepolicy/controller.go"
    click CIPCtrl "https://github.com/github/policy-controller/blob/release/pkg/reconciler/clusterimagepolicy/clusterimagepolicy.go"
    click CIPCtrl "https://github.com/github/policy-controller/blob/release/pkg/reconciler/clusterimagepolicy/resources/configmap.go"
    click TRCtrl "https://github.com/github/policy-controller/blob/release/pkg/reconciler/trustroot/controller.go"
    click TRCtrl "https://github.com/github/policy-controller/blob/release/pkg/reconciler/trustroot/trustroot.go"
    click TRCtrl "https://github.com/github/policy-controller/blob/release/pkg/reconciler/trustroot/resources/configmap.go"
    click Validation "https://github.com/github/policy-controller/blob/release/pkg/webhook/validation.go"
    click Validator "https://github.com/github/policy-controller/blob/release/pkg/webhook/validator.go"
    click ValidatorResult "https://github.com/github/policy-controller/blob/release/pkg/webhook/validator_result.go"
    click CacheLayer "https://github.com/github/policy-controller/blob/release/pkg/webhook/cache.go"
    click CacheLayer "https://github.com/github/policy-controller/blob/release/pkg/webhook/nocache.go"
    click RegistryAuth "https://github.com/github/policy-controller/blob/release/pkg/webhook/registryauth/registryauth.go"
    click RegistryAuth "https://github.com/github/policy-controller/blob/release/pkg/webhook/registryauth/azure/acrhelper.go"
    click PolicyEngine "https://github.com/github/policy-controller/blob/release/pkg/policy/policy.go"
    click PolicyEngine "https://github.com/github/policy-controller/blob/release/pkg/policy/verifier.go"
    click PolicyTester "https://github.com/github/policy-controller/blob/release/cmd/tester/main.go"
    click APIDocs "https://github.com/github/policy-controller/blob/release/cmd/api-docs/main.go"
    click SchemaGen "https://github.com/github/policy-controller/blob/release/cmd/schema/main.go"
    click LocalDev "https://github.com/github/policy-controller/blob/release/cmd/local-dev/main.go"

    %% Styles
    classDef control fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef data fill:#DFFFD0,stroke:#228B22,color:#228B22
    classDef enforce fill:#FFE4B5,stroke:#FF8C00,color:#FF8C00
    classDef external fill:#E8E8E8,stroke:#A9A9A9,color:#696969
    classDef cli fill:#E8D0FF,stroke:#800080,color:#800080
```
