Skip to content

Guided tour

FabrCore 2.0 · Release and package availability

These guides track the current 2.0 source. Stable 2.0.0 publication is pending; package commands show the release target. Until it is published, follow the source quick start or use a matching available prerelease set. Release migration · Runtime modes

MODULE 07 · LESSON 7.2

Preview, deploy, and update deliberately

Preview changes and deploy against the version you reviewed.

Lesson 40 of 86 · FabrCore 2.0

Overview

Ensure is a baseline provisioning operation; update deliberately changes existing agents. A preview is useful only if deployment applies the same revision/digest and the preview itself has no external effects. Per-agent outcomes matter even when the HTTP request succeeds.

A preview binds your review to a definition

Expansion can produce more agents than the document explicitly lists, particularly when extensions such as squads are installed. Preview exposes that expansion before effects occur. Record the stored revision and expansion digest so a later apply can detect whether another operator changed what you reviewed.

Ensure and update express different intent

Ensure creates missing instances. Update intentionally changes existing ones. Neither mode implies deleting agents omitted from the new document. A deployment can succeed for some targets and fail for others, so a single HTTP success is not a fleet result. Per-agent receipts identify the portion that needs investigation or an explicit partial retry.

Preview and deploy a reviewed revision

  1. Read the current revision, preview the canonical blueprint and inspect expansions and targets.
  2. Choose ensure or update and submit the revision/digest you reviewed. Handle a stale revision by reloading and reviewing, not by silently overwriting.
  3. Inspect operation and per-agent results, then check health/configuration of the intended instances. Reactivate/reconfigure where the setting requires it.
Deploy the reviewed expansion and read its receipt 
PUT /fabrcoreapi/admin/v1/principals/dev/operations/ops-deploy-001
Authorization: Bearer <administration-credential>
Content-Type: application/json

{
  "kind": "deploy",
  "blueprintName": "ops-desk",
  "deployment": {
    "operationId": "ops-deploy-001",
    "mode": "update",
    "revision": "<revision-from-preview>",
    "expansionDigest": "<digest-from-preview>"
  }
}

GET /fabrcoreapi/admin/v1/principals/dev/operations/ops-deploy-001
Authorization: Bearer <administration-credential>

Test a conflict and a partial result

  1. Read and preview a named blueprint. Record its revision/digest, then make another edit before trying to deploy the old preview. Expect a stale-review conflict rather than silent overwrite.
  2. Reload, review the new expansion and submit an update for a disposable principal. Poll its operation receipt and inspect each target's outcome.
  3. If one target fails, correct its dependency and explicitly retry only the reviewed targets needing repair. Read runtime configurations afterward to distinguish stored-definition drift from independent agent edits.

You now have evidence of what was reviewed, what was attempted and what actually applied. A timed-out response still requires receipt reconciliation before a new mutation.

If the result is different

Publishing a blueprint resource is not the same as applying it to every principal or restarting every running agent.

Go deeper

Explore the related documentation.