RFC 0013: Generalized Deployment Plans

Documentation Index

Fetch the complete documentation index at: https://docs.ctrlplane.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Summary

​

Motivation

• Agents implement Plannable and return (Current, Proposed).
• The deploymentplanresult controller persists, validates, and broadcasts diffs.
• GitHub check rendering keys off entity metadata (version.metadata["github/owner"|"github/repo"|"git/sha"]), not a kind field. The dispatch is already data-driven.

Before releasing changes to the deployment it would be nice to see what the Application CR looks like, similar to the dry-run previews.

1. deployment_plan has five NOT NULL version_* columns and nothing else is snapshotted; the deployment is re-read live during fan-out.
2. Stage-1 resolves release targets live via GetReleaseTargets(deployment_id), so the caller cannot scope a plan to specific targets.

​

Proposal

​

A plan is a snapshot

CREATE TABLE deployment_plan (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    workspace_id UUID NOT NULL REFERENCES workspace(id) ON DELETE CASCADE,
    deployment_id UUID NOT NULL REFERENCES deployment(id) ON DELETE CASCADE,
    version_snapshot    JSONB NOT NULL,
    deployment_snapshot JSONB NOT NULL,  -- new
    metadata     JSONB NOT NULL DEFAULT '{}',
    created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    completed_at TIMESTAMPTZ,
    expires_at   TIMESTAMPTZ NOT NULL
);

​

The caller scopes the targets

POST /v1/workspaces/{ws}/deployments/{deploymentId}/plan
{
  "version_snapshot":    { /* version blob (currently deployed or proposed) */ },
  "deployment_snapshot": { /* deployment blob (current or draft) */ },
  "targets": [
    { "environment_id": "...", "resource_id": "..." }
  ],
  "metadata": {
    "trigger/type": "deployment_edit_preview",
    "github/owner": "...", "github/repo": "...", "git/sha": "..."
  }
}

​

Broadcasts stay metadata-driven

• Version-published plan → version metadata carries the CI SHA → check posts on that SHA.
• GitOps-managed deployment edit → deployment metadata carries the PR SHA → check posts on the deployment PR’s SHA.
• Manual UI preview with no GitHub metadata anywhere → no check posted, just UI diff.

​

Stage-1 simplifies

- read pre-inserted deployment_plan_target rows  (no GetReleaseTargets call)
- for each (target × matched agent):
    build DispatchContext from version_snapshot + deployment_snapshot + target
    INSERT deployment_plan_target_result
    enqueue stage-2 work item

​

Migration

• Schema. Add version_snapshot JSONB and deployment_snapshot JSONB columns to deployment_plan. Backfill existing rows from current state: version_snapshot from the five version_* columns (a clean transform); deployment_snapshot by reading the deployment by deployment_id and freezing whatever it looks like at migration time.
• Backfill accuracy. The deployment_snapshot backfill is technically inaccurate for in-flight plans whose deployment has been edited since plan-create. This is acceptable: plans have a bounded expires_at, all pre-migration plans drain quickly, and the new model only needs to be correct going forward.
• Stage-1 controller. Swap GetReleaseTargets for GetPlanTargets. Remove the live GetDeployment read. Variable resolution behavior is undecided — see Open Questions.
• API handler. createDeploymentPlan becomes “resolve targets and snapshots, freeze both in one transaction, then enqueue.” The version-publish caller is unchanged externally; only the handler’s internals shift.
• No agent changes. Plannable and DispatchContext are unchanged.
• No reconciler / promotion lifecycle changes.

​

Open Questions

​

1. How generic should the plan model be? (headline question)

1. The concrete ask (#1075) is deployment-scoped. Solving the actual problem is a two-column schema change plus a stage-1 cleanup. A doesn’t solve anything more here.
2. The mental model “plans are typed by what changed” matches how users describe the problem (“show me the plan for my deployment edit”) and makes the UI naturally self-documenting.
3. Future resource- and environment-level plans, when their triggers materialize, will have their own snapshot shapes that we don’t yet know. Designing them speculatively risks getting the shape wrong; growing into them with concrete requirements is cheaper.

​

2. How should variable resolution work if plans are point-in-time snapshots?

• (a) Resolve at plan-create, snapshot the resolved variables. Fully deterministic; matches the snapshot ethos. Cost: API layer either takes a dependency on variableresolver or makes an RPC to the engine to resolve.
• (b) Resolve at fan-out, against snapshotted entities only. Lighter; most inputs to resolution (deployment, env, resource) are already snapshotted, so the only non-determinism comes from variable sets and secrets changing mid-flight — a small window given expires_at.
• (c) Status quo — resolve live against current state. Simplest but breaks the snapshot invariant; results depend on when stage-1 runs.

​

3. Trigger metadata key

• (a) Convention-only trigger/type key inside plan.metadata. No schema cost; querying by trigger means JSONB extraction.
• (b) Explicit trigger_type TEXT column on deployment_plan with an enum of known triggers. Easy to index, filter, and aggregate in the UI; adds enum-maintenance overhead.

​

Adjacent Considerations

​

Plan deduplication

​

Result retention per trigger