# devtron-labs/winter-soldier architecture

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

- Interactive diagram: https://gitdiagram.com/devtron-labs/winter-soldier
- Repository: https://github.com/devtron-labs/winter-soldier

## Overview

##### Project type and purpose
- This is a Kubernetes Operator written in Go, called “Winter Soldier.”
- Purpose: define a Custom Resource Definition (CRD) named Hibernator, then run a controller and webhook that periodically either scales workloads to zero (“sleep”) or deletes them based on time-and-field selectors.

##### File structure
- api/v1alpha1: Go types for the Hibernator CRD, codegen helpers.
- controllers/: reconciliation logic that watches Hibernator resources and enacts actions.
- config/: kustomize overlays for CRD manifests, RBAC, manager Deployment, admission webhook, Prometheus monitor.
- main.go: bootstraps controller-runtime manager, registers controllers and webhooks.
- pkg/: helper utilities for talking to Kubernetes, evaluating selectors (gjson, expr), mocking.
- Dockerfile, Makefile, PROJECT: build, containerize, and package the operator.
- hack/: license boilerplate.
- vendor/: third-party dependencies.

##### README for additional insights
- Describes two actions (“sleep” vs “delete”), selection mechanisms (label, namespace, kind, arbitrary fields via gjson/expr), time ranges, and custom flags.
- Mentions Prometheus monitoring.

- Manager: sets up caches, webhooks, metrics.
- HibernatorController: implements Reconcile(Hibernator) → calls ResourceAction, History, Helper.
- pkg/KubeUtil & pkg/KubectlUtil: wrap client operations, mocking.
- time_util.go: helper for AddTime, ParseTime, Now.
- api/v1alpha1/time_util.go: CRD-level defaults, conversions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External
    UserCI["User / CI/CD\n(kubectl)"]:::external
    Prometheus["Prometheus"]:::external

    %% Cluster
    subgraph "Kubernetes Cluster"
        direction TB
        APIServer["API Server"]:::clusterComp
        Etcd["etcd (Data Store)"]:::clusterComp

        subgraph "Winter Soldier Operator Pod"
            direction TB
            style OperatorPod fill:#90EE90,stroke:#333,stroke-width:2px
            Manager["controller-runtime Manager"]:::operator
            CRDTypes["CRD API Types\n(api/v1alpha1)"]:::operator
            CRDUtils["CRD Utilities\n(defaults, conversions)"]:::operator
            Controller["Hibernator Controller\n(Reconcile Loop)"]:::operator
            Webhook["Admission Webhook Server"]:::operator
            Metrics["Metrics Endpoint"]:::operator
        end

        Workloads["Target Workloads\n(Deployment, StatefulSet, etc.)"]:::workload
    end

    %% Connections
    UserCI -->|"apply Hibernator CR"| APIServer
    APIServer -->|"store CustomResource"| Etcd
    APIServer -->|"add/update events"| Controller
    Controller -->|"get spec & selectors"| APIServer
    Controller -->|"scale-to-0 / delete"| APIServer
    Controller -->|"identify targets"| Workloads
    APIServer -->|"validate/default"| Webhook
    Webhook -->|"response"| APIServer
    Prometheus -->|"scrape /metrics"| Metrics

    %% Click Events
    click CRDTypes "https://github.com/devtron-labs/winter-soldier/blob/main/api/v1alpha1/hibernator_types.go"
    click CRDUtils "https://github.com/devtron-labs/winter-soldier/blob/main/api/v1alpha1/time_util.go"
    click Manager "https://github.com/devtron-labs/winter-soldier/blob/main/main.go"
    click Controller "https://github.com/devtron-labs/winter-soldier/blob/main/controllers/hibernator_controller.go"

    %% Styles
    classDef external fill:none,stroke:#999,stroke-dasharray: 5 5
    classDef clusterComp fill:#ADD8E6,stroke:#000
    classDef operator fill:#90EE90,stroke:#333
    classDef workload fill:#FFA500,stroke:#000
```
