compute_instance_groups

Creates, updates, deletes, gets or lists a compute_instance_groups resource.

Overview

Name	`compute_instance_groups`
Type	Resource
Id	`ovh.public_cloud.compute_instance_groups`

Fields

The following fields are returned by SELECT queries:

get
list

successful operation

Name	Datatype	Description
`id`	`string (uuid)`	Unique identifier of the instance group, assigned at creation and used to reference it on the GET/DELETE routes
`checksum`	`string`	Checksum. Computed hash of the current target specification, used for optimistic concurrency control. Because an instance group has no update route, this value never changes after creation.
`created_at`	`string (date-time)`	Creation date. Timestamp at which the instance group was created, in RFC 3339 format. (wire: createdAt)
`current_state`	`object`	Actual state of the instance group as reported by the backend (OpenStack/Nova server group), including its current members. This is read-only and reflects reality, in contrast to targetSpec which is the desired specification supplied on creation. May be null while the group is still being provisioned and no backend state is known yet. (wire: currentState)
`current_tasks`	`array`	Current tasks. Asynchronous operations currently running against this instance group, for example the initial provisioning or the deletion. Empty or null when no operation is in progress. (wire: currentTasks)
`resource_status`	`string`	Lifecycle status of the instance group in the system, for example whether it is being created, ready, or being deleted. Reflects readiness of the resource, not the placement policy itself. (CREATING, CREATION_PLANNED, DELETING, ERROR, OUT_OF_SYNC, READY, SUSPENDED, UNKNOWN, UPDATING) (wire: resourceStatus)
`target_spec`	`object`	Target specification. Desired specification of the instance group as supplied on creation (name, location and placement policy). Since an instance group cannot be updated, this specification is fixed for the lifetime of the group. Compare it against currentState to see what the backend actually provisioned. (wire: targetSpec)

Instance group (placement group). A Public Cloud instance group, backed by an OpenStack/Nova server group, that constrains how its member instances are placed relative to one another (see policy and PolicyEnum: AFFINITY / ANTI_AFFINITY). An instance group is immutable once created: there is no update (PUT) route, and its membership is fixed. Instances join a group only at instance-creation time, through the instance's targetSpec.group field. They cannot be added to or removed from a group afterward. The only lifecycle operations are create (POST), read (GET/LIST) and delete (DELETE). The object follows the standard envelope: targetSpec is the desired specification supplied on creation, while currentState reflects what the backend actually reports (including the current members).

