# criteo/node-disruption-controller architecture

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

- Interactive diagram: https://gitdiagram.com/criteo/node-disruption-controller
- Repository: https://github.com/criteo/node-disruption-controller

## Overview

##### Project type and purpose
- This project is a Kubernetes “Operator” (controller) named **Node Disruption Controller (NDC)**, built with Go/Kubebuilder.
- Purpose: Gatekeep voluntary node-level disruptions (drains, reboots, scale-down) by validating custom resources (NodeDisruption, ApplicationDisruptionBudget, NodeDisruptionBudget) against quotas, data-awareness rules, and synchronous health checks.

##### File structure
- **cmd/main.go**: entrypoint for the controller manager binary.
- **api/v1alpha1**: CRD Go types (NodeDisruption, ApplicationDisruptionBudget, NodeDisruptionBudget) + autogenerated deepcopy.
- **internal/controller**: reconcile logic for each custom resource, unit tests.
- **pkg/resolver**: helper logic (e.g. resolving which budgets apply to a NodeDisruption).
- **config/**: manifests for CRD installation (kustomize), RBAC roles, manager deployment, Prometheus ServiceMonitor.
- **chart/**: Helm chart for packaging & deployment, with templates for CRDs, RBAC, Manager deployment, metrics-service, ServiceAccount.
- **Makefile/Dockerfile/.github/workflows**: build/test/release automation.

##### Extract additional architectural hints from README
- Uses Kubernetes operator pattern: controller-runtime, reconcile loops, leader election, health & metrics endpoints.
- Exposes a synchronous healthCheck hook (for ApplicationDisruptionBudget).
- Integrates with Prometheus (ServiceMonitor) for metrics.
- Operates via CRDs and custom controllers, no external database.

##### Main components
A. Kubernetes Control Plane
- API Server (holds CRDs & core types: Node, Pod, PVC)
- etcd (backing store)
B. Custom Resource Definitions
- NodeDisruption
- ApplicationDisruptionBudget
- NodeDisruptionBudget
C. NDC Controller Manager (Go binary)
- Reconcile Loop #1: NodeDisruptionController
- Reconcile Loop #2: ApplicationDisruptionBudgetController
- Reconcile Loop #3: NodeDisruptionBudgetController
- Resolver module (pkg/resolver)
- Leader Election
- Metrics & Health HTTP endpoints
D. External Actors & Systems
- Maintenance system / Cluster Autoscaler (creates NodeDisruption CRs)
- Service-level health endpoints (healthHook URL configured on ADB CRs)
- Prometheus server (scrapes metrics via ServiceMonitor)
E. Packaging & Deployment
- Helm Chart (chart/)
- Kustomize manifests (config/)
- Docker image

##### Relationships & interactions
1. **CRD install**: config/crd → API Server
2. **Controller Deployment**: Helm chart or kustomize deploys controller-manager (pod) with ServiceAccount & RBAC.
3. **User/External System** creates a NodeDisruption CR.
4. Controller Watcher sees new NodeDisruption → invokes NodeDisruptionController.Reconcile().
5. Resolver queries existing ApplicationDisruptionBudget & NodeDisruptionBudget CRs → checks quotas.
6. If any ADB has a healthHook configured, the controller issues a POST to that external URL with the NodeDisruption payload.
7. Controller updates NodeDisruption.status to Granted or Rejected.
8. External actor (e.g. `kubectl delete nodedisruption`) cleans up CR → controller finalizes and updates budgets.
9. Controller exposes metrics on `/metrics` → ServiceMonitor picks them up.

##### Architectural patterns & design principles
- **Operator Pattern**: event-driven reconcilers with idempotent Apply logic.
- **Separation of concerns**: each CR has its own controller.
- **Dead simple data store**: relies entirely on Kubernetes API Server & etcd.
- **Extensibility**: external synchronous health checks via HTTP hooks.
- **Packaging**: dual support for Helm and Kustomize.
- **Cloud-native observability**: Prometheus metrics, leader election for HA.

##### Technologies & frameworks to annotate
- Language: Go
- Kubebuilder / controller-runtime
- Kubernetes API (CRDs, informers)
- Kustomize (config/)
- Helm (chart/)
- Prometheus (ServiceMonitor, metrics endpoint)
- CI/CD: GitHub Actions, Makefile, Docker

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Kubernetes Control Plane
    subgraph "Kubernetes Control Plane"
        API["API Server"]:::core
        ETCD["etcd"]:::core
    end

    %% Custom Resources & CRDs
    subgraph "Custom Resources & CRDs"
        NDTypes["NodeDisruption CRD"]:::crd
        ADBTypes["ApplicationDisruptionBudget CRD"]:::crd
        NDBTypes["NodeDisruptionBudget CRD"]:::crd
    end

    %% NDC Controller Manager
    subgraph "NDC Controller Manager"
        ManagerPod["Controller Manager Pod"]:::controller
        subgraph "Reconcilers"
            NRCtrl["NodeDisruptionController"]:::controller
            ADRCtrl["ApplicationDisruptionBudgetController"]:::controller
            NDBCtrl["NodeDisruptionBudgetController"]:::controller
        end
        Resolver["Resolver Module"]:::controller
        HTTPServer["Metrics & Health Server"]:::controller
        LeaderElection["Leader Election"]:::controller
    end

    %% External Actors & Services
    subgraph "External Actors & Services"
        Maint["Maintenance System / Autoscaler"]:::external
        HealthHook["Service-level HealthHook"]:::external
        ServiceMon["ServiceMonitor"]:::external
        PromScrape["Prometheus Server"]:::external
    end

    %% Relationships
    Maint -->|"creates NodeDisruption CR"| API
    NDTypes -.->|"install CRD"| API
    ADBTypes -.->|"install CRD"| API
    NDBTypes -.->|"install CRD"| API

    API -->|"Watch NodeDisruption"| NRCtrl
    API -->|"Watch ApplicationDisruptionBudget"| ADRCtrl
    API -->|"Watch NodeDisruptionBudget"| NDBCtrl

    NRCtrl --> Resolver
    ADRCtrl --> Resolver
    NDBCtrl --> Resolver

    Resolver -->|"Query budgets"| API

    NRCtrl -->|"POST /healthHook"| HealthHook
    Resolver -->|"POST /healthHook"| HealthHook

    NRCtrl -->|"PATCH status"| API

    HTTPServer -->|"/metrics"| ServiceMon
    ServiceMon -->|"scrape metrics"| PromScrape

    LeaderElection --> ManagerPod

    %% Click Events
    click ManagerPod "https://github.com/criteo/node-disruption-controller/blob/main/cmd/main.go"
    click NRCtrl "https://github.com/criteo/node-disruption-controller/blob/main/internal/controller/nodedisruption_controller.go"
    click ADRCtrl "https://github.com/criteo/node-disruption-controller/blob/main/internal/controller/applicationdisruptionbudget_controller.go"
    click NDBCtrl "https://github.com/criteo/node-disruption-controller/blob/main/internal/controller/nodedisruptionbudget_controller.go"
    click NDTypes "https://github.com/criteo/node-disruption-controller/blob/main/api/v1alpha1/nodedisruption_types.go"
    click ADBTypes "https://github.com/criteo/node-disruption-controller/blob/main/api/v1alpha1/applicationdisruptionbudget_types.go"
    click NDBTypes "https://github.com/criteo/node-disruption-controller/blob/main/api/v1alpha1/nodedisruptionbudget_types.go"
    click ADBTypes "https://github.com/criteo/node-disruption-controller/blob/main/api/v1alpha1/groupversion_info.go"
    click ADBTypes "https://github.com/criteo/node-disruption-controller/blob/main/api/v1alpha1/zz_generated.deepcopy.go"
    click Resolver "https://github.com/criteo/node-disruption-controller/blob/main/pkg/resolver/resolver.go"
    click NDTypes "https://github.com/criteo/node-disruption-controller/blob/main/config/crd/bases/nodedisruption.criteo.com_nodedisruptions.yaml"
    click ADBTypes "https://github.com/criteo/node-disruption-controller/blob/main/config/crd/bases/nodedisruption.criteo.com_applicationdisruptionbudgets.yaml"
    click NDBTypes "https://github.com/criteo/node-disruption-controller/blob/main/config/crd/bases/nodedisruption.criteo.com_nodedisruptionbudgets.yaml"
    click ADBTypes "https://github.com/criteo/node-disruption-controller/blob/main/config/crd/kustomization.yaml"
    click LeaderElection "https://github.com/criteo/node-disruption-controller/blob/main/config/rbac/leader_election_role.yaml"
    click LeaderElection "https://github.com/criteo/node-disruption-controller/blob/main/config/rbac/leader_election_role_binding.yaml"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/blob/main/config/manager/manager.yaml"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/blob/main/config/default/manager_auth_proxy_patch.yaml"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/blob/main/config/default/manager_config_patch.yaml"
    click ServiceMon "https://github.com/criteo/node-disruption-controller/blob/main/config/prometheus/monitor.yaml"
    click ServiceMon "https://github.com/criteo/node-disruption-controller/blob/main/chart/templates/service-monitor.yaml"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/blob/main/chart/Chart.yaml"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/blob/main/chart/templates/deployment.yaml"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/blob/main/chart/templates/leader-election-rbac.yaml"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/blob/main/chart/templates/manager-rbac.yaml"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/blob/main/chart/templates/proxy-rbac.yaml"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/blob/main/chart/templates/metrics-service.yaml"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/blob/main/chart/templates/serviceaccount.yaml"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/tree/main/Makefile"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/tree/main/Dockerfile"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/blob/main/.github/workflows/test.yaml"
    click ManagerPod "https://github.com/criteo/node-disruption-controller/blob/main/.github/workflows/releases.yaml"

    %% Styles
    classDef core fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef crd fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef controller fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
```
