# quay/quay-operator architecture

> Architecture diagram of the GitHub repository quay/quay-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/quay-operator
- Repository: https://github.com/quay/quay-operator

## Overview

##### Project type and purpose
- This is a Kubernetes Operator (written in Go using Kubebuilder) for “opinionated deployment” of the Quay container registry on Kubernetes, with support for auxiliary components (Clair, PostgreSQL, Redis, ObjectStorage, HPA, Monitoring, Routes, TLS webhooks, etc.) and delivered via Operator Lifecycle Manager (OLM) bundles.

##### File structure
- Top-level Go source (main.go, controllers/, apis/, pkg/) ⇒ Operator control loop
- config/ & bundle/ directories ⇒ Kubernetes manifests, CRDs, RBAC, webhook, OLM bundle, subscription
- kustomize/ directory ⇒ overlays & base component YAMLs (Quay, Clair, DB, Redis, HPA, routes, monitoring)
- hack/ scripts ⇒ local dev, build, deploy
- e2e/ ⇒ end-to-end tests driving custom resources
- pkg/kustomize & pkg/cmpstatus ⇒ libraries for generating Kubernetes resources and status evaluation
- pkg/middleware & controllers/quay ⇒ reconciliation logic for the QuayRegistry CRD

##### README for additional insights
- This operator defines a QuayRegistry CRD (apis/quay/v1/quayregistry_types.go)
- It watches CR instances, then uses the “kustomize” lib to render component manifests and applies them
- It publishes an OLM bundle under bundle/manifests & metadata so users can install via OperatorHub
- It leverages standard Kubernetes patterns: declarative resources, webhooks, RBAC, and OLM integration

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Control Plane
  subgraph "Control Plane"
    direction TB
    User["User (kubectl/oc)"]:::external
    APIServer["Kubernetes API Server"]:::controlPlane
    CRD["QuayRegistry CRD"]:::crd
    User -->|"create QuayRegistry CR"| APIServer
    APIServer -->|"store CR & fire watch events"| CRD
  end

  %% Admission Webhook
  subgraph "Admission Webhook"
    direction TB
    WebhookSvcYAML["Webhook Service"]:::operator
    WebhookKustomization["Webhook Kustomization"]:::operator
    WebhookConfig["Webhook Config Patches"]:::operator
    APIServer -->|"validate/mutate"| WebhookSvcYAML
    WebhookSvcYAML --> WebhookKustomization
    WebhookKustomization --> WebhookConfig
    WebhookConfig --> APIServer
  end

  %% Operator Deployment
  subgraph "Operator Deployment" 
    direction TB
    Main["Controller Manager (main.go)"]:::operator
    Middleware["pkg/middleware"]:::lib
    KustomizeLib["pkg/kustomize"]:::lib
    CmpStatusLib["pkg/cmpstatus"]:::lib
    QuayCtrl["QuayRegistry Reconciler"]:::operator
    StatusCtrl["QuayRegistry Status Reconciler"]:::operator

    APIServer -->|"watch CR"| Main
    Main --> Middleware
    Main --> QuayCtrl
    Main --> StatusCtrl
    QuayCtrl --> KustomizeLib
    StatusCtrl --> CmpStatusLib
  end

  %% Managed Workloads
  subgraph "Managed Workloads"
    direction TB
    QuayApp["quay-app Deployment"]:::workloads
    Clair["Clair Deployment"]:::workloads
    Postgres["Postgres StatefulSet"]:::workloads
    Redis["Redis Deployment"]:::workloads
    ObjectStore["ObjectStorage (OBC)"]:::workloads
    HPA["HorizontalPodAutoscaler"]:::workloads
    Monitoring["Prometheus & Grafana"]:::workloads
    Route["Route/Ingress"]:::workloads
    TLS["cert-manager Certificates"]:::workloads

    KustomizeLib -->|"apply manifests"| QuayApp
    KustomizeLib --> Clair
    KustomizeLib --> Postgres
    KustomizeLib --> Redis
    KustomizeLib --> ObjectStore
    KustomizeLib --> HPA
    KustomizeLib --> Monitoring
    KustomizeLib --> Route
    KustomizeLib --> TLS

    QuayApp -->|"metrics & health"| Monitoring
    Clair --> Monitoring
    Postgres --> Monitoring
    Redis --> Monitoring
    Monitoring --> CmpStatusLib
    TLS --> Monitoring
  end

  %% Status Update
  CmpStatusLib -->|"evaluate status"| StatusCtrl
  StatusCtrl -->|"update CR status"| APIServer

  %% OLM Bundle
  subgraph "OLM Bundle"
    direction TB
    CatalogSource["CatalogSource"]:::olm
    Subscription["Subscription"]:::olm
    CSV["ClusterServiceVersion"]:::olm
    CRDManifest["QuayRegistry CRD Manifest"]:::olm
    CatalogSource --> Subscription
    Subscription --> CSV
    CSV --> Main
    CSV --> CRDManifest
  end

  %% RBAC and Config
  subgraph "Configuration"
    direction TB
    RBAC["Operator RBAC Roles & Bindings"]:::operator
    ManagerAuthPatch["manager_auth_proxy_patch.yaml"]:::operator
    ManagerWebhookPatch["manager_webhook_patch.yaml"]:::operator
    RBAC --> Main
    ManagerAuthPatch --> Main
    ManagerWebhookPatch --> Main
  end

  %% Kustomize Components
  subgraph "Kustomize Bases & Overlays"
    direction TB
    BaseKustomize["kustomize/base"]:::lib
    CompOverlays["kustomize/components"]:::lib
    Overlays["kustomize/overlays"]:::lib
    BaseKustomize --> CompOverlays
    CompOverlays --> Overlays
    Overlays --> KustomizeLib
  end

  %% Scripts & Tests
  subgraph "Dev & CI"
    direction TB
    HackBuild["hack/build.sh"]:::external
    HackDeploy["hack/deploy.sh"]:::external
    E2E["e2e Tests"]:::external
    HackBuild --> Main
    HackDeploy --> APIServer
    E2E --> APIServer
    E2E --> Main
  end

  %% Click Events
  click CRD "https://github.com/quay/quay-operator/blob/master/apis/quay/v1/quayregistry_types.go"
  click Main "https://github.com/quay/quay-operator/blob/master/main.go"
  click QuayCtrl "https://github.com/quay/quay-operator/blob/master/controllers/quay/quayregistry_controller.go"
  click StatusCtrl "https://github.com/quay/quay-operator/blob/master/controllers/quay/quayregistry_status_controller.go"
  click WebhookSvcYAML "https://github.com/quay/quay-operator/blob/master/config/webhook/service.yaml"
  click WebhookKustomization "https://github.com/quay/quay-operator/blob/master/config/webhook/kustomization.yaml"
  click WebhookConfig "https://github.com/quay/quay-operator/blob/master/config/crd/patches/webhook_in_quayregistries.yaml"
  click CatalogSource "https://github.com/quay/quay-operator/blob/master/bundle/quay-operator.catalogsource.yaml"
  click Subscription "https://github.com/quay/quay-operator/blob/master/bundle/quay-operator.subscription.yaml"
  click CSV "https://github.com/quay/quay-operator/blob/master/bundle/manifests/quay-operator.clusterserviceversion.yaml"
  click CRDManifest "https://github.com/quay/quay-operator/blob/master/bundle/manifests/quayregistries.crd.yaml"
  click RBAC "https://github.com/quay/quay-operator/blob/master/config/rbac/role.yaml"
  click ManagerAuthPatch "https://github.com/quay/quay-operator/blob/master/config/default/manager_auth_proxy_patch.yaml"
  click ManagerWebhookPatch "https://github.com/quay/quay-operator/blob/master/config/default/manager_webhook_patch.yaml"
  click BaseKustomize "https://github.com/quay/quay-operator/blob/master/kustomize/base/kustomization.yaml"
  click CompOverlays "https://github.com/quay/quay-operator/tree/master/kustomize/components/clair"
  click Overlays "https://github.com/quay/quay-operator/tree/master/kustomize/overlays/current"
  click KustomizeLib "https://github.com/quay/quay-operator/blob/master/pkg/kustomize/kustomize.go"
  click CmpStatusLib "https://github.com/quay/quay-operator/blob/master/pkg/cmpstatus/quay.go"
  click Middleware "https://github.com/quay/quay-operator/blob/master/pkg/middleware/middleware.go"
  click HackBuild "https://github.com/quay/quay-operator/blob/master/hack/build.sh"
  click HackDeploy "https://github.com/quay/quay-operator/blob/master/hack/deploy.sh"
  click E2E "https://github.com/quay/quay-operator/tree/master/e2e/happy_path"

  %% Styles
  classDef controlPlane fill:#f0f0f0,stroke:#333,stroke-width:1px
  classDef operator fill:#cce5ff,stroke:#333,stroke-width:1px
  classDef workloads fill:#d4edda,stroke:#333,stroke-width:1px
  classDef olm fill:#ffe5b4,stroke:#333,stroke-width:1px
  classDef external fill:#fff3cd,stroke:#333,stroke-width:1px
  classDef crd fill:#ffffff,stroke:#0066cc,stroke-width:2px
  classDef lib fill:#e2e3e5,stroke:#333,stroke-width:1px
```
