66 lines
3.5 KiB
Markdown
66 lines
3.5 KiB
Markdown
# Server deployment plan v1
|
|
|
|
`deployment.plan.v1` is the capability gate for Run implementations that can
|
|
execute a protected server deployment plan. Platform only sends the plan in a
|
|
leased `RunJobAssignmentResponse.executionInput.deployment`; it never appears
|
|
in public server, job, audit, log, or plugin-bridge responses.
|
|
|
|
SCUM controlled deployments additionally require `deployment.scum.v1`. The
|
|
leased assignment includes `executionInput.serverDeploymentPlan` with
|
|
`schemaVersion: "1"`, an operation of `install` or `adopt`, the frozen template
|
|
key/version, Steam app id, logical executable/config references, explicit field
|
|
mappings, discovery markers, and required verification checks. The plan is
|
|
secret-free and contains logical keys only; the protected deployment body still
|
|
holds the operator's paths/commands and is resolved only by Run.
|
|
|
|
## Capability and policy
|
|
|
|
Run advertises `deployment.plan.v1` along with its normal lifecycle
|
|
capabilities. A Run that supports shell commands additionally advertises its
|
|
local policy for `posix-sh`, `powershell`, or `cmd` out of band with its
|
|
operator configuration. Platform must not infer shell support from command
|
|
text. Empty `shell` means argv-oriented execution.
|
|
|
|
## Required local preflight
|
|
|
|
Before a write, install, or process action, Run validates the selected plan:
|
|
|
|
- absolute server root and working directory are allowed anywhere permitted by
|
|
the local Run policy; they are not required to be adjacent to the Run binary;
|
|
- the effective directory, executable, permissions, timeout, plugin version,
|
|
and requested ports are locally valid;
|
|
- selected shell kind and custom-command policy are enabled;
|
|
- no raw command, path, secret, socket address, or credential is emitted in a
|
|
result, diagnostic, log batch, or artifact name.
|
|
|
|
For an SCUM `install`, Run performs SteamCMD app installation followed by
|
|
configuration materialization and health checks. For `adopt`, Run performs a
|
|
scan first and must not reinstall or overwrite existing configuration. A
|
|
controlled SCUM install or adoption requires an explicit protected server root;
|
|
the root is never exposed in browser projections. Adoption does not require
|
|
new-install create inputs because its mapping phase is read-only unless a
|
|
separate approved write is dispatched. A
|
|
terminal SCUM result must include bounded `serverDeploymentEvidence` with
|
|
preflight, discovery, mapping, and verification states. Required mapping
|
|
results are `applied` or `unchanged`; required verification results are
|
|
`passed` (adoption may report mapping as `skipped`). Failed results include a stable `failureCode` and never include the
|
|
resolved path or command text. Successful result kinds are
|
|
`scum.install.completed` and `scum.adopt.completed`; failed result kinds are
|
|
`scum.install.failed` and `scum.adopt.failed`.
|
|
|
|
An `existing-server` plan may omit installation. A `custom-command` plan
|
|
requires a start command. Guided templates remain plugin recommendations;
|
|
Run owns their local resolution and execution.
|
|
|
|
## Safe progress reports
|
|
|
|
Run reports bounded progress with `percent`, `phase`, and a safe message. The
|
|
allowed phase vocabulary is `queued`, `claimed`, `preflight`, `scan`, `install`,
|
|
`configure`, `mapping`, `start`, and `health`. On failure it reports a stable safe error
|
|
code and summary such as `working-directory-unavailable`, never the supplied
|
|
path or command text.
|
|
|
|
Platform treats preflight as authoritative. It does not open a direct shell,
|
|
SSH connection, raw socket, or host filesystem to compensate for a failed
|
|
preflight.
|