Instance Groups
All operations require authentication.
Get an instance groupProduction
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.
Path parameters
Instance group ID
Project ID
Response
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.
Creation date. Timestamp at which the instance group was created, in RFC 3339 format.
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.
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.
Unique identifier of the instance group, assigned at creation and used to reference it on the GET/DELETE routes
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.
CREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATINGTarget 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.
Example uses instanceGroupId = 00000000-0000-0000-0000-000000000000, projectId = string
$ curl https:/{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "location": { "availabilityZone": "string", "region": "string" }, "members": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "name": "string", "policy": "AFFINITY" }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "location": { "availabilityZone": "string", "region": "string" }, "name": "string", "policy": "AFFINITY" }}
List instance groupsProduction
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.
Path parameters
Project ID
Headers
Pagination cursor
Pagination size
Response
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.
Creation date. Timestamp at which the instance group was created, in RFC 3339 format.
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.
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.
Unique identifier of the instance group, assigned at creation and used to reference it on the GET/DELETE routes
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.
CREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATINGTarget 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.
Example uses projectId = string
$ curl https:/[ { "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "location": { "availabilityZone": "string", "region": "string" }, "members": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "name": "string", "policy": "AFFINITY" }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "location": { "availabilityZone": "string", "region": "string" }, "name": "string", "policy": "AFFINITY" } }]
Create an instance groupProduction
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).
Path parameters
Project ID
Request body (required)
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.
Response
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.
Creation date. Timestamp at which the instance group was created, in RFC 3339 format.
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.
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.
Unique identifier of the instance group, assigned at creation and used to reference it on the GET/DELETE routes
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.
CREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATINGTarget 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.
Example uses projectId = string
$ curl https:/{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "location": { "availabilityZone": "string", "region": "string" }, "members": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "name": "string", "policy": "AFFINITY" }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "location": { "availabilityZone": "string", "region": "string" }, "name": "string", "policy": "AFFINITY" }}
Delete an instance groupProduction
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.
Path parameters
Instance group ID
Project ID
Response
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.
Creation date. Timestamp at which the instance group was created, in RFC 3339 format.
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.
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.
Unique identifier of the instance group, assigned at creation and used to reference it on the GET/DELETE routes
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.
CREATINGCREATION_PLANNEDDELETINGERROROUT_OF_SYNCREADYSUSPENDEDUNKNOWNUPDATINGTarget 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.
Example uses instanceGroupId = 00000000-0000-0000-0000-000000000000, projectId = string
$ curl https:/{ "checksum": "string", "createdAt": "2024-01-01T12:00:00Z", "currentState": { "location": { "availabilityZone": "string", "region": "string" }, "members": [ { "id": "00000000-0000-0000-0000-000000000000" } ], "name": "string", "policy": "AFFINITY" }, "currentTasks": [ { "errors": [ { "message": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "link": "string", "status": "ERROR", "type": "string" } ], "id": "00000000-0000-0000-0000-000000000000", "resourceStatus": "CREATING", "targetSpec": { "location": { "availabilityZone": "string", "region": "string" }, "name": "string", "policy": "AFFINITY" }}