Launch templates¶

Saved instance settings, and launching several instances at once.

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.

Find launches¶

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

The launches from one launch template (template), or the launch that made one instance (server): exactly one of the two, newest first, at most 20. Each instance says whether it is still there.

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.
`org_id`	path	string		No
`project_id`	path	string		No
`server`	query	string		Yes	An instance (`srv_`).
`template`	query	string		Yes	A template (`ltp_`).

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "count": 0,
            "created_at": "string",
            "id": "string",
            "instances": [
                {
                    "operation": {},
                    "present": true,
                    "server": {}
                }
            ],
            "state": "string",
            "template": {}
        }
    ]
}

422 Unprocessable Entity

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

Launch instances¶

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

Creates 1 to 10 instances from a launch template or a create body, admitted all or nothing; each is its own operation. Instances are named <name>-1, <name>-2, ... (the next free numbers in the project). Follow the launch for each instance's state.

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/json202 Accepted

{
    "count": 0,
    "server": {
        "display_name": "string",
        "execute_before": "2022-04-13T15:42:05.901Z",
        "fixed_ip": "string",
        "image": "string",
        "image_id": "string",
        "image_version": "string",
        "load_balancer": {
            "pool_id": "string",
            "port": 0,
            "weight": 0
        },
        "location": "string",
        "network_id": "string",
        "offering": "string",
        "public_ip": true,
        "public_ip_id": "string",
        "security_group_ids": [
            "string"
        ],
        "security_group_templates": [
            "ssh"
        ],
        "server_group_id": "string",
        "ssh_key_id": "string",
        "tags": {},
        "user_data": "string",
        "volumes": [
            {
                "new": {
                    "display_name": "string",
                    "size_gb": 0,
                    "volume_type": "string"
                },
                "volume_id": "string"
            }
        ]
    },
    "template": {
        "id": "string",
        "version": 0
    }
}

Responses

application/jsonapplication/json

{
    "count": 0,
    "created": [
        "string"
    ],
    "created_at": "string",
    "id": "string",
    "instances": [
        {
            "operation": {},
            "present": true,
            "server": {}
        }
    ],
    "state": "string",
    "template": {}
}

422 Unprocessable Entity

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

Get a launch¶

GET /v1/orgs/{org_id}/projects/{project_id}/instance-launches/{launch_id}

Each instance's server and operation, and the launch's state: succeeded when every instance succeeded, failed when none did, partially_succeeded otherwise.

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.
`launch_id`	path	string		No
`org_id`	path	string		No
`project_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "count": 0,
    "created_at": "string",
    "id": "string",
    "instances": [
        {
            "operation": {},
            "present": true,
            "server": {}
        }
    ],
    "state": "string",
    "template": {}
}

422 Unprocessable Entity

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

List launch templates¶

GET /v1/orgs/{org_id}/projects/{project_id}/launch-templates

Every launch template of the project (at most 50), each with its current body.

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.
`org_id`	path	string		No
`project_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "created_at": "string",
            "current_version": 0,
            "description": "string",
            "has_user_data": true,
            "id": "string",
            "name": "string",
            "server": {},
            "shown_version": 0,
            "updated_at": "string",
            "version": 0,
            "versions": [
                {
                    "created_at": "string",
                    "has_user_data": true,
                    "version": 0
                }
            ]
        }
    ]
}

422 Unprocessable Entity

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

Create a launch template¶

POST /v1/orgs/{org_id}/projects/{project_id}/launch-templates

Saves an instance create body under a name unique in the project. References are checked now as far as they can be; a launch checks everything again.

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

{
    "description": "string",
    "name": "string",
    "server": {
        "display_name": "string",
        "execute_before": "2022-04-13T15:42:05.901Z",
        "fixed_ip": "string",
        "image": "string",
        "image_id": "string",
        "image_version": "string",
        "load_balancer": {
            "pool_id": "string",
            "port": 0,
            "weight": 0
        },
        "location": "string",
        "network_id": "string",
        "offering": "string",
        "public_ip": true,
        "public_ip_id": "string",
        "security_group_ids": [
            "string"
        ],
        "security_group_templates": [
            "ssh"
        ],
        "server_group_id": "string",
        "ssh_key_id": "string",
        "tags": {},
        "user_data": "string",
        "volumes": [
            {
                "new": {
                    "display_name": "string",
                    "size_gb": 0,
                    "volume_type": "string"
                },
                "volume_id": "string"
            }
        ]
    }
}

