Getting started using API
Server details
The host endpoint provides details on dedicated bare metal servers in your account.
To list all Hosts with full detail on hardware configuration including IP addresses:
To list details of a specific Host:
Server actions
Basic action for power On/Off/Restart can be performed on each server using below endpoints:
Turn the server On:
PUT /v3/host/{hostId}/start
Turn the server Off:
PUT /v3/host/{hostId}/stop
Restart the server:
PUT /v3/host/{hostId}/restart
Server OS installation
This endpoint allows to install a new operating system onto a server in the customer account.
The {hostId} parameter can be found in GET /v3/host
which lists all the servers in your account.
API endpoint
Trigger an OS installation:
POST /v3/host/{hostId}/os/install
Check the current status of the installation process:
GET /v3/host/{hostId}/os/installLog
You will need to know which Operating System id to use by using below endpoint:
Request body properties
Property | Value type | Required | Description |
---|---|---|---|
hostname | string | Optional | Default is Server{ID} with Unique identifier. NOTE: when installing Talos, the machine name will be derived from the hostname, taking the first part of the hostname. |
os.id | int | Required | Desired os.id look up in GET /v3/operatingsystem |
os.kernelParams | string | Optional | An advanced option, currently only applies when installing Talos (See talos OS section) |
postInstallScript | string | Optional | Optional bash script to be performed after OS installation. Does not apply to Talos. |
sshKeyId | UUid | Required | Manage your SSH keys via POST /v3/sshKey . The public key will be installed for the root user. |
quickFormat | bool | Optional | Optional parameter indicating whether you want the disks to first be quick-formatted prior to OS installation. We recommend to always perform a quick-format, unless you have a specific case where it is not needed to clear the disk partitions prior to installing a new OS. |
Example request
POST /v3/host/{hostId}/os/install
Request Body
{
"hostname": "my.host.name",
"os": {
"id": 261
},
"postInstallScript": "#!/bin/bash\necho \"Hello world\" > /tmp/test.txt",
"sshKeyUuid": "62335584-bee9-48a2-xxxx-3561d8cadad1",
"quickFormat": true
}
Talos OS
Talos can be installed using two methods
- Talos install vanilla: provide required
siderolink.api
link - Talos install via Factory image: provide required
factoryhash
In both cases, additional kernel parameters are required. These will override any defaults injected. Talos default kernel parameters are:
slab_nomerge
pti=on
vga=normal
locale=en_US
console-keymaps-at/keymap=us
net.ifnames=0
panic=0
initrd=initrd.magic
init_on_alloc=1
consoleblank=0
nvme_core.io_timeout=4294967295
printk.devkmsg=on
ima_template=ima-ng
ima_appraise=fix ima_hash=sha512
talos.platform=metal
talos.events.sink=[fdae:41e4:649b:9303::1]:8091
talos.logging.kernel=tcp://[fdae:41e4:649b:9303::1]:8092
More information about Talos kernel parameters you can find here: https://www.talos.dev/v1.7/reference/kernel/
Network configuration for your server will be automatically injected by our systems.
Example Talos OS 1.7.2 Vanilla Request Body
POST /v3/host/{hostId}/os/install
Request body
{
"hostname": "My.Host.Name",
"os": {
"id": 294,
"kernelParams": [
{
"key": "siderolink.api",
"value": "https://path.to/omni?bcwe7r8236r7gwuyiwe"
},
{
"key": "talos.customparam",
"value": "123456"
}
]
},
"postInstallScript": null,
"sshKeyUuid": "62335584-bee9-48a2-a81d-3561d8cadad1"
}
Example Talos OS 1.7.2 Factory Request Body
POST /v3/host/{hostId}/os/install
Request body
{
"hostname": "My.Host.Name",
"os": {
"id": 294,
"kernelParams": [
{
"key": "factoryhash",
"value": "93be9c834b04065cdfb6223049697263586e92471231ed2abdfcc23c2a4551a4"
},
{
"key": "talos.customparam",
"value": "123456"
}
]
},
"postInstallScript": null,
"sshKeyUuid": "62335584-bee9-48a2-a81d-3561d8cadad1"
}