feat(host_agent): a group's updates and reboots on a weekly cadence, one host at a time (#5768)

#5768 "A maintenance cadence: a group's updates and reboots, one host at a
time, on a schedule". A plan names an inventory group, a weekday and time
in a time zone, a window and a reboot policy (only when required by
default). At its slot a run takes the group's hosts in order and gives each
a #5767 maintenance job. The next host starts only when the last is back in
service: its agent is posting and, for a swarm node, the node is active and
every replicated service is at its replicas. A failure stops the run, and
no host is started once the window has passed. A host's latest failure
shows as host_agent/<host>/maintenance_failed, for an ordinary alert rule.
The page is Hosts → Maintenance.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

plugins/host_agent/models.py

@@ -106,3 +106,52 @@ class HostMaintenanceJob(Base):
     created_by = Column(String(36), ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
     created_at = Column(DateTime(timezone=True), nullable=False, default=_utcnow)
     finished_at = Column(DateTime(timezone=True), nullable=True)
+    # The cadence run this job belongs to (#5768); None for Update now.
+    run_id = Column(String(36), ForeignKey("host_maintenance_runs.id", ondelete="SET NULL"),
+                    nullable=True, index=True)
+
+
+class HostMaintenancePlan(Base):
+    """A group's maintenance cadence (#5768): every week on `weekday` at
+    `at_time` in `time_zone`, its hosts are updated one at a time, each
+    rebooting per `reboot_policy`. No host is started after `window_minutes`
+    from the run's start. last_slot_at is the last scheduled slot that fired;
+    Run now leaves it alone, so the schedule keeps its time."""
+    __tablename__ = "host_maintenance_plans"
+
+    id = Column(String(36), primary_key=True, default=_uuid)
+    name = Column(String(128), nullable=False)
+    group_id = Column(String(36), ForeignKey("ansible_groups.id", ondelete="CASCADE"),
+                      nullable=False)
+    weekday = Column(Integer, nullable=False)              # 0 = Monday
+    at_time = Column(String(5), nullable=False)            # "HH:MM"
+    time_zone = Column(String(64), nullable=False, default="UTC")
+    window_minutes = Column(Integer, nullable=False, default=240)
+    reboot_policy = Column(String(16), nullable=False, default="if_required")
+    enabled = Column(Boolean, nullable=False, default=True)
+    last_slot_at = Column(DateTime(timezone=True), nullable=True)
+    created_by = Column(String(36), ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    created_at = Column(DateTime(timezone=True), nullable=False, default=_utcnow)
+
+
+class HostMaintenanceRun(Base):
+    """One run of a plan: its hosts in order, one at a time (#5768).
+
+    host_ids is the order fixed at the start (JSON list); position is the host
+    being worked on; skipped is [{"host_id", "reason"}] for hosts the run
+    passed over. settle_since is when the current host's job finished and the
+    run began waiting for the host to be back in service."""
+    __tablename__ = "host_maintenance_runs"
+
+    id = Column(String(36), primary_key=True, default=_uuid)
+    plan_id = Column(String(36), ForeignKey("host_maintenance_plans.id", ondelete="CASCADE"),
+                     nullable=False, index=True)
+    state = Column(String(16), nullable=False, default="running", index=True)
+    host_ids = Column(Text, nullable=False, default="[]")
+    position = Column(Integer, nullable=False, default=0)
+    skipped = Column(Text, nullable=False, default="[]")
+    settle_since = Column(DateTime(timezone=True), nullable=True)
+    detail = Column(Text, nullable=True)
+    manual = Column(Boolean, nullable=False, default=False)
+    started_at = Column(DateTime(timezone=True), nullable=False, default=_utcnow)
+    finished_at = Column(DateTime(timezone=True), nullable=True)