Force-on, force-off, expiry, reason

Outcome

By the end of this lesson, you will be able to configure force-on and force-off overrides with appropriate expiry and reason fields and verify the override is active.

1. Concept

An override has four parts.

Two you must give: a type, meaning what it does, and an expiry, meaning when it stops. One is optional: a reason, for whoever reads this later. The fourth you do not type at all, the scope, which is simply wherever you set it from, one resource or a whole group.

One note on the reason. It is not a stored field the system checks or searches, so write it for the human who will find this override next week, not for a machine.

Field 1: Type

Two options:

• Force-on (override_type=1): the resource (or group) stays ON during the window. Schedule stop crons are ignored.
• Force-off (override_type=0): the resource (or group) stays OFF during the window. Schedule start crons are ignored.

There is nothing finer than that. ON or OFF, nothing in between. This matches the scheduler’s vocabulary; complex state transitions (e.g., “scale to X replicas”) use the autoscaler features, not overrides.

Field 2: Reason

Free-form text. Optional. When provided, the reason is the operational documentation:

GOOD REASONS                              BAD REASONS
─────────────────────────────────────────────────────────
"Acme demo Sat 2pm, exp Mon 8am"          "test"
"Incident #2026-05-19-payments,           "weekend"
 prevent schedule firing"
"Migration to new instance types,         "asked by sarah"
 expected 6h duration"                     ─── (no context)
"DR drill, force-on all dev for
 24h window"

When provided, the reason becomes the answer to “why is this on?” when a future engineer is investigating. Be specific.

The reason is optional and is not stored as a backend field, so it is not machine-enforced or validated. Treat it as a note for teammates, not a control you can audit against. Writing a clear reason is a good habit, not a requirement.

Field 3: Expiry

Required. The override is removed automatically at the expiry time. No exceptions.

EXPIRY OPTIONS
  Exact datetime:       2026-05-26 08:00 (timezone-aware)
  Relative duration:    +24h, +48h, +7d (computed from now)
  End-of-week:          Monday 00:00 (common shorthand)

The expiry is stored as an absolute UTC timestamp. Timezone conversions happen at display time only.

If the expiry exceeds the resource’s Max Override Duration cap (covered in L4), the create is rejected. A team trying to set a 90-day override on a resource capped at 7 days must either reduce the duration, have an admin raise that resource’s cap, or edit the schedule for a permanent change. If the resource’s cap is 0, overrides are refused there entirely.

Field 4: Scope (implicit)

• Per-resource override is set from the Resource detail page → applies to that one resource only
• Per-group override is set from the Group detail page → applies to every member of the group

Group overrides are more common for the demo / maintenance / incident scenarios. Per-resource overrides are for highly-specific situations (one VM needs to stay on for a specific test).

What the override does internally

WHEN A CRON FIRES on a resource with an active override:
  - The scheduler checks for any active overrides on the resource (or its group)
  - If force-on and the cron is a stop → cron is SKIPPED
  - If force-off and the cron is a start → cron is SKIPPED
  - If force-on and the cron is a start → cron fires (already on, no-op)
  - If force-off and the cron is a stop → cron fires (already off, no-op)
  - The skip is logged in the action log with reason "override active"

AT EXPIRY:
  - The override is removed
  - Subsequent cron firings act normally
  - The resource's state at expiry is its actual state (NO automatic transition)

The override does NOT actively transition the resource. It only prevents the schedule from transitioning. If a force-off override is removed at expiry and the schedule’s next start cron is hours away, the resource stays off until then.

Notifications

Setting an override fires a notification (per the resource’s notification routing: see M1.6 L3):

Slack notification:
─────────────────────────────────────────────────────────
🔔 Override applied
   Resource:  staging-eu-cluster
   Type:      Force-on
   Reason:    "Acme Corp demo Sat 2pm, requested by sarah@sales"
   Expires:   2026-05-26 08:00 Europe/London
   Set by:    engineer@zopcloud.com
─────────────────────────────────────────────────────────

The notification lets the team see overrides happen in real time, even when they’re not the one who set them. Reduces “who set this?” confusion.

A second notification fires when the override expires:

🔔 Override expired
   Resource:  staging-eu-cluster
   Originally set by: engineer@zopcloud.com
   Reason:    "Acme Corp demo Sat 2pm"
   Schedule now resumes normal operation

