mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 11:49:16 +00:00
Anso
cfb42af4e0
* fix(dashboard): replace Stack Health update badge with an icon The pill badge duplicated space already used by the stack name column. A CircleArrowUp icon after the name signals an update is available without competing with the existing ArrowUp/ArrowDown sort indicators in the same table. * fix(dashboard): add accessible name to update-available icon Icon-only indicators need an aria-label directly on the icon; title on a non-interactive span is not reliably announced by screen readers. * test(dashboard): cover the update-available icon's accessible name The icon-only indicator and its aria-label fix had no regression guard, unlike the equivalent update dot in StackRow. * refactor(dashboard): compute the update-available label once per row It was being derived twice (title and aria-label) from the same row.outdatedServices input. * fix: drop Community-tier pricing upsells from settings Community operators no longer see the "See pricing" link in Licensing or the "Need direct support?" callout in Support. The pricing link now only shows for an expired paid license needing to renew. * fix: make Resources images/volumes tables actually scrollable The tables were wrapped in a Radix ScrollArea sized with max-h-[62vh]. Radix's viewport uses height:100%, which cannot resolve against an ancestor whose computed height is auto (max-height alone isn't a definite height), so the viewport silently grew past the visible box and the extra rows were clipped with no way to reach them. Verified live: several image rows were permanently unreachable, with no working internal scrollbar and not enough outer page scroll to compensate. Switched to an explicit h-[62vh], which the viewport can resolve correctly, matching every other working ScrollArea in the codebase. Falls back to h-auto below the md breakpoint so the bespoke mobile layout keeps shrinking to content and scrolling via the outer page instead of gaining a fixed-height inner scroll box. * fix: apply ScrollArea definite-height fix across remaining lists Radix ScrollArea needs an explicit height, not max-height, or the viewport collapses and clipped rows become unreachable. Extend the Resources fix to security, settings, git, and create/import surfaces, and drop redundant outer wrappers where ModalBody already scrolls. * fix: migrate Networking tables to Radix ScrollArea Networks and Findings used native max-h + overflow-auto, which worked but broke glass scrollbar consistency with Resources and the design system. Switch them to ScrollArea with a definite height and the same mobile fallback as the other inventory tables. * fix: warn Classic bar users that the style is retiring soon When Appearance Navigation is set to Classic bar, show the same warn SettingsCallout pattern used for Constrained graphics. Preference is kept until removal; no alternate style is named in the copy. * fix: move Channels delivery retries below channel tabs Put channel configuration first and keep Delivery retries as a shared footer control under the Discord/Slack/Webhook/Apprise tabs. * fix: drop redundant More masthead from Smart bar overflow menu The trigger already reads More, so the dropdown masthead repeated the same label. Leave titled mastheads on Compact Navigate and Add quick link menus. * test: align Smart More E2E with masthead removal The overflow menu no longer shows a More heading. Assert the menu via the Logs item and lock that the redundant masthead stays gone. * fix: consolidate Fleet Map toolbar filters into a single row Adopt the same retractable search control used on Fleet > Overview and move the flag filters (missing deps, port conflicts, orphans, shared) onto the toolbar row right after the Graph/List selector. The node filter becomes a dropdown instead of individual toggle chips so it does not clutter the row as fleet size grows. * fix: move Networking Topology filters onto the search toolbar row Merge the ownership selector and boolean filter chips (include system, exposed, drift, missing external, shared) onto the same row as the stack/network search inputs, matching the Fleet Map toolbar layout. * fix: default the reclaimable-space banner off Resources > Docker & Storage's "Show reclaimable-space banner" toggle now defaults to off instead of on. Also flips the /settings fetch failure path to fail closed (hide the banner) to match the new default, instead of failing open. * fix: raise Compact launcher quick links cap from 5 to 7 * fix: add Discord link to Settings Support Self-serve Gives users a community chat channel alongside Documentation and GitHub Issues, using the official Discord mark since lucide-react has no brand icon for it. * fix: stop container NET I/O metric row height jump Give NET I/O more column share than CPU/MEM and keep metric values on one line with truncate so three-digit rates cannot grow the strip. * fix: elevate Doctor tab between Activity and Drift Make Compose Doctor easier to find in the anatomy strip by placing it with the ops judgment cluster, ahead of Dossier and inventory tabs.
201 lines
15 KiB
Plaintext
201 lines
15 KiB
Plaintext
---
|
|
title: Drift Detection
|
|
description: See at a glance whether a stack's running containers still match the effective Compose model, with specific, actionable reasons when they have diverged.
|
|
---
|
|
|
|
The **Drift** tab answers the core day-two operations question: does what is actually running still match what Compose would deploy?
|
|
|
|
Sencho treats your Compose file as the source of truth. Every time you open the Drift tab, it renders the effective model (variable substitution, multi-file merge, active profiles) and compares the live Docker runtime against that result. If you have deployed through Sencho, it also compares the current file against the baseline it recorded at deploy time, so you know whether the file has already changed for the next deploy.
|
|
|
|
The check is always read-only. It reports drift; it never fixes it on its own.
|
|
|
|
<img
|
|
src="/images/stack-drift/drift-in-sync.png"
|
|
alt="The Drift tab showing In sync status with Matches last deploy below it and a resolved network finding in the history"
|
|
/>
|
|
|
|
## How it works
|
|
|
|
Drift detection is split into two layers that work together.
|
|
|
|
**The spatial engine** performs a stateless diff between the effective Compose model and the containers currently running in Docker, then returns a report. It never writes anything to the database, so opening the tab is always side-effect-free.
|
|
|
|
**The drift ledger** sits on top of the spatial engine and provides persistence. When you click re-check, or when Sencho automatically reconciles after a deploy, it records new findings with timestamps, marks resolved findings as cleared, and writes events to the stack's Activity timeline. This turns a point-in-time snapshot into a short history of when drift appeared and when it cleared.
|
|
|
|
## Status
|
|
|
|
The status badge at the top of the tab summarizes the comparison between the effective Compose model and the running containers.
|
|
|
|
| Status | Meaning |
|
|
|--------|---------|
|
|
| **In sync** | Declared services match runtime: same running services, images, and published ports, or a declared one-shot finished cleanly (`Exited (0)` with explicit `restart: "no"` or `deploy.restart_policy.condition: none`). Omitting `restart:` does not count as a one-shot. |
|
|
| **Not running** | The stack has no running containers, and no declared service is satisfied by a finished one-shot. The file is present but nothing is up. |
|
|
| **Drifted** | Something differs from the model. Specific findings are listed below the badge. |
|
|
| **Unreachable** | Docker could not be reached on the active node, so drift cannot be assessed. |
|
|
|
|
## Since your last deploy
|
|
|
|
Below the status badge, a second signal compares the Compose file on disk against the version that was deployed through Sencho most recently.
|
|
|
|
<img
|
|
src="/images/stack-drift/drift-drifted.png"
|
|
alt="The Drift tab showing Drifted status with Source changed below it, and an image finding in the Findings section showing expected vs running image"
|
|
/>
|
|
|
|
| Signal | Meaning |
|
|
|--------|---------|
|
|
| **Matches last deploy** | The Compose file is unchanged since the last deploy. |
|
|
| **Source changed** | The Compose file has changed since the last deploy. If the change is structural (an image, port, or service definition), Sencho says so. A formatting-only or comment-only edit is noted separately. |
|
|
| **No deploy baseline** | This stack has not yet been deployed through Sencho, so there is no recorded baseline. Deploy it once to start tracking. |
|
|
|
|
This signal is independent of the runtime status. A stack can be **In sync** with its running containers while its file has **already changed** for the next deploy, or it can be **drifted** at runtime while the file itself is unchanged from what was deployed.
|
|
|
|
<Note>
|
|
Sencho records two hashes at deploy time: a raw-file hash (catches any text change, including formatting) and a parsed-model hash (only changes when structure changes, ignoring comments and whitespace). The "source changed" signal uses both: if only the raw hash differs, the edit was formatting or comments. If the model hash also differs, a structural change has been made.
|
|
</Note>
|
|
|
|
## Findings
|
|
|
|
When a stack is drifted, each reason is listed in the **Findings** section against the service it affects.
|
|
|
|
| Finding | What it means |
|
|
|---------|---------------|
|
|
| **Image** | A running container uses a different image than the Compose file declares. Expected and actual values are shown side by side. |
|
|
| **Ports** | The published ports of a service differ from what the Compose file declares. |
|
|
| **Service missing** | The Compose file declares a service, but no running container matches it and no clean one-shot completion satisfies it. |
|
|
| **Undeclared service** | A container is running for the stack but no matching service exists in the Compose file. |
|
|
| **Network undeclared** | A running service is attached to a network that is not declared in the Compose file. |
|
|
| **Network missing** | A network declared in the Compose file is not used by any running service or is absent from the runtime. Network usage still counts only running or restarting containers, so a finished one-shot does not keep a dedicated Compose network marked as in use. |
|
|
|
|
### Image comparison
|
|
|
|
Drift compares running images against the **effective** compose model: the same resolved result Docker produces at deploy time, including variable substitution (for example `${VAR:-default}`), multi-file merge, and active profiles.
|
|
|
|
Image references are normalized before comparison, so equivalent forms do not produce false positives. `nginx`, `docker.io/nginx`, and `docker.io/library/nginx:latest` all resolve to the same reference.
|
|
|
|
If a service has multiple replicas, any replica running a different image than the declared one triggers an image finding. This catches stacks that are mid-update with mixed versions running simultaneously.
|
|
|
|
If the Compose file declares a tag (`:latest`, `:1.25`) and the running container was pulled from a digest pin, the two forms are compared as-is. A digest-pinned container reads as an image mismatch against a tag declaration. This is intentional: the two references are not equivalent. Sencho uses the same distinction in scan history and update detection; see [Tags vs digests](/features/vulnerability-scanning#tags-vs-digests).
|
|
|
|
### Port ranges
|
|
|
|
A Compose port range such as `8000-8002:8000-8002` is compared conservatively. Because the runtime expands ranges into individual ports, the comparison can read as a difference even when the deployment is correct. Sencho errs toward surfacing the possible difference rather than hiding it.
|
|
|
|
### Network findings and the Networking tab
|
|
|
|
The **network-undeclared** and **network-missing** findings reuse the same comparison the stack's [Networking](/features/compose-networking) tab uses, so the two surfaces never disagree about a network attachment. The difference is history: this tab persists findings in the drift ledger over time, while the Networking tab always shows the current live state with no history. A stack with an open network finding also counts toward the **Drift** chip in the Fleet Overview's Networking filter group, so a network-attachment mismatch is visible both per-stack here and across the fleet there.
|
|
|
|
## When drift is recorded
|
|
|
|
**Opening the tab** runs the spatial engine and displays the current state. It does not write anything to the ledger or update the history.
|
|
|
|
**Clicking re-check** runs the spatial engine and then reconciles the result into the ledger: new findings are recorded with a detection timestamp, cleared findings are marked resolved, and Activity timeline events are written for any change. The history and "checked" timestamp update after a re-check.
|
|
|
|
**After every deploy or update**, Sencho automatically records a new baseline hash and runs a full reconciliation. You do not need to click re-check after deploying; the ledger is updated as part of the deploy pipeline.
|
|
|
|
<img
|
|
src="/images/stack-drift/drift-history.png"
|
|
alt="The Drift tab showing both the Findings section and the Drift history section with an open finding marked just now"
|
|
/>
|
|
|
|
## Drift history
|
|
|
|
The **Drift history** section shows up to the 20 most recent findings, both open and resolved. Open findings appear first.
|
|
|
|
Each entry shows:
|
|
- The service name and finding type (image, ports, service, or network)
|
|
- A description of the specific difference
|
|
- When the finding was first detected
|
|
- When it was resolved, if it has cleared
|
|
|
|
The history header shows when the ledger was last reconciled ("checked X ago"). The status badge at the top always reflects the current runtime state, computed fresh each time the tab is loaded. If the two disagree, a re-check will bring the history up to date.
|
|
|
|
### Activity timeline
|
|
|
|
Drift events also appear in the stack's **Activity** tab alongside deploys, restarts, and updates:
|
|
|
|
- **Drift detected**: recorded when a re-check or post-deploy reconciliation finds new open findings
|
|
- **Drift resolved**: recorded when findings that were previously open have all cleared
|
|
|
|
## Accessing the Drift tab
|
|
|
|
<img
|
|
src="/images/stack-drift/drift-tab-location.png"
|
|
alt="The tab bar in the stack detail view showing Anatomy, Activity, Drift, Dossier, Environment, and Compose Labels tabs with Drift selected, and separate Files and Edit compose buttons to the right"
|
|
/>
|
|
|
|
1. Click any stack in the sidebar to open it.
|
|
2. In the right-hand panel, switch to the **Drift** tab. If the tab row doesn't fit the panel width, scroll it to reveal Drift alongside the stack's other tabs (Anatomy, Activity, Doctor, Dossier, Environment, Networking, and so on).
|
|
3. Read the status badge and any findings.
|
|
4. Click **re-check** after editing the Compose file or after a manual Docker operation to refresh the ledger.
|
|
|
|
**Files** and **Edit compose** are separate buttons next to the tab row, not tabs themselves; they open the file browser and the compose editor respectively.
|
|
|
|
On mobile, the same report appears under the **Compose** segment of the stack detail view.
|
|
|
|
## Requirements
|
|
|
|
Drift detection is available on all plans with no additional configuration. As long as the stack has a Compose file and Docker is reachable on the node, the tab is functional.
|
|
|
|
Viewing the tab requires read access to the stack; any role that can see a stack (including read-only **viewer** and **auditor** roles) can open the Drift tab. Clicking **re-check** requires the same read-level access, so a read-only role can still trigger a ledger write (new findings recorded, resolved findings cleared, an Activity event logged) even though it cannot edit or deploy the stack.
|
|
|
|
## Limitations
|
|
|
|
**Read-only and advisory.** Drift detection never alters a stack. It reports differences and records them in the ledger, but deploying to resolve drift is a separate, explicit action.
|
|
|
|
**No automatic background scanning.** Drift is checked when you open the tab, when you click re-check, and after every deploy or update through Sencho. There is no automatic background poll that checks stacks on a schedule outside of those events.
|
|
|
|
**History cap.** The ledger keeps the 20 most recent findings per stack. Older entries are not shown in the UI.
|
|
|
|
**Port ranges.** Compose port ranges are compared conservatively and may report a difference even when the deployment is correct.
|
|
|
|
**Unreachable Docker.** When Docker cannot be reached, the status shows as Unreachable and no findings are reported. Open findings in the ledger are not resolved just because the check could not run; they remain open until a successful check confirms they have cleared.
|
|
|
|
**Parse errors.** If the Compose file cannot be parsed, no findings are extracted from it and the ledger is not updated. Resolve the parse error and re-check.
|
|
|
|
## Troubleshooting
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="A stack I deliberately stopped shows as 'Not running'">
|
|
That is expected for long-running services. Drift compares the file on disk against what is actually running, so a stack with no running containers and no finished one-shot jobs reports **Not running** even when you stopped it intentionally. Deploy it to return it to **In sync**. A stack made only of one-shot jobs that already exited `0` with explicit `restart: "no"` (or `deploy.restart_policy.condition: none`) can show **In sync** (or **Drifted** for other findings such as unused networks) with no containers currently running.
|
|
</Accordion>
|
|
<Accordion title="The image finding flags a stack I just updated">
|
|
Click **re-check** after the deploy finishes. During a rolling update, replicas can briefly run different images, and the report captures that moment. Once every container is on the declared image, the finding clears.
|
|
</Accordion>
|
|
<Accordion title="A stack that uses a published port range shows a ports finding">
|
|
A Compose port range such as `8000-8002:8000-8002` is compared conservatively and can read as a ports difference even when the deployment is correct. Sencho errs toward surfacing a possible difference rather than hiding one.
|
|
</Accordion>
|
|
<Accordion title="The status says 'Unreachable'">
|
|
Sencho could not reach Docker on the active node, so it cannot compare the runtime. Confirm the Docker engine is running and the node is online, then use **re-check**. Other stacks on the same node will show the same state until Docker responds. While Docker is unreachable, Sencho does not update the drift history, so open findings are never cleared just because the check could not run.
|
|
</Accordion>
|
|
<Accordion title="The tab says 'No deploy baseline'">
|
|
Sencho records a baseline the first time you deploy a stack through it. A stack that was imported or has not yet been deployed from Sencho has nothing to compare against. Deploy it once from Sencho and the signal changes to **Matches last deploy**.
|
|
</Accordion>
|
|
<Accordion title="The Activity tab shows a drift event but the Drift tab now shows In sync">
|
|
The Activity event was written when drift was detected or resolved during a previous reconciliation. The Drift tab always shows the current live state, which may already be back in sync. If the history and badge disagree, click **re-check** to reconcile the ledger with the current runtime.
|
|
</Accordion>
|
|
<Accordion title="Opening the tab does not update the history">
|
|
Opening the tab runs the spatial engine (read-only) and updates the status badge, but does not write to the ledger. Only **re-check** and post-deploy reconciliation persist findings and update the history. Click re-check explicitly when you want the history to reflect the current state.
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
## Related
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Stack Activity" icon="clock-rotate-left" href="/features/stack-activity">
|
|
Drift detected and resolved events appear in the Activity timeline alongside deploys and restarts.
|
|
</Card>
|
|
<Card title="Stack Dossier" icon="book-open" href="/features/stack-dossier">
|
|
The Dossier tab stores documentation and access URLs; its documentation drift feature checks whether URLs still match the stack's published ports.
|
|
</Card>
|
|
<Card title="Atomic Deployments" icon="rocket" href="/features/atomic-deployments">
|
|
Understanding how Sencho deploys stacks explains when and how drift baselines are recorded.
|
|
</Card>
|
|
<Card title="Blueprint Model" icon="drafting-compass" href="/features/blueprint-model">
|
|
Blueprints have a separate policy-based drift mode (observe, suggest, enforce) distinct from the runtime drift detection described on this page.
|
|
</Card>
|
|
<Card title="Compose Networking" icon="diagram-project" href="/features/compose-networking">
|
|
The Networking tab's runtime drift section uses the same network comparison as the findings on this page, without the persisted history.
|
|
</Card>
|
|
</CardGroup>
|