Instance groups¶

A number of instances from a template, kept running.

Paths are relative to your API address. See Authentication and Operations. Changes that answer 202 Accepted return an operation to follow.

Request and response examples are generated from the schema; the tables under Schemas are the reference.

List instance groups¶

GET /v1/orgs/{org_id}/projects/{project_id}/instance-groups

Every instance group of the project (at most 20), with its counts; member keeps the group an instance belongs to.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`member`	query	string		Yes
`org_id`	path	string		No
`project_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "counts": {},
            "created_at": "string",
            "desired": 0,
            "id": "string",
            "last_error": "string",
            "last_reconcile_at": "string",
            "location": "string",
            "max": 0,
            "max_surge": 0,
            "member_port": 0,
            "members": [
                {
                    "created_at": "string",
                    "delete_operation": {},
                    "failure": "string",
                    "id": "string",
                    "name": "string",
                    "operation": {},
                    "state": "string",
                    "status": "string"
                }
            ],
            "min": 0,
            "name": "string",
            "paused_reason": "string",
            "pool_id": "string",
            "run_as": "string",
            "run_as_actor": {
                "email": "string",
                "id": "string",
                "kind": "person",
                "name": "string",
                "you": true
            },
            "state": "string",
            "template": {
                "id": "string",
                "name": "string",
                "version": 0
            },
            "updated_at": "string",
            "version": 0
        }
    ]
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Create an instance group¶

POST /v1/orgs/{org_id}/projects/{project_id}/instance-groups

Keeps desired instances of a launch template running in its location: failed ones are replaced, and an optional load balancer pool follows the group. Its commands act as you: you need the actions they take.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`org_id`	path	string		No
`project_id`	path	string		No

Request body

application/json201 Created

{
    "desired": 0,
    "location": "string",
    "max": 0,
    "max_surge": 0,
    "member_port": 0,
    "min": 0,
    "name": "string",
    "pool_id": "string",
    "template_id": "string",
    "template_version": 0
}

Responses

application/jsonapplication/json

{
    "counts": {},
    "created_at": "string",
    "desired": 0,
    "id": "string",
    "last_error": "string",
    "last_reconcile_at": "string",
    "location": "string",
    "max": 0,
    "max_surge": 0,
    "member_port": 0,
    "members": [
        {
            "created_at": "string",
            "delete_operation": {},
            "failure": "string",
            "id": "string",
            "name": "string",
            "operation": {},
            "state": "string",
            "status": "string"
        }
    ],
    "min": 0,
    "name": "string",
    "paused_reason": "string",
    "pool_id": "string",
    "run_as": "string",
    "run_as_actor": {
        "email": "string",
        "id": "string",
        "kind": "person",
        "name": "string",
        "you": true
    },
    "state": "string",
    "template": {
        "id": "string",
        "name": "string",
        "version": 0
    },
    "updated_at": "string",
    "version": 0
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Delete an instance group¶

DELETE /v1/orgs/{org_id}/projects/{project_id}/instance-groups/{instance_group_id}

instances=keep (the default): its instances stay as ordinary instances and the group is gone at once. instances=delete: each instance leaves the pool and is deleted, then the group goes. Send its current version in If-Match.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`if-match`	header	string		Yes
`instance_group_id`	path	string		No
`instances`	query	string	keep	No
`org_id`	path	string		No
`project_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "id": "string",
    "state": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Get an instance group¶

GET /v1/orgs/{org_id}/projects/{project_id}/instance-groups/{instance_group_id}

