How criteo/node-disruption-controller works
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