compute_instances
Creates, updates, deletes, gets or lists a compute_instances resource.
Overview​
| Name | compute_instances |
| Type | Resource |
| Id | ovh.public_cloud.compute_instances |
Fields​
The following fields are returned by SELECT queries:
- get
- list
successful operation
| Name | Datatype | Description |
|---|---|---|
id | string (uuid) | Unique identifier of the instance |
checksum | string | Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins). |
created_at | string (date-time) | Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp (wire: createdAt) |
current_state | object | Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet. (wire: currentState) |
current_tasks | array | In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied. (wire: currentTasks) |
resource_status | string | Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine. (CREATING, CREATION_PLANNED, DELETING, ERROR, OUT_OF_SYNC, READY, SUSPENDED, UNKNOWN, UPDATING) (wire: resourceStatus) |
target_spec | object | Desired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach). (wire: targetSpec) |
updated_at | string (date-time) | Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp (wire: updatedAt) |
A Public Cloud compute instance: a virtual machine provisioned from a flavor and an image, connected to one or more networks and backed by block volumes. The resource follows the standard desired-state / observed-state model: targetSpec holds the specification you asked for. currentState reflects what the compute backend actually reports. resourceStatus and currentTasks describe the reconciliation between the two. Updates are performed by sending a new targetSpec on the PUT route. The requested operations (rename, resize, power change, volume attach/detach, share attach/detach) are derived from the diff.
| Name | Datatype | Description |
|---|---|---|
id | string (uuid) | Unique identifier of the instance |
checksum | string | Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins). |
created_at | string (date-time) | Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp (wire: createdAt) |
current_state | object | Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet. (wire: currentState) |
current_tasks | array | In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied. (wire: currentTasks) |
resource_status | string | Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine. (CREATING, CREATION_PLANNED, DELETING, ERROR, OUT_OF_SYNC, READY, SUSPENDED, UNKNOWN, UPDATING) (wire: resourceStatus) |
target_spec | object | Desired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach). (wire: targetSpec) |
updated_at | string (date-time) | Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp (wire: updatedAt) |
Methods​
The following methods are available for this resource:
| Name | Accessible by | Required Params | Optional Params | Description |
|---|---|---|---|---|
get | select | instance_id, project_id | ### Get an instance<br /><br />Returns a single Public Cloud instance, including its desired targetSpec and observed currentState.<br /><br />### Optimistic concurrency<br />The checksum returned here is the hash of the current targetSpec. Keep it and send it back on any subsequent PUT or imperative action call on the instance to guard against lost updates. It is optional, but omitting it forces the write (see the PUT route).<br /><br />### Filesystem attachments<br />currentState.shares — the list of filesystems (Manila shares) attached to the instance — is populated only on this single-instance GET. It is deliberately not returned by the LIST route for performance reasons. Fetch the individual instance when you need it. | |
list | select | project_id | x_pagination_cursor, x_pagination_size, flavor, name, region, status | ### List instances<br /><br />Lists all instances in the project. Each item is a full instance envelope with the same shape as the GET route (desired targetSpec and observed currentState).<br /><br />### Filesystem attachments<br />For performance, currentState.shares is not populated in list responses. To see the filesystems attached to a given instance, call GET .../instance/{instanceId} on it.<br /><br />### Filters<br />The optional name, flavor, region and status query parameters narrow the list. Each one can be repeated, for example ?status=READY&status=CREATING: repeated values of the same parameter are combined with OR, and different parameters are combined with AND. Filters apply only within the instances you are authorized to list. An unknown status value or an unavailable region is rejected with a 400 InvalidParameter. |
create | insert | project_id, target_spec | ### Create an instance<br /><br />Provisions a new instance from the supplied targetSpec. Creation is asynchronous: the resource starts in CREATING and becomes READY once the backend has booted it. Poll GET .../instance/{instanceId} until resourceStatus is READY and currentTasks is empty.<br /><br />### Create-time-only fields (immutable afterward)<br />Several fields can be set only at creation and can never be changed later:<br />* location — the region (and optional availability zone) the instance is deployed in.<br />* sshKeyName — the SSH key injected into the instance at boot.<br />* group — placement / instance-group membership. It binds the instance to an existing instance group (Nova server group) for AFFINITY / ANTI_AFFINITY scheduling. Server-group membership is fixed by OpenStack at boot and cannot be added, removed, or changed afterward — there is no group PUT.<br /><br />### User data (cloud-init)<br />targetSpec.userData is a base64-encoded (strict standard encoding) cloud-init payload handed to the instance at boot through the OpenStack metadata service / config drive, and interpreted by cloud-init inside the guest image. The encoded string must be at most 65535 bytes. It is write-only: the value is never returned by GET/LIST. It is also not persisted or stored by the Public Cloud API: the payload is handed to the compute service, which makes it available to the instance via the metadata service. Only a non-reversible fingerprint of the value is retained, for change detection. Unlike the create-time-only fields above, userData can be changed later via PUT. See the PUT route for the destructive semantics of doing so.<br /><br />### Declarative volumes<br />targetSpec.volumes is a declarative list of block-volume references attached to the instance. Supply the volumes to attach at boot. On a subsequent PUT the list is diffed to attach or detach volumes (see the PUT route). There is no imperative attach/detach endpoint.<br /><br />### Declarative shares<br />targetSpec.shares is a declarative list of filesystem (Manila share) attachments. Each entry references a share plus an optional per-entry accessLevel (defaults to READ_WRITE). At creation, each attach creates a Manila IP access rule for the instance's interface on the share's network. The instance must have an interface on that network. As with volumes, the list is reconciled by diffing on PUT.<br /><br />### Declarative networks and public IPs<br />targetSpec.networks is a declarative list of network interfaces. Each entry is {id?, subnetId?, ip?, autoAssignPublicIp?}, and the fields you set decide what it means:<br />* {"autoAssignPublicIp": true} — a public (Ext-Net) interface with a platform-assigned public IP. At most one entry may set it.<br />* {"ip": "..."} without a network id — a public IP the project already owns: either an existing additional IP (also known as a failover IP), or an Ext-Net IP of the project in the instance's region. Any other address is rejected. Such an entry implicitly attaches the public (Ext-Net) interface. Several are allowed, and they may coexist with an autoAssignPublicIp entry.<br />* {"id": "...", "subnetId": "..."} — a private interface whose fixed address is assigned by IPAM.<br />* {"id": "...", "subnetId": "...", "ip": "..."} — a private interface where ip pins the fixed address when it falls inside the subnet CIDR, and otherwise designates an existing floating IP to associate with that interface (the floating IP must already exist).<br /><br />Any entry that sets autoAssignPublicIp or carries a public ip requires the optional instance/usePublicIP IAM action, including floating IP associations.<br /><br />In currentState.networks the shape is different: there is one entry per network plus at most one id-less entry for the public (Ext-Net) interface, and every address is reported through that entry's addresses list. There is no scalar ip. Each address carries a type: FIXED for an address configured on the interface itself (a private fixed address, whether IPAM-assigned or pinned, and the Ext-Net address), FLOATING for a floating IP associated with the interface, and ADDITIONAL for an additional IP routed to the public interface (additional IPs no longer form their own entry). autoAssignPublicIp is never echoed back, because the backend cannot distinguish a platform-assigned address from a pinned one. | |
update | update | instance_id, project_id, target_spec | ### Update an instance<br /><br />This is the single, declarative route for changing an instance. You do not call verb-specific endpoints. Instead you submit a new desired targetSpec and the API derives the operations to perform from the diff against the current specification. (Imperative power/lifecycle operations such as reboot, start, stop, and rescue live on the separate .../instance/{instanceId}/action route.)<br /><br />### Asynchronous, desired-state model<br />1. You send the new targetSpec, optionally together with the checksum from your last GET.<br />2. If accepted, you immediately get back the instance with the updated targetSpec and a new checksum. resourceStatus becomes UPDATING.<br />3. One or more asynchronous tasks reconcile currentState toward targetSpec. Poll GET .../instance/{instanceId} until resourceStatus is READY and currentTasks is empty to know the change has been applied.<br /><br />### Operations derived from the diff<br />* Rename — changing name renames the instance.<br />* Resize (flavor) — changing flavor migrates the instance to the new flavor.<br />* Volume attach / detach — done declaratively by diffing the volumes list: adding a volume reference attaches that volume, removing one detaches it. There is no imperative attach/detach endpoint — the diff is the only mechanism.<br />* Network attach / detach — done declaratively by diffing the networks list, whose entries are {id?, subnetId?, ip?, autoAssignPublicIp?}: a platform-assigned Ext-Net IP ({"autoAssignPublicIp": true}, at most one entry), a public IP the project already owns — additional IP or project Ext-Net IP in the instance's region — ({"ip"}, no network id), a private interface with an IPAM address ({"id", "subnetId"}), or a private interface with ip either pinning its fixed address (address inside the subnet CIDR) or associating an existing floating IP (address outside it). Any entry that sets autoAssignPublicIp or carries a public ip requires the optional instance/usePublicIP IAM action.<br />* Filesystem (share) attach / detach — done declaratively by diffing the shares list. Adding an entry attaches the share: it creates a Manila IP access rule for the instance's interface on the share's network, so the instance must already have an interface on that network or the attach errors. Removing an entry detaches the share: the matching access rule is removed, and the detach is idempotent. Each entry's accessLevel defaults to READ_WRITE. Caveat: managing per-share access rules directly on the share resource and attaching the same share instance-side here is unsupported — the share will report OUT_OF_SYNC.<br /><br />### Immutable fields (excluded from update)<br />location, sshKeyName, and group are set only at creation and are not part of the update. In particular, placement-group (group) membership cannot change post-create. OpenStack/Nova server groups are immutable and there is deliberately no group PUT.<br /><br />### Destructive update (userData)<br />Changing targetSpec.userData reinstalls the instance — a Nova rebuild on its current image — which wipes the root disk and all data on it. Semantics are tri-state: omitting the field (or sending null) keeps the current value unchanged, an empty string "" clears it, and any other value replaces it. Both the clear and the replace trigger the reinstall. An instance with no image (boot-from-volume) has nothing to rebuild onto, so a userData change on it is rejected with a 400 InvalidParameter.<br /><br />### Optimistic concurrency (checksum)<br />The checksum guards against lost updates and is optional. When you send it, it must match the server-side value: if another request modified the instance since your last GET, the checksum no longer matches and the request is rejected with a checksum-mismatch error (ChecksumMismatch). Re-GET the instance and retry against the fresh state. When you omit it (or send an empty string), the check is skipped and the update is forced (last-write-wins). | |
delete | delete | instance_id, project_id | ### Delete an instance<br /><br />Permanently deletes a Public Cloud instance. Deletion is asynchronous: the resource transitions to DELETING, the response echoes the instance, and the backend then removes it. Poll GET .../instance/{instanceId} until it returns InstanceDoesNotExist (404) to confirm removal.<br /><br />Behavior<br />* Independent block volumes attached to the instance are detached, not deleted — they are separate resources and survive.<br />* Filesystem (share) attachments are released as part of the teardown.<br /><br />A delete already in progress is reported as ResourceAlreadyBeingDeleted. An instance in a transient or otherwise invalid state may be rejected with ResourceInInvalidState. | |
action | exec | instanceId, project_id, type | ### Perform an instance action<br /><br />Imperative endpoint for power and lifecycle actions on an instance. This is the one place such imperative operations live. Distinct from the declarative PUT on the instance, which reconciles desired state from a targetSpec diff. Actions are asynchronous: the instance transitions through the relevant transient state and the response echoes the instance. Poll GET .../instance/{instanceId} until resourceStatus is READY and currentTasks is empty.<br /><br />### Action type<br />The type field selects the operation:<br />* REBOOT — reboot the instance (parameters.hard chooses a hard vs. soft reboot).<br />* START / STOP — power the instance on / off.<br />* SHELVE / UNSHELVE — shelve the instance (freeing hypervisor resources) and restore it.<br />* PAUSE / UNPAUSE — freeze a running instance in the memory of the host, and unfreeze it.<br />* SUSPEND / RESUME — save the memory state of a running instance to disk and stop it, and restore it.<br />* RESCUE / UNRESCUE — boot into rescue mode (optionally from parameters.imageId) and return to normal boot.<br />* LOCK / UNLOCK — lock the instance against accidental actions / modifications, and unlock it.<br /><br />### Optimistic concurrency (checksum)<br />The checksum is optional. When you send it, it must match the current server-side value or the action is rejected with a checksum-mismatch error. Re-GET and retry. When you omit it (or send an empty string), the check is skipped and the action is forced (last-write-wins). An action requested while the instance is in an incompatible state is rejected with ResourceInInvalidState. | |
console | exec | instanceId, project_id, protocol, type | ### Create a remote console<br /><br />Opens a remote console session to the instance and returns the connection details (a url and, depending on the protocol, an access token) for a client to connect. This is a synchronous call — no desired-state reconciliation — and the returned URL is short-lived, so request a fresh console when it expires.<br /><br />### Protocol and type<br />Choose the console via the request body:<br />* protocol — the console transport, for example VNC, SPICE, SERIAL.<br />* type — the concrete console kind for that protocol, for example NOVNC for VNC, SERIAL for SERIAL.<br /><br />The instance must be in a state that supports a console, otherwise the request is rejected with ResourceInInvalidState. |
Parameters​
Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.
| Name | Datatype | Description |
|---|---|---|
api_host | string | The OVHcloud API host. Selected by OVH_ENDPOINT (ovh-eu, ovh-ca or ovh-us; default ovh-eu). (default: api.eu.ovhcloud.com, x-stackQL-envVarSelector: {"envVar":"OVH_ENDPOINT","default":"ovh-eu","values":{"ovh-eu":"api.eu.ovhcloud.com","ovh-ca":"api.ca.ovhcloud.com","ovh-us":"api.us.ovhcloud.com"}}) |
instanceId | string (uuid) | Instance ID |
instance_id | string (uuid) | Instance ID (wire: instanceId) |
project_id | string | The Public Cloud project ID. Resolved from OVH_CLOUD_PROJECT_SERVICE when set. |
flavor | array | Filter by flavor ID or flavor name. Repeatable. |
name | array | Filter by instance name (case-insensitive substring match). Repeatable. |
region | array | Filter by instance region. An unavailable region is rejected. Repeatable. |
status | array | Filter by resourceStatus. Repeatable. |
x_pagination_cursor | string | Pagination cursor (wire: X-Pagination-Cursor) |
x_pagination_size | integer | Pagination size (wire: X-Pagination-Size) |
SELECT examples​
- get
- list
Get an instance<br /><br />Returns a single Public Cloud instance, including its desired targetSpec and observed currentState.<br /><br />### Optimistic concurrency<br />The checksum returned here is the hash of the current targetSpec. Keep it and send it back on any subsequent PUT or imperative action call on the instance to guard against lost updates. It is optional, but omitting it forces the write (see the PUT route).<br /><br />### Filesystem attachments<br />currentState.shares — the list of filesystems (Manila shares) attached to the instance — is populated only on this single-instance GET. It is deliberately not returned by the LIST route for performance reasons. Fetch the individual instance when you need it.​
SELECT
id,
checksum,
created_at,
current_state,
current_tasks,
resource_status,
target_spec,
updated_at
FROM ovh.public_cloud.compute_instances
WHERE instance_id = '{{ instance_id }}' -- required
AND project_id = '{{ project_id }}' -- required unless OVH_CLOUD_PROJECT_SERVICE is set
;
List instances<br /><br />Lists all instances in the project. Each item is a full instance envelope with the same shape as the GET route (desired targetSpec and observed currentState).<br /><br />### Filesystem attachments<br />For performance, currentState.shares is not populated in list responses. To see the filesystems attached to a given instance, call GET .../instance/{instanceId} on it.<br /><br />### Filters<br />The optional name, flavor, region and status query parameters narrow the list. Each one can be repeated, for example ?status=READY&status=CREATING: repeated values of the same parameter are combined with OR, and different parameters are combined with AND. Filters apply only within the instances you are authorized to list. An unknown status value or an unavailable region is rejected with a 400 InvalidParameter.​
SELECT
id,
checksum,
created_at,
current_state,
current_tasks,
resource_status,
target_spec,
updated_at
FROM ovh.public_cloud.compute_instances
WHERE project_id = '{{ project_id }}' -- required unless OVH_CLOUD_PROJECT_SERVICE is set
AND x_pagination_cursor = '{{ x_pagination_cursor }}'
AND x_pagination_size = '{{ x_pagination_size }}'
AND flavor = '{{ flavor }}'
AND name = '{{ name }}'
AND region = '{{ region }}'
AND status = '{{ status }}'
;
INSERT examples​
- create
- Manifest
Create an instance<br /><br />Provisions a new instance from the supplied targetSpec. Creation is asynchronous: the resource starts in CREATING and becomes READY once the backend has booted it. Poll GET .../instance/{instanceId} until resourceStatus is READY and currentTasks is empty.<br /><br />### Create-time-only fields (immutable afterward)<br />Several fields can be set only at creation and can never be changed later:<br />* location — the region (and optional availability zone) the instance is deployed in.<br />* sshKeyName — the SSH key injected into the instance at boot.<br />* group — placement / instance-group membership. It binds the instance to an existing instance group (Nova server group) for AFFINITY / ANTI_AFFINITY scheduling. Server-group membership is fixed by OpenStack at boot and cannot be added, removed, or changed afterward — there is no group PUT.<br /><br />### User data (cloud-init)<br />targetSpec.userData is a base64-encoded (strict standard encoding) cloud-init payload handed to the instance at boot through the OpenStack metadata service / config drive, and interpreted by cloud-init inside the guest image. The encoded string must be at most 65535 bytes. It is write-only: the value is never returned by GET/LIST. It is also not persisted or stored by the Public Cloud API: the payload is handed to the compute service, which makes it available to the instance via the metadata service. Only a non-reversible fingerprint of the value is retained, for change detection. Unlike the create-time-only fields above, userData can be changed later via PUT. See the PUT route for the destructive semantics of doing so.<br /><br />### Declarative volumes<br />targetSpec.volumes is a declarative list of block-volume references attached to the instance. Supply the volumes to attach at boot. On a subsequent PUT the list is diffed to attach or detach volumes (see the PUT route). There is no imperative attach/detach endpoint.<br /><br />### Declarative shares<br />targetSpec.shares is a declarative list of filesystem (Manila share) attachments. Each entry references a share plus an optional per-entry accessLevel (defaults to READ_WRITE). At creation, each attach creates a Manila IP access rule for the instance's interface on the share's network. The instance must have an interface on that network. As with volumes, the list is reconciled by diffing on PUT.<br /><br />### Declarative networks and public IPs<br />targetSpec.networks is a declarative list of network interfaces. Each entry is {id?, subnetId?, ip?, autoAssignPublicIp?}, and the fields you set decide what it means:<br />* {"autoAssignPublicIp": true} — a public (Ext-Net) interface with a platform-assigned public IP. At most one entry may set it.<br />* {"ip": "..."} without a network id — a public IP the project already owns: either an existing additional IP (also known as a failover IP), or an Ext-Net IP of the project in the instance's region. Any other address is rejected. Such an entry implicitly attaches the public (Ext-Net) interface. Several are allowed, and they may coexist with an autoAssignPublicIp entry.<br />* {"id": "...", "subnetId": "..."} — a private interface whose fixed address is assigned by IPAM.<br />* {"id": "...", "subnetId": "...", "ip": "..."} — a private interface where ip pins the fixed address when it falls inside the subnet CIDR, and otherwise designates an existing floating IP to associate with that interface (the floating IP must already exist).<br /><br />Any entry that sets autoAssignPublicIp or carries a public ip requires the optional instance/usePublicIP IAM action, including floating IP associations.<br /><br />In currentState.networks the shape is different: there is one entry per network plus at most one id-less entry for the public (Ext-Net) interface, and every address is reported through that entry's addresses list. There is no scalar ip. Each address carries a type: FIXED for an address configured on the interface itself (a private fixed address, whether IPAM-assigned or pinned, and the Ext-Net address), FLOATING for a floating IP associated with the interface, and ADDITIONAL for an additional IP routed to the public interface (additional IPs no longer form their own entry). autoAssignPublicIp is never echoed back, because the backend cannot distinguish a platform-assigned address from a pinned one.​
INSERT INTO ovh.public_cloud.compute_instances (
target_spec,
project_id
)
SELECT
'{{ target_spec }}' /* required */,
'{{ project_id }}'
RETURNING
id,
checksum,
created_at,
current_state,
current_tasks,
resource_status,
target_spec,
updated_at
;
# Description fields are for documentation purposes
- name: compute_instances
props:
- name: project_id
value: "{{ project_id }}"
description: Required parameter for the compute_instances resource.
- name: target_spec
description: |
Desired specification. Full target specification of the instance to create. See InstanceTargetSpec for the per-field creation rules and immutability constraints.
value:
flavor:
id: "{{ id }}"
group:
id: "{{ id }}"
image:
id: "{{ id }}"
location:
availabilityZone: "{{ availabilityZone }}"
region: "{{ region }}"
name: "{{ name }}"
networks:
- autoAssignPublicIp: {{ autoAssignPublicIp }}
id: "{{ id }}"
ip: "{{ ip }}"
subnetId: "{{ subnetId }}"
powerState: "{{ powerState }}"
securityGroups:
- id: "{{ id }}"
shares:
- accessLevel: "{{ accessLevel }}"
id: "{{ id }}"
sshKeyName: "{{ sshKeyName }}"
userData: "{{ userData }}"
volumes:
- id: "{{ id }}"
UPDATE examples​
- update
Update an instance<br /><br />This is the single, declarative route for changing an instance. You do not call verb-specific endpoints. Instead you submit a new desired targetSpec and the API derives the operations to perform from the diff against the current specification. (Imperative power/lifecycle operations such as reboot, start, stop, and rescue live on the separate .../instance/{instanceId}/action route.)<br /><br />### Asynchronous, desired-state model<br />1. You send the new targetSpec, optionally together with the checksum from your last GET.<br />2. If accepted, you immediately get back the instance with the updated targetSpec and a new checksum. resourceStatus becomes UPDATING.<br />3. One or more asynchronous tasks reconcile currentState toward targetSpec. Poll GET .../instance/{instanceId} until resourceStatus is READY and currentTasks is empty to know the change has been applied.<br /><br />### Operations derived from the diff<br />* Rename — changing name renames the instance.<br />* Resize (flavor) — changing flavor migrates the instance to the new flavor.<br />* Volume attach / detach — done declaratively by diffing the volumes list: adding a volume reference attaches that volume, removing one detaches it. There is no imperative attach/detach endpoint — the diff is the only mechanism.<br />* Network attach / detach — done declaratively by diffing the networks list, whose entries are {id?, subnetId?, ip?, autoAssignPublicIp?}: a platform-assigned Ext-Net IP ({"autoAssignPublicIp": true}, at most one entry), a public IP the project already owns — additional IP or project Ext-Net IP in the instance's region — ({"ip"}, no network id), a private interface with an IPAM address ({"id", "subnetId"}), or a private interface with ip either pinning its fixed address (address inside the subnet CIDR) or associating an existing floating IP (address outside it). Any entry that sets autoAssignPublicIp or carries a public ip requires the optional instance/usePublicIP IAM action.<br />* Filesystem (share) attach / detach — done declaratively by diffing the shares list. Adding an entry attaches the share: it creates a Manila IP access rule for the instance's interface on the share's network, so the instance must already have an interface on that network or the attach errors. Removing an entry detaches the share: the matching access rule is removed, and the detach is idempotent. Each entry's accessLevel defaults to READ_WRITE. Caveat: managing per-share access rules directly on the share resource and attaching the same share instance-side here is unsupported — the share will report OUT_OF_SYNC.<br /><br />### Immutable fields (excluded from update)<br />location, sshKeyName, and group are set only at creation and are not part of the update. In particular, placement-group (group) membership cannot change post-create. OpenStack/Nova server groups are immutable and there is deliberately no group PUT.<br /><br />### Destructive update (userData)<br />Changing targetSpec.userData reinstalls the instance — a Nova rebuild on its current image — which wipes the root disk and all data on it. Semantics are tri-state: omitting the field (or sending null) keeps the current value unchanged, an empty string "" clears it, and any other value replaces it. Both the clear and the replace trigger the reinstall. An instance with no image (boot-from-volume) has nothing to rebuild onto, so a userData change on it is rejected with a 400 InvalidParameter.<br /><br />### Optimistic concurrency (checksum)<br />The checksum guards against lost updates and is optional. When you send it, it must match the server-side value: if another request modified the instance since your last GET, the checksum no longer matches and the request is rejected with a checksum-mismatch error (ChecksumMismatch). Re-GET the instance and retry against the fresh state. When you omit it (or send an empty string), the check is skipped and the update is forced (last-write-wins).​
UPDATE ovh.public_cloud.compute_instances
SET
checksum = '{{ checksum }}',
target_spec = '{{ target_spec }}'
WHERE
instance_id = '{{ instance_id }}' --required
AND project_id = '{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
AND target_spec = '{{ target_spec }}' --required
RETURNING
id,
checksum,
created_at,
current_state,
current_tasks,
resource_status,
target_spec,
updated_at;
DELETE examples​
- delete
Delete an instance<br /><br />Permanently deletes a Public Cloud instance. Deletion is asynchronous: the resource transitions to DELETING, the response echoes the instance, and the backend then removes it. Poll GET .../instance/{instanceId} until it returns InstanceDoesNotExist (404) to confirm removal.<br /><br />Behavior<br />* Independent block volumes attached to the instance are detached, not deleted — they are separate resources and survive.<br />* Filesystem (share) attachments are released as part of the teardown.<br /><br />A delete already in progress is reported as ResourceAlreadyBeingDeleted. An instance in a transient or otherwise invalid state may be rejected with ResourceInInvalidState.​
DELETE FROM ovh.public_cloud.compute_instances
WHERE instance_id = '{{ instance_id }}' --required
AND project_id = '{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
;
Lifecycle Methods​
EXEC variables use wire (API) names.
- action
- console
Perform an instance action<br /><br />Imperative endpoint for power and lifecycle actions on an instance. This is the one place such imperative operations live. Distinct from the declarative PUT on the instance, which reconciles desired state from a targetSpec diff. Actions are asynchronous: the instance transitions through the relevant transient state and the response echoes the instance. Poll GET .../instance/{instanceId} until resourceStatus is READY and currentTasks is empty.<br /><br />### Action type<br />The type field selects the operation:<br />* REBOOT — reboot the instance (parameters.hard chooses a hard vs. soft reboot).<br />* START / STOP — power the instance on / off.<br />* SHELVE / UNSHELVE — shelve the instance (freeing hypervisor resources) and restore it.<br />* PAUSE / UNPAUSE — freeze a running instance in the memory of the host, and unfreeze it.<br />* SUSPEND / RESUME — save the memory state of a running instance to disk and stop it, and restore it.<br />* RESCUE / UNRESCUE — boot into rescue mode (optionally from parameters.imageId) and return to normal boot.<br />* LOCK / UNLOCK — lock the instance against accidental actions / modifications, and unlock it.<br /><br />### Optimistic concurrency (checksum)<br />The checksum is optional. When you send it, it must match the current server-side value or the action is rejected with a checksum-mismatch error. Re-GET and retry. When you omit it (or send an empty string), the check is skipped and the action is forced (last-write-wins). An action requested while the instance is in an incompatible state is rejected with ResourceInInvalidState.​
EXEC ovh.public_cloud.compute_instances.action
@instanceId='{{ instanceId }}' --required,
@project_id='{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
@@json=
'{
"checksum": "{{ checksum }}",
"parameters": "{{ parameters }}",
"type": "{{ type }}"
}'
;
Create a remote console<br /><br />Opens a remote console session to the instance and returns the connection details (a url and, depending on the protocol, an access token) for a client to connect. This is a synchronous call — no desired-state reconciliation — and the returned URL is short-lived, so request a fresh console when it expires.<br /><br />### Protocol and type<br />Choose the console via the request body:<br />* protocol — the console transport, for example VNC, SPICE, SERIAL.<br />* type — the concrete console kind for that protocol, for example NOVNC for VNC, SERIAL for SERIAL.<br /><br />The instance must be in a state that supports a console, otherwise the request is rejected with ResourceInInvalidState.​
EXEC ovh.public_cloud.compute_instances.console
@instanceId='{{ instanceId }}' --required,
@project_id='{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
@@json=
'{
"protocol": "{{ protocol }}",
"type": "{{ type }}"
}'
;