How github/policy-controller works
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