# ardikabs/hibernator architecture

> Architecture diagram of the GitHub repository ardikabs/hibernator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ardikabs/hibernator
- Repository: https://github.com/ardikabs/hibernator

## Overview

Hibernator is a Kubernetes operator for scheduled, dependency-aware suspension and restoration of cloud and Kubernetes infrastructure. Users declare HibernatePlans and related connector, exception, and notification resources; the controller evaluates schedules and coordinates isolated runner jobs, whose pluggable executors perform operations and persist restore metadata. Progress and logs return through authenticated streaming, while lifecycle notifications fan out to configured sinks. The CLI supports plan operations and restore-state management. The README documents these capabilities; sampled source confirms controller setup, runner configuration, streaming service behavior, and restore ConfigMap access, but not every controller-to-job call.

Main entry points: [`internal/provider/provider.go`](https://github.com/ardikabs/hibernator/blob/main/internal/provider/provider.go) (Resource provider), [`cmd/runner/app/app.go`](https://github.com/ardikabs/hibernator/blob/main/cmd/runner/app/app.go) (Runner application), [`internal/executor/interface.go`](https://github.com/ardikabs/hibernator/blob/main/internal/executor/interface.go) (Cloud executors), [`internal/provider/processor/plan/coordinator.go`](https://github.com/ardikabs/hibernator/blob/main/internal/provider/processor/plan/coordinator.go) (Plan state coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_api["Custom resources"]
  node_controller["Controller manager<br/>[app.go]"]
  node_provider["Resource provider<br/>[provider.go]"]
  node_planner["Schedule planner<br/>[planner.go]"]
  node_planflow["Plan state coordinator<br/>[coordinator.go]"]
  node_exceptions["Schedule exceptions<br/>[lifecycle.go]"]
end

subgraph group_execution["Execution"]
  node_runnerjob["Isolated runner jobs<br/>[worker.go]"]
  node_runner["Runner application<br/>[app.go]"]
  node_executors{{"Cloud executors<br/>[interface.go]"}}
  node_eks["EKS executor<br/>[eks.go]"]
  node_rds["RDS executor<br/>[rds.go]"]
  node_ec2["EC2 executor<br/>[ec2.go]"]
end

subgraph group_feedback["Feedback and state"]
  node_restore["Restore manager<br/>[manager.go]"]
  node_configmaps[("Restore metadata")]
  node_streammanager["Streaming setup<br/>[manager.go]"]
  node_streamservice["Execution service<br/>[service.go]"]
  node_streamclient["Runner stream clients<br/>[client.go]"]
  node_notifications["Notification dispatch<br/>[dispatcher.go]"]
  node_sinks["Notification sinks<br/>[sink.go]"]
end

subgraph group_interfaces["User interfaces"]
  node_kubectl["kubectl-hibernator<br/>[root.go]"]
end

node_operator(("Operator users"))
node_kubernetes[("Kubernetes API")]
node_cloud{{"Cloud services"}}
node_notifyuser(("Notification recipients"))

node_operator -->|"runs commands"| node_kubectl
node_operator -->|"declares resources"| node_api
node_kubectl -->|"reads and updates"| node_kubernetes
node_controller -->|"sets up"| node_provider
node_controller -->|"sets up"| node_streammanager
node_provider -->|"evaluates schedules"| node_planner
node_provider -->|"registers processing"| node_planflow
node_provider -->|"registers processing"| node_exceptions
node_planflow -->|"coordinates jobs"| node_runnerjob
node_runnerjob -->|"starts job"| node_runner
node_runner -->|"selects executor"| node_executors
node_executors -->|"implements"| node_eks
node_executors -->|"implements"| node_rds
node_executors -->|"implements"| node_ec2
node_eks -->|"operates resources"| node_cloud
node_rds -->|"operates resources"| node_cloud
node_ec2 -->|"operates resources"| node_cloud
node_runner -->|"persists restore state"| node_restore
node_restore -->|"reads and writes"| node_configmaps
node_runner -->|"streams progress"| node_streamclient
node_streamclient -->|"sends logs and status"| node_streamservice
node_streammanager -->|"hosts service"| node_streamservice
node_streamservice -->|"reads plan metadata"| node_kubernetes
node_planflow -.->|"emits lifecycle events"| node_notifications
node_notifications -->|"dispatches messages"| node_sinks
node_sinks -->|"delivers notifications"| node_notifyuser

click node_kubectl "https://github.com/ardikabs/hibernator/blob/main/cmd/kubectl-hibernator/cli/root.go"
click node_api "https://github.com/ardikabs/hibernator/blob/main/api/v1alpha1/hibernateplan_types.go"
click node_controller "https://github.com/ardikabs/hibernator/blob/main/cmd/controller/app/app.go"
click node_provider "https://github.com/ardikabs/hibernator/blob/main/internal/provider/provider.go"
click node_planner "https://github.com/ardikabs/hibernator/blob/main/internal/scheduler/planner.go"
click node_planflow "https://github.com/ardikabs/hibernator/blob/main/internal/provider/processor/plan/coordinator.go"
click node_exceptions "https://github.com/ardikabs/hibernator/blob/main/internal/provider/processor/scheduleexception/lifecycle.go"
click node_runnerjob "https://github.com/ardikabs/hibernator/blob/main/internal/provider/processor/plan/worker.go"
click node_runner "https://github.com/ardikabs/hibernator/blob/main/cmd/runner/app/app.go"
click node_executors "https://github.com/ardikabs/hibernator/blob/main/internal/executor/interface.go"
click node_eks "https://github.com/ardikabs/hibernator/blob/main/internal/executor/eks/eks.go"
click node_rds "https://github.com/ardikabs/hibernator/blob/main/internal/executor/rds/rds.go"
click node_ec2 "https://github.com/ardikabs/hibernator/blob/main/internal/executor/ec2/ec2.go"
click node_restore "https://github.com/ardikabs/hibernator/blob/main/internal/restore/manager.go"
click node_streammanager "https://github.com/ardikabs/hibernator/blob/main/internal/streaming/manager.go"
click node_streamservice "https://github.com/ardikabs/hibernator/blob/main/internal/streaming/server/service.go"
click node_streamclient "https://github.com/ardikabs/hibernator/blob/main/internal/streaming/client/client.go"
click node_notifications "https://github.com/ardikabs/hibernator/blob/main/internal/notification/dispatcher.go"
click node_sinks "https://github.com/ardikabs/hibernator/blob/main/internal/notification/sink/sink.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_controller,node_provider,node_planner,node_planflow,node_exceptions,node_operator toneBlue
class node_runnerjob,node_runner,node_executors,node_eks,node_rds,node_ec2,node_kubernetes toneAmber
class node_restore,node_configmaps,node_streammanager,node_streamservice,node_streamclient,node_notifications,node_sinks toneMint
class node_kubectl toneRose
class node_cloud,node_notifyuser toneIndigo
```

## Components

### Control plane

- [Custom resources](https://github.com/ardikabs/hibernator/blob/main/api/v1alpha1/hibernateplan_types.go): `api/v1alpha1/hibernateplan_types.go`
- [Controller manager](https://github.com/ardikabs/hibernator/blob/main/cmd/controller/app/app.go): `cmd/controller/app/app.go`
- [Resource provider](https://github.com/ardikabs/hibernator/blob/main/internal/provider/provider.go): `internal/provider/provider.go`
- [Schedule planner](https://github.com/ardikabs/hibernator/blob/main/internal/scheduler/planner.go): `internal/scheduler/planner.go`
- [Plan state coordinator](https://github.com/ardikabs/hibernator/blob/main/internal/provider/processor/plan/coordinator.go): `internal/provider/processor/plan/coordinator.go`
- [Schedule exceptions](https://github.com/ardikabs/hibernator/blob/main/internal/provider/processor/scheduleexception/lifecycle.go): `internal/provider/processor/scheduleexception/lifecycle.go`

### Execution

- [Isolated runner jobs](https://github.com/ardikabs/hibernator/blob/main/internal/provider/processor/plan/worker.go): `internal/provider/processor/plan/worker.go`
- [Runner application](https://github.com/ardikabs/hibernator/blob/main/cmd/runner/app/app.go): `cmd/runner/app/app.go`
- [Cloud executors](https://github.com/ardikabs/hibernator/blob/main/internal/executor/interface.go): `internal/executor/interface.go`
- [EKS executor](https://github.com/ardikabs/hibernator/blob/main/internal/executor/eks/eks.go): `internal/executor/eks/eks.go`
- [RDS executor](https://github.com/ardikabs/hibernator/blob/main/internal/executor/rds/rds.go): `internal/executor/rds/rds.go`
- [EC2 executor](https://github.com/ardikabs/hibernator/blob/main/internal/executor/ec2/ec2.go): `internal/executor/ec2/ec2.go`

### Feedback and state

- [Restore manager](https://github.com/ardikabs/hibernator/blob/main/internal/restore/manager.go): `internal/restore/manager.go`
- **Restore metadata**
- [Streaming setup](https://github.com/ardikabs/hibernator/blob/main/internal/streaming/manager.go): `internal/streaming/manager.go`
- [Execution service](https://github.com/ardikabs/hibernator/blob/main/internal/streaming/server/service.go): `internal/streaming/server/service.go`
- [Runner stream clients](https://github.com/ardikabs/hibernator/blob/main/internal/streaming/client/client.go): `internal/streaming/client/client.go`
- [Notification dispatch](https://github.com/ardikabs/hibernator/blob/main/internal/notification/dispatcher.go): `internal/notification/dispatcher.go`
- [Notification sinks](https://github.com/ardikabs/hibernator/blob/main/internal/notification/sink/sink.go): `internal/notification/sink/sink.go`

### User interfaces

- [kubectl-hibernator](https://github.com/ardikabs/hibernator/blob/main/cmd/kubectl-hibernator/cli/root.go): `cmd/kubectl-hibernator/cli/root.go`

### Other components

- **Operator users**
- **Kubernetes API**
- **Cloud services**
- **Notification recipients**

## Connections

- Operator users → kubectl-hibernator: runs commands
- Operator users → Custom resources: declares resources
- kubectl-hibernator → Kubernetes API: reads and updates
- Controller manager → Resource provider: sets up
- Controller manager → Streaming setup: sets up
- Resource provider → Schedule planner: evaluates schedules
- Resource provider → Plan state coordinator: registers processing
- Resource provider → Schedule exceptions: registers processing
- Plan state coordinator → Isolated runner jobs: coordinates jobs
- Isolated runner jobs → Runner application: starts job
- Runner application → Cloud executors: selects executor
- Cloud executors → EKS executor: implements
- Cloud executors → RDS executor: implements
- Cloud executors → EC2 executor: implements
- EKS executor → Cloud services: operates resources
- RDS executor → Cloud services: operates resources
- EC2 executor → Cloud services: operates resources
- Runner application → Restore manager: persists restore state
- Restore manager → Restore metadata: reads and writes
- Runner application → Runner stream clients: streams progress
- Runner stream clients → Execution service: sends logs and status
- Streaming setup → Execution service: hosts service
- Execution service → Kubernetes API: reads plan metadata
- Plan state coordinator → Notification dispatch: emits lifecycle events
- Notification dispatch → Notification sinks: dispatches messages
- Notification sinks → Notification recipients: delivers notifications