mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-08-05 16:37:46 +00:00
Anso
5f7a887ed6
Restructures the Documentation tab so each group answers one operator question. - Split the 12-page "Stacks & Deployments" into Stacks (per-stack work) and Deployment (the act of deploying); promote Resources Hub to a standalone item. - Dissolve the 2-page "Platform" junk drawer: Sidebar moves to Stacks, Host Console moves to Fleet. - Rename "Fleet & Multi-Node" to "Fleet"; absorb Node Compatibility from Reference. Move Scheduled Operations from Fleet to Automation (now a 4-page group covering Scheduled Ops, Auto-Update, Auto-Heal, Webhooks). - Clean up the Reference tab: drop misplaced node-compatibility, move root-level security.mdx into reference/, delete the orphan reference/verifying-images.mdx after porting its Available Tags table into operations/verifying-images.mdx. - Reorder top-level groups: Operations moves above Reference. - Rename two misleading page titles: "Deploy Progress Modal" becomes "Deploy Progress" (drops the UI implementation leak); "Auto-Update Readiness" becomes "Auto-Update Policies" (matches filename and sibling "Auto-Heal Policies"). Verified: docs.json parses as valid JSON, 59 disk .mdx files match 59 nav entries with zero orphans and zero broken refs.
133 lines
10 KiB
Plaintext
133 lines
10 KiB
Plaintext
---
|
|
title: "Auto-Update Policies"
|
|
description: "Review pending container updates across your fleet, with risk badges, changelogs, and scheduled run times, before applying."
|
|
---
|
|
|
|
<Note>
|
|
Auto-Update Policies require a **Skipper** or **Admiral** license.
|
|
</Note>
|
|
|
|
<Note>
|
|
Auto-Update is hub-only and is hidden from the nav strip when a remote node is the active selection. See [Multi-Node Management](/features/multi-node#what-top-level-views-show-when-a-remote-node-is-active).
|
|
</Note>
|
|
|
|
## Overview
|
|
|
|
Auto-Update Policies are the launchpad for every pending update across your stacks. Instead of a list of CRUD policies, the view surfaces one card per stack with an available update and tells you, at a glance, whether it is safe to apply.
|
|
|
|
Each card shows:
|
|
|
|
- The current tag and (for semver updates) the next tag, with the new version highlighted in cyan. For digest-only updates, the card shows the current tag with a **Rebuild available** marker instead of a version diff.
|
|
- A **risk badge** derived from the version delta: `Safe · patch` (green), `Review · minor` (amber), `Blocked · major` (red), or `Digest rebuild` (gray) for non-semver tags.
|
|
- The primary image reference, plus a count of additional services if more than one image in the stack has an update.
|
|
- A one-line changelog preview when the registry publishes one. Registries that omit changelog metadata render the card with "No changelog available from the registry yet."
|
|
- The next scheduled run for the matching auto-update task, if one exists, or "No schedule".
|
|
|
|
<Frame>
|
|
<img src="/images/auto-update/readiness-board.png" alt="Readiness board with hero counter, per-node groups, and risk badges" />
|
|
</Frame>
|
|
|
|
The hero at the top counts pending updates across every node in your fleet and tells you how many are ready to apply without human review. Its subtitle reads `X of Y ready to apply automatically across N nodes`. Stacks with a major version bump are surfaced as a separate count (`· Z blocked by major bump`) so they can be reviewed before the scheduler runs.
|
|
|
|
Cards are grouped by node, with a section header for each node that has at least one pending update. The header shows the node name, a `local` or `remote` pill, and the stack count. The local node is listed first, followed by remote nodes alphabetically. If any of your online nodes is unreachable when the page loads, a small line under the hero reads `X of Y nodes reachable. Unreachable nodes are not shown.`
|
|
|
|
## Empty state
|
|
|
|
When nothing is pending, the board renders a single Shield-icon panel with the headline "All stacks on current builds" and the sub-line "Sencho will recheck registries on the scheduler interval." Image update detection runs every six hours on each node; the readiness board reflects that cached status until the next cycle (or until you press **Recheck**).
|
|
|
|
## Workflow
|
|
|
|
1. Open **Auto-Update** from the top nav strip.
|
|
2. Skim the card grid. The badge tells you the risk at a glance: `Safe · patch` is green, `Review · minor` is amber, `Blocked · major` is red, and a digest-only rebuild on a non-semver tag shows the gray `Digest rebuild` badge.
|
|
3. For a safe update, click **Apply now** on the card to pull and recreate the stack immediately.
|
|
4. For a major bump, review the changelog preview and the upstream release notes. **Apply now** is disabled on the readiness board for blocked cards; to apply a major bump after review, use the stack's lifecycle **Update** action (right-click the stack in the sidebar, or open the kebab menu and choose **Update**, or click **Deploy** in the stack editor).
|
|
5. Use **Recheck** in the hero to force an immediate registry poll across every reachable node. A 2-minute per-node cooldown applies, and the toast tells you how many nodes were triggered, rate-limited, or failed.
|
|
|
|
## Risk badges
|
|
|
|
| Badge | Color | When it appears |
|
|
|-------|-------|-----------------|
|
|
| `Safe · patch` | Green (Shield icon) | Patch-level semver bump (e.g. `1.2.3` to `1.2.4`) |
|
|
| `Review · minor` | Amber (AlertTriangle icon) | Minor semver bump (e.g. `1.2.3` to `1.3.0`) |
|
|
| `Blocked · major` | Red (ShieldAlert icon) | Major semver bump (e.g. `1.2.3` to `2.0.0`). **Apply now** is disabled; the card surfaces the reason "Major version jumps require human review before applying." |
|
|
| `Digest rebuild` | Gray | Non-semver tag (e.g. `main`, `stable`) with an updated digest |
|
|
|
|
A separate inline `Rebuild available` label replaces the version diff when only the digest changed (same tag, new image). The risk badge on those cards still reflects the underlying semver classification reported by the registry.
|
|
|
|
Blocked updates still surface in scheduled check runs so you stay informed, but the apply button is disabled until you review them manually.
|
|
|
|
## Per-stack control
|
|
|
|
Auto-updates can be disabled on a per-stack basis from the stack's context menu. This lets you keep the global schedule active while opting specific stacks out of unattended updates, such as databases, self-built images, or any stack pinned to a fixed tag.
|
|
|
|
### Disabling auto-updates for a stack
|
|
|
|
1. Right-click the stack in the sidebar, or open the kebab menu (three dots).
|
|
2. In the **Inspect** group, click **Auto-update: Enabled** to toggle it off. The label changes to **Auto-update: Disabled** and the icon switches to a slash-circle.
|
|
3. The setting persists across restarts. The readiness board shows an **Auto: Off** pill on that card, and the **Apply now** button is disabled with the tooltip "Auto-updates are disabled for this stack. Update it from its actions menu."
|
|
|
|
<Note>
|
|
Per-stack auto-update control requires a **Skipper** or **Admiral** license.
|
|
</Note>
|
|
|
|
### What disabling means
|
|
|
|
- **Scheduled and fleet-wide auto-update runs skip the stack entirely.** No registry call is made, and no image update is applied automatically.
|
|
- **Image update detection still runs.** The sidebar dot and the readiness card still reflect whether an update is available. You are informed; the system just does not apply it for you.
|
|
- **Manual updates are unaffected.** You can still click **Update** in the lifecycle menu (or **Deploy**) to apply an update on demand. Per-stack control governs only the automated path.
|
|
|
|
### Re-enabling
|
|
|
|
Open the same menu and click **Auto-update: Disabled** to toggle it back on. The next scheduled run will include the stack again.
|
|
|
|
## Scheduling auto-updates
|
|
|
|
Auto-update is a first-class action in the Schedules view. To create a recurring check for a stack:
|
|
|
|
1. Open **Schedules** in the top nav.
|
|
2. Click **New Schedule**.
|
|
3. Set **Action** to **Auto-update Stack**, choose the target node and stack, pick a cron expression, and save.
|
|
|
|
The task lives alongside restart, prune, snapshot, and scan tasks in the same timeline and table. Run history, notifications, and the Run Now button behave the same as for every other scheduled action. See [Scheduled Operations](/features/scheduled-operations) for details.
|
|
|
|
## Multi-node support
|
|
|
|
The readiness board shows pending updates from every node in your fleet in a single view, regardless of which node is selected in the sidebar. You do not need to switch nodes to inspect what is pending elsewhere.
|
|
|
|
Each node group renders its own card grid under a header showing the node name, a `local` or `remote` pill, and a stack count. **Apply now** runs on the node that owns the stack, and **Recheck** fans out to every reachable node so registries get polled in parallel. Sencho handles the routing through the Distributed API; no additional configuration is needed.
|
|
|
|
## How readiness is computed
|
|
|
|
For each stack with a pending image update, Sencho computes a preview by:
|
|
|
|
1. Parsing the compose file to enumerate every pullable image reference.
|
|
2. Calling the registry with your configured credentials to fetch the current tag list and remote digest.
|
|
3. Picking the highest semver tag greater than the current tag (keeping the same prefix and suffix). If the highest available tag matches the current one but the remote digest has changed, the card surfaces as a `Rebuild available` update.
|
|
4. Scoring the overall stack by the most severe image bump. Any major bump marks the stack as blocked.
|
|
5. Normalizing Docker Hub library paths so credentials and changelog lookups resolve correctly.
|
|
|
|
The preview is recomputed each time the readiness board loads, so it reflects the live state of your registries and local images.
|
|
|
|
## Troubleshooting
|
|
|
|
<AccordionGroup>
|
|
<Accordion title='Card shows "No changelog available"'>
|
|
Sencho reads changelog metadata from the registry's manifest and OCI annotations. Registries that do not publish this metadata (most private registries and many self-hosted ones) render the card without a changelog. The risk badge is still accurate because it is computed from the tag itself.
|
|
</Accordion>
|
|
<Accordion title='Apply now is disabled with a "Blocked · major" tooltip'>
|
|
The stack has a major version bump and is blocked on the readiness board by policy: major updates never auto-apply without human review. To apply after reviewing the upstream release notes, use the stack's lifecycle **Update** action from the sidebar kebab or right-click menu, or open the stack editor and click **Deploy**.
|
|
</Accordion>
|
|
<Accordion title='Card stays stuck on "Checking registry..."'>
|
|
The registry call is either still pending or it failed. Click **Recheck** in the hero to retry. If the stack uses private-registry credentials, confirm they are still valid in **Settings > Registries**.
|
|
</Accordion>
|
|
<Accordion title='"Nothing to update" but I see an update on another view'>
|
|
Image update detection runs every six hours on each node and the readiness board uses the same cached status. Trigger **Recheck** to force a fresh check across every reachable node.
|
|
</Accordion>
|
|
<Accordion title='Scheduled auto-update runs are not applying to a specific stack'>
|
|
The stack likely has auto-updates disabled. Open the stack's kebab menu or right-click context menu and check the **Inspect** group. If the item reads **Auto-update: Disabled**, click it to re-enable. Once re-enabled, the next scheduled run will include the stack, or you can trigger an immediate run from the Auto-Update view.
|
|
</Accordion>
|
|
<Accordion title='Banner says "X of Y nodes reachable"'>
|
|
One or more nodes that are marked online in your fleet did not respond within the request timeout. Pending updates from those nodes are not shown until they come back. Check the node's status from the Fleet view and the network path between this Sencho instance and the unreachable node.
|
|
</Accordion>
|
|
</AccordionGroup>
|