Skip to content
Olivares AI docs

Module VII — deployment & integration

Deployment definitions, plans, applies, rollbacks, retirements, the executor setup and the wiring ledger are Business features. Community answers these API routes with 501 and hides the command group. Stored definitions, revisions, wirings and operations remain in the database and in disaster-recovery backups. The sections below describe the Business behavior.

Module VII is the only module that mutates customer infrastructure — every other part of the product is read-first. It provisions, updates and retires agents and MCP servers as declarative, versioned, reversible operations, and declares the connectivity and referenced identity an agent uses to reach an enterprise resource. Because it acts, its security bar is the highest in the product, and live actuation is held behind a deny-closed seam until an operator explicitly provisions it.

Plan and govern, then (maybe) apply

Section titled “Plan and govern, then (maybe) apply”

The lifecycle is plan → apply → verify → retire, reconciling a desired state against the real one. The split that matters is declare ≠ mutate:

  • Declaring desired state — create, update, rollback a definition (also via the manage-as-code olivares_deployment resource) — is control-plane only and never touches infrastructure.
  • plan is a pure dry-run diff; verify checks drift and refreshes the snapshot. Neither mutates.
  • apply and retire are the only mutating operations. They are two-phase and deny-by-default: phase one computes the diff and requests a human approval bound to the plan hash without changing anything; phase two proceeds only if the approval is approved and the plan hash still matches — any other state (pending, expired, rejected, no gate, stale plan) is refused and recorded. Re-specifying changes the hash and invalidates the approval (anti-TOCTOU).

Mutating apply/retire is not live by default. The actuation seam (Executor) is deny-closed: with no executor provisioned, apply/retire/plan/verify fail closed with a 503 — the control plane can declare desired state but cannot reconcile to real infrastructure. A real engine (Tofu/Terraform, GitOps, Kubernetes, Docker, Nomad, Crossplane) plus a short-lived, per-operation, attested credential source wire in only on operator configuration; absent that, the module never silently acts.

Connect an executor

Section titled “Connect an executor”

Until an administrator connects an executor, Deploy keeps your deployment definitions and changes no infrastructure. To connect one:

  1. Write a JSON file with a block for each runtime you deploy to (docker, k8s, nomad, tofu, terraform, gitops or crossplane) and a credential block. Only the runtimes in the file are connected. For Docker on the same host:

    {
      "docker": { "socket_path": "/var/run/docker.sock" },
      "credential": {
        "kind": "file",
        "path_template": "/run/olivares/deploy/{env}-{mode}.token",
        "ttl_seconds": 900
      }
    }

    For each operation Olivares reads a short-lived token from path_template: {env} is the definition’s environment and {mode} is read (Plan, Verify) or write (Apply, Retire). A tool you already run, such as Vault Agent or a SPIFFE helper, creates that directory and writes and rotates the token files. Without a token, every operation is refused. For Docker, the olivares service user must also be able to open the socket; membership of the docker group gives it root-level access to that host.

  2. Point Olivares at the file. With the deb or rpm package, add this line to /etc/olivares/olivares.env:

    Terminal window
    OLIVARES_DEPLOY_EXECUTOR_CONFIG=/etc/olivares/deploy-executor.json

    The olivares user must be able to read the JSON file, for example with owner root:olivares and mode 0640.

  3. Restart Olivares with sudo systemctl restart olivares. If the file cannot be read or is not valid, Olivares does not start and its log says why.

The Deploy page then offers Declare deployment as its main action, and Plan and Apply reach the runtime. Every Apply and Retire still waits for an approval.

Entities and the declared contract

Section titled “Entities and the declared contract”

The module declares four namespaced entities plus the core Deployment as the applied snapshot:

Entity Role
definition desired state — desired vs applied version, spec hash, link to the core Deployment
revision append-only, immutable spec history — the reversible source for rollback
wiring the permitted connectivity agent → resource it declares (the contract module III contrasts)
operation append-only change-management ledger — version, plan hash, who approved, result

The desired spec is typed and re-serialized from the struct (never an operator JSON round-trip): unknown fields are rejected, an inline-credential guard runs, and a spec carrying credential material in cleartext is refused at declaration. Credentials travel by reference only (<scheme>:<locator>, allow-listed scheme) — a property of the wire, never a stored secret.

What it produces on the bus (the PERMITTED side of module III)

Section titled “What it produces on the bus (the PERMITTED side of module III)”

Module VII never writes the access map; module III is the sole writer of its edges. On a committed apply, for each wiring the module publishes a policy-grant edge.observed event (Source = policy) carrying only references and the mode. Module III reconciles it into the PERMITTED side of its permitted-vs-observed diff — so what this module declares is exactly what module III contrasts against what it observes. Identity is bound per agent through governance: a firm, unique non-human identity yields an attributed edge; a shared or absent identity is reported as approximate — marked, never faked.

Section titled “Related”