<span id="更新计算资源管理配置"></span>

# Update administrative compute resource configuration

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Update a target compute resource as a configured administrator and return the ordinary resource object.

```text
PUT https://api.moi.matrixorigin.cn/v5/admin/compute-resources/{id}
```

<span id="调用前准备"></span>

## Before you call this API

Prepare an identity configured as a compute specification administrator in this deployment and an accessible authentication Workspace. Workspace Owner status or a Genesis administration scope is insufficient. Replace example IDs with targets you are authorized to read or operate on. See [Compute Instances](../../../../../developer/cli/tasks/compute-resources.md).

Submit only fields you want to change. Omitted or null scalars retain their values; explicit zero values and empty strings are validated as updates. An empty worker_images array is rejected. Neither {} nor null is a reliable no-op: the current implementation may still clear status_message and update the timestamp.

<span id="请求参数"></span>

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
curl -X PUT "https://api.moi.matrixorigin.cn/v5/admin/compute-resources/cr-example" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $AUTH_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  --data '{"description":"更新说明"}'
```

:::::
:::::{tab-item} Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | string | Yes (in this example) | A valid personal access token for an identity configured as a compute specification administrator in this deployment. |
| `X-Workspace-ID` | string | Yes | One nonempty authentication Workspace, separate from the resource's Workspace and the workspace_id list filter. |
| `id` | string | Yes | Target resource ID. The service resolves its owning workspace from the administrative repository. |
| `name` | string | No | Must not be empty after trimming whitespace. |
| `description` | string | No | Saved verbatim; an explicit empty string clears the value. |
| `kind` | string | No | task or query. On submission, the final spec_id must reference an enabled specification of the matching kind; the specification is reapplied. |
| `spec_id` | string | No | Whitespace is trimmed, and the specification must exist. An explicit change requires an enabled specification of the matching kind. Specification values override legacy CPU/memory/GPU fields in the same request. |
| `cpu` | integer | No | Final value must be greater than 0, in cores. Setting it alone does not synchronize cpu_milli. |
| `memory_gib` | integer | No | Final value must be greater than 0, in GiB. Setting it alone does not synchronize memory_mib. |
| `gpu` | integer | No | Final value must be at least 0. Setting it alone does not synchronize gpu_count. |
| `worker_images` | object (array of objects) | No | Replace the full image selection. Omission or null retains it; [] is validated and rejected. Cover every Worker type in the current ACTIVE catalog exactly once, with matching IDs, types, and platforms. is_default=true is not required. See common objects for nested fields. |
| `min_replicas` | integer | No | Current update validation requires the final value to be 0. |
| `max_replicas` | integer | No | Final value must be greater than 0 and at least min_replicas. This is a per-Worker-type limit. |
| `go_worker_image_id` | string | No | Legacy image field; an empty string clears it. This does not replace the full worker_images selection. |
| `python_worker_image_id` | string | No | Legacy image field; an empty string clears it. This does not replace the full worker_images selection. |
| `platform` | string | No | Must not be empty after trimming whitespace. The image selection platform must also match the image catalog. |
| `auto_suspend_minutes` | integer | No | Final value must be at least 0. An explicit 0 is retained; values above 60 are capped at 60. |
| `py_requirements_txt` | string | No | Omission or null retains the value. An explicit empty string clears both text and SHA. Nonempty text requires a Python Worker, a configured validator, and the capability enabled; current dynamic size, line-count, and source rules apply. |

:::::
::::::
:::::::

<span id="成功响应"></span>

## Successful response

HTTP 200。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "cr-example",
    "workspace_id": "target-workspace",
    "name": "示例实例",
    "description": "更新说明",
    "kind": "task",
    "spec_id": "spec-example",
    "cpu": 1,
    "memory_gib": 4,
    "gpu": 0,
    "cpu_milli": 1000,
    "memory_mib": 4096,
    "gpu_count": 0,
    "gpu_memory_mib": 0,
    "gpu_cores": 0,
    "min_replicas": 0,
    "max_replicas": 2,
    "current_replicas": 0,
    "desired_replicas": 0,
    "go_worker_image_id": "",
    "python_worker_image_id": "",
    "worker_images": [
      {
        "worker_type": "python-worker",
        "image_id": "image-example",
        "platform": "linux/amd64"
      }
    ],
    "platform": "linux/amd64",
    "auto_suspend_minutes": 30,
    "scale_reason": "",
    "is_default": false,
    "status": "IDLE",
    "status_message": "",
    "created_by": "creator-example",
    "allowed_actions": [],
    "created_at": "2026-11-12T07:00:00Z",
    "updated_at": "2026-11-12T07:00:00Z"
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | OK on success. |
| `data` | object | Data returned by this API; see the fields below. |
| `data.id` | string | Compute instance ID. |
| `data.workspace_id` | string | The instance's actual Workspace, separate from the authentication header. |
| `data.name` | string | Instance name. |
| `data.description` | string | Instance description; may be an empty string. |
| `data.kind` | string | task or query. |
| `data.spec_id` | string | Associated specification ID. |
| `data.cpu` | integer | Legacy CPU specification field, in cores; do not confuse it with cpu_milli. |
| `data.memory_gib` | integer | Legacy memory specification field, in GiB. |
| `data.gpu` | integer | Legacy GPU specification field. |
| `data.cpu_milli` | integer | Specification CPU, in millicores. |
| `data.memory_mib` | integer | Specification memory, in MiB. |
| `data.gpu_count` | integer | Specification GPU count. |
| `data.gpu_memory_mib` | integer | Specification GPU memory, in MiB. |
| `data.gpu_cores` | integer | Specification GPU core field. |
| `data.min_replicas` | integer | Configured minimum replica field; not the currently observed replica count. |
| `data.max_replicas` | integer | Replica limit for each Worker type, not a combined limit across all types. |
| `data.current_replicas` | integer | Aggregate current instance replica field; separate from per-type observations. |
| `data.desired_replicas` | integer | Target instance replica field; does not indicate readiness. |
| `data.go_worker_image_id` | string | Legacy Go Worker image ID; may be empty. |
| `data.python_worker_image_id` | string | Legacy Python Worker image ID; may be empty. |
| `data.worker_images` | object (array of objects), optional | Optional images selected by Worker type. See the item fields below. |
| `data.platform` | string | Worker platform configuration. |
| `data.auto_suspend_minutes` | integer | Configured automatic suspension delay in minutes; not a duration guarantee for this operation. |
| `data.scale_reason` | string | Most recent scaling or lifecycle reason. |
| `data.is_default` | boolean | Whether this is the default instance; may be false. |
| `data.status` | string | Parent instance state. Current models include IDLE, DEPLOYING, SCALING, ACTIVE, DRAINING, SUSPENDED, TERMINATING, ERROR, and others. Do not conflate this with Worker states. |
| `data.status_message` | string | Status text; may be empty. |
| `data.py_requirements_txt` | string, optional | Echoes normalized dependency text when nonempty; not declared in current typed SDK models. |
| `data.py_requirements_sha` | string, optional | Echoes the text's SHA256 when nonempty; not declared in current typed SDK models. |
| `data.py_deps` | object, optional | Declared optional observation object. Current list/update converters do not populate it, so it does not guarantee installation progress information. |
| `data.created_by` | string | Creating principal. |
| `data.allowed_actions` | string (array of strings) | Regular resource projection; update results may contain []. Administrative lists remove this field. Do not use it to determine administrator eligibility. |
| `data.last_activation_at` | string, optional | Most recent activation time in RFC3339; omitted when unrecorded. |
| `data.last_active_at` | string, optional | Most recent activity time in RFC3339; omitted when unrecorded. |
| `data.created_at` | string | Creation time in RFC3339. |
| `data.updated_at` | string | Update time in RFC3339; not a caller-supplied concurrency version. |

See [Shared objects](compute-admin-crud-objects.md) for nested objects and omission rules.
:::::
::::::
:::::::

<span id="错误响应"></span>

## Error responses

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{"code": "INVALID_PARAMS", "msg": "invalid compute resource request", "data": null}
```

:::::
:::::{tab-item} Fields

| HTTP / code | Conditions and handling |
| --- | --- |
| 400 / INVALID_PARAMS | Required context is missing, JSON cannot be parsed, or a second JSON value is present. Unknown JSON properties are not currently rejected strictly; this does not mean those fields are supported. |
| 403 / ErrForbidden | A classified rejection of administrator eligibility, principal, or Workspace access. |
| 503 / ErrServiceUnavailable | A classified shared authorization unavailability error; does not cover every directory/configuration error. |
| 500 / ErrServer | The current administrative handler uses the shared service mapping throughout. Missing resources and specification/parameter/dependency validation failures are not separately classified. The ordinary update API's 404/409/UPDATE_UNAVAILABLE mappings do not apply. |

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Classified by the specific failure stage. |
| `msg` | string | Error text; shared errors may be localized. |
| `data` | null or omitted | Direct compute errors use null. See error recovery for shared error formats. |

:::::
::::::
:::::::

An error does not mean every stage was rolled back. See [Errors and recovery](compute-admin-crud-errors-recovery.md).