Name	Datatype	Description
`id`	`string (uuid)`	Unique identifier of the instance group, assigned at creation and used to reference it on the GET/DELETE routes
`checksum`	`string`	Checksum. Computed hash of the current target specification, used for optimistic concurrency control. Because an instance group has no update route, this value never changes after creation.
`created_at`	`string (date-time)`	Creation date. Timestamp at which the instance group was created, in RFC 3339 format. (wire: createdAt)
`current_state`	`object`	Actual state of the instance group as reported by the backend (OpenStack/Nova server group), including its current members. This is read-only and reflects reality, in contrast to targetSpec which is the desired specification supplied on creation. May be null while the group is still being provisioned and no backend state is known yet. (wire: currentState)
`current_tasks`	`array`	Current tasks. Asynchronous operations currently running against this instance group, for example the initial provisioning or the deletion. Empty or null when no operation is in progress. (wire: currentTasks)
`resource_status`	`string`	Lifecycle status of the instance group in the system, for example whether it is being created, ready, or being deleted. Reflects readiness of the resource, not the placement policy itself. (CREATING, CREATION_PLANNED, DELETING, ERROR, OUT_OF_SYNC, READY, SUSPENDED, UNKNOWN, UPDATING) (wire: resourceStatus)
`target_spec`	`object`	Target specification. Desired specification of the instance group as supplied on creation (name, location and placement policy). Since an instance group cannot be updated, this specification is fixed for the lifetime of the group. Compare it against currentState to see what the backend actually provisioned. (wire: targetSpec)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`instance_group_id`, `project_id`		### Get an instance group<br /><br />Returns a single instance group (placement group), including its scheduling `policy` and its members.<br /><br />### Immutable by design<br />Instance groups are immutable after creation. There is deliberately no `PUT` / update route. Neither the placement `policy` nor the set of members can be changed once the group exists. Membership is fixed at instance creation time: an instance joins a group via its `targetSpec.group` field when it is created (see the instance `POST`), and cannot be added to or removed from a group afterward. To change grouping you delete and recreate the affected instances into a different group.
`list`	`select`	`project_id`	`x_pagination_cursor`, `x_pagination_size`	### List instance groups<br /><br />Lists all instance groups (placement groups) in the project, each with the same shape as the `GET` route (scheduling `policy` and members).<br /><br />### Immutable by design<br />Instance groups cannot be modified after creation. There is deliberately no `PUT` / update route, and membership is fixed at instance creation time via the instance's `targetSpec.group` field. See the `GET` route for details.
`create`	`insert`	`project_id`, `target_spec`		### Create an instance group<br /><br />Creates a new instance group (placement group). Creation is asynchronous: the group starts in `CREATING` and becomes `READY` once the backend has provisioned it.<br /><br />### Placement policy<br />`targetSpec.policy` chooses how members are scheduled relative to each other:<br />* `AFFINITY` — members are placed on the same hypervisor.<br />* `ANTI_AFFINITY` — members are placed on different hypervisors (for high availability).<br /><br />### Immutable, membership set at instance creation<br />The group is immutable once created. There is deliberately no `PUT` / update route, so the `policy` can never be changed. The group is created empty: instances are not added here. An instance joins the group only at its own creation time, via its `targetSpec.group` field (see the instance `POST`), and membership cannot change afterward (OpenStack/Nova server groups are immutable).
`delete`	`delete`	`instance_group_id`, `project_id`		### Delete an instance group<br /><br />Deletes an instance group (placement group). Deletion is asynchronous: the resource transitions to `DELETING` and the backend then removes it.<br /><br />A group is normally removed once it is empty (has no member instances). Because membership is fixed at instance creation time and cannot be edited on an existing group, freeing a group means deleting or recreating its member instances first. Deleting the group tears down only the placement grouping. It does not delete the instances themselves. A delete already in progress is reported as `ResourceAlreadyBeingDeleted`.

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"}})
`instance_group_id`	`string (uuid)`	Instance group ID (wire: instanceGroupId)
`project_id`	`string`	The Public Cloud project ID. Resolved from OVH_CLOUD_PROJECT_SERVICE when set.
`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 group Returns a single instance group (placement group), including its scheduling `policy` and its members. ### Immutable by design Instance groups are immutable after creation. There is deliberately no `PUT` / update route. Neither the placement `policy` nor the set of members can be changed once the group exists. Membership is fixed at instance creation time: an instance joins a group via its `targetSpec.group` field when it is created (see the instance `POST`), and cannot be added to or removed from a group afterward. To change grouping you delete and recreate the affected instances into a different group.

SELECT
id,
checksum,
created_at,
current_state,
current_tasks,
resource_status,
target_spec
FROM ovh.public_cloud.compute_instance_groups
WHERE instance_group_id = '{{ instance_group_id }}' -- required
AND project_id = '{{ project_id }}' -- required unless OVH_CLOUD_PROJECT_SERVICE is set
;

List instance groups Lists all instance groups (placement groups) in the project, each with the same shape as the `GET` route (scheduling `policy` and members). ### Immutable by design Instance groups cannot be modified after creation. There is deliberately no `PUT` / update route, and membership is fixed at instance creation time via the instance's `targetSpec.group` field. See the `GET` route for details.

SELECT
id,
checksum,
created_at,
current_state,
current_tasks,
resource_status,
target_spec
FROM ovh.public_cloud.compute_instance_groups
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 }}'
;

`INSERT` examples

create
Manifest

Create an instance group Creates a new instance group (placement group). Creation is asynchronous: the group starts in `CREATING` and becomes `READY` once the backend has provisioned it. ### Placement policy `targetSpec.policy` chooses how members are scheduled relative to each other: * `AFFINITY` — members are placed on the same hypervisor. * `ANTI_AFFINITY` — members are placed on different hypervisors (for high availability). ### Immutable, membership set at instance creation The group is immutable once created. There is deliberately no `PUT` / update route, so the `policy` can never be changed. The group is created empty: instances are not added here. An instance joins the group only at its own creation time, via its `targetSpec.group` field (see the instance `POST`), and membership cannot change afterward (OpenStack/Nova server groups are immutable).

INSERT INTO ovh.public_cloud.compute_instance_groups (
target_spec,
project_id
)
SELECT 
'{{ target_spec }}' /* required */,
'{{ project_id }}'
RETURNING
id,
checksum,
created_at,
current_state,
current_tasks,
resource_status,
target_spec
;

# Description fields are for documentation purposes
- name: compute_instance_groups
props:
  - name: project_id
    value: "{{ project_id }}"
    description: Required parameter for the compute_instance_groups resource.
  - name: target_spec
    description: |
      Target specification. Desired specification of the instance group to create: its name, location and placement policy (see PolicyEnum). All of these values are fixed for the lifetime of the group, as instance groups cannot be updated once created.
    value:
      location:
        availabilityZone: "{{ availabilityZone }}"
        region: "{{ region }}"
      name: "{{ name }}"
      policy: "{{ policy }}"

`DELETE` examples

delete

Delete an instance group Deletes an instance group (placement group). Deletion is asynchronous: the resource transitions to `DELETING` and the backend then removes it. A group is normally removed once it is empty (has no member instances). Because membership is fixed at instance creation time and cannot be edited on an existing group, freeing a group means deleting or recreating its member instances first. Deleting the group tears down only the placement grouping. It does not delete the instances themselves. A delete already in progress is reported as `ResourceAlreadyBeingDeleted`.

DELETE FROM ovh.public_cloud.compute_instance_groups
WHERE instance_group_id = '{{ instance_group_id }}' --required
AND project_id = '{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
;

Overview
Fields
Methods
Parameters
SELECT examples
- Get an instance group Returns a single instance group (placement group), including its scheduling policy and its members. ### Immutable by design Instance groups are immutable after creation. There is deliberately no PUT / update route. Neither the placement policy nor the set of members can be changed once the group exists. Membership is fixed at instance creation time: an instance joins a group via its targetSpec.group field when it is created (see the instance POST), and cannot be added to or removed from a group afterward. To change grouping you delete and recreate the affected instances into a different group.
- List instance groups Lists all instance groups (placement groups) in the project, each with the same shape as the GET route (scheduling policy and members). ### Immutable by design Instance groups cannot be modified after creation. There is deliberately no PUT / update route, and membership is fixed at instance creation time via the instance's targetSpec.group field. See the GET route for details.
INSERT examples
- Create an instance group Creates a new instance group (placement group). Creation is asynchronous: the group starts in CREATING and becomes READY once the backend has provisioned it. ### Placement policy targetSpec.policy chooses how members are scheduled relative to each other: * AFFINITY — members are placed on the same hypervisor. * ANTI_AFFINITY — members are placed on different hypervisors (for high availability). ### Immutable, membership set at instance creation The group is immutable once created. There is deliberately no PUT / update route, so the policy can never be changed. The group is created empty: instances are not added here. An instance joins the group only at its own creation time, via its targetSpec.group field (see the instance POST), and membership cannot change afterward (OpenStack/Nova server groups are immutable).
DELETE examples
- Delete an instance group Deletes an instance group (placement group). Deletion is asynchronous: the resource transitions to DELETING and the backend then removes it. A group is normally removed once it is empty (has no member instances). Because membership is fixed at instance creation time and cannot be edited on an existing group, freeing a group means deleting or recreating its member instances first. Deleting the group tears down only the placement grouping. It does not delete the instances themselves. A delete already in progress is reported as ResourceAlreadyBeingDeleted.

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

DELETE examples​