Operation details
GET /v1/admin/control-upgrade-plan
Read native standalone publication and matching execution status
- operationId
getNativeControlUpgradePlanStatus- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：control.upgrades.manage
Description (from the contract)
Available only in explicitly enabled native-standalone mode. Requires a platform session with control.upgrades.manage and rejects every query parameter. This no-store projection does not expose signed bundle bytes, download URLs, tokens, process identifiers, or filesystem paths. Unknown, corrupt, stale, or mismatched execution evidence is unavailable, never an invented not_started or success. Publication revision is zero exactly when publication is null. A running or completed execution is bound to that publication's plan, bundle digest, release sequence and, for a receipt, its versions and native-standalone target.
Responses
getNativeControlUpgradePlanStatus Responses| Status | Description |
|---|
200 | Installation-bound publication, execution, and runtime readiness. Fields：schema: string observed_at: string(date-time) mode: string publication_revision: integer(int64) publication: PublicationReceipt | null execution: NativeExecutionStatus runtime: object |
|---|
400 | Stable error code and request identifier. |
|---|
401 | Stable error code and request identifier. |
|---|
403 | Stable error code and request identifier. |
|---|
503 | Stable error code and request identifier. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/admin/control-upgrade-plan
Publish a verified signed control-plane upgrade bundle
- operationId
publishControlUpgradePlan- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：control.upgrades.manage
Description (from the contract)
Requires a platform session with control.upgrades.manage. If-Match is the current publication revision and Idempotency-Key is bound to the exact signed bundle. The bundle is verified against the local License trust snapshot before the Kubernetes Secret or installation-bound systemd PostgreSQL repository is updated with revision compare-and-swap. Systemd HA uses the same repository as the internal plan source and does not relax its strict-majority quorum. Native-standalone uses a separate root-owned executor, package digest and fail-closed maintenance gate; a new publication requires a trusted ready runner and recent authenticated plan-source read. It may interrupt the single management host and is not an HA upgrade. An exact authenticated native replay remains a read-only operation during drain and after the installed version changes: raw bundle bytes, idempotency key, expected revision, actor and scope must match the durable publication. The original publication receipt and ETag are returned.
Parameters
publishControlUpgradePlan Parameters| Name | In | Type | Required | Description |
|---|
If-Match | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
Responses
publishControlUpgradePlan Responses| Status | Description |
|---|
201 | A new monotonic publication was persisted. Fields：schema: string receipt_id: string plan_id: string(uuid) bundle_sha256: string publication_revision: integer(int64) expected_revision: integer(int64) channel_revision: integer(int64) release_sequence: integer(int64) installation_id: string(uuid) component: string current_version: string current_digest: string target_version: string target_digest: string rollback_version: string rollback_digest: string protocol_version: integer idempotency_sha256: string request_id: string actor_user_id: string(uuid) actor_scope_id: string(uuid) published_at: integer(int64) |
|---|
200 | The exact idempotent publication was replayed without another write. Fields：schema: string receipt_id: string plan_id: string(uuid) bundle_sha256: string publication_revision: integer(int64) expected_revision: integer(int64) channel_revision: integer(int64) release_sequence: integer(int64) installation_id: string(uuid) component: string current_version: string current_digest: string target_version: string target_digest: string rollback_version: string rollback_digest: string protocol_version: integer idempotency_sha256: string request_id: string actor_user_id: string(uuid) actor_scope_id: string(uuid) published_at: integer(int64) |
|---|
400 | Stable error code and request identifier. |
|---|
401 | Stable error code and request identifier. |
|---|
403 | Stable error code and request identifier. |
|---|
409 | Stable error code and request identifier. |
|---|
415 | Stable error code and request identifier. |
|---|
503 | Stable error code and request identifier. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/admin/control-upgrade-plan/issue
Have the License service issue a signed plan and publish it
- operationId
issueNativeControlUpgradePlan- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：control.upgrades.manage
Description (from the contract)
Available only in native-standalone mode. Requires a platform session with control.upgrades.manage, exactly one Idempotency-Key and no query parameter. The control API asks the License service for a parent upgrade grant (the channel target, the pin, or requested_artifact_id from the version picker) and a signed plan artifact bundle, then publishes it as POST /v1/admin/control-upgrade-plan does, at the current publication revision. A target the License service refuses is 409 upgrade_target_blocked with its reason_code (for example same_version when the parent grant is a reinstall, downgrade_not_supported for a rollback). Any other License business refusal (403/409/422 with a code) is passed through as 409 with the License code, for example upgrade_plan_artifact_bundle_unavailable or installation_banned. Only an unreachable License service, a timeout or a License 5xx is 503 control_upgrade_state_unavailable. Without a License client the answer is 503 plan_source_unavailable; a draining master is 503 control_upgrade_draining.
Parameters
issueNativeControlUpgradePlan Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
issueNativeControlUpgradePlan Request body| Name | Type | Required | Description |
|---|
requested_artifact_id | string(uuid) | No | The chosen option's artifact_id (lower case canonical UUID); absent keeps the channel target or the pin. |
|---|
Responses
issueNativeControlUpgradePlan Responses| Status | Description |
|---|
201 | A new monotonic publication was persisted. Fields：schema: string receipt_id: string plan_id: string(uuid) bundle_sha256: string publication_revision: integer(int64) expected_revision: integer(int64) channel_revision: integer(int64) release_sequence: integer(int64) installation_id: string(uuid) component: string current_version: string current_digest: string target_version: string target_digest: string rollback_version: string rollback_digest: string protocol_version: integer idempotency_sha256: string request_id: string actor_user_id: string(uuid) actor_scope_id: string(uuid) published_at: integer(int64) |
|---|
200 | The exact idempotent publication was replayed without another write. Fields：schema: string receipt_id: string plan_id: string(uuid) bundle_sha256: string publication_revision: integer(int64) expected_revision: integer(int64) channel_revision: integer(int64) release_sequence: integer(int64) installation_id: string(uuid) component: string current_version: string current_digest: string target_version: string target_digest: string rollback_version: string rollback_digest: string protocol_version: integer idempotency_sha256: string request_id: string actor_user_id: string(uuid) actor_scope_id: string(uuid) published_at: integer(int64) |
|---|
400 | Stable error code and request identifier. |
|---|
401 | Stable error code and request identifier. |
|---|
403 | Stable error code and request identifier. |
|---|
409 | version_conflict, idempotency_conflict, control_upgrade_plan_conflict, a passed-through License refusal code (ErrorEnvelope), or upgrade_target_blocked with reason_code. |
|---|
415 | Stable error code and request identifier. |
|---|
503 | Stable error code and request identifier. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/admin/control-upgrade-plan/options
List the versions the master may upgrade to (version picker)
- operationId
listNativeControlUpgradeOptions- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：control.upgrades.manage
Description (from the contract)
Available only in native-standalone mode. Requires a platform session with control.upgrades.manage and rejects every query parameter. The License service lists the installation's selectable versions for the running control API version and protocol. Without a License client the answer is 503 plan_source_unavailable; a License service that cannot list versions is 503 upgrade_options_unavailable.
Responses
listNativeControlUpgradeOptions Responses| Status | Description |
|---|
200 | The License service's upgrade options. Fields：schema: string observed_at: string(date-time) options: UpgradeOptions |
|---|
400 | Stable error code and request identifier. |
|---|
401 | Stable error code and request identifier. |
|---|
403 | Stable error code and request identifier. |
|---|
503 | Stable error code and request identifier. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/admin/control-upgrade-plan/run-log
Read the native master upgrade script log and service-log tail
- operationId
getNativeControlUpgradeRunLog- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：control.upgrades.manage
Description (from the contract)
Available only in native-standalone mode. Requires a platform session with control.upgrades.manage and rejects every query parameter. The root-owned runner publishes a bounded log for the current execution: stable event and reason codes (rendered per locale by the console, never server text) and, at terminal points, the last journal lines of the control API, gateway and runner. Journal lines are stripped of control characters and redacted (URL query strings and userinfo, bearer/basic credentials, JWTs, secret-named flags and key/value pairs, private keys) by the runner and again before this response. Download events record only the artifact host. A log of another plan or sequence, or one that is missing or corrupt, is state unavailable with a null run_log.
Responses
getNativeControlUpgradeRunLog Responses| Status | Description |
|---|
200 | The current execution's run log, or unavailable. Fields：schema: string observed_at: string(date-time) state: string: available / unavailable run_log: NativeRunLog | null |
|---|
400 | Stable error code and request identifier. |
|---|
401 | Stable error code and request identifier. |
|---|
403 | Stable error code and request identifier. |
|---|
503 | Stable error code and request identifier. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list