Dedicated Bare Metal

A powerful single-tenant machine that has no virtualization layer and allows full control of the hardware for increased compute efficiency and security (no noisy neighbours).

API Token

1. Generate an API token, the procedure is documented in API v3 Authentication

   1. Add IP whitelisting for security (whitelist the IP addresses that will access the API)

2. Include your API key in every request using this HTTP header:

   HTTP Header Name	HTTP Header Value
   PRIVATE-TOKEN	YOUR_API_KEY

3. Throughout these documentation pages, we will refer to API endpoints like for instance:

   GET /v3/host

   This is not a complete endpoint. You must prefix this with the API URI and API version tag:

   https://api.i3d.net/v3/

   That results in the complete URL:

   GET https://api.i3d.net/v3/host

Example HTTP request:

GET /v3/host
Host: api.i3d.net
PRIVATE-TOKEN: abc123xyz789

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:

GET /v3/host

To list details of a specific Host:

GET /v3/host/{hostId}

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 the installation of 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:

GET /v3/operatingsystem

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.

Table 1: Install OS element structure

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 is a stripped down Linux distribution tailored towards easy setup and management of Kubernetes clusters.

Sidero Talos allows you to create a Kubernetes cluster, using Omni as the central administration hub. To connect Talos nodes to Omni, a join token needs to be passed to the node. This configuration parameter is referenced as a siderolink.api URL.

i3D.net currently only support Talos installations that connect to Omni. Therefore a siderolink.api URL must always be provided by means a kernel argument injected into the API call for a vanilla Talos install, or injected into a Talos Factory image.

Talos can be installed in two flavors, using a vanilla image or using a Talos Factory image:

• Talos install vanilla: provide required siderolink.api link

• Talos install via Factory image: provide required factoryhash

Example Talos OS Vanilla Request Body

POST /v3/host/{hostId}/os/install

You must provide a siderolink.api URL as a kernel argument in the API request body. This makes the Talos node join your Omni instance.

You can provide additional Talos kernel arguments in the request body complementing or overriding our defaults.

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
nvme_core.multipath=n
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.11/reference/kernel/

Our systems will automatically inject network configuration for your server.

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 Factory Request Body

POST /v3/host/{hostId}/os/install

You must provide a factoryhash as a kernel argument in the request body, pointing to the Factory image you want to use.

You should add all your kernel arguments inside of the Factory Image configuration, and not add any here in the request body, as they will be forgotten by Talos when you add a node to a cluster, or upgrade a node.

Request body

{
  "hostname": "My.Host.Name",
  "os": {
    "id": 294,
    "kernelParams": [
      {
        "key": "factoryhash",
        "value": "93be9c834b04065cdfb6223049697263586e92471231ed2abdfcc23c2a4551a4"
      }
    ]
  },
  "postInstallScript": null,
  "sshKeyUuid": "62335584-bee9-48a2-a81d-3561d8cadad1"
}

Note: When installing Talos, it relies on an external site. If the external site is down, installation cannot proceed.

Classic NIC names vs predictable NIC names

The kernel parameter net.ifnames=0 will disable predictable network interface names and revert to classic names like eth0, eth1, etc.

In most cases it is best practice to use net.ifnames=0 so make sure you add that as a kernel argument to your Factory Image configuration.

This works in most cases where a server only has 1 or 2 uplinks. If you have more than 2 uplinks and network configuration is failing, it can be that Talos is assigning the wrong interfaces to eth0 and / or eth1. In that case you can try using the "predictable interface names" solution, by using the kernel parameter net.ifnames=1.