Skip to content

Manifests and versioning

A release changes an image tag, and optionally env and resources. When you need anything else, such as a probe, a volume, a sidecar, an annotation or an ingress host, edit the manifest. Every change Seylo makes, whichever path it takes, is recorded as a version in the same history.

What you need: releaser for the namespace.

  1. Open the editor.

    On the namespace page (click a version on Operate → Overview), find the component under Per-component tools and press Edit manifests. The page is titled Edit manifests: checkout-api in shop.

  2. Edit the YAML.

    There is one tab each for deployment, service and ingress. Each tab holds the version Seylo last recorded. If Seylo has never written that resource, for example a Deployment created by someone else before you connected the cluster, the tab is read from the live object, so any component can be edited.

    A dot on a tab means it has unsaved changes. Only the tabs you change are submitted.

  3. Press Validate.

    For each changed resource, Seylo checks that:

    • the YAML parses to a single Kubernetes object,
    • its kind matches the tab,
    • metadata.name is the component’s name, and
    • metadata.namespace, if set, is the namespace you are editing in.

    It then runs a server-side dry run against the cluster. On an agent-managed cluster the agent performs the dry run inside your cluster. If the dry run could not be performed, the result says (client-side only). The Validation pane also shows a line diff against the version Seylo has stored.

  4. Press Submit for approval.

    Add a note saying what you changed and why. The approver is shown the complete proposed YAML for each kind you touched, not a diff, so the note is how they find the change quickly.

Once approved (or straight away, if your organisation has approvals turned off):

  • Seylo records one version covering every resource you changed. It is labelled like manifest-edit(shop): checkout-api [deployment] and includes who requested and approved it.
  • Each changed resource is applied with server-side apply. If one resource fails, the others are still applied, the failure is reported against that resource, and the recorded version stays as the record of what was requested.
  • For a Deployment, Seylo reads it back and checks that Kubernetes created a new revision (metadata.generation advanced). This proves something rolled out, not that every field you typed is present. Seylo does not compare free-form YAML field by field.
  • For a Service or an Ingress, the API server accepting the write is the check. There is no read-back comparison.

A Deployment change rolls out new pods, and Seylo follows that rollout the same way as a release. See watch the rollout.

Seylo checks who owns each of the Deployment, Service and Ingress before writing it. If Argo CD, Flux, Helm or another controller owns one, the edit is refused and nothing is applied. The editor shows This manifest edit was REFUSED: another controller owns the target, naming the owner and the evidence for each resource.

The durable fix is to change the resource where that controller reads it. A change made here would be reverted at the next sync, or overwritten at the next helm upgrade. To apply it through Seylo anyway, tick the box under the refusal that starts “I understand this change will be reverted by the controller above…” (“…overwritten by that owner” for Helm) and press Submit for approval again. Your acknowledgement and your name are stored on the request, shown to the approver, and written to the audit log.

New namespace, a button on Overview, generates a Deployment, Service and Ingress from a form. Press Render preview to see the YAML exactly as it would be recorded. If the form cannot express what you need, such as a sidecar, a volume or a toleration, press Edit these manifests:

  • A banner says You are editing these manifests directly. The form stops regenerating the YAML, and what you type is applied exactly as written, after the same checks and approval as a generated manifest.
  • Each document is checked for the right kind in the right tab, the component’s name, and the target namespace. A tab with a problem is marked ! and lists the problem.
  • Discard edits and regenerate goes back to the generated YAML.

The approver of an Add component request sees the difference. If the YAML was edited by hand, the request opens with a warning that the form fields describe what the form generated, not what will be applied, followed by a diff against the generated version. If the editor was opened but nothing changed, the request says the documents are byte-identical to the generated ones.

Releases, manifest edits, environment and ConfigMap edits, resource patches, new components and namespace copies each record a version. Versions are kept in Seylo’s own database, not in a git working tree. Git is an export format for them; see exporting to git.

  • Per resource. Each resource, identified by cluster, namespace, kind and name, has its own chain of versions. One action that changes several resources records them together under one version id.
  • No-op writes add nothing. A release that sets the tag a component already runs does not add a version.
  • Append-only. Nothing in the portal edits or deletes a version. A rollback is a new version, never a rewind. See rollback.
  • Version ids. The short id shown in the portal is the start of a 40-character Seylo version id. It is not a commit in any git repository of yours.

There are two views:

  • The manifest editor’s History card lists every version that touched any of the component’s three resources. View deployment @ this (or service, or ingress, depending on the open tab) shows that resource as it was, with a diff against the version before it.
  • The namespace page’s History button lists the versions of the component’s Deployment, newest first. Each has Rollback to this version, which re-applies that version’s image tag, env and CPU and memory as a new release. Env is restored exactly, so a variable added since is removed, and the confirmation lists those by name before anything is submitted. An ordinary release still merges env. See rollback.

Each version stores the SHA-256 of its own content and the SHA-256 and id of the version before it of the same resource. Walking a chain therefore detects three things: content changed after it was written, a version deleted from the middle or the start, and links rewritten to hide a deletion.

The portal does not show the result of a chain check. That is not available as a self-service feature.

Seylo’s version store can be replayed into a git repository, one commit per recorded version with its original message, author and timestamp. The replay is deterministic, so the same history always produces the same commits. There is no export or push control in the portal.

“Drift” here means the live cluster no longer matches what Seylo wrote. Seylo detects it in two places:

  1. After every write. The read-back described above. A change that was accepted and then rewritten ends as drifted (Reverted (drift) in Activity), with a message naming the likely cause: a GitOps controller, a Helm release, or a mutating admission webhook.
  2. On demand, for ConfigMaps. On Configure → Environment, each ConfigMap has Check drift, which compares the live data with the version Seylo recorded. It shows in sync with repo, DRIFTED with counts of keys that differ, are missing and are extra, or drift unknown when the live ConfigMap could not be read or Seylo has no recorded version to compare.

Seylo does not run a background comparison of live Deployments, Services or Ingresses against their stored versions. The dashboard shows the image each component is running right now. To see how two environments differ, see environments and drift.

You see What it means What to do
YAML parse error: … The YAML does not parse The message gives the line
Manifest must be a single Kubernetes object. The tab holds a list, or several documents One object per tab
Expected kind Deployment, got Service. A document is in the wrong tab Move it to the tab for its kind
metadata.name must equal the component "checkout-api" (got "…"). The object is named differently from the component Use the component’s name. Seylo tracks the object by that name
metadata.namespace must be "shop" (got "…"). The YAML would land in another namespace Remove metadata.namespace or correct it
(client-side only) after a result The server-side dry run could not be performed The structural checks passed, but the API server has not seen the YAML
No changes to submit. Nothing differs from what was loaded Edit a tab first
This manifest edit was REFUSED: another controller owns the target A controller owns one of the resources. Nothing was applied Change it at that controller’s source, or tick the acknowledgement and press Submit for approval again
Refusing to change Deployment shop/checkout-api: … A controller owns the resource As above
… metadata.generation did not change (still …), so the API server treated the applied YAML as identical to what is already running - nothing rolled out. The edit did not change the Deployment’s spec, for example only its labels. It is reported as a failed verification Check the edit was to the field you meant
No manifest history recorded yet Seylo has not written this component yet The first release or edit through Seylo creates the first version
  • Rollback: three ways to go back to an earlier version through approval
  • Approvals: what the approver is shown for each kind