diff --git a/reference/cli/operations-api-commands.md b/reference/cli/operations-api-commands.md index e893f42e..032d45ae 100644 --- a/reference/cli/operations-api-commands.md +++ b/reference/cli/operations-api-commands.md @@ -34,80 +34,84 @@ The following operations are available through the CLI. Operations that require This is just a brief overview of all operations available as CLI commands. Review the respective operation documentation for more information on available arguments and expected behavior. Keep in mind that all operations options are converted to CLI arguments in the same way (using `snake_case`). ::: -| Operation | Description | Category | Available Since | -| -------------------------------- | ------------------------------------- | ---------------------------------------------------------------------- | --------------- | -| `describe_table` | Describe table structure and metadata | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | -| `describe_all` | Describe all databases and tables | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | -| `describe_database` | Describe database structure | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | -| `create_database` | Create a new database | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | -| `drop_database` | Delete a database | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | -| `create_table` | Create a new table | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | -| `drop_table` | Delete a table | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | -| `create_attribute` | Create a table attribute | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | -| `drop_attribute` | Delete a table attribute | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | -| `search_by_id` | Search records by ID | [Data](../operations-api/operations.md#nosql-operations) | v4.3.0 | -| `search_by_value` | Search records by attribute value | [Data](../operations-api/operations.md#nosql-operations) | v4.3.0 | -| `insert` | Insert new records | [Data](../operations-api/operations.md#nosql-operations) | v4.4.9 | -| `update` | Update existing records | [Data](../operations-api/operations.md#nosql-operations) | v4.4.9 | -| `upsert` | Insert or update records | [Data](../operations-api/operations.md#nosql-operations) | v4.4.9 | -| `delete` | Delete records | [Data](../operations-api/operations.md#nosql-operations) | v4.3.0 | -| `sql` | Execute SQL queries | [Data](../operations-api/operations.md#nosql-operations) | v4.3.0 | -| `csv_file_load` | Load data from CSV file | [Data](../operations-api/operations.md#nosql-operations) | v4.3.0 | -| `csv_url_load` | Load data from CSV URL | [Data](../operations-api/operations.md#nosql-operations) | v4.3.0 | -| `list_users` | List all users | [Security](../operations-api/operations.md#certificate-management) | v4.3.0 | -| `add_user` | Create a new user | [Security](../operations-api/operations.md#certificate-management) | v4.3.0 | -| `alter_user` | Modify user properties | [Security](../operations-api/operations.md#certificate-management) | v4.3.0 | -| `drop_user` | Delete a user | [Security](../operations-api/operations.md#certificate-management) | v4.3.0 | -| `list_roles` | List all roles | [Security](../operations-api/operations.md#certificate-management) | v4.3.0 | -| `drop_role` | Delete a role | [Security](../operations-api/operations.md#certificate-management) | v4.3.0 | -| `create_csr` | Create certificate signing request | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | -| `sign_certificate` | Sign a certificate | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | -| `list_certificates` | List SSL/TLS certificates | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | -| `add_certificate` | Add SSL/TLS certificate | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | -| `remove_certificate` | Remove SSL/TLS certificate | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | -| `add_ssh_key` | Add SSH key | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | -| `get_ssh_key` | Get SSH key | [Security](../operations-api/operations.md#certificate-management) | v4.7.2 | -| `update_ssh_key` | Update SSH key | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | -| `delete_ssh_key` | Delete SSH key | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | -| `list_ssh_keys` | List all SSH keys | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | -| `set_ssh_known_hosts` | Set SSH known hosts | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | -| `get_ssh_known_hosts` | Get SSH known hosts | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | -| `cluster_get_routes` | Get cluster routing information | [Clustering](../operations-api/operations.md#replication--clustering) | v4.3.0 | -| `cluster_network` | Get cluster network status | [Clustering](../operations-api/operations.md#replication--clustering) | v4.3.0 | -| `cluster_status` | Get cluster status | [Clustering](../operations-api/operations.md#replication--clustering) | v4.3.0 | -| `remove_node` | Remove node from cluster | [Clustering](../operations-api/operations.md#replication--clustering) | v4.3.0 | -| `add_component` | Add a component | [Components](../operations-api/operations.md#components) | v4.3.0 | -| `deploy_component` | Deploy a component | [Components](../operations-api/operations.md#components) | v4.3.0 | -| `deploy` (alias) | Alias for `deploy_component` | [Components](../operations-api/operations.md#components) | v4.3.0 | -| `package_component` | Package a component | [Components](../operations-api/operations.md#components) | v4.3.0 | -| `package` (alias) | Alias for `package_component` | [Components](../operations-api/operations.md#components) | v4.3.0 | -| `drop_component` | Remove a component | [Components](../operations-api/operations.md#components) | v4.3.0 | -| `get_components` | List all components | [Components](../operations-api/operations.md#components) | v4.3.0 | -| `get_component_file` | Get component file contents | [Components](../operations-api/operations.md#components) | v4.3.0 | -| `set_component_file` | Set component file contents | [Components](../operations-api/operations.md#components) | v4.3.0 | -| `install_node_modules` | Install Node.js dependencies | [Components](../operations-api/operations.md#components) | v4.3.0 | -| `set_configuration` | Update configuration settings | [Configuration](../operations-api/operations.md#configuration) | v4.3.0 | -| `get_configuration` | Get current configuration | [Configuration](../operations-api/operations.md#configuration) | v4.3.0 | -| `create_authentication_tokens` | Create authentication tokens | [Authentication](../operations-api/operations.md#token-authentication) | v4.3.0 | -| `refresh_operation_token` | Refresh operation token | [Authentication](../operations-api/operations.md#token-authentication) | v4.3.0 | -| `restart_service` | Restart Harper service | [System](../operations-api/operations.md#registration--licensing) | v4.3.0 | -| `restart` | Restart Harper instance | [System](../operations-api/operations.md#registration--licensing) | v4.3.0 | -| `system_information` | Get system information | [System](../operations-api/operations.md#registration--licensing) | v4.3.0 | -| `registration_info` | Get registration information | [Licensing](../operations-api/operations.md#registration--licensing) | v4.3.0 | -| `get_fingerprint` | Get instance fingerprint | [Licensing](../operations-api/operations.md#registration--licensing) | v4.3.0 | -| `set_license` | Set license key | [Licensing](../operations-api/operations.md#registration--licensing) | v4.3.0 | -| `get_usage_licenses` | Get usage and license info | [Licensing](../operations-api/operations.md#registration--licensing) | v4.7.3 | -| `get_job` | Get job status | [Jobs](../operations-api/operations.md#jobs) | v4.3.0 | -| `search_jobs_by_start_date` | Search jobs by start date | [Jobs](../operations-api/operations.md#jobs) | v4.3.0 | -| `read_log` | Read application logs | [Logging](../operations-api/operations.md#logs) | v4.3.0 | -| `read_transaction_log` | Read transaction logs | [Logging](../operations-api/operations.md#logs) | v4.3.0 | -| `read_audit_log` | Read audit logs | [Logging](../operations-api/operations.md#logs) | v4.3.0 | -| `delete_transaction_logs_before` | Delete old transaction logs | [Logging](../operations-api/operations.md#logs) | v4.3.0 | -| `purge_stream` | Purge streaming data | [Maintenance](../operations-api/operations.md#jobs) | v4.3.0 | -| `delete_records_before` | Delete old records | [Maintenance](../operations-api/operations.md#jobs) | v4.3.0 | -| `get_status` | Get custom status information | [Status](../operations-api/operations.md#registration--licensing) | v4.6.0 | -| `set_status` | Set custom status information | [Status](../operations-api/operations.md#registration--licensing) | v4.6.0 | -| `clear_status` | Clear custom status information | [Status](../operations-api/operations.md#registration--licensing) | v4.6.0 | +| Operation | Description | Category | Available Since | +| -------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------- | --------------- | +| `describe_table` | Describe table structure and metadata | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | +| `describe_all` | Describe all databases and tables | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | +| `describe_database` | Describe database structure | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | +| `create_database` | Create a new database | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | +| `drop_database` | Delete a database | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | +| `create_table` | Create a new table | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | +| `drop_table` | Delete a table | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | +| `create_attribute` | Create a table attribute | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | +| `drop_attribute` | Delete a table attribute | [Database](../operations-api/operations.md#databases--tables) | v4.3.0 | +| `search_by_id` | Search records by ID | [Data](../operations-api/operations.md#nosql-operations) | v4.3.0 | +| `search_by_value` | Search records by attribute value | [Data](../operations-api/operations.md#nosql-operations) | v4.3.0 | +| `insert` | Insert new records | [Data](../operations-api/operations.md#nosql-operations) | v4.4.9 | +| `update` | Update existing records | [Data](../operations-api/operations.md#nosql-operations) | v4.4.9 | +| `upsert` | Insert or update records | [Data](../operations-api/operations.md#nosql-operations) | v4.4.9 | +| `delete` | Delete records | [Data](../operations-api/operations.md#nosql-operations) | v4.3.0 | +| `sql` | Execute SQL queries | [Data](../operations-api/operations.md#nosql-operations) | v4.3.0 | +| `csv_file_load` | Load data from CSV file | [Data](../operations-api/operations.md#nosql-operations) | v4.3.0 | +| `csv_url_load` | Load data from CSV URL | [Data](../operations-api/operations.md#nosql-operations) | v4.3.0 | +| `list_users` | List all users | [Security](../operations-api/operations.md#certificate-management) | v4.3.0 | +| `add_user` | Create a new user | [Security](../operations-api/operations.md#certificate-management) | v4.3.0 | +| `alter_user` | Modify user properties | [Security](../operations-api/operations.md#certificate-management) | v4.3.0 | +| `drop_user` | Delete a user | [Security](../operations-api/operations.md#certificate-management) | v4.3.0 | +| `list_roles` | List all roles | [Security](../operations-api/operations.md#certificate-management) | v4.3.0 | +| `drop_role` | Delete a role | [Security](../operations-api/operations.md#certificate-management) | v4.3.0 | +| `create_csr` | Create certificate signing request | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | +| `sign_certificate` | Sign a certificate | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | +| `list_certificates` | List SSL/TLS certificates | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | +| `add_certificate` | Add SSL/TLS certificate | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | +| `remove_certificate` | Remove SSL/TLS certificate | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | +| `add_ssh_key` | Add SSH key | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | +| `get_ssh_key` | Get SSH key | [Security](../operations-api/operations.md#certificate-management) | v4.7.2 | +| `update_ssh_key` | Update SSH key | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | +| `delete_ssh_key` | Delete SSH key | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | +| `list_ssh_keys` | List all SSH keys | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | +| `set_ssh_known_hosts` | Set SSH known hosts | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | +| `get_ssh_known_hosts` | Get SSH known hosts | [Security](../operations-api/operations.md#certificate-management) | v4.4.0 | +| `cluster_get_routes` | Get cluster routing information | [Clustering](../operations-api/operations.md#replication--clustering) | v4.3.0 | +| `cluster_network` | Get cluster network status | [Clustering](../operations-api/operations.md#replication--clustering) | v4.3.0 | +| `cluster_status` | Get cluster status | [Clustering](../operations-api/operations.md#replication--clustering) | v4.3.0 | +| `remove_node` | Remove node from cluster | [Clustering](../operations-api/operations.md#replication--clustering) | v4.3.0 | +| `add_component` | Add a component | [Components](../operations-api/operations.md#components) | v4.3.0 | +| `deploy_component` | Deploy a component | [Components](../operations-api/operations.md#components) | v4.3.0 | +| `deploy` (alias) | Alias for `deploy_component` | [Components](../operations-api/operations.md#components) | v4.3.0 | +| `stage` (alias) | Stage a component without going live | [Components](../operations-api/operations.md#components) | v5.2.0 | +| `activate` (alias) | Activate a previously-staged deploy | [Components](../operations-api/operations.md#components) | v5.2.0 | +| `revert_component` | Roll a component back to its previous version | [Components](../operations-api/operations.md#components) | v5.2.0 | +| `revert` (alias) | Alias for `revert_component` | [Components](../operations-api/operations.md#components) | v5.2.0 | +| `package_component` | Package a component | [Components](../operations-api/operations.md#components) | v4.3.0 | +| `package` (alias) | Alias for `package_component` | [Components](../operations-api/operations.md#components) | v4.3.0 | +| `drop_component` | Remove a component | [Components](../operations-api/operations.md#components) | v4.3.0 | +| `get_components` | List all components | [Components](../operations-api/operations.md#components) | v4.3.0 | +| `get_component_file` | Get component file contents | [Components](../operations-api/operations.md#components) | v4.3.0 | +| `set_component_file` | Set component file contents | [Components](../operations-api/operations.md#components) | v4.3.0 | +| `install_node_modules` | Install Node.js dependencies | [Components](../operations-api/operations.md#components) | v4.3.0 | +| `set_configuration` | Update configuration settings | [Configuration](../operations-api/operations.md#configuration) | v4.3.0 | +| `get_configuration` | Get current configuration | [Configuration](../operations-api/operations.md#configuration) | v4.3.0 | +| `create_authentication_tokens` | Create authentication tokens | [Authentication](../operations-api/operations.md#token-authentication) | v4.3.0 | +| `refresh_operation_token` | Refresh operation token | [Authentication](../operations-api/operations.md#token-authentication) | v4.3.0 | +| `restart_service` | Restart Harper service | [System](../operations-api/operations.md#registration--licensing) | v4.3.0 | +| `restart` | Restart Harper instance | [System](../operations-api/operations.md#registration--licensing) | v4.3.0 | +| `system_information` | Get system information | [System](../operations-api/operations.md#registration--licensing) | v4.3.0 | +| `registration_info` | Get registration information | [Licensing](../operations-api/operations.md#registration--licensing) | v4.3.0 | +| `get_fingerprint` | Get instance fingerprint | [Licensing](../operations-api/operations.md#registration--licensing) | v4.3.0 | +| `set_license` | Set license key | [Licensing](../operations-api/operations.md#registration--licensing) | v4.3.0 | +| `get_usage_licenses` | Get usage and license info | [Licensing](../operations-api/operations.md#registration--licensing) | v4.7.3 | +| `get_job` | Get job status | [Jobs](../operations-api/operations.md#jobs) | v4.3.0 | +| `search_jobs_by_start_date` | Search jobs by start date | [Jobs](../operations-api/operations.md#jobs) | v4.3.0 | +| `read_log` | Read application logs | [Logging](../operations-api/operations.md#logs) | v4.3.0 | +| `read_transaction_log` | Read transaction logs | [Logging](../operations-api/operations.md#logs) | v4.3.0 | +| `read_audit_log` | Read audit logs | [Logging](../operations-api/operations.md#logs) | v4.3.0 | +| `delete_transaction_logs_before` | Delete old transaction logs | [Logging](../operations-api/operations.md#logs) | v4.3.0 | +| `purge_stream` | Purge streaming data | [Maintenance](../operations-api/operations.md#jobs) | v4.3.0 | +| `delete_records_before` | Delete old records | [Maintenance](../operations-api/operations.md#jobs) | v4.3.0 | +| `get_status` | Get custom status information | [Status](../operations-api/operations.md#registration--licensing) | v4.6.0 | +| `set_status` | Set custom status information | [Status](../operations-api/operations.md#registration--licensing) | v4.6.0 | +| `clear_status` | Clear custom status information | [Status](../operations-api/operations.md#registration--licensing) | v4.6.0 | ### Command Aliases @@ -115,6 +119,9 @@ The following aliases are available for convenience: - `deploy` → `deploy_component` - `package` → `package_component` +- `stage` → `deploy_component` with `activate=false` (build + upload the component cluster-wide without going live; prints a `deployment_id`) +- `activate` → `deploy_component` with a `deployment_id` (take a previously staged deployment live; requires `deployment_id`) +- `revert` → `revert_component` For detailed parameter information for each operation, see the [Operations API documentation](../operations-api/operations.md). @@ -212,6 +219,24 @@ harper get_components harper deploy project=my-app package=https://github.com/user/repo ``` +**Stage a component without going live** (builds + uploads across the cluster and prints a `deployment_id`): + +```bash +harper stage project=my-app +``` + +**Activate a previously-staged deployment** (takes it live; requires the `deployment_id` from `stage`): + +```bash +harper activate project=my-app deployment_id=a3f8c2d1... +``` + +**Roll a component back to its previous version**: + +```bash +harper revert project=my-app +``` + :::tip For more information on components and applications, see the [Components Reference](../components/overview.md). ::: diff --git a/reference/operations-api/operations.md b/reference/operations-api/operations.md index e958e881..a428bfaa 100644 --- a/reference/operations-api/operations.md +++ b/reference/operations-api/operations.md @@ -602,12 +602,25 @@ Detailed documentation: [Components Overview](../components/overview.md) Deploys a component. The `package` option accepts any valid NPM reference including GitHub repos (`HarperDB/app#semver:v1.0.0`), tarballs, or NPM packages. The `payload` option accepts a base64-encoded tar string from `package_component`. Supports `"replicated": true` and `"restart": true` or `"restart": "rolling"`. +Across a cluster, `deploy_component` runs in two phases so a deploy is all-or-nothing at go-live: + +1. **Stage** — the incoming version is downloaded/packed, extracted, and `npm install`ed into a hidden staging directory on **every** node, without touching the live component. +2. **Activate** — only after every node reports a successful stage does any node atomically swap the staged copy into the live path and restart. + +If a node can't fetch the package or fails `npm install`, it fails during staging and the live component is left untouched on every node, rather than leaving part of the cluster half-updated. The request and response shape are unchanged; the two phases are internal. + Additional parameters: - `urlPath` — override the HTTP URL path the component is mounted at (e.g. `"/api/v2"`) - `install_allow_scripts` — set to `true` to allow npm pre/post install scripts (disabled by default) +- `activate` — set to `false` to **stage only** and stop before go-live. The build is prepared and verified on every node and the response returns a `deployment_id` in a `staged` state; nothing goes live. Activate it later by calling `deploy_component` again with that `deployment_id` (see below). Useful for pre-staging a release and flipping it live in a separate, fast step. +- `deployment_id` — activate a previously-staged deployment (from an `activate: false` call). No new payload is fetched or installed; the already-staged build is swapped live cluster-wide. `project` is still required. +- `revert_on_failure` — if the activate phase fails on some nodes (leaving the cluster split across versions), automatically swap the nodes that did activate back to their previous version so the cluster reconverges. Off by default. +- `ignore_replication_errors` — treat replication/peer failures as non-fatal (best-effort deploy to a partially-available cluster). This also opts out of the stage barrier. +- `deployment_timeout` — per-deploy budget (ms) for peers to receive the replicated deployment row; defaults to 120000. +- `two_phase` — set to `false` to force the legacy single-phase (in-place) deploy instead of stage-then-activate. -The response includes a `deployment_id` that can be used to query the deployment record: +A normal deploy (stage + activate): ```json { @@ -624,26 +637,64 @@ Response: ```json { "deployment_id": "a3f8c2d1...", - "message": "Component deployed successfully" + "message": "Successfully deployed: my-app" +} +``` + +Stage now, activate later: + +**Stage request** (`activate: false`): + +```json +{ "operation": "deploy_component", "project": "my-app", "package": "my-org/my-app#semver:v1.2.3", "activate": false } +``` + +**Stage response** (nothing is live yet; note the `staged` marker and the `deployment_id`): + +```json +{ "deployment_id": "a3f8c2d1...", "project": "my-app", "staged": true, "message": "Staged component: my-app" } +``` + +**Activation request** (take the staged build live by passing its `deployment_id`): + +```json +{ "operation": "deploy_component", "project": "my-app", "deployment_id": "a3f8c2d1...", "restart": "rolling" } +``` + +### `revert_component` + +Swaps a component's live version back to its **retained previous version** across the cluster, then restarts. Every `deploy_component` activation retains the version it replaced (one previous version is kept per component), so `revert_component` is a fast rollback that does not re-fetch or re-install. The swap is bidirectional — reverting a revert rolls forward again. + +This supports customer-driven rollback: deploy a new version, run your own health checks against it, and revert if you are not happy — even when the cluster otherwise looks healthy. + +```json +{ + "operation": "revert_component", + "project": "my-app", + "restart": "rolling" } ``` +`revert_component` fails with "no previous version is retained" for a component that has only ever been deployed once (nothing to revert to). + ### Deployment Operations -Harper records every `deploy_component` call in the `system.hdb_deployment` table, capturing the full lifecycle of a deployment including phase transitions (prepare → load → replicate → restart → success/failed), per-node outcomes, and a bounded event log of install output. +Harper records every `deploy_component` call in the `system.hdb_deployment` table, capturing the full lifecycle of a deployment including phase transitions (`stage` → `activate` → `restart` → `success`/`failed`, or `prepare` → `replicate` → `restart` on the legacy single-phase path), per-node outcomes, and a bounded event log of install output. + +**Staged-build retention.** Deployments staged with `activate: false` leave their built files on disk until they are activated. Harper keeps only the most recent staged builds per component (default 5, configurable via the `deployment_stagingRetention_maxCount` configuration option); older not-yet-activated staged builds are evicted automatically when a new stage lands. Activating a `deployment_id` that has aged out of this window fails with "no staged build found." The `hdb_deployment` records themselves are retained as an audit trail; large payload tarballs are reclaimed automatically after a successful deploy (see `deployment_payloadRetention_maxSize`). ### `list_deployments` Returns a list of deployment records, newest first. All filter parameters are optional. -| Parameter | Type | Description | -| --------- | ------ | ------------------------------------------------ | -| `project` | string | Filter to a specific component project | -| `status` | string | Filter by status: `pending`, `success`, `failed` | -| `since` | number | Start of time range (Unix timestamp ms) | -| `until` | number | End of time range (Unix timestamp ms) | -| `limit` | number | Maximum number of results (default: 100) | -| `offset` | number | Pagination offset | +| Parameter | Type | Description | +| --------- | ------ | ------------------------------------------------------------------------- | +| `project` | string | Filter to a specific component project | +| `status` | string | Filter by status: `pending`, `staged`, `success`, `failed`, `rolled_back` | +| `since` | number | Start of time range (Unix timestamp ms) | +| `until` | number | End of time range (Unix timestamp ms) | +| `limit` | number | Maximum number of results (default: 100) | +| `offset` | number | Pagination offset | ```json { @@ -669,22 +720,22 @@ Returns a single deployment record by `deployment_id`. When called on an in-prog The deployment record includes: -| Field | Description | -| -------------------- | ----------------------------------------------------------------------- | -| `deployment_id` | Unique identifier (content hash) | -| `project` | Component project name | -| `package_identifier` | Package reference or `payload` for tar uploads | -| `status` | `pending`, `success`, `failed`, or `rolled_back` | -| `phase` | Current lifecycle phase: `prepare`, `load`, `replicate`, `restart` | -| `event_log` | Bounded log of install output and phase transitions (up to 200 entries) | -| `peer_results` | Per-node outcome map for replicated deployments | -| `payload_hash` | SHA-256 hash of the deployment tarball | -| `payload_size` | Byte size of the deployment tarball | -| `started_at` | Timestamp when deployment began | -| `completed_at` | Timestamp when deployment finished | -| `user` | User who initiated the deployment | -| `rollback_of` | `deployment_id` of the deployment this rolls back, if applicable | -| `error` | Error message for failed deployments | +| Field | Description | +| -------------------- | -------------------------------------------------------------------------------------------------- | +| `deployment_id` | Unique identifier (content hash) | +| `project` | Component project name | +| `package_identifier` | Package reference or `payload` for tar uploads | +| `status` | `pending`, `staging`, `staged`, `activating`, `success`, `failed`, or `rolled_back` | +| `phase` | Current lifecycle phase: `stage`, `load`, `activate`, `restart` (or legacy `prepare`, `replicate`) | +| `event_log` | Bounded log of install output and phase transitions (up to 200 entries) | +| `peer_results` | Per-node outcome map for replicated deployments | +| `payload_hash` | SHA-256 hash of the deployment tarball | +| `payload_size` | Byte size of the deployment tarball | +| `started_at` | Timestamp when deployment began | +| `completed_at` | Timestamp when deployment finished | +| `user` | User who initiated the deployment | +| `rollback_of` | `deployment_id` of the deployment this rolls back, if applicable | +| `error` | Error message for failed deployments | ### `get_deployment_payload`