# quay/container-security-operator architecture

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

- Interactive diagram: https://gitdiagram.com/quay/container-security-operator
- Repository: https://github.com/quay/container-security-operator

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Kubernetes Control Plane
    subgraph "Kubernetes Control Plane"
        API["API Server"]:::cp
        ETCD[(etcd)]:::cp
        CRDDef["CRD Definitions"]:::cp
    end
    API --> ETCD
    CRDDef --> API

    %% Operator Pod
    subgraph "Operator Pod (Security Labeller)"
        Entry["Operator Entry Point"]:::operator
        subgraph "Informer & Generated Code"
            Clientset["Clientset"]:::operator
            InformerCode["Informer"]:::operator
            ListerCode["Lister"]:::operator
        end
        subgraph "Controller"
            Reconciler["Reconcile Loop"]:::operator
            Manifest["Manifest Extraction"]:::operator
            MultiNS["Multi-Namespace Watcher"]:::operator
        end
        subgraph "secscan Client"
            RestClient["REST Client"]:::operator
            QuayClient["Quay/Clair Client"]:::operator
        end
        subgraph "Utilities & Metrics"
            K8sUtils["k8sutils"]:::operator
            PromServer["Prometheus HTTP Endpoint"]:::operator
        end
    end

    %% External Scanning Service
    subgraph "External Scanning Service"
        QuayReg["Quay Registry"]:::external
        Clair["Clair Scanner"]:::external
    end

    %% OLM Packaging
    subgraph "OLM Packaging"
        CSV["ClusterServiceVersion"]:::olm
        Subscription["Subscription"]:::olm
        Catalog["CatalogSource"]:::olm
        Scripts["hack Scripts"]:::olm
        BundleCRD["bundle CRD YAML"]:::olm
    end

    %% Example Consumer
    subgraph "Example Consumer"
        Kubectl["kubectl / OCP Console"]:::consumer
        ExampleFiles["Example Pod & Config"]:::consumer
    end

    %% Interactions
    CRDDef -->|"Register CRD"| API
    API -->|Watch Pods| InformerCode
    MultiNS -->|Feeds| InformerCode
    InformerCode -->|"Pod Add/Update"| Reconciler
    Reconciler -->|Extract Digests| Manifest
    Reconciler -->|Query Vulnerabilities| RestClient
    RestClient -->|HTTP GET /.well-known/app-capabilities| QuayClient
    QuayClient --> QuayReg
    QuayClient --> Clair
    Reconciler -->|Create/Update ImageManifestVuln| API
    API --> ETCD
    Kubectl -->|Get ImageManifestVuln| API
    Prometheus["Prometheus Server"]:::external -->|Scrape metrics| PromServer

    %% Click Events
    click Entry "https://github.com/quay/container-security-operator/blob/master/cmd/security-labeller/main.go"
    click CRDDef "https://github.com/quay/container-security-operator/blob/master/apis/secscan/v1alpha1/types.go"
    click CRDDef "https://github.com/quay/container-security-operator/blob/master/apis/secscan/v1alpha1/register.go"
    click CRDDef "https://github.com/quay/container-security-operator/blob/master/bundle/manifests/imagemanifestvulns.secscan.quay.redhat.com.crd.yaml"
    click Clientset "https://github.com/quay/container-security-operator/tree/master/generated/clientset/versioned/"
    click InformerCode "https://github.com/quay/container-security-operator/blob/master/generated/informers/externalversions/secscan/v1alpha1/imagemanifestvuln.go"
    click ListerCode "https://github.com/quay/container-security-operator/blob/master/generated/listers/secscan/v1alpha1/imagemanifestvuln.go"
    click Reconciler "https://github.com/quay/container-security-operator/blob/master/labeller/labeller.go"
    click Manifest "https://github.com/quay/container-security-operator/blob/master/labeller/manifest.go"
    click MultiNS "https://github.com/quay/container-security-operator/blob/master/labeller/multinamespacelistwatcher.go"
    click RestClient "https://github.com/quay/container-security-operator/blob/master/secscan/rest/rest.go"
    click QuayClient "https://github.com/quay/container-security-operator/blob/master/secscan/client.go"
    click QuayClient "https://github.com/quay/container-security-operator/blob/master/secscan/quay/quay.go"
    click QuayClient "https://github.com/quay/container-security-operator/blob/master/secscan/quay/security.go"
    click QuayClient "https://github.com/quay/container-security-operator/blob/master/secscan/quay/wellknown.go"
    click K8sUtils "https://github.com/quay/container-security-operator/blob/master/k8sutils/k8sutils.go"
    click PromServer "https://github.com/quay/container-security-operator/blob/master/prometheus/server.go"
    click PromServer "https://github.com/quay/container-security-operator/blob/master/prometheus/prometheus.go"
    click Scripts "https://github.com/quay/container-security-operator/blob/master/hack/build.sh"
    click Scripts "https://github.com/quay/container-security-operator/blob/master/hack/deploy.sh"
    click Scripts "https://github.com/quay/container-security-operator/blob/master/hack/teardown.sh"
    click CSV "https://github.com/quay/container-security-operator/blob/master/bundle/manifests/container-security-operator.clusterserviceversion.yaml"
    click Subscription "https://github.com/quay/container-security-operator/blob/master/bundle/cso.subscription.yaml"
    click Catalog "https://github.com/quay/container-security-operator/blob/master/bundle/cso.catalogsource.yaml"
    click ExampleFiles "https://github.com/quay/container-security-operator/blob/master/example/bad-pods/high.pod.yaml"
    click ExampleFiles "https://github.com/quay/container-security-operator/blob/master/example/example-config.yaml"

    %% Styles
    classDef cp fill:#D6E9FF,stroke:#1E6FB7,stroke-width:2px;
    classDef operator fill:#E6F9D6,stroke:#3C8D0D,stroke-width:2px;
    classDef external fill:#FFE5B4,stroke:#FF8C00,stroke-width:2px;
    classDef olm fill:#F0F0F0,stroke:#A0A0A0,stroke-width:2px;
    classDef consumer fill:#F9E6FF,stroke:#B347FF,stroke-width:2px;
```
