Hibernate Deployments

An Astro Private Cloud (APC) Deployment runs every Airflow component continuously (scheduler, webserver or API server, triggerer, Dag processor, and workers) even when no Dags are scheduled. A Deployment that is used only during working hours still costs the same as one that runs all day. Hibernation scales a Deployment to zero pods according to a recurring schedule or on demand, regardless of whether the Deployment is idle, and wakes it again when you need it.

Astro Private Cloud 2.2This feature was introduced in Astro Private Cloud 2.2. To access this feature, upgrade your Astro Private Cloud installation to 2.2 or later.

When a Deployment hibernates, all of its state is preserved in the external metadata database, which hibernation never touches. On wake, every component returns to its configured replica count.

Hibernation doesn’t delete, migrate, or modify any Airflow data.

Prerequisites

Hibernation is available only when all of the following are true for a Deployment:

The Deployment runs in operator mode, not Helm mode.
Laminar is enabled on the Deployment’s data plane with global.laminar.enabled: true. See Configure the data plane.
KEDA 2.20.0 or later is installed on the Deployment’s data plane, and global.keda.enabled is true in that data plane’s values.yaml. KEDA lets worker pods scale to zero. You install KEDA yourself. See Configure worker autoscaling.

A platform administrator must also enable hibernation for the Deployment through config governance. See Enable hibernation. To configure or override hibernation, you need the deployment.config.upsert permission. The Workspace Operator, Workspace Owner, Organization Owner, and Deployment Admin roles include it. If you use a custom Deployment role, make sure it grants deployment.config.upsert.

Enable hibernation

Hibernation is off by default. A platform administrator enables it through config governance with the governed setting hibernation.enabled, which resolves across three levels, from least to most specific: Cluster, Workspace, and Deployment. The most specific level that sets the value wins, and an unset level inherits from the level above it. For example, a platform administrator can enable hibernation for a cluster and disable it for a production Workspace, or leave it off and enable it for specific Workspaces or Deployments. See Config governance for setting each level.

Turning hibernation off doesn’t wake or update any Deployment, and existing configuration is preserved. A Deployment that already has hibernation configured can no longer have its schedules set or changed or a hibernating override added, but you can still remove its schedules or override so it can wake.

Hibernate and wake a Deployment on demand

Use an on-demand override to hibernate or wake a Deployment immediately, outside any schedule. An override takes precedence over any configured schedule while it’s in effect. When a timed override lapses, control returns to the schedule automatically.

Astro UI
APC API
Astro CLI

Click Deployments, select a Deployment, then open the Settings tab.
Expand the Hibernation section.
Select Hibernate now or Wake now.
In the dialog, set how long the override lasts:
- No expiry: The override holds until you resume the schedule or remove it.
- For a fixed duration: 1 hour, 8 hours, 24 hours, or 1 week.
- Custom date and time: The override lasts until the date and time you set, interpreted in UTC.
Confirm the dialog, then deploy your changes to apply the override.

To clear an active override, select Resume schedule if the Deployment has a schedule, or Remove override if it doesn’t.

Set the override through the APC API with upsertDeployment. The hibernationOverride field takes a hibernate boolean (true hibernates now, false wakes now) and an optional overrideUntil timestamp for when the override lapses. Omit overrideUntil for an override with no expiry.

# Hibernate now, until the override is removed.
mutation {
  upsertDeployment(
    deploymentUuid: "<deployment-id>"
    hibernationOverride: { hibernate: true }
  ) {
    id
  }
}

# Wake now, until a specific time.
mutation {
  upsertDeployment(
    deploymentUuid: "<deployment-id>"
    hibernationOverride: { hibernate: false, overrideUntil: "2026-06-01T18:00:00Z" }
  ) {
    id
  }
}

To clear an active override and return the Deployment to its schedule, set hibernationOverride to null.

Use astro deployment hibernate to hibernate and astro deployment wake-up to wake. With no flags, the override holds until you remove it.

# Hibernate until the override is removed.
astro deployment hibernate <deployment-id>

# Hibernate for a duration.
astro deployment hibernate <deployment-id> --for 2h30m

# Wake up until a specific time.
astro deployment wake-up <deployment-id> --until 2026-06-01T18:00:00Z

# Remove any existing override and resume the regular schedule.
astro deployment hibernate <deployment-id> --remove-override

Flag	Description
`--for`, `-d`	Set the override period using a duration, such as `1h30m`.
`--until`, `-u`	Set the override period using an end date and time, such as `2026-01-01T00:00:00Z`.
`--remove-override`, `-r`	Remove any existing override and resume the regular hibernation schedule.
`--force`, `-f`	Skip the confirmation prompt.

--for, --until, and --remove-override are mutually exclusive. astro deployment wake-up takes the same flags; its aliases are hb for hibernate and wu for wake-up.

Governance never blocks waking, even if hibernation was turned off at a governing level while a Deployment was asleep. The Hibernation section stays visible for any Deployment with hibernation configured, so you can remove its schedules or override and wake it.

Hibernate a Deployment on a schedule

A schedule is a pair of cron expressions: one that hibernates the Deployment and one that wakes it. Use schedules to hibernate overnight and weekend idle time.

Astro UI
APC API

Click Deployments, select a Deployment, then open the Settings tab.
Expand the Hibernation section and add a schedule in Wake Schedules. This opens the Add Wake Schedule dialog.
Give the schedule an optional Description (up to 200 characters), then define it in one of two ways:
- Simple scheduling: Pick a Schedule Type and a Timezone, select the days to Wake On, and set the awake Window.
- Advanced cron scheduling: Enter a Wake at schedule cron expression and a Hibernate at schedule cron expression.
Save the schedule, then deploy your changes to apply it.

