PHphala
CVMs
cvms-annotations

Replace CVM annotations

Changed on

Replaces every annotation of this CVM; an empty object clears them. The VMM applies the change at once, without a restart and without a compose change. Host tools that read annotations only when QEMU launches (for example memory tiers or vCPU pinning) see the new values after the CVM restarts. Other CVM updates never change annotations. Annotations are opaque key/value metadata for host-side tooling, such as a QEMU wrapper that reads the VM manifest. The dstack VMM stores them with the VM. They are not passed to the guest, not measured, and not part of the compose hash, so attestation does not cover them: tenants must not rely on them for security. Phala Cloud keeps no copy of annotations as CVM state: only the node's VMM holds them, and Cloud never copies or restores them. A replica starts without annotations; a relocated CVM keeps whatever its VMM manifest carries. A create request that carries annotations is recorded in the audit log. Requires the cvm_annotations feature flag (ERR-03-049) and dstack VMM 0.6.1 or newer on the node (ERR-03-050).

put/api/v1/cvms/{cvm_id}/annotations

Request

Path parameters

cvm_idstring required

Request body

annotationsobject required

Opaque key/value metadata for host-side tooling. The dstack VMM stores it with the VM; it is not passed to the guest, not measured, and not part of the compose hash, so it is host configuration that attestation does not cover. Do not rely on it for security. Replaces every annotation; an empty object clears them. Keys must not be empty.

Example request

{
  "annotations": {
    "memory_tier": "fast"
  }
}

Response

The annotations now stored

annotationsobject required

Opaque key/value metadata for host-side tooling. The dstack VMM stores it with the VM; it is not passed to the guest, not measured, and not part of the compose hash, so it is host configuration that attestation does not cover. Do not rely on it for security.

Changes