mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-10-26 05:30:18 +00:00
Anso
26f77cac96
* docs(gitops): complete the overview's source states, placement limits, and control locations List every source state the app can show, with the order in which the most serious one wins. Add the pin-driven and unreadable-evidence cases to what the placement policy hands back to an operator, and name the controls where each policy is set. * docs(git-sources): document the polling controls, Manual behavior, and pending-update indicators State the per-node polling interval and its range, that a Manual source is never polled or retried but still stages a plan when a webhook delivers a commit, and where the pending-update icon and button lead. Add common setups and what Git sources do not do, and correct the create form's alt text. * docs(git-authentication): cover the Git error cases and current Bitbucket credentials Add the failures a Git source can report that were missing from troubleshooting (embedded credentials, SSH without a deploy key, blocked hosts, rate limits, certificate expiry and hostname mismatch, network errors), state that the token is only given to the repository's host, and replace the deprecated Bitbucket app password guidance. * docs(git-webhooks): state the GitHub content type, remote-node failures, and limits A form-encoded GitHub delivery fails verification and answers 404, so say to set the content type to JSON. Add the 500 a delivery gets when the owning node is unreachable, correct how the hub forwards to a remote node, and list what provider hooks do not cover. * docs(git-secrets): document linking an encrypted repository and where encrypted values work A repository that is already encrypted cannot be linked, because the identity belongs to a linked source. Encrypted values belong in env files and file-backed secrets, not in image references or published ports, which Sencho resolves before decrypting. * docs(blueprints): correct permissions, remote deploys, and roadmap wording Describe the permissions Blueprint actions need instead of an admin-only rule, say that a remote node runs the deploy itself with its own policy and scanner state, and list all three drift notifications. Remove the repeated marker, policy gate, and snapshot explanations, the raw apply request format, and statements about future features. * docs(git-managed-blueprints): add who can take each step and the limits List the permission each authority step and rollout control needs, say that webhooks do not fetch a Blueprint's source so Pull source and polling bring in new commits, and gather the constraints that were scattered through the page. * docs(gitops-portfolio): name the row menu actions and state what the portfolio does not do List the exact row menu items for Direct and Blueprint applications, and add the limits: hub only, navigation from row menus, and how unreachable nodes appear. * docs(gitops-drift): describe the drift row as it appears and add a screenshot The row shows the class, the deriving component, evidence age, reason, and expected against observed; the resolving action lives on the application's status. Name the retry-interval setting, drop rollout states Sencho never reports, and replace a hedge about which classes are reported. * docs(git-transport): refresh the live attestations against the 0.98.0 release Re-run all 21 live attestations (hosted public repositories, the direct proxy and Pilot node paths, and disposable Gitea and Forgejo instances over HTTPS with a private CA and over SSH with a deploy key) against the 0.98.0 image, record the new date, commit, and image digest, and regenerate the matrix page. Describe unlisted hosts without claiming more than was tested, and add the procedure the attestation record refers to.
171 lines
14 KiB
Plaintext
171 lines
14 KiB
Plaintext
---
|
|
title: GitOps overview
|
|
sidebarTitle: Overview
|
|
description: How Sencho runs stacks and fleet templates from Git. Direct sources versus Blueprints, the chain from commit to container, who decides each step, and the words every GitOps page uses.
|
|
---
|
|
|
|
GitOps in Sencho means a Git repository is the source of truth for a stack's Compose files, and Sencho moves what is running toward it without skipping a decision. Every step between a commit and a container is recorded separately: the commit Sencho accepted, the images it resolved, the nodes it approved, the rollout it authorized, and what the node reports back.
|
|
|
|
This page defines the model once. The other GitOps pages link here instead of explaining it again.
|
|
|
|
<Note>
|
|
GitOps is available on every tier, including Community.
|
|
</Note>
|
|
|
|
## Two ways to manage from Git
|
|
|
|
| | Direct Git source | Git-managed Blueprint |
|
|
|---|---|---|
|
|
| **What it is** | A Git source linked to one stack on one node | A fleet template whose Compose content comes from one Git source, placed on the nodes a selector chooses |
|
|
| **Where you work** | The **Git Source** sheet in the stack editor | **Fleet · Blueprints**, and the application's page in **GitOps** |
|
|
| **What a commit does** | The source policy decides how far Sencho goes on its own: nothing, stage a plan, write files, or write and deploy | A new candidate generation. Accepting it, approving its placement, and authorizing its rollout are three separate steps |
|
|
| **Reach** | One node | Every node the approved placement names, deployed one after another |
|
|
| **Guide** | [Git sources](/features/git-sources) | [Git-managed Blueprints](/features/git-managed-blueprints) |
|
|
|
|
Choose a **Direct** source when one stack on one node should follow a repository. Choose a **Git-managed Blueprint** when the same project should run on several nodes, or when you want an explicit approval and rollout record for each change. Both kinds of application appear together in the [GitOps portfolio](/features/gitops-portfolio).
|
|
|
|
An **Inline** Blueprint is edited in Sencho and has no Git source; see [Blueprints](/features/blueprint-model). **Convert to Git** on a Blueprint moves a live Direct source onto it, and **Adopt onto Blueprint** on the Git Source sheet does the same from the stack side. **Detach Git** and **Retire to Direct** reverse the move.
|
|
|
|
## The chain from commit to container
|
|
|
|
Every application is described by up to five stages, in this order.
|
|
|
|
| Stage | The question it answers |
|
|
|---|---|
|
|
| **Source** | Which commit did Sencho fetch and accept as the generation to run? |
|
|
| **Artifact** | Which container images would that generation run, as proven digests? |
|
|
| **Placement** | Which nodes is the generation approved for? |
|
|
| **Rollout** | Has the authorized deploy reached those nodes, and how did each one answer? |
|
|
| **Runtime** | What is running now, and does it match what was approved? |
|
|
|
|
A stage that does not apply to an application is left out. A Direct source has no separate placement or rollout, and an Inline Blueprint has no Git source or artifact set.
|
|
|
|
## Who decides each step
|
|
|
|
A Git-managed Blueprint takes three authority steps. Each is its own action, and one never implies another.
|
|
|
|
| Step | What it records | Policy that can take it for you |
|
|
|---|---|---|
|
|
| **Accept source** | The fetched candidate is the content to run | **Source policy** |
|
|
| **Review and approve placement** | The exact nodes to place or remove, frozen for the current intent | **Placement policy** |
|
|
| **Authorize rollout** | The accepted generation, its artifact set, and the placement, opened as an immutable rollout generation | **Rollout authorization policy** |
|
|
|
|
Two more policies decide what happens after a rollout starts or after something drifts. Every policy is independent of the others.
|
|
|
|
| Policy | Options | Where it lives |
|
|
|---|---|---|
|
|
| **Source policy** | Manual, Review only, Auto-write files, Auto-deploy | **Apply behavior** on the Git source's **Automation** tab |
|
|
| **Placement policy** | Operator approves each change, One stateless change at a time | The **Placement policy** button beside **Review and approve placement** |
|
|
| **Rollout authorization policy** | Operator authorizes each rollout, Authorizes without an operator | The **Rollout authorization policy** button beside the placement policy on an Inline Blueprint, and an item in the rollout overflow menu on a Git-managed Blueprint |
|
|
| **Drift mode** | Observe, Suggest, Enforce | The Blueprint editor. See [Blueprints](/features/blueprint-model#drift-policy) |
|
|
| **Health rollout policy** | Observe, Pause, Retry once, Stop, Roll back | **Health rollout policy** in the rollout overflow menu. See [Health rollout policy](/features/health-rollout-policy) |
|
|
|
|
A new application, and any Blueprint you convert or adopt, starts on operator review at every step. Nothing about it has yet proved that a node can take a generation. Each setting sits beside the action it governs, so turning one on is a single click.
|
|
|
|
Every rollout freezes the policy values it executes, and every placement approval carries the values that decided it. Editing a policy changes what the next decision may do and nothing else: no standing approval is withdrawn and no generation is invalidated. The one exception is switching the placement or rollout authorization policy on again: an approval that policy made earlier is withdrawn, so the change it decided waits for you again.
|
|
|
|
### How the policy names map
|
|
|
|
**Evidence** labels its three policy lines **Source policy**, **Placement policy**, and **Rollout policy** (the rollout authorization policy). The source policy line uses different words from the Git source form, and the policy controls show short forms of the other two. The names map one to one, except that Auto-write files and Auto-deploy share a value.
|
|
|
|
| Apply behavior on the Git source | Source policy as written in Evidence |
|
|
|---|---|
|
|
| **Manual** | Operator applies each revision |
|
|
| **Review only** | Operator reviews each revision |
|
|
| **Auto-write files**, **Auto-deploy** | Applies without an operator |
|
|
|
|
| Policy control, short form | Full name |
|
|
|---|---|
|
|
| **Operator** | Operator approves each change |
|
|
| **Bounded auto** | One stateless change at a time |
|
|
| **Manual** | Operator authorizes each rollout |
|
|
| **Automatic** | Authorizes without an operator |
|
|
|
|
Auto-write files stops after writing the files; Auto-deploy also redeploys the stack. On a Git-managed Blueprint both mean the source is accepted without an operator, and the rollout authorization policy decides whether a rollout starts. A withdrawn stateful target always waits for you, whatever the source policy says.
|
|
|
|
### What One stateless change at a time may do
|
|
|
|
This is the whole of what the placement policy approves without you, and it is deliberately narrow. Sencho approves a placement change on its own only when it adds exactly one node or removes exactly one, and the workload is stateless. Everything else falls back to you with the reason on the placement card:
|
|
|
|
- A change that adds and removes nodes, or moves more than one node either way.
|
|
- A workload that carries data, or whose contents Sencho could not establish. Sencho reads this from the Compose content that would be placed, not from the Blueprint's stored classification.
|
|
- A first placement that spans more than one node.
|
|
- A placement that moved because a pin moved. Where a workload runs by pin is your choice.
|
|
- A node that is cordoned, not answering, or last seen unreachable.
|
|
- A node that has not reported, or that this Sencho does not know.
|
|
- A change that would leave the application with nothing running it.
|
|
- An operation already in flight for the application or for a node in the plan.
|
|
- Evidence Sencho needed and could not read, or read and could not use.
|
|
|
|
A withdrawal is judged from what the node itself reported: it must be answering now and must have reported the workload that ran there. A node that has never reported keeps running where it is, and the withdrawal falls back to you. A cordoned node is never withdrawn automatically, because cordoning says where work may not go, not that work should leave. The workload keeps running there; uncordon the node or approve the move yourself.
|
|
|
|
The policy records its reason at the moment it runs and decides again only when something changes. A reason recorded because an operation was in flight is still what is recorded after that operation finishes, which is why Evidence also shows when the reason was recorded.
|
|
|
|
## Source states
|
|
|
|
A commit SHA says which files Sencho wrote. It does not say whether that commit was accepted, whether something newer is waiting, or whether an operation stopped halfway. The **source state** answers those in one short phrase that means the same thing on the Git Source sheet, the Drift tab, the stack list, and the dashboard's stack rows.
|
|
|
|
| State | What it means |
|
|
| --- | --- |
|
|
| **Never reconciled** | No commit from this repository has been accepted yet. |
|
|
| **Fetching** | Sencho is reading from the repository right now. |
|
|
| **Accepted** | The fetched commit has been accepted as the current generation. |
|
|
| **Pending update** | A fetched commit is ready to apply. |
|
|
| **Review required** | A fetched commit is waiting for review before it can apply. |
|
|
| **Pending update blocked** | The change plan has local conflicts. Apply stays disabled until they are resolved. |
|
|
| **Reconcile required** | What was reconciled no longer matches the configuration in force. Fetch again to rebuild the candidate. |
|
|
| **Applying** | A commit is being written to the stack directory. |
|
|
| **Poll scheduled** | The source is healthy and waiting for its next scheduled poll. |
|
|
| **Retry scheduled** | The last attempt failed and another is queued. |
|
|
| **Suspended** | Reconciliation is paused until you resume. Polling, webhooks, automatic apply, and Pull now stay off for this source. |
|
|
| **Source failed** | The last operation on this source failed. |
|
|
| **Outcome unknown** | An operation was interrupted, so Sencho cannot confirm how it ended. |
|
|
| **Recovering** | A recovery is running on this stack. |
|
|
| **Recovery failed** | Recovery of this stack did not complete. |
|
|
| **Not live** | The source was detached or its application deleted. The identity shown is what it was. |
|
|
|
|
When several conditions hold at once, the state names the most serious one: a recovery, an operation in progress, an interrupted operation, or a suspension comes before a failure, a failure comes before a pending update, and a scheduled poll shows only when nothing stronger applies. A failure is never hidden behind a scheduled poll.
|
|
|
|
**Outcome unknown** and **Recovery failed** matter most. Sencho reports an interrupted operation as unknown rather than guessing, so a stack whose pull was cut short by a restart says so instead of reading as up to date.
|
|
|
|
Some state comes with qualifications: a managed manifest that does not identify this stack on this node, an approval that could not be restored after a recovery, a record that has gone. Each is its own line at the top of the status. They are not failures. They tell you which part of the state to trust less, because a stack with partly missing evidence would otherwise look identical to one with complete evidence.
|
|
|
|
## Reading a status: answer, path, evidence
|
|
|
|
Wherever Sencho shows an application, the Git Source sheet, a Blueprint sheet, and the portfolio's application sheet, it uses the same three-part block.
|
|
|
|
- **Answer.** One toned state and the reason that needs an operator first, with a count of any others. It says when the evidence behind it is partial.
|
|
- **Path.** A single row naming each stage that applies, with its state. A stage that is blocking says why on its own line.
|
|
- **Evidence.** Opens what backs the answer: the steps with a recorded grant (**Source accepted**, **Placement approved**, **Rollout authorized**), the settled stages, each decision's policy line, and everything Sencho could not prove.
|
|
|
|
<Frame caption="A Git source waiting for review. The answer is Review required with its action, the path row names each stage, and Evidence is open to show the recorded authority, the stages, the source policy line, and what could not be proven.">
|
|
<img src="/images/gitops-overview/answer-path-evidence.png" alt="Git source sheet Overview with a Review required answer and a Review update button, a path row of Source review required, Artifact qualified, and Runtime applied not deployed, and an expanded Evidence section listing recorded authority, stages, the source policy line Operator reviews each revision, and one target" />
|
|
</Frame>
|
|
|
|
A policy line says who is configured to decide that stage and what the policy actually did. A recorded decline also says when it was recorded, so a reason kept from an earlier moment reads as a fact about that moment. While a rollout is in flight it also names the value it was decided under.
|
|
|
|
## Executable identity
|
|
|
|
**Source state** says whether a commit was accepted. **Executable identity** says whether Sencho can prove which container images that generation runs, without rewriting your Compose files.
|
|
|
|
When a generation is accepted, Sencho resolves each service image against the target node's platform. Registry tags become digest evidence, and a multi-platform image records the child digest for that node. Services with a local `build:` stay unverified across nodes, because Sencho does not claim a portable digest for them.
|
|
|
|
After a deploy, Sencho inspects what is running and compares it to the frozen expected set. If a registry tag moved after acceptance, it records stale artifact evidence and leaves the expected set alone. If a running digest disagrees with the expected fingerprint, runtime state reports artifact drift while the source can still read as accepted. [GitOps drift](/features/gitops-drift-model) covers the comparison.
|
|
|
|
## Where to go next
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Git sources" icon="git-branch" href="/features/git-sources">
|
|
Link a stack to a repository, set an apply behavior, and review the change plan.
|
|
</Card>
|
|
<Card title="Git-managed Blueprints" icon="layers" href="/features/git-managed-blueprints">
|
|
Convert, accept, approve, authorize, pause, and roll back across the fleet.
|
|
</Card>
|
|
<Card title="GitOps portfolio" icon="chart-pie" href="/features/gitops-portfolio">
|
|
Every application in one place, with one attention queue.
|
|
</Card>
|
|
<Card title="GitOps drift" icon="magnifying-glass" href="/features/gitops-drift-model">
|
|
The seven drift classes and what each one proves.
|
|
</Card>
|
|
</CardGroup>
|