Responses

application/jsonapplication/json

{
    "created_at": "string",
    "current_version": 0,
    "description": "string",
    "has_user_data": true,
    "id": "string",
    "name": "string",
    "server": {},
    "shown_version": 0,
    "updated_at": "string",
    "version": 0,
    "versions": [
        {
            "created_at": "string",
            "has_user_data": true,
            "version": 0
        }
    ]
}

422 Unprocessable Entity

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

Delete a launch template¶

DELETE /v1/orgs/{org_id}/projects/{project_id}/launch-templates/{template_id}

Deletes it and erases its saved user data. Refused while a launch from it has not yet created its instances. 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
`org_id`	path	string		No
`project_id`	path	string		No
`template_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "deleted": true,
    "id": "string"
}

422 Unprocessable Entity

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

Get a launch template¶

GET /v1/orgs/{org_id}/projects/{project_id}/launch-templates/{template_id}

The current version's body, or ?version=n's. User data is never shown.

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.
`org_id`	path	string		No
`project_id`	path	string		No
`template_id`	path	string		No
`version`	query	integer		Yes

Responses

200 OK

application/jsonapplication/json

{
    "created_at": "string",
    "current_version": 0,
    "description": "string",
    "has_user_data": true,
    "id": "string",
    "name": "string",
    "server": {},
    "shown_version": 0,
    "updated_at": "string",
    "version": 0,
    "versions": [
        {
            "created_at": "string",
            "has_user_data": true,
            "version": 0
        }
    ]
}

422 Unprocessable Entity

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

Change a launch template¶

PATCH /v1/orgs/{org_id}/projects/{project_id}/launch-templates/{template_id}

Renames it, changes its description, or saves a new body as the next version (which becomes current). 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
`org_id`	path	string		No
`project_id`	path	string		No
`template_id`	path	string		No

Request body

application/json200 OK

{
    "description": "string",
    "name": "string",
    "server": {
        "display_name": "string",
        "execute_before": "2022-04-13T15:42:05.901Z",
        "fixed_ip": "string",
        "image": "string",
        "image_id": "string",
        "image_version": "string",
        "load_balancer": {
            "pool_id": "string",
            "port": 0,
            "weight": 0
        },
        "location": "string",
        "network_id": "string",
        "offering": "string",
        "public_ip": true,
        "public_ip_id": "string",
        "security_group_ids": [
            "string"
        ],
        "security_group_templates": [
            "ssh"
        ],
        "server_group_id": "string",
        "ssh_key_id": "string",
        "tags": {},
        "user_data": "string",
        "volumes": [
            {
                "new": {
                    "display_name": "string",
                    "size_gb": 0,
                    "volume_type": "string"
                },
                "volume_id": "string"
            }
        ]
    }
}

Responses

application/jsonapplication/json

{
    "created_at": "string",
    "current_version": 0,
    "description": "string",
    "has_user_data": true,
    "id": "string",
    "name": "string",
    "server": {},
    "shown_version": 0,
    "updated_at": "string",
    "version": 0,
    "versions": [
        {
            "created_at": "string",
            "has_user_data": true,
            "version": 0
        }
    ]
}

422 Unprocessable Entity

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

Schemas¶

HTTPValidationError¶

Name	Type	Description
`detail`	Array<ValidationError>

LaunchAccepted¶

Name	Type	Description
`count`	integer
`created`	Array<string>	The instances' IDs (`srv_`), in launch order.
`created_at`	string
`id`	string
`instances`	Array<LaunchInstance>
`state`	string
`template`		The template and version it launched from (`id`, `version`, and `name`, null once the template is deleted); null for a create body.

LaunchBody¶

Name	Type	Description
`count`	integer	How many instances, 1 to 10.
`server`	ServerCreateBody	A create body, when no template is named.
`template`	TemplateRef

LaunchInstance¶

Name	Type	Description
`operation`
`present`	boolean	False once the instance has been deleted.
`server`

LaunchList¶

Name	Type	Description
`items`	Array<LaunchView>

LaunchView¶

Name	Type	Description
`count`	integer
`created_at`	string
`id`	string
`instances`	Array<LaunchInstance>
`state`	string
`template`		The template and version it launched from (`id`, `version`, and `name`, null once the template is deleted); null for a create body.

NewVolumeBody¶

Name	Type	Description
`display_name`	string
`size_gb`	integer
`volume_type`	string

PoolMemberBody¶

Name	Type	Description
`pool_id`	string	A pool (`lbp_`) of a load balancer of this project.
`port`	integer	The port the instance serves on.
`weight`	integer

ServerCreateBody¶

Name	Type	Description
`display_name`	string
`execute_before`	string(date-time) \| null
`fixed_ip`	string \| null
`image`	string \| null
`image_id`	string \| null
`image_version`	string \| null
`load_balancer`	PoolMemberBody	A pool of one of this project's load balancers in the same location that the instance joins once it runs, at its private address on `network_id`. If joining fails, the instance stays and the operation ends `partially_succeeded`. Deleting the instance later leaves the member in the pool.
`location`	string
`network_id`	string \| null
`offering`	string
`public_ip`	boolean
`public_ip_id`	string \| null
`security_group_ids`	Array<string>
`security_group_templates`	Array<string>	Inbound rules from anywhere (0.0.0.0/0): `ssh` is TCP 22, `web` is TCP 80 and 443. A rule that any group in `security_group_ids` already allows is not added again; the others are added to the first group named there, the cloud's `default` group included, and no group is created. When no group is named, one new group `-access `is created with them (`-2`,` -3`, ... when that name is taken in the organization).
`server_group_id`	string \| null	A server group of this project in the same location. The instance joins it now; it cannot join, leave or change group later.
`ssh_key_id`	string \| null
`tags`		Labels `key: value` NubeStack Cloud keeps and writes to the resource in its location as `nx.= `(a volume's metadata key` nx.`), keeping its other tags. At most 20; a key is 1-32 of` a-z`,` 0-9`,` _`,` .`,` -`, starting with a letter; a value is 0-24 of` A-Z`,` a-z`,` 0-9`,` _`,` .`,` :`,` -`. An organization uses at most 50 keys.
`user_data`	string \| null
`volumes`	Array<ServerVolumeBody>	Up to 8 data volumes, attached in this order once the instance runs: each an existing volume (`volume_id`) or a new empty one (`new`). New volumes are made before the instance. If an attachment fails, the instance and every volume stay, and the operation ends `partially_succeeded`. Deleting the instance later detaches its volumes and keeps them.

ServerVolumeBody¶

Name	Type	Description
`new`	NewVolumeBody	A new empty volume.
`volume_id`	string \| null	An existing volume of this project in the same location, available and attached to nothing.

TemplateChangeBody¶

Name	Type	Description
`description`	string \| null
`name`	string \| null
`server`	ServerCreateBody	A new body: saved as the next version, which becomes current. It has exactly the user data it sends (none when absent).

TemplateCreateBody¶

Name	Type	Description
`description`	string
`name`	string
`server`	ServerCreateBody	What `POST …/servers` takes, without `execute_before`, `fixed_ip`, `public_ip_id` or an existing volume. `display_name` is the base of the instances' names. `user_data` is sealed and never shown again.

TemplateDeleted¶

Name	Type	Description
`deleted`	boolean
`id`	string

TemplateList¶

Name	Type	Description
`items`	Array<TemplateView>

TemplateRef¶

Name	Type	Description
`id`	string	The launch template (`ltp_`).
`version`	integer \| null	A version of it; the current one when absent.

TemplateVersionView¶

Name	Type	Description
`created_at`	string
`has_user_data`	boolean
`version`	integer

TemplateView¶

Name	Type	Description
`created_at`	string
`current_version`	integer
`description`	string
`has_user_data`	boolean
`id`	string
`name`	string
`server`		The version's body, without its user data.
`shown_version`	integer
`updated_at`	string
`version`	integer	The ETag: send it in `If-Match` to change or delete.
`versions`	Array<TemplateVersionView>

ValidationError¶

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