How quay/container-security-operator works
Project type and purpose
• This is a Kubernetes “Operator” implemented in Go. Its purpose is to monitor Pods in one or more namespaces, retrieve container image manifests, query an external container‐scanning service (Quay+Clair) for vulnerability data, and expose that data as CustomResources (ImageManifestVuln) via the Kubernetes API. It also exports Prometheus metrics.
File structure
• Top-level:
• cmd/security-labeller: the Operator’s entry point
• apis/secscan/v1alpha1: CRD definitions for ImageManifestVuln
• generated/: clientset, informers, listers (codegen)
• labeller/: core controller logic (watch pods, reconcile loop)
• secscan/: client library for talking to Quay/Clair
• k8sutils/: helper to build Kubernetes clients/in‐cluster config
• prometheus/: metrics server
• hack/: build & deploy scripts (OLM, CRD install)
• bundle/: OLM bundle for packaging the Operator
• The presence of generated clientsets and informers indicates a standard “controller‐runtime” pattern: an informer/injection of event streams, a reconcile loop, and client.Update calls on CRDs.
README for additional insights
• Confirms it is an OLM-packaged Operator.
• Explains configuration (flags/configMap).
• Describes the CRD schema (spec & status).
• Shows integration points: kubeconfig/in-cluster config, Quay SCAN endpoint (“.well-known/app-capabilities”), Prometheus metrics.
Main components
a. Kubernetes Cluster
– API Server (storing built-in objects + ImageManifestVuln CRDs)
– etcd (persistence, implicit)
b. Operator Pod (Security Labeller)
– In-cluster config or kubeconfig
– Informers / Listers (generated code)
– Controller/Reconcile Loop (labeller package)
– secscan client (Quay/Clair interaction)
– k8sutils helper
– Prometheus HTTP endpoint (metrics)
c. External Service
– Quay image registry + Clair scanner
d. OLM components (optional detail)
– CSV, Subscription, CatalogSource
e. Example Consumer
– kubectl or OCP Console (reads ImageManifestVuln resources, visualizes vulnerabilities)
Relationships & interactions
1. Operator Pod registers CRD definitions in API Server (initial setup)
2. Informer subscribes to Pod events from API Server
3. On Pod add/update ⇒ reconcile() in labeller
– Extract container image references and manifest digests
– Call secscan.Client to query Quay/Clair REST endpoints
– Receive vulnerability report
– Create or Update ImageManifestVuln resource via clientset to API Server
4. API Server persists ImageManifestVuln in etcd
5. Prometheus scrapes metrics from the Operator’s HTTP server
6. Admin/User queries kubectl get imagemanifestvuln or views in OCP Console
Architectural patterns & design principles
• Kubernetes Controller pattern (informers → reconcile loops → CRD updates)
• Code-generation for type safety (clientsets, listers, informers)
• Single binary microservice (no sidecars)
• External-service integration via REST client abstraction (secscan/rest + secscan/quay)
• Observability via Prometheus metrics
Essential elements
• CustomResourceDefinition registration
• informer/lister stack (generated/)
• reconcile loop in labeller/
• secscan REST client abstraction
• Prometheus scrape endpoint
• OLM bundle & hack scripts (optional)
• CRD objects (ImageManifestVuln) stored in etcd