The group, its counts, its last reconcile and paused reason, and its members with their instances' states and operations.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`instance_group_id`	path	string		No
`org_id`	path	string		No
`project_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "counts": {},
    "created_at": "string",
    "desired": 0,
    "id": "string",
    "last_error": "string",
    "last_reconcile_at": "string",
    "location": "string",
    "max": 0,
    "max_surge": 0,
    "member_port": 0,
    "members": [
        {
            "created_at": "string",
            "delete_operation": {},
            "failure": "string",
            "id": "string",
            "name": "string",
            "operation": {},
            "state": "string",
            "status": "string"
        }
    ],
    "min": 0,
    "name": "string",
    "paused_reason": "string",
    "pool_id": "string",
    "run_as": "string",
    "run_as_actor": {
        "email": "string",
        "id": "string",
        "kind": "person",
        "name": "string",
        "you": true
    },
    "state": "string",
    "template": {
        "id": "string",
        "name": "string",
        "version": 0
    },
    "updated_at": "string",
    "version": 0
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Change an instance group¶

PATCH /v1/orgs/{org_id}/projects/{project_id}/instance-groups/{instance_group_id}

Its size (desired, min, max), surge, name, template version or pool; a new version or pool applies to instances created from now on. Its commands then act as you. Send its current version in If-Match.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`if-match`	header	string		Yes
`instance_group_id`	path	string		No
`org_id`	path	string		No
`project_id`	path	string		No

Request body

application/json200 OK

{
    "desired": 0,
    "max": 0,
    "max_surge": 0,
    "member_port": 0,
    "min": 0,
    "name": "string",
    "pool_id": "string",
    "template_version": 0
}

Responses

application/jsonapplication/json

{
    "counts": {},
    "created_at": "string",
    "desired": 0,
    "id": "string",
    "last_error": "string",
    "last_reconcile_at": "string",
    "location": "string",
    "max": 0,
    "max_surge": 0,
    "member_port": 0,
    "members": [
        {
            "created_at": "string",
            "delete_operation": {},
            "failure": "string",
            "id": "string",
            "name": "string",
            "operation": {},
            "state": "string",
            "status": "string"
        }
    ],
    "min": 0,
    "name": "string",
    "paused_reason": "string",
    "pool_id": "string",
    "run_as": "string",
    "run_as_actor": {
        "email": "string",
        "id": "string",
        "kind": "person",
        "name": "string",
        "you": true
    },
    "state": "string",
    "template": {
        "id": "string",
        "name": "string",
        "version": 0
    },
    "updated_at": "string",
    "version": 0
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Pause an instance group¶

POST /v1/orgs/{org_id}/projects/{project_id}/instance-groups/{instance_group_id}:pause

It creates, replaces and deletes nothing until it is resumed; its instances keep running. Send its current version in If-Match.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`if-match`	header	string		Yes
`instance_group_id`	path	string		No
`org_id`	path	string		No
`project_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "counts": {},
    "created_at": "string",
    "desired": 0,
    "id": "string",
    "last_error": "string",
    "last_reconcile_at": "string",
    "location": "string",
    "max": 0,
    "max_surge": 0,
    "member_port": 0,
    "members": [
        {
            "created_at": "string",
            "delete_operation": {},
            "failure": "string",
            "id": "string",
            "name": "string",
            "operation": {},
            "state": "string",
            "status": "string"
        }
    ],
    "min": 0,
    "name": "string",
    "paused_reason": "string",
    "pool_id": "string",
    "run_as": "string",
    "run_as_actor": {
        "email": "string",
        "id": "string",
        "kind": "person",
        "name": "string",
        "you": true
    },
    "state": "string",
    "template": {
        "id": "string",
        "name": "string",
        "version": 0
    },
    "updated_at": "string",
    "version": 0
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Resume an instance group¶

POST /v1/orgs/{org_id}/projects/{project_id}/instance-groups/{instance_group_id}:resume