The expiry notification confirms the override cleanup happened on time.

Configuration flow

Resource (or Group) detail page → Override button
─────────────────────────────────────────────────────────
SET OVERRIDE

  Type:       [ Force-on  ▾ ]
  Reason:     [                                       ]  (optional)
  Expiry:     [ Exact ▾ ] [ 2026-05-26 08:00 ]
              [ Relative ▾ ] [ +24h ]
  Scope:      ● This resource only
              ○ Apply to the resource group ('staging-eu')

[Cancel]                                              [Apply override]

Two required fields (type and expiry), one optional note, one optional scope expander. The form is short on purpose: overrides should be set quickly, not deliberated over.

2. Demo

A team setting a maintenance override:

INTENT: Maintenance on dev-cluster-1, expected 6 hours, want schedule
         not to interfere.

T+0       Open dev-cluster-1 → Override button
T+10 sec  Fill in:
            Type:    Force-off
            Reason:  "Planned migration to graviton node types,
                      expected 6h duration. Tracked in ticket DEV-4521."
            Expiry:  Relative +8h (8 hours from now, buffer of 2h)
            Scope:   This resource only

T+20 sec  Apply override.

T+25 sec  Slack notification fires.

T+25 sec  Resource is force-off (was already stopped manually before maintenance).
          Any scheduled start in the next 8 hours is skipped.

T+6 hrs   Maintenance complete. Resource is restarted manually by the team.
          Override is still active: the resource is now running despite the
          force-off override. (The override prevents the SCHEDULE from acting,
          not from manual start.)

T+8 hrs   Override expires automatically.
T+8 hrs   Expiry notification fires.
T+8 hrs   Schedule resumes normal operation.

The override prevented schedule interference during maintenance without preventing manual control. The team kept agency over the resource.

3. Hands-on (6 min)

In a sandbox:

1. Pick a sandbox resource that has a schedule attached.
2. Apply a force-off override:
   - Reason: "Test override: exploring the UI"
   - Expiry: +1h (one hour from now)
3. Save.
4. Verify the override appears:
   - On the resource detail page
   - On the schedule's 24-hour grid (visible as a separate color band)
   - In the Overrides page list
5. Verify the Slack notification (if configured) fires.
6. Wait or trigger a cron firing during the override window: confirm
   the cron is skipped (the resource state doesn't change).
7. Wait for expiry (or cancel early via L3 mechanics).
8. Confirm the override cleans up.

The hands-on takes longer than the 6 minutes if you wait for expiry. The mechanics are quick; the verification is what takes the clock.

Do it through MCP. The same task you just did in the console, asked in one sentence.

BEFORE  A ZopNight account with one cloud connected. One resource already covered by a schedule.
ASK     "Keep the staging database up until Friday at 18:00, reason: release testing."
CHECK   the expiry came back set. An override with no expiry is the one that quietly costs you a month.

Tools behind it: create_override (write, tier 2, reversible), list_overrides (read, Operate), get_override_candidates (read, Optimize). The full catalogue is at zop.dev/learn/mcp-tools.

4. Knowledge check

Q1

An override expires while a resource is in the “wrong” state for what the schedule would normally enforce. What happens?

A. The schedule immediately transitions the resource back into its correct scheduled state
B. The override is recreated
C. An error fires
D. The resource stays in its current state until the schedule’s next cron fires for that resource

Q2

A team needs to set an override that expires in 90 days. The resource’s max override duration is 7 days. What happens?

A. The override is created with 90-day expiry
B. The create is rejected
C. ZopNight warns but accepts
D. The override expires after 7 days

Q3

A force-on override is active on a resource. The user manually clicks Stop. What happens?

A. The stop is rejected outright, since the override is currently forcing that particular resource on
B. The override is automatically removed
C. An error fires
D. The stop succeeds; the override prevents the SCHEDULE from acting, not the user from acting manually

5. Apply

Override configuration:

• Resource detail → Override (per-resource)
• Group detail → Override (per-group)
• Overrides page → see all active overrides

For managing existing overrides, continue to L3.

Related lessons

• L3: Managing active overrides (next)
• L4: Max override duration
• M1.6 L3: Notifications

Glossary terms touched

Force-on · Force-off · Reason field · Override expiry · Override scope