To manage an existing schedule, use the controls on its row in Wake Schedules, then deploy your changes:

Edit: Change the schedule’s description, days, window, or cron expressions.
Disable Schedule: Keep the schedule but stop it from taking effect. A disabled schedule shows in the timeline but doesn’t hibernate or wake the Deployment. Re-enable it from the same menu.
Delete Schedule: Remove the schedule permanently.

A Wake Schedule row with an Edit button and an overflow menu open, showing Disable Schedule and Delete Schedule options.

Manage schedules through the APC API with upsertDeployment. The hibernationSchedules field is replace-all: whatever list you send becomes the Deployment’s complete set of schedules, and there is no per-schedule create, update, or delete call. To add, change, or remove one schedule, send the full list you want the Deployment to end up with.Each entry in the list has these fields:

Field	Type	Description
`hibernateAtCron`	`String!`	Cron expression for when to hibernate. Required.
`wakeAtCron`	`String!`	Cron expression for when to wake. Required.
`isEnabled`	`Boolean!`	Whether the schedule is active. Required. Set `false` to keep a schedule but stop it from taking effect.
`description`	`String`	Optional label, up to 200 characters.

Set the Deployment’s schedules by sending the full list:

mutation {
  upsertDeployment(
    deploymentUuid: "<deployment-id>"
    hibernationSchedules: [
      {
        description: "Weeknights"
        hibernateAtCron: "0 22 * * 1-5"
        wakeAtCron: "0 6 * * 1-5"
        isEnabled: true
      }
    ]
  ) {
    id
    hibernationSchedules {
      id
      description
      hibernateAtCron
      wakeAtCron
      isEnabled
    }
  }
}

To read or change schedules, use these calls:

Operation	What to send
Read	Query the Deployment’s `hibernationSchedules`. Each returned schedule has a server-assigned `id`, `createdAt`, and `updatedAt`.
Add or update	Send the full list with the new or changed entries included. Entries you resend are preserved; omitted entries are deleted.
Delete one	Send the full list with that entry removed.
Delete all	Send an empty list, `hibernationSchedules: []`.
Leave unchanged	Omit `hibernationSchedules` from the mutation entirely.

hibernationSchedules and hibernationOverride are independent: changing one never affects the other.

You can configure up to 10 schedules per Deployment. When schedules overlap, hibernation wins: the Deployment is awake only when no schedule’s hibernation window covers the current time.

Schedules are stored and evaluated in UTC. In Simple mode, pick your time zone and APC converts the times to UTC. In Custom mode, write the cron expressions in UTC yourself. For example, to hibernate at 17:00 EST, use 0 22 * * * (22:00 UTC). Stored UTC times don’t shift with daylight saving time.

Hibernate indefinitely

To hibernate a Deployment and keep it asleep until you wake it, create a schedule with @always as the hibernate expression and @never as the wake expression. You can wake the Deployment at any time with Wake now.

Schedule validation

Apart from the @always/@never pair described in Hibernate indefinitely, APC rejects a schedule if:

The hibernate and wake cron expressions are identical.
The wake expression is * * * * *, which would keep the Deployment permanently awake.
A cron expression contains the ? character. Use * instead.
A cron expression has six fields (seconds). APC uses standard five-field cron expressions.
@always or @never is used without the other.
A cron expression can’t be parsed or never produces a next occurrence.

Status and behavior while hibernated

The APC UI shows a status badge for the Deployment’s hibernation state, along with the next scheduled event and its type, labeled in UTC. The badge reads Hibernated while the Deployment is asleep and Active while it’s awake.

The Hibernation section showing a Hibernated status badge, the next scheduled wake event in UTC, and the Wake Schedules timeline.

While a Deployment is hibernated:

All Deployment resources are scaled to zero, including the scheduler, webserver or API server, triggerer, and all workers.
Open Airflow is disabled, and the Airflow UI isn’t reachable.
Tasks and Dags don’t run.

Hibernation terminates any task that is still running and marks it as failed. It doesn’t wait for in-progress tasks to finish.

Operations blocked while hibernated

Operations that act on running components fail on a hibernated Deployment, with a message telling you to wake it first:

Deploying code or a new image.
Changing the Deployment’s configuration.
Upgrading runtime versions.

On a sleeping Deployment, you can still edit the hibernation configuration, such as changing a schedule or removing an override, and wake it. To run a blocked operation, wake the Deployment, perform the operation, then hibernate it again. The Deployment returns to its schedule.

A Deployment hibernates again only once all of its components are healthy and running. If a deploy leaves it unhealthy, it stays awake and ignores its schedule until you resolve the problem, so check its health first if it stops hibernating on schedule.

State preservation

Across a full hibernate-and-wake cycle, the following are preserved:

Dags, connections, variables, and pools.
Task instance history and Dag run history.
Task logs.
Every Deployment configuration, including each worker queue’s worker count or autoscaling range, scheduler size, and environment variables.

Pods scale to zero and back. Nothing is deleted or recreated.

​Prerequisites

​Enable hibernation

​Hibernate and wake a Deployment on demand

​Hibernate a Deployment on a schedule

​Hibernate indefinitely

​Schedule validation

​Status and behavior while hibernated

​Operations blocked while hibernated

​State preservation

​Related documentation

Prerequisites

Enable hibernation

Hibernate and wake a Deployment on demand

Hibernate a Deployment on a schedule

Hibernate indefinitely

Schedule validation

Status and behavior while hibernated

Operations blocked while hibernated

State preservation

Related documentation