mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-10-26 05:30:18 +00:00
Anso
87db3f121e
* feat(drift): let a team dismiss a drift finding on the ledger Drift findings can now be dismissed until they change, for a set number of days, or permanently. The dismissal lives on the finding's own row in the drift ledger on the node that owns the stack, so the ledger's detected to resolved lifecycle retires it: once the finding clears its row is closed, and a recurrence is a new finding with no dismissal. Each live finding is published with a stable id, a fingerprint of its structured facts (kind, service, compose value, running value, never the message), a count, and a per-kind policy. The Git managed-path conflict is not dismissable. Dismissing and restoring need exact deploy authority on the stack, the dismiss route re-reads the stack and refuses a finding that changed or cleared since it was seen, and the drift status and finding count keep counting dismissed findings. Image mismatch findings also carry whether the running image was built after the one compose names, read from the images' build times. Anything that cannot be proven reads as unknown. * feat(drift): resolve and dismiss drift findings from the Drift tab Each drift finding now names its fix and carries the verb that runs it: redeploy to match compose (confirmed first, through the editor's own deploy handler), start a missing service, or open the stack editor or Git source where the change is a decision about compose rather than the runtime. When the running image is provably newer than the one compose names, the editor leads and the redeploy confirm says it moves the service back to an older image. Verbs the account cannot run are dropped instead of left to answer 403. Findings can be dismissed until they change, for 7 days, or permanently, and restored from the dismissed list. The status keeps its verdict and counts the dismissed findings. A report from an older remote node, which cannot record a dismissal, offers no Dismiss. * docs(drift): document resolving and dismissing drift findings Describe the verb each finding kind offers, the redeploy confirm, dismissing and restoring, and who can run what. Rework the drift tutorial around the redeploy button on the finding, with fresh screenshots of the finding, the overflow menu, the confirm, the resolved state, and the Activity timeline. * fix(drift): scope dismissals and late answers to the stack they belong to Dismissing a finding now writes only that finding's own ledger row instead of reconciling the whole stack from a snapshot that may be behind a concurrent check, so it can no longer resolve or insert sibling findings or stamp the check time. The Drift tab ignores a re-check, dismissal, or restore that finishes after the operator moved to another stack or node, and closes an open redeploy confirm on a switch. Open stack editor needs permission to edit the stack, so a deployer is not shown a button that does nothing. The dismissal hook takes either a hub surface or a node endpoint, a restore that finds nothing re-reads the list, a dismissal's mode and expiry are one type, and the drift dismiss route bounds the count like the other dismissal routes. Adds tests for the dismissal lifecycle, the race, the failure paths, and the handler wiring. * docs(drift): say which buttons need permission to edit or deploy
125 lines
10 KiB
Plaintext
125 lines
10 KiB
Plaintext
---
|
|
title: Catch and Fix a Container That's Drifted From Its Compose File
|
|
sidebarTitle: Catch and fix drift
|
|
description: Read a real Drift finding after a manual out-of-band container change, then redeploy from the finding to bring the running state back in line with the compose file.
|
|
---
|
|
|
|
Say an on-call engineer hotfixes a container directly on the host during an incident: change the image tag, run `docker compose up -d`, done, the site's back up. Nobody thinks to also make the same edit through Sencho, so the compose file it deploys from tomorrow never learns about tonight's fix. This walks through catching exactly that: read a real Drift finding after an out-of-band container change, confirm what's different, and redeploy from the finding to bring the running state back in line with the compose file.
|
|
|
|
This tutorial covers the runtime drift detection described on the Drift feature page: the status badge, the findings list, the drift ledger, and resolving a finding with the redeploy button on the finding itself. It does not cover Blueprint's separate policy-based drift mode (observe/suggest/enforce), which reconciles drift on Blueprint-deployed stacks automatically instead of leaving it for you to redeploy; see [Blueprint Model](/features/blueprint-model). It also does not cover network-attachment drift findings, which reuse this same mechanism but compare against the Networking tab instead of an image; see [Compose Networking](/features/compose-networking).
|
|
|
|
## Prerequisites
|
|
|
|
- Any role that can view a stack, including the read-only **viewer** and **auditor** roles, can open the Drift tab and click **re-check**. Actually resolving drift means redeploying, which needs the `stack:deploy` permission for this stack (the same permission Start, Stop, Restart, and Update already require); the redeploy button does not appear without it.
|
|
- The stack must have been deployed through Sencho at least once. Drift's "since last deploy" signal has nothing to compare against until then, and shows **No deploy baseline** instead of a useful state.
|
|
- No plan requirement and nothing to turn on. Drift detection runs automatically as soon as a stack has a compose file and Docker is reachable on the node.
|
|
- Shell or SSH access to the host, if you want to reproduce this tutorial's own out-of-band change yourself. Any real manual Docker operation that changes a running container without going back through Sencho works just as well.
|
|
|
|
This tutorial uses a small single-service stack called `landing-page`:
|
|
|
|
```yaml
|
|
services:
|
|
app:
|
|
image: nginx:1.27-alpine
|
|
restart: always
|
|
ports:
|
|
- "8096:80"
|
|
```
|
|
|
|
Deploy this stack (or adapt an existing one) before continuing.
|
|
|
|
<Steps>
|
|
<Step title="Open the Drift tab and confirm the baseline">
|
|
Click the stack in the sidebar to open it, then switch to the **Drift** tab in the right-hand panel (scroll the tab row if it doesn't fit). Right after a deploy through Sencho, the status reads **in sync** ("Runtime matches the compose file.") and the card below it reads **matches last deploy** ("The compose source is unchanged since the last deploy."). This is the state the rest of this tutorial gets you back to.
|
|
|
|
<Frame>
|
|
<img src="/images/tutorials/resolve-stack-drift/drift-baseline-in-sync.png" alt="The Drift tab showing In sync status (Runtime matches the compose file) and Matches last deploy below it, with no findings or drift history." />
|
|
</Frame>
|
|
</Step>
|
|
|
|
<Step title="Make an out-of-band change on the host">
|
|
Simulate the incident hotfix: on the host, point the compose file at a different image tag, bring it up directly with Compose, then revert the file without redeploying through Sencho.
|
|
|
|
```bash
|
|
cd /path/to/landing-page
|
|
sed -i 's/nginx:1.27-alpine/nginx:1.29-alpine/' compose.yaml
|
|
docker compose up -d
|
|
sed -i 's/nginx:1.29-alpine/nginx:1.27-alpine/' compose.yaml
|
|
```
|
|
|
|
The running container is now on `nginx:1.29-alpine`, but the compose file on disk is back to declaring `nginx:1.27-alpine`, exactly as if someone had made a quick fix and never told Sencho about it.
|
|
</Step>
|
|
|
|
<Step title="Read the drift finding">
|
|
Reopen the Drift tab. Just opening it re-runs the comparison, so the status flips to **drifted · 1 finding** ("Runtime differs from the compose file."), while **matches last deploy** stays exactly as it was: the file itself never changed, only what's running under it. Under **Findings**, the `app` service shows an **image** finding with the expected and actual images side by side, and a line underneath saying what fixes it. Because the running image is newer than the one the Compose file names, the line offers two ways out: update Compose to keep the newer image (**Open stack editor**), or redeploy to go back to the compose image.
|
|
|
|
<Frame>
|
|
<img src="/images/tutorials/resolve-stack-drift/drift-detected-image-finding.png" alt="The Drift tab showing Drifted status with 1 finding, Matches last deploy still green below it, and a Findings section with an app image finding: compose nginx:1.27-alpine to running nginx:1.29-alpine." />
|
|
</Frame>
|
|
|
|
This is the moment the two signals' independence actually matters: a stack can be drifted at runtime while its file is unchanged, or the reverse. Here it's drifted with an unchanged file, because the fix happened directly against Docker, not through a compose edit.
|
|
</Step>
|
|
|
|
<Step title="Log the finding with re-check">
|
|
Click **re-check**. A **Drift history** section appears with the same finding marked **OPEN** and a detected timestamp, and the header now reads "checked just now." The status badge above it, though, still says **drifted**.
|
|
|
|
<Frame>
|
|
<img src="/images/tutorials/resolve-stack-drift/drift-recheck-still-drifted.png" alt="The Drift tab still showing Drifted status after clicking re-check, with a new Drift history section showing an app image finding marked OPEN, detected just now." />
|
|
</Frame>
|
|
|
|
Re-check is a read plus a ledger write: it records the finding into the stack's history and logs a **Drift detected** entry to the Activity tab, but it never touches the running container. Nothing about the actual deployment has changed yet.
|
|
</Step>
|
|
|
|
<Step title="Resolve it: redeploy from the finding">
|
|
This tutorial brings the container back to what the Compose file says, so open the **...** menu on the finding and choose **Redeploy to compose image**. It sits in the menu rather than leading because it moves the service back to an older image; for a finding where the running image is not newer, **Redeploy to match compose** is the button on the row.
|
|
|
|
<Frame>
|
|
<img src="/images/tutorials/resolve-stack-drift/drift-redeploy-menu.png" alt="The Drift tab with the app image finding and its overflow menu open, showing Redeploy to compose image." />
|
|
</Frame>
|
|
|
|
A confirmation names the consequence: "The running app image is newer than the one compose names. Redeploying moves it back to the older compose image." Click **Redeploy**.
|
|
|
|
<Frame>
|
|
<img src="/images/tutorials/resolve-stack-drift/drift-redeploy-confirm.png" alt="The Redeploy landing-page confirmation, explaining that redeploying moves the running app image back to the older compose image, with Cancel and Redeploy buttons." />
|
|
</Frame>
|
|
|
|
Sencho runs the same deploy as the editor's **Deploy** button, with the same progress view, and recreates the `app` container from the compose file, which puts it back on `nginx:1.27-alpine`. If you would rather keep the newer image, click **Open stack editor** instead, change the image in the Compose file to match, and save; the finding clears the same way.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Verify it worked
|
|
|
|
Check from two independent surfaces.
|
|
|
|
Back on the **Drift** tab, the status returns to **in sync**, and the drift history entry that was **OPEN** a moment ago now reads **RESOLVED**, with both a detected and a resolved timestamp:
|
|
|
|
<Frame>
|
|
<img src="/images/tutorials/resolve-stack-drift/drift-resolved-in-sync.png" alt="The Drift tab back to In sync status, with the drift history entry now marked RESOLVED, showing both a detected and a resolved timestamp." />
|
|
</Frame>
|
|
|
|
On the **Activity** tab, which lists most-recent-first, the new **landing-page deployed** entry sits above a **Drift resolved** entry, which sits above the **Drift detected** entry from earlier in this tutorial: the finding was detected, then resolved by the redeploy.
|
|
|
|
<Frame>
|
|
<img src="/images/tutorials/resolve-stack-drift/activity-drift-resolved.png" alt="The Activity tab showing, in order: landing-page deployed by admin, Drift resolved on landing-page: 1 finding cleared, Drift detected on landing-page: 1 new finding, and the earlier landing-page deployed entry." />
|
|
</Frame>
|
|
|
|
## If something goes wrong
|
|
|
|
**Clicking re-check doesn't fix anything, and the status still says drifted.** That's not a bug, it's the read-only design: re-check only reconciles the ledger (recording what it currently sees, as in the screenshot above) so the finding shows up in history and on the Activity timeline. It never changes what Docker is running. If you want the drifted container gone, redeploy it from the finding as in the last step above (or **Save & Deploy** from the compose editor); that's the only action that actually reconciles the runtime with the compose file.
|
|
|
|
**A finding is in the way and you know it is expected.** Click **Dismiss** on the row to set it aside for the team until it changes. It moves under **1 dismissed**, where **Restore** brings it back, and the status keeps reading **drifted** because dismissing a finding does not change what is running.
|
|
|
|
## Related
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Stack Drift" icon="magnifying-glass-chart" href="/features/stack-drift">
|
|
Full mechanics: every finding type, image comparison rules, port ranges, the drift ledger, and troubleshooting.
|
|
</Card>
|
|
<Card title="Stack Activity" icon="clock-rotate-left" href="/features/stack-activity">
|
|
Drift detected and resolved events sit in the same timeline as deploys and restarts.
|
|
</Card>
|
|
<Card title="Blueprint Model" icon="drafting-compass" href="/features/blueprint-model">
|
|
Blueprints manage drift differently, with a separate observe/suggest/enforce policy mode.
|
|
</Card>
|
|
</CardGroup>
|