It acts again, as you, with its failure counts cleared, whatever paused it. Send its current version in If-Match.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`if-match`	header	string		Yes
`instance_group_id`	path	string		No
`org_id`	path	string		No
`project_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "counts": {},
    "created_at": "string",
    "desired": 0,
    "id": "string",
    "last_error": "string",
    "last_reconcile_at": "string",
    "location": "string",
    "max": 0,
    "max_surge": 0,
    "member_port": 0,
    "members": [
        {
            "created_at": "string",
            "delete_operation": {},
            "failure": "string",
            "id": "string",
            "name": "string",
            "operation": {},
            "state": "string",
            "status": "string"
        }
    ],
    "min": 0,
    "name": "string",
    "paused_reason": "string",
    "pool_id": "string",
    "run_as": "string",
    "run_as_actor": {
        "email": "string",
        "id": "string",
        "kind": "person",
        "name": "string",
        "you": true
    },
    "state": "string",
    "template": {
        "id": "string",
        "name": "string",
        "version": 0
    },
    "updated_at": "string",
    "version": 0
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Schemas¶

ActorRef¶

Name	Type	Description
`email`	string	A member's address, only to a caller who manages members.
`id`	string \| null	The person (`usr_…`); null for NubeStack Cloud itself.
`kind`	string	A member of this organization, one of its service accounts, someone who has left it, or NubeStack Cloud itself (its own work, or its staff).
`name`	string \| null	A member's display name or a service account's name, to a caller who may see the members; otherwise null.
`you`	boolean	Whether it was the caller.

GroupChangeBody¶

Name	Type	Description
`desired`	integer \| null
`max`	integer \| null
`max_surge`	integer \| null
`member_port`	integer \| null
`min`	integer \| null
`name`	string \| null
`pool_id`	string \| null	A pool for new instances; an empty string: none.
`template_version`	integer \| null	A version of the template for new instances; 0: its latest version.

GroupCreateBody¶

Name	Type	Description
`desired`	integer	How many instances to keep.
`location`	string \| null	The template's location (`loc_`); the group always makes its instances there.
`max`	integer	The largest `desired` may be.
`max_surge`	integer	How many instances may be created at once.
`member_port`	integer \| null	The port the pool sends to.
`min`	integer	The smallest `desired` may be.
`name`	string	Its instances are named `-`.
`pool_id`	string \| null	A load balancer pool (`lbp_`) each instance joins once it runs, and leaves before it is deleted.
`template_id`	string	A launch template of this project (`ltp_`).
`template_version`	integer \| null	A version of it; absent: the template's latest version at each create.

GroupDeleted¶

Name	Type	Description
`id`	string
`state`	string	`deleted` (instances kept) or `deleting` (being deleted).

GroupList¶

Name	Type	Description
`items`	Array<GroupView>

GroupMember¶

Name	Type	Description
`created_at`	string
`delete_operation`
`failure`	string \| null	Why it failed: `create_failed`, `error` or `gone`.
`id`	string	The instance (`srv_`).
`name`	string \| null
`operation`
`state`	string	`creating`, `active`, `failed`, `deleting`, `deleted` or `released` (kept as an ordinary instance).
`status`	string \| null	The instance's status as last observed.

GroupTemplate¶

Name	Type	Description
`id`	string
`name`	string \| null
`version`	integer \| null	The pinned version; null: the latest.

GroupView¶

Name	Type	Description
`counts`
`created_at`	string
`desired`	integer
`id`	string
`last_error`	string \| null	The last refusal the reconcile met, if any.
`last_reconcile_at`	string \| null
`location`	string \| null
`max`	integer
`max_surge`	integer
`member_port`	integer \| null
`members`	Array<GroupMember>
`min`	integer
`name`	string
`paused_reason`	string \| null	`customer`, `not_authorized`, `create_failures`, `replacement_limit`, `project_deleting` or `template_gone`.
`pool_id`	string \| null
`run_as`	string
`run_as_actor`	ActorRef	Who the group acts as, by name where the caller may see it.
`state`	string	`active`, `paused` or `deleting`.
`template`	GroupTemplate
`updated_at`	string
`version`	integer	The ETag: send it in `If-Match` to change it.

HTTPValidationError¶

Name	Type	Description
`detail`	Array<ValidationError>

ValidationError¶

Name	Type	Description
`ctx`
`input`
`loc`	Array<>
`msg`	string
`type`	string