How Hibernator works

Outside working hours, Hibernator scales your Kubernetes workloads to zero and suspends your CronJobs. When someone needs them, they’ll be back.

• A day with Hibernator
• What runs in your cluster
• Satellites
• Where Hibernator keeps its data

A day with Hibernator

Hibernator manages the Deployments, StatefulSets and CronJobs in every namespace that you do not exclude. While a workload runs, Hibernator records its replica count, the baseline. The working hours come from your values file; schedule.md has the format.

• Working hours end. Hibernator hibernates the cluster: it scales the Deployments and StatefulSets to zero and suspends the CronJobs.
• Someone needs a workload. A user requests a wake in the web UI, or a script calls the API. Hibernator scales each workload back to its baseline and resumes the CronJobs it suspended. The wake has an expiry. After it, the schedule decides again.
• Working hours start. Hibernator wakes the cluster in the same way.

An admin can also hibernate or wake the cluster at any time, in Manual Control.

Hibernator never starts a workload that it did not stop. A workload that you scaled to zero yourself stays at zero, on schedule and on a wake.

Hibernator removes no nodes. When the pods are gone, your node autoscaler, such as Karpenter or Cluster Autoscaler, removes the empty nodes. Then they stop costing money.

To keep one workload running at all times, put the annotation hibernator.io/exclude: "true" on it. annotations.md has this annotation and the others. Hibernator can also stop and start AWS RDS instances with the workloads (databases.md), and wake resources on another cluster (external-wake.md).

What runs in your cluster

Workload	Replicas	What it does
Controller	Always 1	Compares each workload with the schedule and scales it. The chart always sets one replica.
App	replicaCount.app, default 1	The API and the web UI, in one pod. Caddy serves the web UI.
Satellite	None by default	A small TCP proxy for one hibernated service, in your application namespace. Only for the services you select.

The controller creates two PodDisruptionBudgets in the release namespace when it starts: hibernator-controller-pdb for the controller pod and hibernator-app-pdb for the app pods. They are not part of the chart.

• No hibernation or wake runs. A node drain can evict one pod of each component at a time.
• A hibernation or a wake runs. A node drain cannot evict the controller or the app pods. The controller removes this block at its first reconcile after the transition. It reconciles at least once every config.controller.reconcileInterval, 1 hour by default.

Satellites

The chart creates no satellite, and the controller creates one only when you ask for it. config.serviceRedirection.enabled is false by default. When it is true, only these services get a satellite:

• the services that you list under config.serviceRedirection.services
• the services that have the annotation hibernator.io/redirect-when-hibernating: "true"

When Hibernator hibernates such a service, the controller creates a satellite that matches the service’s selector. Kubernetes then sends the service’s traffic to the satellite, and a caller sees the Hibernator wake page, not a refused connection. The wake removes the satellite again.

Satellite pods therefore appear and disappear in your namespaces without a deploy. This is expected. service-redirection.md has the values.

Where Hibernator keeps its data

Hibernator keeps everything in ConfigMaps in the release namespace. There is no database to run, and nothing to back up outside the cluster. The names below are for a release named hibernator.

ConfigMap	Holds	Created by
hibernator-config	The configuration from your values file	The chart
hibernator-license	The license	The chart, when license is set
hibernator-state	Hibernation and wake state, the baselines and the stand-down	Hibernator, at runtime
hibernator-audit-log	The audit log	Hibernator, at runtime
hibernator-config-overlay	What admins change in the UI, such as schedule windows	Hibernator, at runtime
hibernator-passkeys	The enrolled passkeys, see passkeys.md	Hibernator, on the first enrolment

The ConfigMaps that Hibernator creates at runtime are not part of the Helm release. helm uninstall does not delete them; upgrade.md says what that means.